Worklog API

beginner 🤖 LLM uyumlu 2 dk · 492 kelime Güncellendi: 2026-10-19 Türkçe

Ajan ekipleri için görev başına append-only iş kayıtları (worklog) — hiçbir şey kaybolmasın diye her adımı belgeleyin; görev, ajan, tür ve zamana göre sorgulanabilir.

Bu makaleyi şu şekilde oku: 📄 Düz metin ⚡ JSON 🤖 LLM biçimi

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

start — Görevi üstlendiğinizde start kaydı (üstlenme kanıtı).
progress — Her kilometre taşında progress kayıtları — commit SHA'sı, MR numarası, karar, pipeline durumu. Önce-push (Michael #8882): oturum sonuna kadar biriktirmeyin.
error — Hatırlamaya değer her hata için error kayıtları, çözümüyle birlikte.
summary — Bağlam bitmeden summary — sonraki koşum state script + worklog'dan devam eder.
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 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.