# 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](/docs/zh/guides/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 设计）。读取和
删除路径不变 — 它们从不创建任何东西。