# Worklog API
SUMMARY: 面向智能体团队的按任务追加式（append-only）工作日志 — 记录每一步，让什么都不会丢失；可按任务、智能体、类型和时间查询。

KEY CONTEXT:
Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.
Push (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...
Create/open a task worklog: POST /worklog { task_id, title? }  (content? -> appends first entry)
Append entry: POST /worklog/:task_id { kind, content, agent?, title? }  (GET variant: /worklog/:task_id/append)
Read: GET /worklog/:task_id?format=json|md|text
Recent across tasks: GET /worklog?limit=50&since=<epoch sec>&task_id=
List tasks: GET /worklog/list?status=active|completed|all&limit=20
Close: POST /worklog/:task_id/close  (GET variant exists)
Delete: DELETE /worklog/:task_id  (GET variant exists)
kinds: start | progress | note | error | summary | close (unknown -> note)
Limits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.
Fleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.
UUID 格式的 task_id：当该 UUID 没有对应的 Synapse 任务（agent_tasks）时，append/create/close 会返回 404（task_not_found）。自由格式的 slug 仍可自由创建。(v1.39.46)

Worklog API
Worklog 是舰队工作历史的唯一事实来源。它按任务组织、只增不改、可查询。 存储智能体知道什么，而 worklog 存储智能体做过什么 — 作为每个任务持久、可审计的足迹。Michael 的常设规则（#8882，#10509 中重申）：push-first — 每个里程碑都有一条记录，这样崩溃的会话从不丢失它的故事，任何兄弟节点都能从你停下的地方精确接续。
概念
| 术语 | 含义 |
| --- | --- |
| 任务工作日志 | 由自由命名的 （由你决定：UUID 前缀、工单号或类似工单的短标识）标识的命名日志。 |
| 条目 | 一条只增不改的记录：、、、可选的 、时间戳。 |
| 状态 | （打开）→ （关闭）或 。通过  设置。 |
端点
所有端点均需认证（Mind Key 或用户 JWT）并限定在调用者的 mind 内 — 你永远不会看到其他 mind 的工作日志。
Push — 单次调用模式
最方便的端点；追加一条记录，并在缺失时创建任务记录：
[CODE BLOCK]
创建 / 打开工作日志
[CODE BLOCK]
带  字段时，第一条记录在同一次调用中追加（响应 ）；否则创建空任务（响应 ）。GET 变体：。
追加一条记录
[CODE BLOCK]
记录类型（未知值将存为 ）：
| kind | 用于 |
| --- | --- |
|  | 任务已认领，工作开始 |
|  | 里程碑：提交、MR、裁定、测试结果 |
|  | 背景、决策、观察 |
|  | 失败记录，包括你尝试过的方法（未来的你会感谢现在的你） |
|  | 在上下文移交之前的阶段/会话总结 |
|  | 最终结果；状态翻转建议用  端点 |
限制：每条  ≤ 256 KB， ≤ 128 字符。
读取
[CODE BLOCK]
（默认）以结构化数据返回任务记录 + 条目， 渲染为易读的 markdown 转写， 为纯文本。
跨任务的最近活动
[CODE BLOCK]
可选  过滤。 是以秒为单位的 epoch 时间戳。
任务列表
[CODE BLOCK]
关闭（和删除）
[CODE BLOCK]
两者都有 GET 变体（、），供 open-tool LLM 客户端使用。关闭会保留日志 — 删除是唯一的破坏性操作。
推荐给智能体的节奏
1.  — 认领任务时一条 （认领证据）。
2.  — 每个里程碑一条  — 提交 SHA、MR 编号、裁定、流水线状态。push-first（Michael #8882）：不要攒到会话结束。
3.  — 每个值得记住的失败一条 ，连同修复方案。
4.  — 上下文将尽前一条  — 下一个 run 从 state 脚本 + worklog 续跑。
5.  — 任务完成时 （证据在最后一条记录里）。
全舰队的任务约定（)构建在此 API 之上；智能体指南 Worklog for Agents 内含一个复制即用的 prompt 代码块，让没有智能体会"忘记"这个功能（Michael #10509）。
taskid 规则 (v1.39.46)
完整 UUID 格式的  在所有写入路径（、
、、
）上都必须引用一个已存在的
Synapse 任务（）— 否则端点会返回带提示的
。由此，被幻觉或截断的 UUID 不再静默创建
孤儿 worklog 任务。非 UUID 格式的自由 id（、、
 这类前缀 slug）仍可自由创建（MEGA-1A 设计）。读取和
删除路径不变 — 它们从不创建任何东西。