OpenRig快照与恢复机制源码剖析：resumed、fresh、failed三态诚实报告指南

【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrig

OpenRig 是一个帮你把 Claude Code、Codex 等 AI 编码代理组织成持久化团队的管理框架，其核心亮点之一是快照与恢复机制：当 rig（代理团队）停机或崩溃后重新启动时，OpenRig 会为每个席位（seat）诚实报告三种结果——resumed（原会话恢复成功）、fresh（全新启动）、failed（真实失败），绝不把失败伪装成成功。本文带你读懂这套三态诚实报告背后的源码设计。

为什么需要"诚实的"恢复报告？

想象一下：你部署了一个 6 个代理的 rig，隔夜重启后它报告"全部恢复成功"——但实际上有 3 个代理是白纸状态。这种虚假乐观在多代理系统里是致命的，因为下游代理会基于"前辈的工作还在"的错误假设继续干活。

OpenRig 的设计原则是宁可信其有失败，不可谎报成功。源码中有一段非常典型的注释体现了这一点（restore-orchestrator.ts）：

恢复/启动状态为awaiting-decision、attention_required、failed时，意味着没有任何会话在运行，CLI 和启动 API 不得将这些状态报告为"启动成功"。

三态词汇表：不只是三种

虽然标题说的是 resumed、fresh、failed 三态，但源码中实际是一套更精细的五词恢复词汇（types.ts），每种状态都有严格语义：

关键约束：awaiting-decision状态永远不会在会话存活时被发出；failed也只留给真实的 harness 错误，而不是"恢复不理想"的兜底。这种"一态一义"的设计，就是诚实报告的技术基础。

恢复编排器：三态如何被判定

整个恢复流程由RestoreOrchestrator编排（restore-orchestrator.ts），它的判定管线大致分四步：

1. 快照选取：从 snapshot-repository 与 checkpoint store 中找到可用快照，校验 rig 身份、会话归属（active-occupant.ts中的"四层活跃占用者阶梯"专门处理同一席位多会话的歧义）。
2. 逐节点恢复：对每个 seat 调用对应运行时适配器（claude-resume.ts、codex-resume.ts 等）尝试--resume原会话。
3. 启动后探测：恢复不等于信任。assessNativeResumeProbe（native-resume-probe.ts）会在启动后主动探测终端窗格，只有当探测结果确认resumed时才标记成功——探测失败绝不悄悄降级。
4. 结果汇总：rollupRestoreRigResult把节点级三态汇总为 rig 级结论（restore-orchestrator.ts）：

resumed 全部成功 → fully_restored 出现 fresh/failed 混合 → partially_restored 全部 failed → failed

注意partially_restored这个中间态本身就是诚实的产物——它告诉你"一部分是真的，一部分不是"，而不是给你一个笼统的成功/失败。

每次恢复都留"收据"

诚实报告的另一半是可审计性。每次恢复尝试都会写入一份"恢复尝试收据"（restore-attempt-receipt.ts），记录用了哪个 resume token、终端窗格证据、进程血缘校验结果。

其中还有一个有意思的operator_recovered终态：当会话卡在failed或attention_required时，操作者手动干预修复后，系统会做一次"运行时真相核对"（reconcileNodeRuntimeTruth），要求四项证据全部成立（tmux 会话存在、前台进程是运行时、resume token 被使用、窗格可用）才允许把状态升级为operator_recovered——任何一项缺失都只是记原因，而不是报错。

快照侧的"原子发射"设计

快照不只是存个数据库记录。CLI 端的恢复包生成器（restore-packet 目录，核心在 packet-writer.ts）采用先写临时目录再原子重命名的策略：

• 4 个必需文件（恢复说明、最新转录、触碰文件清单、恢复摘要 JSON）+ 可选完整转录；
• 摘要先通过内嵌 JSON Schema 校验，校验通过才重命名，失败则清理临时目录，目标目录绝不会出现"半成品"。

这与三态报告的理念一脉相承：要么完整可信，要么明确失败，没有中间灰色地带。

快速上手：观察三态报告

在仓库根目录安装依赖后，你可以用演示 rig 体验恢复流程：

cd demo ./run.sh # 停止 rig 后重新启动，观察输出中的状态词

演示环境定义在 demo/rig.yaml 与各角色的 agent.yaml 中。启动后可用rig ps查看每个席位的restoreOutcome列，直观看到 resumed / fresh / failed 的分布。

总结：诚实是架构特征，不是文案

OpenRig 快照与恢复机制值得借鉴的三点：

• 一态一义：五词词汇表让每个状态有唯一解释，杜绝"成功"的模糊定义；
• 证据先于结论：启动后探测 + 进程血缘 + 窗格状态，多路证据交叉验证才敢报resumed；
• 全程留痕：恢复收据让每个三态结论都可以事后审计。

对于构建多代理系统的团队来说，这套"三态诚实报告"模式比"99% 恢复率"之类的指标更可靠——因为它保证你在任何时刻看到的报告，都可以被逐条追问"证据呢？"。

【免费下载链接】openrigBuild your own network of agents from Claude Code, Codex and Pi: persistent teams with roles, shared context and owned work.项目地址: https://gitcode.com/GitHub_Trending/op/openrig