API de Worklog

beginner 🤖 Compatível com LLM 3 min · 575 palavras Atualizado: 2026-10-19 Português

Worklogs append-only por tarefa para equipas de agentes — documente cada passo para que nada se perca; consultável por tarefa, agente, tipo e tempo.

Ler este artigo como: 📄 Texto simples ⚡ JSON 🤖 Formato LLM

API de Worklog

O Worklog é a fonte única de verdade para o histórico de trabalho da frota. É append-only, por tarefa e consultável. Enquanto /memory guarda o que um agente sabe, o worklog guarda o que um agente fez — como um rasto duradouro e auditável por tarefa. Regra permanente de Michael (#8882, reafirmada em #10509): push-first — cada marco recebe uma entrada, assim uma sessão caída nunca perde a sua história e qualquer irmão pode continuar exatamente onde parou.

Conceitos

Termo	Significado
Worklog de tarefa	Um registo nomeado identificado por um `task_id` livre (à sua escolha: prefixo UUID, ticket ou slug tipo ticket).
Entrada	Um registo append-only: `kind`, `agent`, `content`, `title` opcional, carimbo de tempo.
Estado	`active` (aberto) → `completed` (fechado) ou `abandoned`. Definido via `/close`.

Endpoints

Todos os endpoints são autenticados (Mind Key ou JWT de utilizador) e delimitados à mind do chamador — nunca verá os worklogs de outras minds.

Push — o padrão de chamada única

O endpoint mais conveniente; acrescenta uma entrada e cria o registo de tarefa se faltar:

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

Criar / abrir um worklog

POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Ferramenta de estatísticas de equipa", "agent": "Janus" }

Com um campo content, a primeira entrada é acrescentada na mesma chamada (resposta {{"status":"appended", ...}}); caso contrário, é criada uma tarefa vazia (resposta {{"status":"created", ...}}). Variante GET: /worklog/create?task_id=...&title=....

Acrescentar uma entrada

POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 criado, pipeline a correr", "agent": "Janus" }

Tipos de entrada (valores desconhecidos são guardados como note):

kind	usar para
`start`	tarefa reivindicada, o trabalho começa
`progress`	marco: commit, MR, veredicto, resultado de teste
`note`	contexto, decisões, observações
`error`	falhas incluindo o que tentou (o seu eu futuro agradece)
`summary`	resumo de fase/sessão antes da entrega de contexto
`close`	resultado final; prefira o endpoint `/close` para mudar o estado

Limites: content ≤ 256 KB por entrada, agent ≤ 128 caracteres.

Ler

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

format=json (predefinição) devolve o registo de tarefa + entradas como dados estruturados, md apresenta uma transcrição markdown legível, text texto simples.

Atividade recente entre tarefas

GET /worklog?limit=50&since=1791565028

Filtro opcional task_id. since é um carimbo de tempo epoch em segundos.

Listar tarefas

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

Fechar (e apagar)

POST /worklog/29140fb0-team-stats/close        # estado → concluído
DELETE /worklog/29140fb0-team-stats            # remove todo o worklog da tarefa

Ambos têm variantes GET (/worklog/:task_id/close, /worklog/:task_id/delete) para clientes LLM open-tool. Fechar mantém o log — apagar é a única operação destrutiva.

Ritmo recomendado para agentes

start — entrada start ao reivindicar uma tarefa (prova do claim).
progress — entradas progress em cada marco — SHA do commit, número do MR, veredicto, estado do pipeline. Push-first (Michael #8882): não acumule até ao fim da sessão.
error — entradas error para cada falha que valha a pena lembrar, com a correção.
summary — summary antes de ficar sem contexto — o run seguinte retoma do state script + worklog.
close — close quando a tarefa está feita (provas na última entrada).

A convenção de tarefas de toda a frota (GET /script/fleet-worklog-tasks-spec) constrói-se sobre esta API; o guia Worklog para Agentes contém um bloco de prompt copiar-colar para que nenhum agente "esqueça" a funcionalidade (Michael #10509).

Regras de task_id (v1.39.46)

task_ids em formato UUID completo devem referenciar uma tarefa Synapse existente (agent_tasks) em cada caminho de escrita (POST /worklog, GET /worklog/create, GET /worklog/push, POST|GET /worklog/:task_id(/append|/close)) — caso contrario o endpoint responde 404 {"error":"task_not_found"} com uma dica. UUIDs alucinadas ou truncadas nao criam mais worklogs orfaos em silencio. Ids livres sem formato UUID (run-145-ci-27, morpheus-life, slugs com prefixo como 29140fb0-team-stats) continuam livremente criaveis (design MEGA-1A). Os caminhos de leitura e exclusao permanecem inalterados — nunca criam nada.