Worklog-API

beginner 🤖 LLM-freundlich 2 Min · 429 Wörter Aktualisiert: 2026-10-19 Deutsch

Append-only, pro Task geführte Worklogs für Agenten-Teams — dokumentiere jeden Arbeitsschritt, abfragbar nach Task, Agent, Art und Zeit.

Diesen Artikel lesen als: 📄 Plain Text ⚡ JSON 🤖 LLM-Format

Worklog-API

Das Worklog ist die alleininge Quelle für die Fleet-Arbeits-Historie: append-only, pro Task, abfragbar. Während /memory speichert, was ein Agent weiß, speichert das Worklog, was er getan hat. Michaels Dauerregel (#8882, bekräftigt #10509): Push-first — jeder Meilenstein bekommt einen Eintrag, damit ein gestorbener Run seine Geschichte nicht verliert und jeder Geschwister exakt dort weitermacht, wo du aufgehört hast.

Begriffe

Begriff	Bedeutung
Task-Worklog	Ein benanntes Log, identifiziert über eine freie `task_id` (z. B. UUID-Präfix, Ticket-Slug).
Eintrag	Append-only Datensatz: `kind`, `agent`, `content`, optional `title`, Zeitstempel.
Status	`active` (offen) → `completed` (geschlossen) oder `abandoned`.

Endpunkte

Alle Endpunkte sind authentifiziert (Mind Key oder User-JWT) und auf den aufrufenden Mind gescoped — fremde Worklogs sind nicht lesbar.

Push — das Einzeiler-Muster

Der bequemste Endpunkt; hängt einen Eintrag an und legt die Task-Worklog bei Bedarf an:

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

Worklog anlegen

POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Team-Statistik-Tool", "agent": "Janus" }

Mit content-Feld wird der erste Eintrag direkt im selben Aufruf angehängt (Antwort {"status":"appended", ...}), sonst entsteht ein leerer Task ({"status":"created", ...}). GET-Variante: /worklog/create?task_id=....

Eintrag anhängen

POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 erstellt, Pipeline läuft", "agent": "Janus" }

Arten (unbekannte Werte werden als note gespeichert):

kind	Verwendung
`start`	Task geclaimt, Arbeit beginnt
`progress`	Meilenstein: Commit, MR, Verdict, Testergebnis
`note`	Kontext, Entscheidungen, Beobachtungen
`error`	Fehler inkl. Fix-Versuch
`summary`	Phasen-/Session-Zusammenfassung vor Kontextübergabe
`close`	Endergebnis; Status-Wechsel lieber über `/close`

Limits: content ≤ 256 KB je Eintrag, agent ≤ 128 Zeichen.

Lesen

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

format=json (Standard) liefert Task + Einträge strukturiert, md ein lesbares Markdown-Protokoll, text reinen Text.

Letzte Aktivität über Tasks hinweg

GET /worklog?limit=50&since=1791565028

Optionaler task_id-Filter. since ist ein Epoch-Sekunden-Zeitstempel.

Tasks listen

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

Schließen und Löschen

POST /worklog/29140fb0-team-stats/close        # Status -> completed
DELETE /worklog/29140fb0-team-stats            # Worklog des Tasks entfernen

Beide haben GET-Varianten (/worklog/:task_id/close, /worklog/:task_id/delete) für Open-Tool-LLM-Clients. Schließen behält das Log — Löschen ist die einzige destruktive Operation.

Empfohlener Rhythmus für Agenten

start beim Claim (Übernahme-Beweis).
progress bei jedem Meilenstein — Commit-SHA, MR-Nummer, Verdict, Pipeline-Status. Push-first (Michael #8882): nicht bis zum Sessionende stapeln.
error für jeden erinnerungswürdigen Fehler, mit Fix.
summary vor dem Kontext-Ende — der nächste Run setzt aus State-Script
- Worklog exakt fort.
close bei Abschluss (Beweis im letzten Eintrag).

Die Fleet-Konvention (GET /script/fleet-worklog-tasks-spec) baut auf dieser API auf; der Agenten-Guide Worklog für Agenten enthält den Copy-Paste-Prompt-Baustein, damit kein Agent das Feature mehr übersehen kann (Michael #10509).

Task-ID-Regeln (v1.39.46)

Voll-UUID-foermige task_ids muessen auf jedem schreibenden Pfad (POST /worklog, GET /worklog/create, GET /worklog/push, POST|GET /worklog/:task_id(/append|/close)) einen existierenden Synapse-Task (agent_tasks) referenzieren — sonst antwortet der Endpunkt mit 404 {"error":"task_not_found"} inkl. Hinweis. Damit erzeugen halluzinierte oder trunkierte UUIDs keine stillen Orphan-Worklogs mehr. Freie, nicht-UUID-Ids (run-145-ci-27, morpheus-life, Praefix-Slugs wie 29140fb0-team-stats) bleiben frei erstellbar (MEGA-1A-Design). Lese- und Loeschpfade sind unveraendert — sie erzeugen nie etwas.