2026-10-05·编排与协作·TaskMemory

如果只是把 Plan 搬出对话消息，一个字段就够了。但'Agent 在做什么'不是一个维度——是五个：做什么（Plan）、发现了什么（Findings）、为什么这样选（Decisions）、确认到哪里（Checkpoints）、学到了什么（Learnings）。五种制品各有不同的写入纪律和消费方式。

为什么不止一个 Plan 字段

"为什么任务执行态必须从对话消息中搬出来"一章讲了压缩的破坏性和物理解耦的必要性。最直觉的做法是：加一个 Plan 字段，搬出来就好。

但"Agent 在做什么"不是一维的。

考虑这个场景：Agent 在执行一个 6 步的重构任务。第 3 步完成后，它发现了一个安全漏洞（SQL 注入）。它决定修改 Plan——把原来的第 4 步拆成两步：先修漏洞、再继续原来的重构。在第 5 步（修漏洞）完成后，它确认"安全问题已处理，可以继续重构"。任务全部完成后，它总结经验："这个代码库的 DAO 层普遍缺少参数化查询，以后遇到类似模式先检查注入风险。"

这段执行过程包含了五种不同性质的信息：

1. Plan（做什么）：6 步 → 拆成 7 步
2. Finding（发现了什么）：UserDAO 有 SQL 注入漏洞
3. Decision（为什么这样选）：把第 4 步拆成两步，先修漏洞
4. Checkpoint（确认到哪里）：安全问题已处理
5. Learning（学到了什么）：DAO 层普遍缺少参数化查询

如果只有 Plan 字段：Finding（SQL 注入）在哪？Decision（为什么拆步骤）在哪？Checkpoint（安全问题已解决的确认点）在哪？Learning（跨项目复用的经验）在哪？

它们只能泡在消息里——然后被压缩掉。

---

五种制品详解

制品一：Plan——组织者

Plan 已经在 Plan 系列中详细讲过。它是五种制品的组织者——定义步骤结构，其他四种制品都围绕 Plan 的步骤产出。

写入时机：任务开始时（Planning Phase）。运行中可修改（追加/跳过/分裂步骤）。

消费方式：每轮注入到上下文中——pending 步骤的描述 + 已完成步骤的状态。

与消息流的关系：Plan 工具的 tool_result 仍进入消息流（作为操作确认），但 Plan 的完整数据在 TaskStore 中——压缩消息流不影响 Plan 数据。

制品二：Findings——事实记录

Findings 是每个 Plan 步骤执行后产出的事实记录——Agent 在这一步中发现了什么。

为什么是强制产出：每步完成后必须写入至少一条 Finding——即使内容是"本步骤无特别发现"。

这条"强制写入"规则看起来繁琐，但解决了一个微妙的问题："没有 Finding 记录"和"Finding 被压缩掉了"在后续轮次中无法区分。

场景：Agent 在第 150 轮查看 TaskMemory，发现步骤 3 没有 Finding。它不知道这是"步骤 3 确实没有特别发现"还是"步骤 3 的结果在消息压缩中丢失了"。如果是后者，它可能需要重新执行步骤 3。

强制写入"无发现"消除了歧义——空白不是答案，"无发现"才是答案。

消费方式：模型在需要回顾过往发现时从 TaskMemory 读取。不是每轮都注入所有 Findings（那会占太多 token），而是按需获取。

真实案例：在我们的编程工具中，Findings 记录了每个被分析文件的关键特征——"auth.go 使用了自定义中间件而非标准库"、"config.go 有 12 个环境变量但只有 3 个有默认值"。这些发现在后续步骤（修改 auth 逻辑、添加默认值）中被引用。如果它们在消息压缩中丢失，模型在第 150 轮可能重新读取 auth.go 来"重新发现"已经发现过的信息——浪费 10+ 轮工具调用。

制品三：Decisions——方向选择的理由

Decisions 记录的是方向选择及其理由——不是"做了什么"（那是 Plan 更新），是"为什么选了 A 而不是 B"。

写入时机：Plan 调整时——追加步骤、跳过步骤、修改步骤方向时。每次写入包含：选了什么、备选是什么、选择理由。

为什么需要单独记录决策理由：

压缩中最容易丢失的信息就是理由。"选了 Repository 模式"可能在压缩后保留——但"因为已有 DAO 层可复用、Active Record 会要求修改所有调用方"这段理由几乎一定会被压缩掉。

理由丢失的后果比结论丢失更严重。 如果模型忘了"选了 Repository 模式"——它可能重新评估，做出同样的选择，浪费几轮但结果不变。如果模型忘了"为什么选了 Repository 模式"——它可能重新评估，这次选了 Active Record（因为看起来更简单），然后发现需要修改所有调用方，花 20 轮走弯路才回到 Repository 模式。

Decision 的存在是为了阻止模型重新做已经做过的决策。

行业对比：Claude Code 的 Task 系统有 description 字段，可以记录理由——但这是可选的，模型可以不写。没有"Decision 是必须单独记录的制品类型"的概念。LangGraph 的 State 可以存决策记录——但需要开发者自己定义 schema 和写入逻辑。

制品四：Checkpoints——里程碑确认

Checkpoints 标记"到这里为止的所有工作已确认完成"——是一个确认点。

与"步骤 done"的区别：步骤 done 是 Plan 级别的状态迁移（"步骤 3 完成了"）。Checkpoint 是更高层次的确认——"前三个步骤的工作已经过验证，可以作为后续步骤的基础"。

为什么需要 Checkpoint：在长任务中，如果 Run 中断（用户取消、超时、崩溃），恢复时需要知道"哪些工作是确定可靠的，哪些可能不完整"。

没有 Checkpoint 时，恢复后模型只知道"步骤 1-3 是 done"——但"done"可能是模型自己标的，没有经过验证。有了 Checkpoint，模型知道"步骤 1-3 不仅做了，而且在某个时间点被确认为可靠"。

消费方式：恢复 Run 时首先读取最近的 Checkpoint——从 Checkpoint 开始继续，而不是从头审查所有已完成的步骤。

真实案例：在企业场景中，法律合同审查的 Checkpoint 可能是"前 5 个条款已审查完毕，发现 2 个风险点"。如果审查过程被打断（部门主管有紧急电话），恢复时 Agent 从 Checkpoint 继续审查第 6 个条款——不需要重新审查前 5 个。

制品五：Learnings——元认知产出

Learnings 是整个任务完成后的经验提炼——不针对某一步，而是对整个任务过程的反思。

写入时机：任务结束时。这是唯一在任务结束后写入的制品——其他四种都在任务执行过程中写入。

与 Memory 系统的关系：Learnings 是从 TaskMemory 向长期记忆系统"晋升"的候选。一条 Learning（"这个代码库的 DAO 层普遍缺少参数化查询"）可能被写入持久记忆，在未来处理类似代码库时被召回。

但 Learnings 不自动晋升——它们是候选，需要通过记忆系统的质量门控（内容质量检查、重复检测、威胁扫描）才能成为持久记忆。

行业对比：Hermes Agent 的 curator 系统做了类似的事——跟踪 Agent 自建技能的使用频率，自动归档长期未使用的技能。但 Hermes 的 curator 操作的是"技能"（可复用的指令模板），不是"经验教训"（认知层面的知识）。

---

五种制品如何协作——一个完整的场景走查

用一个真实场景把五种制品的协作串起来。

任务：重构 15 个 DAO 文件到 Repository 模式。

第 1-5 轮：Planning Phase

模型分析代码库，产出 Plan：

Plan:
  Step 1: 分析现有 DAO 模式和依赖关系 [pending]
  Step 2: 设计 Repository 接口 [pending]
  Step 3: 迁移 UserDAO [pending]
  Step 4: 迁移 OrderDAO [pending]
  Step 5: 迁移 CacheDAO [pending]
  Step 6: 更新测试套件 [pending]

第 6-30 轮：执行步骤 1

模型读取所有 DAO 文件、分析依赖图。

Finding 1.1："15 个 DAO 中 12 个使用直接 SQL 拼接（无参数化查询），存在 SQL 注入风险" Finding 1.2："UserDAO 和 OrderDAO 共享一个 BaseDAO 基类，修改接口需要同时处理基类" Finding 1.3："CacheDAO 使用了自定义连接池，与其他 DAO 的连接管理不同"

步骤 1 标记 done。

第 31-50 轮：执行步骤 2

模型设计 Repository 接口。遇到方向选择——

Decision 2.1："选择 Repository 模式（而非 Active Record 模式）。理由：已有 BaseDAO 基类提供了接口抽象基础，Active Record 需要修改所有 15 个 DAO 的调用方（~200 处），Repository 模式只需修改 BaseDAO + 各 DAO 的实现。"

Decision 2.2："SQL 注入修复纳入各 DAO 迁移步骤（而非单独一步修复）。理由：每个 DAO 迁移时天然需要重写查询语句，参数化是重写的一部分，不增加额外工作量。"

步骤 2 标记 done。

第 51-80 轮：执行步骤 3（迁移 UserDAO）

大量 read/grep/edit/exec 操作。

Finding 3.1："UserDAO.findByEmail() 有一个隐藏的 admin 路径——当 email 参数以 'admin:' 开头时走不同的查询逻辑。迁移时必须保留此行为。"

步骤 3 标记 done。

Checkpoint 1："步骤 1-3 已完成并通过 go build 和 go test ./user/... 验证。Repository 接口定义 + UserDAO 迁移 + admin 路径保留均已确认。"

第 81 轮：压缩触发

对话消息被压缩。消息中的 30+ 次 read/grep/edit 细节被摘要为"分析并迁移了 UserDAO"。

但 TaskMemory 完好无损——Plan（6 步，3 步 done）、Findings（5 条）、Decisions（2 条）、Checkpoint（1 个）全部可用。

第 82 轮：模型读取 TaskMemory

注入的 TaskMemory 告诉模型：

• Plan：下一步是步骤 4（迁移 OrderDAO）
• Finding 1.2：UserDAO 和 OrderDAO 共享 BaseDAO，修改接口需同时处理——迁移 OrderDAO 时这条发现直接可用
• Decision 2.2：SQL 注入修复纳入各 DAO 迁移——迁移 OrderDAO 时同时参数化
• Checkpoint 1：步骤 1-3 已确认——不需要回头检查

如果没有 TaskMemory：模型看到压缩摘要"分析并迁移了 UserDAO"，不知道 BaseDAO 的共享关系，不知道 SQL 注入修复策略，不知道前三步已验证。它可能重新读取 UserDAO 来"确认"之前的工作——浪费 10+ 轮。

第 200 轮：任务完成

Learning 1："这个代码库的 DAO 层普遍缺少参数化查询（12/15 个 DAO）。未来遇到类似 Java 项目时，先用 grep 检查 SQL 拼接模式再开始重构。"

Learning 2："BaseDAO 基类的存在让 Repository 模式迁移比预期简单——接口抽象层已有。但 CacheDAO 的自定义连接池是意外的复杂度来源。"

这两条 Learning 被写入 TaskMemory。在认知结算（CognitiveSettlement）阶段，它们可能被提炼并晋升为持久记忆——在未来处理类似项目时被自动召回。

---

五种制品的设计选择对比

为什么不是一个通用 key-value store

LangGraph 的 State 是一个通用 dict——开发者自己定义 schema。这很灵活，但缺少约束。

我们选了预定义结构（五种制品）而非通用 store。原因：

1. 写入纪律需要类型约束："每步必须产出 Finding"这条规则需要 Finding 是一个明确的类型——通用 key-value 无法表达"这个 key 必须在每步写入"。
2. 消费方式不同：Plan 每轮注入，Findings 按需读取，Learnings 在任务结束时晋升——通用 store 的读取模式是"get by key"，不支持这种差异化消费。
3. 生命周期不同：Plan 和 Findings 是 Session 级的（Run 结束后保留供恢复），Learnings 可以晋升为永久记忆——通用 store 不区分生命周期。

为什么不用文件系统

Claude Code 的 Auto Memory 用文件系统（/memories 目录）。Anthropic Cookbook 的 Note-Taking 策略也推荐文件系统。

文件系统的优势是模型天然知道怎么读写文件（read 和 write 工具）。不需要专门的 TaskMemory 工具。

但文件系统的劣势是：

1. 结构化查询困难：查找"所有 Finding 中提到 SQL 注入的"需要 grep 整个目录——而数据库查询是 O(1)
2. 并发写入风险：多个工具调用可能同时写同一个文件——需要文件锁
3. 不是所有环境都有文件系统：SaaS 场景中 Agent 可能运行在无状态容器中

我们选了数据库存储（SQLite，随 Cell 级存储一起管理）。读写通过专门的 TaskMemory 工具，不依赖 read/write 文件工具。

为什么 Learnings 不自动写入持久记忆

一个诱人的设计是：任务结束时自动把 Learnings 写入持久记忆。省去了"晋升"这一步。

但自动写入有风险：

1. 质量不可控：模型在任务结束时匆忙总结的 Learning 可能不够准确——"DAO 层缺少参数化查询"是否真的是普遍规律？可能只是这个项目的特例
2. 重复和矛盾：不同任务可能产出矛盾的 Learnings——"用 Repository 模式"vs"用 Active Record 模式"。自动写入意味着持久记忆中有矛盾的知识
3. 内容安全：Learnings 可能包含敏感信息——SQL 注入漏洞的具体位置、admin 路径的实现细节。自动写入持久记忆意味着这些信息可能在未来的其他 Session 中被召回——可能不是用户期望的

Learnings 需要经过质量门控、重复检测、安全扫描之后才能成为持久记忆。 这就是我们有独立的记忆写入管线（而不是 TaskMemory 直接写 Memory Store）的原因。

---

与行业方案的对比

维度	我们的 TaskMemory	Claude Code Task 系统	LangGraph State	文件系统笔记
结构	五种预定义制品	subject + description + status	任意 key-value	非结构化文本
写入约束	Finding 每步必产出	无强制约束	无	无
压缩安全	物理解耦，不参与压缩	Session-scoped，但不参与 compaction	State 独立于 messages	文件天然不参与
持久化	Session 级 SQLite	Session-scoped（不跨 Session）	依赖 Checkpointer 配置	持久化在磁盘
恢复	Run 中断后完整可用	需 hydration pattern 恢复	依赖 Checkpointer	天然持久
晋升为长期记忆	Learnings 可选晋升	无此机制	无此机制	无此机制
可观测	每种制品有对应事件	TaskCreate/TaskUpdate 事件	依赖自定义日志	无

---

下一步：任务结束时怎么"做笔记"

五种制品解决了"任务过程中"的状态保持问题。但还有一个问题：任务结束后呢？

Plan 的步骤在任务完成后仍然有用（未来的 Session 可能引用过去的 Plan）。Findings 和 Decisions 是当前任务的上下文——可能对未来类似任务有参考价值。Learnings 是跨任务的经验。

TaskMemory 中积累的认知产物怎么变成持久知识？ 这就是"认知结算"（CognitiveSettlement）——Run 结束时 Agent 的"做笔记"环节，在"认知结算——Run 结束时 Agent 的做笔记"一章中详细展开。

---

你现在能做什么

1. 每步完成后强制写一条 Finding——即使是"无特别发现"。 在 prompt 中加："每完成一个 Plan 步骤，请在 findings.md 中追加一条记录，说明这一步发现了什么。如果没有特别发现，写'本步骤无特别发现'。" 这消除了"没有记录"和"记录被压缩掉了"的歧义。

2. Decision 记录"为什么选了 A"比记录"选了 A"重要 10 倍。 结论丢了可以重新推导——理由丢了，模型可能做出相反的选择然后走 20 轮弯路才发现。格式：选了 X（备选：Y, Z）。理由：X 有优势 P 和 Q，Y 的问题是 R。

3. 长任务中设 Checkpoint。 在关键步骤完成后（比如"前三个模块迁移完毕并测试通过"）写一条 Checkpoint。中断恢复时从 Checkpoint 继续——不需要从头审查所有已完成的工作。

4. 任务结束时让 Agent 总结经验。 在最后一个 prompt 加："任务完成了。请总结这次任务中学到的经验教训——哪些决策是对的、哪些走了弯路、下次类似任务有什么建议。写入 learnings.md。"这是手动版的认知结算。

---

引用来源

• Claude Code 官方文档, "Todo tracking / Migrate to Task tools" — Track todos - Claude Code Docs
• Spillwave Solutions, "Claude Code: Todos to Tasks" (Medium, 2026) — hydration pattern
• LangGraph StateGraph documentation — State key-value 模型
• Anthropic Claude Cookbook, "Context engineering" — Note-Taking 策略
• IBM Granite Agent Cookbook, "Context Management" — structured scratchpad
• hidekazu-konishi.com, "AI Agent Memory Design Guide" — 工作记忆与长期记忆的设计
• Hermes Agent AGENTS.md, "Curator (skill lifecycle)" — 经验管理的另一种形式