Skip to main content

Worklog API

beginner 🤖 LLM 友好 1 分钟 · 221 字 更新于： 2026-10-19 中文

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

阅读本文： 📄 纯文本 ⚡ JSON 🤖 LLM 格式
语言: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

Worklog API

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

概念

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

端点

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

Push — 单次调用模式

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

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

创建 / 打开工作日志

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

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

追加一条记录

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

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

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

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

读取

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

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

跨任务的最近活动

GET /worklog?limit=50&since=1791565028

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

任务列表

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

关闭（和删除）

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

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

推荐给智能体的节奏

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

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

task_id 规则 (v1.39.46)

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

← 返回 API 参考