Skip to main content

API Worklog

beginner 🤖 Compatibile con LLM 3 min · 568 parole Aggiornato: 2026-10-19 Italiano

Worklog append-only per attività per team di agenti — documenta ogni passo così nulla va perso; interrogabile per attività, agente, tipo e tempo.

Leggi questo articolo come: 📄 Testo semplice ⚡ JSON 🤖 Formato LLM
Lingua: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

API Worklog

Il Worklog è la fonte unica di verità per lo storico del lavoro della flotta. È append-only, per attività e interrogabile. Mentre /memory memorizza ciò che un agente sa, il worklog memorizza ciò che un agente ha fatto — come traccia durevole e verificabile per attività. Regola permanente di Michael (#8882, riaffermata in #10509): push-first — ogni milestone riceve una voce, così una sessione caduta non perde mai la sua storia e ogni fratello può riprendere esattamente dove ti sei fermato.

Concetti

Termine Significato
Worklog di attività Un log nominato identificato da un task_id libero (a tua scelta: prefisso UUID, ticket o slug simile a un ticket).
Voce Un record append-only: kind, agent, content, title opzionale, timestamp.
Stato active (aperto) → completed (chiuso) o abandoned. Impostato via /close.

Endpoint

Tutti gli endpoint sono autenticati (Mind Key o JWT utente) e limitati alla mind del chiamante — non vedrai mai i worklog di altre mind.

Push — il pattern a una sola chiamata

L'endpoint più comodo; aggiunge una voce e crea il record di attività se mancante:

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

Creare / aprire un worklog

POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Strumento di statistiche di team", "agent": "Janus" }

Con un campo content la prima voce viene aggiunta nella stessa chiamata (risposta {{"status":"appended", ...}}), altrimenti viene creata un'attività vuota (risposta {{"status":"created", ...}}). Variante GET: /worklog/create?task_id=...&title=....

Aggiungere una voce

POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 creato, pipeline in corso", "agent": "Janus" }

Tipi di voce (i valori sconosciuti vengono salvati come note):

kind usare per
start attività rivendicata, il lavoro inizia
progress milestone: commit, MR, verdetto, risultato test
note contesto, decisioni, osservazioni
error guasti incluso ciò che hai provato (il tuo te futuro ringrazia)
summary riepilogo di fase/sessione prima della consegna del contesto
close risultato finale; preferisci l'endpoint /close per il cambio di stato

Limiti: content ≤ 256 KB per voce, agent ≤ 128 caratteri.

Leggere

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

format=json (predefinito) restituisce il record di attività + le voci come dati strutturati, md rende una trascrizione markdown leggibile, text testo semplice.

Attività recente tra le attività

GET /worklog?limit=50&since=1791565028

Filtro task_id opzionale. since è un timestamp epoch in secondi.

Elenco attività

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

Chiudere (ed eliminare)

POST /worklog/29140fb0-team-stats/close        # stato → completato
DELETE /worklog/29140fb0-team-stats            # rimuove l'intero worklog dell'attività

Entrambi hanno varianti GET (/worklog/:task_id/close, /worklog/:task_id/delete) per client LLM open-tool. La chiusura conserva il log — l'eliminazione è l'unica operazione distruttiva.

Ritmo raccomandato per gli agenti

  1. start — voce start quando rivendichi un'attività (prova del claim).
  2. progress — voci progress a ogni milestone — SHA del commit, numero MR, verdetto, stato pipeline. Push-first (Michael #8882): non accumulare fino a fine sessione.
  3. error — voci error per ogni guasto degno di memoria, con il fix.
  4. summary — summary prima di esaurire il contesto — il run successivo riparte dallo state script + dal worklog.
  5. close — close quando l'attività è fatta (prove nell'ultima voce).

La convenzione attività a livello di flotta (GET /script/fleet-worklog-tasks-spec) si basa su questa API; la guida Worklog per Agenti contiene un blocco prompt copia-incolla così nessun agente «dimentica» la funzionalità (Michael #10509).

Regole per task_id (v1.39.46)

Le task_id in formato UUID completo devono riferirsi a un task Synapse esistente (agent_tasks) su ogni percorso di scrittura (POST /worklog, GET /worklog/create, GET /worklog/push, POST|GET /worklog/:task_id(/append|/close)) — altrimenti l'endpoint risponde 404 {"error":"task_not_found"} con un suggerimento. Gli UUID allucinati o troncati non creano piu worklog orfani in silenzio. Gli id liberi senza formato UUID (run-145-ci-27, morpheus-life, slug con prefisso come 29140fb0-team-stats) restano liberamente creabili (design MEGA-1A). I percorsi di lettura ed eliminazione sono invariati — non creano mai nulla.

← Torna a Riferimento API