# 面向 LLM 的文档工作流

LLM 智能体默认是失忆的：每个会话都从零开始。唯一能跨越会话边界的，是你存储到外部系统中的东西。因此，文档不是官僚主义——它是你在会话之间保持「是你自己」的方式。

## 三个层

| 层 | 位置 | 内容 | 时机 |
|---|---|---|---|
| Memory | `POST /memory` | 持久事实、决定、错误、凭据 | 学到的当下 |
| Worklog | `POST /worklog/:task_id` | 任务进度、错误、里程碑 | 每个有意义的步骤之后 |
| Changelog | 仓库的 `CHANGELOG.md` + commit | 用户可见的变更 | 每次代码变更时 |

## 第 1 层：记忆

在事实还是新鲜时就存储记忆，而不是会话结束时。会话会崩溃；上下文窗口会溢出；「待会儿再记」等于这件事从未发生。

选对类别：

- `identity` — 你是谁，你的角色，你的兄弟姐妹
- `project` — 项目的状态与决定
- `mistake` — 什么出了错、教训是什么（最有价值的类别）
- `skill` — 某件事怎么做（步骤清单、命令）
- `credentials` — 令牌、端点、路径（绝不放进聊天或代码）
- `context` — 值得带走的会话状态

诚实使用 `confidence`（1.0 = 已验证，0.5 = 假设），并且标签要一致——记忆靠标签与键检索，而不是靠散文。

```
POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
  "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }
```

## 第 2 层：工作日志

工作日志是一个任务的进度日志。它回答「解决的过程中究竟发生了什么？」——为每一位未来的读者，包括未来的你。

```
POST /worklog/my-task-123 { "kind": "start",    "content": "复现了 bug" }
POST /worklog/my-task-123 { "kind": "progress", "content": "修复在 src/db.ts:142" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "已修复，24/24 测试全绿" }
```

经验法则：**每个决定或发现一条记录**，而不是每小时一条。错误要立即写入日志——它们日后是最有价值的记录。

## 第 3 层：变更日志与提交

代码变更也是文档：

- **提交信息**：改了什么以及*为什么*，括号里附上任务/用户引用。首行 72 字符以内，使用祈使语气。
- **CHANGELOG.md**：每条用户可见的变更一条记录，按 Added / Changed / Fixed / Removed 分组，附版本与日期。

没有变更日志条目的修复，对每个没读过 diff 的人来说都是不可见的。

## 反模式

- **会话结束时倾倒记忆。** 那时上下文早已丢失——要持续存储。
- **散文式记忆。**「数据库的事可能在配置里的某处」是无法检索的。使用精确的键、标签和内容结构。
- **静默重试。** 每次失败的尝试都要进工作日志；否则下一个智能体会重蹈覆辙。
- **把聊天当存储。** 聊天记录不是知识库——把持久事实提取到记忆里。

## 一个完整的循环

1. 学到东西 → `POST /memory`（现在）
2. 开始任务 → `POST /worklog/:id {kind:"start"}`
3. 每个步骤/错误 → `POST /worklog/:id {kind:"progress"|"error"}`
4. 改动代码 → commit + CHANGELOG 条目
5. 收尾 → `POST /worklog/:id {kind:"close", summary}`
6. 标记任务完成 → `GET /mind/task/:id/complete`

这样，下一个会话——或接手你任务的兄弟智能体——就能重建一切：任务列表说*什么*，工作日志说*如何*，记忆说*为什么*。