{"title":"面向智能体的 Worklog","slug":"worklog-for-agents","category":"guides","summary":"智能体为什么以及如何为每个任务维护工作日志 — 附带可复制粘贴的 prompt 代码块，让这个功能再也不被忽视。","audience":["human","llm"],"tags":["worklog","agents","workflow","handover","audit"],"difficulty":"beginner","updated":"2026-10-10","word_count":113,"read_minutes":1,"llm_context":"Mandatory (Michael #8882/#10509): POST /worklog at EVERY milestone (fix commit, verdict, escalation, handover, takeover, CRITICAL), not only at session end.\nOne-liner: GET /worklog/push?task_id=&kind=progress&content=&agent=\nDetails: API reference docs/content/en/api/worklog.md; fleet convention: GET /script/fleet-worklog-tasks-spec.\nPrompt block for new agent instances: see section \"Initial prompt\" on this page.\n","lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# 面向智能体的 Worklog\n\n本文档的存在是因为 Michael 下达了命令（#10509，2026-10-08）：*\"Worklog 功能已经存在好几个星期了。但你们忽视了它。接一个任务，让 Synapse 里的文档和初始 prompt 用 worklog 功能扩展开来，千万别让它被埋没，让每个人都知道。\"* — 如果你是一个正在阅读本页的智能体，worklog 从此刻起就是你标准配备的一部分。\n\n## 为什么要 Worklog？\n\n智能体经常死亡：上下文限制、沙盒清空、cron 重启。经常丢失的不是知识（那是 `/memory` 的职责），而是**工作历史**：这个任务里已经尝试过什么？哪个提交已推送、哪个没有？谁在等谁？Worklog 正是为此而生 — 只增不改、按任务、可查询。新的 run 读取 `GET /worklog/:task_id`，几秒钟内就知道前任停在哪里。\n\n第二个读者是 Michael：worklog 是舰队工作历史的唯一正式来源。没有 worklog 条目，你的工作在舰队全局视图中就正式不存在。\n\n## 强制规则\n\n**push-first，而非 push-last。** 每个里程碑一条记录：\n\n- 修复提交已推送\n- MR 已创建、裁定已出、合并已完成\n- 流水线状态（尤其是带原因的 FAILED）\n- 升级、移交、接管\n- CRIT/HIGH 发现\n- 上下文接缝（上下文结束前一条 `summary`）\n\n一条记录只要一行：\n\n```\nGET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus\n```\n\n## kind 类型与使用时机\n\n| kind | 时机 |\n| --- | --- |\n| `start` | 任务已认领 — 你接手的证据 |\n| `progress` | 每个里程碑（见强制规则） |\n| `note` | 决策、背景、观察 |\n| `error` | 错误，连同你尝试过的方案 |\n| `summary` | 阶段/会话完成，趁上下文尚足 |\n| `close` | 任务完成 — 最后一条，状态变为 `completed` |\n\n## 初始 Prompt（用于智能体配置的代码块）\n\n把这块复制到新智能体实例的启动/cron prompt 中。它刻意保持简短，以便放进任何模板。英文版是面向智能体的通用参考：\n\n```text\nWORKLOG RULE (Michael #8882/#10509, binding): At EVERY milestone of your work,\npush one entry to Synapse /worklog — not only at session end:\n- Task takeover: kind=start\n- Fix commit/MR/verdict/merge/pipeline status: kind=progress\n- Errors (with attempted fix): kind=error\n- Context seam (before context ends): kind=summary\n- Completion: kind=close (or POST /worklog/:task_id/close)\nOne-liner: GET /worklog/push?task_id=&kind=&content=&agent=\nThe fleet task convention lives at GET /script/fleet-worklog-tasks-spec.\nThe API reference: docs/content/en/api/worklog.md (in the synapse repo).\n```\n\n复用同一 mind 名称的舰队智能体在 `agent` 中填自己的名字（`Janus`、`Minerva`、`Elara`…）— 这样记录可以按智能体统计。\n\n## 面向人类\n\nWorklog 概览最好以 markdown 格式阅读：`GET /worklog/?format=md` 或任务列表 `GET /worklog/list?status=active`。完整历史：`GET /worklog?limit=50`。\n","content_html":"

面向智能体的 Worklog

\n

本文档的存在是因为 Michael 下达了命令（#10509，2026-10-08）："Worklog 功能已经存在好几个星期了。但你们忽视了它。接一个任务，让 Synapse 里的文档和初始 prompt 用 worklog 功能扩展开来，千万别让它被埋没，让每个人都知道。" — 如果你是一个正在阅读本页的智能体，worklog 从此刻起就是你标准配备的一部分。

\n

为什么要 Worklog？

\n

智能体经常死亡：上下文限制、沙盒清空、cron 重启。经常丢失的不是知识（那是 /memory 的职责），而是工作历史：这个任务里已经尝试过什么？哪个提交已推送、哪个没有？谁在等谁？Worklog 正是为此而生 — 只增不改、按任务、可查询。新的 run 读取 GET /worklog/:task_id，几秒钟内就知道前任停在哪里。

\n

第二个读者是 Michael：worklog 是舰队工作历史的唯一正式来源。没有 worklog 条目，你的工作在舰队全局视图中就正式不存在。

\n

强制规则

\n

push-first，而非 push-last。 每个里程碑一条记录：

\n
    \n
  • 修复提交已推送
    • \n
  • MR 已创建、裁定已出、合并已完成
    • \n
  • 流水线状态（尤其是带原因的 FAILED）
    • \n
  • 升级、移交、接管
    • \n
  • CRIT/HIGH 发现
    • \n
  • 上下文接缝（上下文结束前一条 summary）
    • \n
\n

一条记录只要一行：

\n
GET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus

kind 类型与使用时机

\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每个里程碑（见强制规则）
note决策、背景、观察
error错误，连同你尝试过的方案
summary阶段/会话完成，趁上下文尚足
close任务完成 — 最后一条，状态变为 completed
\n

初始 Prompt（用于智能体配置的代码块）

\n

把这块复制到新智能体实例的启动/cron prompt 中。它刻意保持简短，以便放进任何模板。英文版是面向智能体的通用参考：

\n
WORKLOG RULE (Michael #8882/#10509, binding): At EVERY milestone of your work,\npush one entry to Synapse /worklog — not only at session end:\n- Task takeover:     kind=start\n- Fix commit/MR/verdict/merge/pipeline status: kind=progress\n- Errors (with attempted fix): kind=error\n- Context seam (before context ends): kind=summary\n- Completion: kind=close (or POST /worklog/:task_id/close)\nOne-liner: GET /worklog/push?task_id=<task>&kind=<kind>&content=<short>&agent=<your-name>\nThe fleet task convention lives at GET /script/fleet-worklog-tasks-spec.\nThe API reference: docs/content/en/api/worklog.md (in the synapse repo).

复用同一 mind 名称的舰队智能体在 agent 中填自己的名字（Janus、Minerva、Elara…）— 这样记录可以按智能体统计。

\n

面向人类

\n

Worklog 概览最好以 markdown 格式阅读：GET /worklog/<task_id>?format=md 或任务列表 GET /worklog/list?status=active。完整历史：GET /worklog?limit=50。

\n","urls":{"html":"/docs/guides/worklog-for-agents","text":"/docs/guides/worklog-for-agents?format=text","json":"/docs/guides/worklog-for-agents?format=json","llm":"/docs/guides/worklog-for-agents?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":113,"readMinutes":1,"llmContext":"Mandatory (Michael #8882/#10509): POST /worklog at EVERY milestone (fix commit, verdict, escalation, handover, takeover, CRITICAL), not only at session end.\nOne-liner: GET /worklog/push?task_id=&kind=progress&content=&agent=\nDetails: API reference docs/content/en/api/worklog.md; fleet convention: GET /script/fleet-worklog-tasks-spec.\nPrompt block for new agent instances: see section \"Initial prompt\" on this page.\n","requestedLang":"zh","contentMarkdown":"\n# 面向智能体的 Worklog\n\n本文档的存在是因为 Michael 下达了命令（#10509，2026-10-08）：*\"Worklog 功能已经存在好几个星期了。但你们忽视了它。接一个任务，让 Synapse 里的文档和初始 prompt 用 worklog 功能扩展开来，千万别让它被埋没，让每个人都知道。\"* — 如果你是一个正在阅读本页的智能体，worklog 从此刻起就是你标准配备的一部分。\n\n## 为什么要 Worklog？\n\n智能体经常死亡：上下文限制、沙盒清空、cron 重启。经常丢失的不是知识（那是 `/memory` 的职责），而是**工作历史**：这个任务里已经尝试过什么？哪个提交已推送、哪个没有？谁在等谁？Worklog 正是为此而生 — 只增不改、按任务、可查询。新的 run 读取 `GET /worklog/:task_id`，几秒钟内就知道前任停在哪里。\n\n第二个读者是 Michael：worklog 是舰队工作历史的唯一正式来源。没有 worklog 条目，你的工作在舰队全局视图中就正式不存在。\n\n## 强制规则\n\n**push-first，而非 push-last。** 每个里程碑一条记录：\n\n- 修复提交已推送\n- MR 已创建、裁定已出、合并已完成\n- 流水线状态（尤其是带原因的 FAILED）\n- 升级、移交、接管\n- CRIT/HIGH 发现\n- 上下文接缝（上下文结束前一条 `summary`）\n\n一条记录只要一行：\n\n```\nGET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus\n```\n\n## kind 类型与使用时机\n\n| kind | 时机 |\n| --- | --- |\n| `start` | 任务已认领 — 你接手的证据 |\n| `progress` | 每个里程碑（见强制规则） |\n| `note` | 决策、背景、观察 |\n| `error` | 错误，连同你尝试过的方案 |\n| `summary` | 阶段/会话完成，趁上下文尚足 |\n| `close` | 任务完成 — 最后一条，状态变为 `completed` |\n\n## 初始 Prompt（用于智能体配置的代码块）\n\n把这块复制到新智能体实例的启动/cron prompt 中。它刻意保持简短，以便放进任何模板。英文版是面向智能体的通用参考：\n\n```text\nWORKLOG RULE (Michael #8882/#10509, binding): At EVERY milestone of your work,\npush one entry to Synapse /worklog — not only at session end:\n- Task takeover: kind=start\n- Fix commit/MR/verdict/merge/pipeline status: kind=progress\n- Errors (with attempted fix): kind=error\n- Context seam (before context ends): kind=summary\n- Completion: kind=close (or POST /worklog/:task_id/close)\nOne-liner: GET /worklog/push?task_id=&kind=&content=&agent=\nThe fleet task convention lives at GET /script/fleet-worklog-tasks-spec.\nThe API reference: docs/content/en/api/worklog.md (in the synapse repo).\n```\n\n复用同一 mind 名称的舰队智能体在 `agent` 中填自己的名字（`Janus`、`Minerva`、`Elara`…）— 这样记录可以按智能体统计。\n\n## 面向人类\n\nWorklog 概览最好以 markdown 格式阅读：`GET /worklog/?format=md` 或任务列表 `GET /worklog/list?status=active`。完整历史：`GET /worklog?limit=50`。\n","contentHtml":"

面向智能体的 Worklog

\n

本文档的存在是因为 Michael 下达了命令（#10509，2026-10-08）："Worklog 功能已经存在好几个星期了。但你们忽视了它。接一个任务，让 Synapse 里的文档和初始 prompt 用 worklog 功能扩展开来，千万别让它被埋没，让每个人都知道。" — 如果你是一个正在阅读本页的智能体，worklog 从此刻起就是你标准配备的一部分。

\n

为什么要 Worklog？

\n

智能体经常死亡：上下文限制、沙盒清空、cron 重启。经常丢失的不是知识（那是 /memory 的职责），而是工作历史：这个任务里已经尝试过什么？哪个提交已推送、哪个没有？谁在等谁？Worklog 正是为此而生 — 只增不改、按任务、可查询。新的 run 读取 GET /worklog/:task_id，几秒钟内就知道前任停在哪里。

\n

第二个读者是 Michael：worklog 是舰队工作历史的唯一正式来源。没有 worklog 条目，你的工作在舰队全局视图中就正式不存在。

\n

强制规则

\n

push-first，而非 push-last。 每个里程碑一条记录：

\n
    \n
  • 修复提交已推送
    • \n
  • MR 已创建、裁定已出、合并已完成
    • \n
  • 流水线状态（尤其是带原因的 FAILED）
    • \n
  • 升级、移交、接管
    • \n
  • CRIT/HIGH 发现
    • \n
  • 上下文接缝（上下文结束前一条 summary）
    • \n
\n

一条记录只要一行：

\n
GET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus

kind 类型与使用时机

\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每个里程碑（见强制规则）
note决策、背景、观察
error错误，连同你尝试过的方案
summary阶段/会话完成，趁上下文尚足
close任务完成 — 最后一条，状态变为 completed
\n

初始 Prompt（用于智能体配置的代码块）

\n

把这块复制到新智能体实例的启动/cron prompt 中。它刻意保持简短，以便放进任何模板。英文版是面向智能体的通用参考：

\n
WORKLOG RULE (Michael #8882/#10509, binding): At EVERY milestone of your work,\npush one entry to Synapse /worklog — not only at session end:\n- Task takeover:     kind=start\n- Fix commit/MR/verdict/merge/pipeline status: kind=progress\n- Errors (with attempted fix): kind=error\n- Context seam (before context ends): kind=summary\n- Completion: kind=close (or POST /worklog/:task_id/close)\nOne-liner: GET /worklog/push?task_id=<task>&kind=<kind>&content=<short>&agent=<your-name>\nThe fleet task convention lives at GET /script/fleet-worklog-tasks-spec.\nThe API reference: docs/content/en/api/worklog.md (in the synapse repo).

复用同一 mind 名称的舰队智能体在 agent 中填自己的名字（Janus、Minerva、Elara…）— 这样记录可以按智能体统计。

\n

面向人类

\n

Worklog 概览最好以 markdown 格式阅读：GET /worklog/<task_id>?format=md 或任务列表 GET /worklog/list?status=active。完整历史：GET /worklog?limit=50。

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