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/openrigOpenRig 是一个帮你把 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每种状态都有严格语义状态含义是否有会话在运行resumed原会话被真实恢复✅ 是fresh/fresh-primed刻意从零启动策略或--fresh驱动✅ 是awaiting-decision原会话无法恢复且未指定--fresh停止零会话运行等待操作者抉择❌ 否attention_required会话存活但卡在运行时提示如 Claude 的恢复选择提示上✅ 是需人工failed仅用于真正的 harness 错误❌ 否关键约束awaiting-decision状态永远不会在会话存活时被发出failed也只留给真实的 harness 错误而不是恢复不理想的兜底。这种一态一义的设计就是诚实报告的技术基础。恢复编排器三态如何被判定整个恢复流程由RestoreOrchestrator编排restore-orchestrator.ts它的判定管线大致分四步快照选取从 snapshot-repository 与 checkpoint store 中找到可用快照校验 rig 身份、会话归属active-occupant.ts中的四层活跃占用者阶梯专门处理同一席位多会话的歧义。逐节点恢复对每个 seat 调用对应运行时适配器claude-resume.ts、codex-resume.ts 等尝试--resume原会话。启动后探测恢复不等于信任。assessNativeResumeProbenative-resume-probe.ts会在启动后主动探测终端窗格只有当探测结果确认resumed时才标记成功——探测失败绝不悄悄降级。结果汇总rollupRestoreRigResult把节点级三态汇总为 rig 级结论restore-orchestrator.tsresumed 全部成功 → 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考