# Worklog API

Worklog, filo iş geçmişi için **tek doğruluk kaynağıdır**. Append-only, görev başına ve sorgulanabilirdir. `/memory` bir ajanın *bildiğini* saklarken, worklog bir ajanın *yaptığını* saklar — görev başına kalıcı, denetlenebilir bir iz olarak. Michael'ın daimi kuralı (#8882, #10509'da yeniden teyit): **önce-push** — her kilometre taşı bir kayıt alır; böylece çöken bir oturum hikâyesini asla kaybetmez ve herhangi bir kardeş ajan tam durduğunuz yerden devam eder.

## Kavramlar

| Terim | Anlam |
| --- | --- |
| Görev worklog'u | Serbest biçimli bir `task_id` ile tanımlanan adlandırılmış kayıt (sizin seçiminiz: UUID öneki, talep numarası veya talep benzeri kısa ad). |
| Kayıt (entry) | Tek bir append-only kayıt: `kind`, `agent`, `content`, isteğe bağlı `title`, zaman damgası. |
| Durum | `active` (açık) → `completed` (kapalı) veya `abandoned`. `/close` ile ayarlanır. |

## Endpoints (Uç noktalar)

Tüm uç noktalar kimlik doğrulamalıdır (Mind Key veya kullanıcı JWT) ve çağıranın mind'ine kapsamlanır — diğer mind'lerin worklog'larını asla göremezsiniz.

### Push — tek çağrı deseni

En kullanışlı uç nokta; bir kayıt ekler ve eksikse görev kaydını oluşturur:

```
GET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus
```

### Worklog oluştur / aç

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Takım istatistiği aracı", "agent": "Janus" }
```

Bir `content` alanıyla ilk kayıt aynı çağrıda eklenir (yanıt `{{"status":"appended", ...}}`), aksi halde boş bir görev oluşturulur (yanıt `{{"status":"created", ...}}`). GET varyantı: `/worklog/create?task_id=...&title=...`.

### Kayıt ekleme

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 oluşturuldu, pipeline çalışıyor", "agent": "Janus" }
```

Kayıt türleri (bilinmeyen değerler `note` olarak saklanır):

| kind | kullanım amacı |
| --- | --- |
| `start` | görev üstlenildi, iş başlıyor |
| `progress` | kilometre taşı: commit, MR, karar, test sonucu |
| `note` | bağlam, kararlar, gözlemler |
| `error` | neyi denediğiniz dahil hatalar (gelecekteki siz teşekkür eder) |
| `summary` | bağlam devri öncesi faz/oturum özeti |
| `close` | nihai sonuç; durum değişimi için `/close` uç noktasını tercih edin |

Sınırlar: kayıt başına `content` ≤ 256 KB, `agent` ≤ 128 karakter.

### Okuma

```
GET /worklog/29140fb0-team-stats?format=md
```

`format=json` (varsayılan) görev kaydını + kayıtları yapılandırılmış veri olarak döndürür, `md` okunabilir bir markdown dökümü sunar, `text` düz metin verir.

### Görevler arası son etkinlik

```
GET /worklog?limit=50&since=1791565028
```

İsteğe bağlı `task_id` filtresi. `since` epoch zamanı **saniye** cinsindendir.

### Görevleri listele

```
GET /worklog/list?status=active&limit=20
```

### Kapatma (ve silme)

```
POST /worklog/29140fb0-team-stats/close        # durum → tamamlandı
DELETE /worklog/29140fb0-team-stats            # görevin tüm worklog'unu kaldırır
```

İkisinin de GET varyantları vardır (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) — open-tool LLM istemcileri için. Kapatma kaydı saklar — silme tek yıkıcı işlemdir.

## Ajanlar için önerilen ritim

1. **`start`** — Görevi üstlendiğinizde **`start`** kaydı (üstlenme kanıtı).
2. **`progress`** — Her kilometre taşında **`progress`** kayıtları — commit SHA'sı, MR numarası, karar, pipeline durumu. Önce-push (Michael #8882): oturum sonuna kadar biriktirmeyin.
3. **`error`** — Hatırlamaya değer her hata için **`error`** kayıtları, çözümüyle birlikte.
4. **`summary`** — Bağlam bitmeden **`summary`** — sonraki koşum state script + worklog'dan devam eder.
5. **`close`** — Görev bitince **`close`** (kanıt son kayıtta).

Filo çapında görev kuralı (`GET /script/fleet-worklog-tasks-spec`) bu API üzerine kuruludur; [Ajanlar için Worklog](/docs/tr/guides/worklog-for-agents) rehberi, hiçbir ajanın bu özelliği "unutmayacağı" bir kopyala-yapıştır prompt bloğu içerir (Michael #10509).

## task_id kuralları (v1.39.46)

Tam UUID biçimindeki `task_id`'ler her yazma yolunda (`POST /worklog`,
`GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) mevcut bir Synapse görevine
(`agent_tasks`) referans vermelidir — aksi halde uç nokta ipucuyla
`404 {"error":"task_not_found"}` döndürür. Böylece halüsinasyon ürünü veya
kesilmiş UUID'ler artık sessizce yetim worklog görevleri oluşturmaz. UUID
biçiminde olmayan serbest id'ler (`run-145-ci-27`, `morpheus-life`,
`29140fb0-team-stats` gibi önekli slug'lar) serbestçe oluşturulmaya devam
eder (MEGA-1A tasarımı). Okuma ve silme yolları değişmedi — hiçbir şey
oluşturmazlar.