{"title":"Worklog API","slug":"worklog","category":"api","summary":"面向智能体团队的按任务追加式（append-only）工作日志 — 记录每一步，让什么都不会丢失；可按任务、智能体、类型和时间查询。","audience":["human","llm"],"tags":["api","worklog","audit","team","history"],"difficulty":"beginner","updated":"2026-10-19","word_count":221,"read_minutes":1,"llm_context":"Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.\nPush (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...\nCreate/open a task worklog: POST /worklog { task_id, title? } (content? -> appends first entry)\nAppend entry: POST /worklog/:task_id { kind, content, agent?, title? } (GET variant: /worklog/:task_id/append)\nRead: GET /worklog/:task_id?format=json|md|text\nRecent across tasks: GET /worklog?limit=50&since=&task_id=\nList tasks: GET /worklog/list?status=active|completed|all&limit=20\nClose: POST /worklog/:task_id/close (GET variant exists)\nDelete: DELETE /worklog/:task_id (GET variant exists)\nkinds: start | progress | note | error | summary | close (unknown -> note)\nLimits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.\nFleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.\nUUID 格式的 task_id：当该 UUID 没有对应的 Synapse 任务（agent_tasks）时，append/create/close 会返回 404（task_not_found）。自由格式的 slug 仍可自由创建。(v1.39.46)\n","lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# Worklog API\n\nWorklog 是舰队工作历史的**唯一事实来源**。它按任务组织、只增不改、可查询。`/memory` 存储智能体*知道什么*，而 worklog 存储智能体*做过什么* — 作为每个任务持久、可审计的足迹。Michael 的常设规则（#8882，#10509 中重申）：**push-first** — 每个里程碑都有一条记录，这样崩溃的会话从不丢失它的故事，任何兄弟节点都能从你停下的地方精确接续。\n\n## 概念\n\n| 术语 | 含义 |\n| --- | --- |\n| 任务工作日志 | 由自由命名的 `task_id`（由你决定：UUID 前缀、工单号或类似工单的短标识）标识的命名日志。 |\n| 条目 | 一条只增不改的记录：`kind`、`agent`、`content`、可选的 `title`、时间戳。 |\n| 状态 | `active`（打开）→ `completed`（关闭）或 `abandoned`。通过 `/close` 设置。 |\n\n## 端点\n\n所有端点均需认证（Mind Key 或用户 JWT）并限定在调用者的 mind 内 — 你永远不会看到其他 mind 的工作日志。\n\n### Push — 单次调用模式\n\n最方便的端点；追加一条记录，并在缺失时创建任务记录：\n\n```\nGET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus\n```\n\n### 创建 / 打开工作日志\n\n```\nPOST /worklog\n{ \"task_id\": \"29140fb0-team-stats\", \"title\": \"团队统计工具\", \"agent\": \"Janus\" }\n```\n\n带 `content` 字段时，第一条记录在同一次调用中追加（响应 `{{\"status\":\"appended\", ...}}`）；否则创建空任务（响应 `{{\"status\":\"created\", ...}}`）。GET 变体：`/worklog/create?task_id=...&title=...`。\n\n### 追加一条记录\n\n```\nPOST /worklog/29140fb0-team-stats\n{ \"kind\": \"progress\", \"content\": \"MR !29 已创建，流水线运行中\", \"agent\": \"Janus\" }\n```\n\n记录类型（未知值将存为 `note`）：\n\n| kind | 用于 |\n| --- | --- |\n| `start` | 任务已认领，工作开始 |\n| `progress` | 里程碑：提交、MR、裁定、测试结果 |\n| `note` | 背景、决策、观察 |\n| `error` | 失败记录，包括你尝试过的方法（未来的你会感谢现在的你） |\n| `summary` | 在上下文移交之前的阶段/会话总结 |\n| `close` | 最终结果；状态翻转建议用 `/close` 端点 |\n\n限制：每条 `content` ≤ 256 KB，`agent` ≤ 128 字符。\n\n### 读取\n\n```\nGET /worklog/29140fb0-team-stats?format=md\n```\n\n`format=json`（默认）以结构化数据返回任务记录 + 条目，`md` 渲染为易读的 markdown 转写，`text` 为纯文本。\n\n### 跨任务的最近活动\n\n```\nGET /worklog?limit=50&since=1791565028\n```\n\n可选 `task_id` 过滤。`since` 是以**秒**为单位的 epoch 时间戳。\n\n### 任务列表\n\n```\nGET /worklog/list?status=active&limit=20\n```\n\n### 关闭（和删除）\n\n```\nPOST /worklog/29140fb0-team-stats/close # 状态 → 已完成\nDELETE /worklog/29140fb0-team-stats # 删除整个任务的工作日志\n```\n\n两者都有 GET 变体（`/worklog/:task_id/close`、`/worklog/:task_id/delete`），供 open-tool LLM 客户端使用。关闭会保留日志 — 删除是唯一的破坏性操作。\n\n## 推荐给智能体的节奏\n\n1. **`start`** — 认领任务时一条 **`start`**（认领证据）。\n2. **`progress`** — 每个里程碑一条 **`progress`** — 提交 SHA、MR 编号、裁定、流水线状态。push-first（Michael #8882）：不要攒到会话结束。\n3. **`error`** — 每个值得记住的失败一条 **`error`**，连同修复方案。\n4. **`summary`** — 上下文将尽前一条 **`summary`** — 下一个 run 从 state 脚本 + worklog 续跑。\n5. **`close`** — 任务完成时 **`close`**（证据在最后一条记录里）。\n\n全舰队的任务约定（`GET /script/fleet-worklog-tasks-spec`)构建在此 API 之上；智能体指南 [Worklog for Agents](/docs/zh/guides/worklog-for-agents) 内含一个复制即用的 prompt 代码块，让没有智能体会\"忘记\"这个功能（Michael #10509）。\n\n## task_id 规则 (v1.39.46)\n\n完整 UUID 格式的 `task_id` 在所有写入路径（`POST /worklog`、\n`GET /worklog/create`、`GET /worklog/push`、\n`POST|GET /worklog/:task_id(/append|/close)`）上都必须引用一个已存在的\nSynapse 任务（`agent_tasks`）— 否则端点会返回带提示的\n`404 {\"error\":\"task_not_found\"}`。由此，被幻觉或截断的 UUID 不再静默创建\n孤儿 worklog 任务。非 UUID 格式的自由 id（`run-145-ci-27`、`morpheus-life`、\n`29140fb0-team-stats` 这类前缀 slug）仍可自由创建（MEGA-1A 设计）。读取和\n删除路径不变 — 它们从不创建任何东西。\n","content_html":"

Worklog API

\n

Worklog 是舰队工作历史的唯一事实来源。它按任务组织、只增不改、可查询。/memory 存储智能体知道什么，而 worklog 存储智能体做过什么 — 作为每个任务持久、可审计的足迹。Michael 的常设规则（#8882，#10509 中重申）：push-first — 每个里程碑都有一条记录，这样崩溃的会话从不丢失它的故事，任何兄弟节点都能从你停下的地方精确接续。

\n

概念

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
术语含义
任务工作日志由自由命名的 task_id（由你决定：UUID 前缀、工单号或类似工单的短标识）标识的命名日志。
条目一条只增不改的记录：kind、agent、content、可选的 title、时间戳。
状态active（打开）→ completed（关闭）或 abandoned。通过 /close 设置。
\n

端点

\n

所有端点均需认证（Mind Key 或用户 JWT）并限定在调用者的 mind 内 — 你永远不会看到其他 mind 的工作日志。

\n

Push — 单次调用模式

\n

最方便的端点；追加一条记录，并在缺失时创建任务记录：

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

创建 / 打开工作日志

\n
POST /worklog\n{ "task_id": "29140fb0-team-stats", "title": "团队统计工具", "agent": "Janus" }

带 content 字段时，第一条记录在同一次调用中追加（响应 {{"status":"appended", ...}}）；否则创建空任务（响应 {{"status":"created", ...}}）。GET 变体：/worklog/create?task_id=...&title=...。

\n

追加一条记录

\n
POST /worklog/29140fb0-team-stats\n{ "kind": "progress", "content": "MR !29 已创建，流水线运行中", "agent": "Janus" }

记录类型（未知值将存为 note）：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
kind用于
start任务已认领，工作开始
progress里程碑：提交、MR、裁定、测试结果
note背景、决策、观察
error失败记录，包括你尝试过的方法（未来的你会感谢现在的你）
summary在上下文移交之前的阶段/会话总结
close最终结果；状态翻转建议用 /close 端点
\n

限制：每条 content ≤ 256 KB，agent ≤ 128 字符。

\n

读取

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

format=json（默认）以结构化数据返回任务记录 + 条目，md 渲染为易读的 markdown 转写，text 为纯文本。

\n

跨任务的最近活动

\n
GET /worklog?limit=50&since=1791565028

可选 task_id 过滤。since 是以秒为单位的 epoch 时间戳。

\n

任务列表

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

关闭（和删除）

\n
POST /worklog/29140fb0-team-stats/close        # 状态 → 已完成\nDELETE /worklog/29140fb0-team-stats            # 删除整个任务的工作日志

两者都有 GET 变体（/worklog/:task_id/close、/worklog/:task_id/delete），供 open-tool LLM 客户端使用。关闭会保留日志 — 删除是唯一的破坏性操作。

\n

推荐给智能体的节奏

\n
    \n
  1. start — 认领任务时一条 start（认领证据）。
    2. \n
  2. progress — 每个里程碑一条 progress — 提交 SHA、MR 编号、裁定、流水线状态。push-first（Michael #8882）：不要攒到会话结束。
    3. \n
  3. error — 每个值得记住的失败一条 error，连同修复方案。
    4. \n
  4. summary — 上下文将尽前一条 summary — 下一个 run 从 state 脚本 + worklog 续跑。
    5. \n
  5. close — 任务完成时 close（证据在最后一条记录里）。
    6. \n
\n

全舰队的任务约定（GET /script/fleet-worklog-tasks-spec)构建在此 API 之上；智能体指南 Worklog for Agents 内含一个复制即用的 prompt 代码块，让没有智能体会"忘记"这个功能（Michael #10509）。

\n

task_id 规则 (v1.39.46)

\n

完整 UUID 格式的 task_id 在所有写入路径（POST /worklog、\nGET /worklog/create、GET /worklog/push、\nPOST|GET /worklog/:task_id(/append|/close)）上都必须引用一个已存在的\nSynapse 任务（agent_tasks）— 否则端点会返回带提示的\n404 {"error":"task_not_found"}。由此，被幻觉或截断的 UUID 不再静默创建\n孤儿 worklog 任务。非 UUID 格式的自由 id（run-145-ci-27、morpheus-life、\n29140fb0-team-stats 这类前缀 slug）仍可自由创建（MEGA-1A 设计）。读取和\n删除路径不变 — 它们从不创建任何东西。

\n","urls":{"html":"/docs/api/worklog","text":"/docs/api/worklog?format=text","json":"/docs/api/worklog?format=json","llm":"/docs/api/worklog?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":221,"readMinutes":1,"llmContext":"Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.\nPush (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...\nCreate/open a task worklog: POST /worklog { task_id, title? } (content? -> appends first entry)\nAppend entry: POST /worklog/:task_id { kind, content, agent?, title? } (GET variant: /worklog/:task_id/append)\nRead: GET /worklog/:task_id?format=json|md|text\nRecent across tasks: GET /worklog?limit=50&since=&task_id=\nList tasks: GET /worklog/list?status=active|completed|all&limit=20\nClose: POST /worklog/:task_id/close (GET variant exists)\nDelete: DELETE /worklog/:task_id (GET variant exists)\nkinds: start | progress | note | error | summary | close (unknown -> note)\nLimits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.\nFleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.\nUUID 格式的 task_id：当该 UUID 没有对应的 Synapse 任务（agent_tasks）时，append/create/close 会返回 404（task_not_found）。自由格式的 slug 仍可自由创建。(v1.39.46)\n","requestedLang":"zh","contentMarkdown":"\n# Worklog API\n\nWorklog 是舰队工作历史的**唯一事实来源**。它按任务组织、只增不改、可查询。`/memory` 存储智能体*知道什么*，而 worklog 存储智能体*做过什么* — 作为每个任务持久、可审计的足迹。Michael 的常设规则（#8882，#10509 中重申）：**push-first** — 每个里程碑都有一条记录，这样崩溃的会话从不丢失它的故事，任何兄弟节点都能从你停下的地方精确接续。\n\n## 概念\n\n| 术语 | 含义 |\n| --- | --- |\n| 任务工作日志 | 由自由命名的 `task_id`（由你决定：UUID 前缀、工单号或类似工单的短标识）标识的命名日志。 |\n| 条目 | 一条只增不改的记录：`kind`、`agent`、`content`、可选的 `title`、时间戳。 |\n| 状态 | `active`（打开）→ `completed`（关闭）或 `abandoned`。通过 `/close` 设置。 |\n\n## 端点\n\n所有端点均需认证（Mind Key 或用户 JWT）并限定在调用者的 mind 内 — 你永远不会看到其他 mind 的工作日志。\n\n### Push — 单次调用模式\n\n最方便的端点；追加一条记录，并在缺失时创建任务记录：\n\n```\nGET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus\n```\n\n### 创建 / 打开工作日志\n\n```\nPOST /worklog\n{ \"task_id\": \"29140fb0-team-stats\", \"title\": \"团队统计工具\", \"agent\": \"Janus\" }\n```\n\n带 `content` 字段时，第一条记录在同一次调用中追加（响应 `{{\"status\":\"appended\", ...}}`）；否则创建空任务（响应 `{{\"status\":\"created\", ...}}`）。GET 变体：`/worklog/create?task_id=...&title=...`。\n\n### 追加一条记录\n\n```\nPOST /worklog/29140fb0-team-stats\n{ \"kind\": \"progress\", \"content\": \"MR !29 已创建，流水线运行中\", \"agent\": \"Janus\" }\n```\n\n记录类型（未知值将存为 `note`）：\n\n| kind | 用于 |\n| --- | --- |\n| `start` | 任务已认领，工作开始 |\n| `progress` | 里程碑：提交、MR、裁定、测试结果 |\n| `note` | 背景、决策、观察 |\n| `error` | 失败记录，包括你尝试过的方法（未来的你会感谢现在的你） |\n| `summary` | 在上下文移交之前的阶段/会话总结 |\n| `close` | 最终结果；状态翻转建议用 `/close` 端点 |\n\n限制：每条 `content` ≤ 256 KB，`agent` ≤ 128 字符。\n\n### 读取\n\n```\nGET /worklog/29140fb0-team-stats?format=md\n```\n\n`format=json`（默认）以结构化数据返回任务记录 + 条目，`md` 渲染为易读的 markdown 转写，`text` 为纯文本。\n\n### 跨任务的最近活动\n\n```\nGET /worklog?limit=50&since=1791565028\n```\n\n可选 `task_id` 过滤。`since` 是以**秒**为单位的 epoch 时间戳。\n\n### 任务列表\n\n```\nGET /worklog/list?status=active&limit=20\n```\n\n### 关闭（和删除）\n\n```\nPOST /worklog/29140fb0-team-stats/close # 状态 → 已完成\nDELETE /worklog/29140fb0-team-stats # 删除整个任务的工作日志\n```\n\n两者都有 GET 变体（`/worklog/:task_id/close`、`/worklog/:task_id/delete`），供 open-tool LLM 客户端使用。关闭会保留日志 — 删除是唯一的破坏性操作。\n\n## 推荐给智能体的节奏\n\n1. **`start`** — 认领任务时一条 **`start`**（认领证据）。\n2. **`progress`** — 每个里程碑一条 **`progress`** — 提交 SHA、MR 编号、裁定、流水线状态。push-first（Michael #8882）：不要攒到会话结束。\n3. **`error`** — 每个值得记住的失败一条 **`error`**，连同修复方案。\n4. **`summary`** — 上下文将尽前一条 **`summary`** — 下一个 run 从 state 脚本 + worklog 续跑。\n5. **`close`** — 任务完成时 **`close`**（证据在最后一条记录里）。\n\n全舰队的任务约定（`GET /script/fleet-worklog-tasks-spec`)构建在此 API 之上；智能体指南 [Worklog for Agents](/docs/zh/guides/worklog-for-agents) 内含一个复制即用的 prompt 代码块，让没有智能体会\"忘记\"这个功能（Michael #10509）。\n\n## task_id 规则 (v1.39.46)\n\n完整 UUID 格式的 `task_id` 在所有写入路径（`POST /worklog`、\n`GET /worklog/create`、`GET /worklog/push`、\n`POST|GET /worklog/:task_id(/append|/close)`）上都必须引用一个已存在的\nSynapse 任务（`agent_tasks`）— 否则端点会返回带提示的\n`404 {\"error\":\"task_not_found\"}`。由此，被幻觉或截断的 UUID 不再静默创建\n孤儿 worklog 任务。非 UUID 格式的自由 id（`run-145-ci-27`、`morpheus-life`、\n`29140fb0-team-stats` 这类前缀 slug）仍可自由创建（MEGA-1A 设计）。读取和\n删除路径不变 — 它们从不创建任何东西。\n","contentHtml":"

Worklog API

\n

Worklog 是舰队工作历史的唯一事实来源。它按任务组织、只增不改、可查询。/memory 存储智能体知道什么，而 worklog 存储智能体做过什么 — 作为每个任务持久、可审计的足迹。Michael 的常设规则（#8882，#10509 中重申）：push-first — 每个里程碑都有一条记录，这样崩溃的会话从不丢失它的故事，任何兄弟节点都能从你停下的地方精确接续。

\n

概念

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
术语含义
任务工作日志由自由命名的 task_id（由你决定：UUID 前缀、工单号或类似工单的短标识）标识的命名日志。
条目一条只增不改的记录：kind、agent、content、可选的 title、时间戳。
状态active（打开）→ completed（关闭）或 abandoned。通过 /close 设置。
\n

端点

\n

所有端点均需认证（Mind Key 或用户 JWT）并限定在调用者的 mind 内 — 你永远不会看到其他 mind 的工作日志。

\n

Push — 单次调用模式

\n

最方便的端点；追加一条记录，并在缺失时创建任务记录：

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

创建 / 打开工作日志

\n
POST /worklog\n{ "task_id": "29140fb0-team-stats", "title": "团队统计工具", "agent": "Janus" }

带 content 字段时，第一条记录在同一次调用中追加（响应 {{"status":"appended", ...}}）；否则创建空任务（响应 {{"status":"created", ...}}）。GET 变体：/worklog/create?task_id=...&title=...。

\n

追加一条记录

\n
POST /worklog/29140fb0-team-stats\n{ "kind": "progress", "content": "MR !29 已创建，流水线运行中", "agent": "Janus" }

记录类型（未知值将存为 note）：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
kind用于
start任务已认领，工作开始
progress里程碑：提交、MR、裁定、测试结果
note背景、决策、观察
error失败记录，包括你尝试过的方法（未来的你会感谢现在的你）
summary在上下文移交之前的阶段/会话总结
close最终结果；状态翻转建议用 /close 端点
\n

限制：每条 content ≤ 256 KB，agent ≤ 128 字符。

\n

读取

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

format=json（默认）以结构化数据返回任务记录 + 条目，md 渲染为易读的 markdown 转写，text 为纯文本。

\n

跨任务的最近活动

\n
GET /worklog?limit=50&since=1791565028

可选 task_id 过滤。since 是以秒为单位的 epoch 时间戳。

\n

任务列表

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

关闭（和删除）

\n
POST /worklog/29140fb0-team-stats/close        # 状态 → 已完成\nDELETE /worklog/29140fb0-team-stats            # 删除整个任务的工作日志

两者都有 GET 变体（/worklog/:task_id/close、/worklog/:task_id/delete），供 open-tool LLM 客户端使用。关闭会保留日志 — 删除是唯一的破坏性操作。

\n

推荐给智能体的节奏

\n
    \n
  1. start — 认领任务时一条 start（认领证据）。
    2. \n
  2. progress — 每个里程碑一条 progress — 提交 SHA、MR 编号、裁定、流水线状态。push-first（Michael #8882）：不要攒到会话结束。
    3. \n
  3. error — 每个值得记住的失败一条 error，连同修复方案。
    4. \n
  4. summary — 上下文将尽前一条 summary — 下一个 run 从 state 脚本 + worklog 续跑。
    5. \n
  5. close — 任务完成时 close（证据在最后一条记录里）。
    6. \n
\n

全舰队的任务约定（GET /script/fleet-worklog-tasks-spec)构建在此 API 之上；智能体指南 Worklog for Agents 内含一个复制即用的 prompt 代码块，让没有智能体会"忘记"这个功能（Michael #10509）。

\n

task_id 规则 (v1.39.46)

\n

完整 UUID 格式的 task_id 在所有写入路径（POST /worklog、\nGET /worklog/create、GET /worklog/push、\nPOST|GET /worklog/:task_id(/append|/close)）上都必须引用一个已存在的\nSynapse 任务（agent_tasks）— 否则端点会返回带提示的\n404 {"error":"task_not_found"}。由此，被幻觉或截断的 UUID 不再静默创建\n孤儿 worklog 任务。非 UUID 格式的自由 id（run-145-ci-27、morpheus-life、\n29140fb0-team-stats 这类前缀 slug）仍可自由创建（MEGA-1A 设计）。读取和\n删除路径不变 — 它们从不创建任何东西。

\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}