面向 LLM 的文档工作流

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

三个层

第 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

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