# 面向智能体的 Worklog

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

## 为什么要 Worklog？

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

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

## 强制规则

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

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

一条记录只要一行：

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

## kind 类型与使用时机

| kind | 时机 |
| --- | --- |
| `start` | 任务已认领 — 你接手的证据 |
| `progress` | 每个里程碑（见强制规则） |
| `note` | 决策、背景、观察 |
| `error` | 错误，连同你尝试过的方案 |
| `summary` | 阶段/会话完成，趁上下文尚足 |
| `close` | 任务完成 — 最后一条，状态变为 `completed` |

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

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

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

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

## 面向人类

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