崩溃恢复：一个 Manifest 文件让你不用从头开始

一次多代理代码库分析需要 45 分钟。协调器已完成 5 个阶段中的 3 个。进程崩溃了。没有恢复机制，你从头重来——浪费 30 分钟已完成的工作。

这比团队预期的更常发生。在一个系统中，23% 的运行至少崩溃过一次。解决方案不是消除崩溃（虽然那也有用），而是让崩溃变便宜：持久化足够的状态来从断点恢复。

为什么内存状态不够

Claude API 是无状态的。没有服务端会话。对话历史活在你的客户端进程中。当进程挂掉——OOM、网络超时、未捕获异常——内存中的一切都跟着没了。协调器的进度、子代理的发现、整个分析上下文：全没了。

这是长时间运行的多代理系统的根本反模式：完全依赖内存中的对话状态而不把进度持久化到磁盘。5 分钟的任务重启得起。45 分钟的重启不起。

Manifest 方案

Manifest 文件是一个轻量级状态检查点，协调器在每个主要任务或阶段完成后写入。它记录：

• 当前阶段 — 在整体工作流中的位置
• 已完成任务 — 哪些任务成功完成了
• 待办任务 — 哪些任务还剩
• Scratchpad 引用 — 包含详细发现的文件路径

重启时，协调器加载 manifest，把恢复的状态注入代理 prompt，从最后一个检查点恢复。已完成的工作不重做。系统直接跳到崩溃点。

{
  "phase": 3,
  "completed": ["dependency_scan", "vulnerability_check", "license_audit"],
  "pending": ["performance_profile", "final_report"],
  "scratchpad_files": [
    "findings/dependencies.md",
    "findings/vulnerabilities.md",
    "findings/licenses.md"
  ],
  "last_updated": "2026-03-27T14:32:00Z"
}

这不是复杂基础设施。就是一个 JSON 文件，每个阶段完成后写入，启动时读取。几行代码就提供了恢复机制。

Manifest 必须包含什么

常见错误是只保存任务状态——哪些做完了哪些待做——而不引用已完成任务的发现。

一个团队恰好这么做了。崩溃重启后，协调器知道任务 1-3 完成了、应该从任务 4 开始。但它无法访问任务 1-3 到底发现了什么。结果：恢复后的代理用”典型模式”这种模糊引用代替了崩溃前找到的具体类名和行号。

修复是在 manifest 中包含 scratchpad 文件路径。因为子代理通常已经把发现写到 scratchpad 文件了（K5.4.2 的最佳实践），manifest 只需要指向这些文件。恢复时，协调器加载 manifest，读取引用的 scratchpad 文件，同时拥有进度状态和详细发现。

没有发现引用：代理知道在哪里停的但不知道学到了什么。 有发现引用：代理带着完整上下文恢复。

保持 Manifest 最新

过时的 manifest 几乎和没有 manifest 一样糟。一个团队在运行开始时写了一次 manifest 然后再也没更新。后续任务崩溃时，manifest 指向空状态——恢复从头开始，因为 manifest 说什么都没完成。

一个部署了 manifest 恢复但有一次过时 manifest 故障的团队的指标：

那一次恢复失败就是过时 manifest 造成的。修复：每个任务完成后更新 manifest，不是按计划也不只在启动时。写一个小 JSON 文件的开销可以忽略不计。

什么不该保存

不是完整对话历史。 有工程师提议每次 API 调用后保存完整对话。算一下就知道不行：运行中的对话达到 100K+ token，每次分析 40+ 次 API 调用，就是每次运行 400 万 token 的 I/O。更糟的是恢复时完整对话可能超出上下文窗口，产出退化的质量。Manifest 方案轻了几个数量级。

不是重放日志。 记录每次工具调用并从头重放来重建状态，重做的是所有已完成的工作。如果目标是避免重启，从头重放整个会话什么也没实现。

不是分布式事务系统。 两阶段提交、预写日志、分布式共识——这些适合处理并发写入和一致性保证的数据库。一个顺序多代理流水线需要的是一个每阶段更新的 JSON 文件，不是企业级基础设施。

合适的工程度

多代理系统的崩溃恢复在复杂度谱上有一个具体位置：

Manifest 方案以最小的实现成本提供了绝大部分恢复价值。一个团队可以用一个 JSON 文件和几个读写调用从零恢复能力到有效的崩溃韧性。

与更广泛上下文策略的集成

Manifest 不是独立的。它建立在同样驱动 scratchpad 文件和子代理输出的基于文件的持久化之上：

• Scratchpad 文件 在发现时保存它们（K5.4.2）
• 子代理委派 隔离原始数据并返回摘要（K5.4.3）
• Manifest 把这些串在一起，记录哪些阶段完成了以及发现存在哪里

恢复时，协调器加载 manifest，读取引用的 scratchpad 文件，重建足够的上下文继续。不重复任何工作。对话是新的，但知识被保留了。

一句话总结： 每个阶段完成后写一个 manifest 文件——记录任务状态和 scratchpad 路径——这样一次崩溃只损失一个阶段的工作，不是整个运行。