Skip to main content
Native 会自动恢复大多数中断。它保留仓库中能够证明的需求、实现进度和验收结果，只重新执行已经丢失的本机过程或验证证据。你可以直接继续原来的 Change，Runtime 会读取当前状态、检查工作目录，并返回安全的下一步。 恢复依据来自项目文件。brief.md、目标 Specs、comet-state.yaml 和 verification.md 记录任务已经确认和完成的内容；.comet/runtime/native/ 保存当前设备上的执行过程，可以在需要时重建。

​
自动恢复机制

每次继续 Change 时，Native 都会对照仓库状态和本机执行记录：
  1. 找到 Change 实际所在的分支或 worktree；
  2. 读取最近一次完整写入的 comet-state.yaml；
  3. 检查正在运行的任务、测试或 Verifier 是否已经中断；
  4. 重建缺失或过期的本机执行记录；
  5. 根据现有证据继续当前阶段，或回到需要重新验证的位置。
Shape 和 Build 的本机记录丢失时，Native 会在原阶段继续，已经确认的需求和验收项保持不变。Verify 或 Archive 依赖本机执行证据，相关记录丢失时会重新验证当前实现。

​
会话中断恢复

关闭终端、Agent 会话结束或进程意外退出后，Native 会把仍在运行的本机任务标记为中断，再判断哪些步骤可以安全重试。 恢复造成的重新验证归入执行恢复，实现失败和连续无进展计数保持不变。实际启动新的 Verifier 时，Verifier 尝试次数会正常增加。

​
跨设备继续

换设备前，先同步以下内容：
  • 项目代码；
  • Change 中的 brief.md、目标 Specs 和 comet-state.yaml；
  • 已经生成的 verification.md；
  • 使用自定义产物目录时对应的 .comet/config.yaml。
新设备打开同一仓库后，Native 会根据这些文件重建本机执行记录。旧进程、Agent 会话和 Subagent 任务停留在原设备；新设备从仓库中可核实的状态创建新的执行任务。 已经完成的 Shape 和 Build 会保留。Change 正在 Verify，或已经等待 Archive 时，新设备会重新验证同步后的代码。恢复期间，验收失败次数、实现失败次数和无进展计数保持不变。 旧设备上尚未同步的代码无法从 Change 状态中还原。同步后的实现不满足验收项时，新的 Verifier 会指出未满足的部分，并把 Change 返回 Build。

​
工作区恢复

Native 会扫描 Git 已登记的 worktree，优先选择与 Change 分支绑定一致的工作目录。即使你从仓库主目录开始，Runtime 也能找到 Change 实际所在的位置，并让 Agent 在该目录继续。 当前分支、worktree 类型或项目根与 Change 记录不一致时，Runtime 会暂停写入并返回预期目录。原目录仍然存在时，Agent 会切换到正确位置；worktree 已移除但分支仍然有效时，Native 可以重建 worktree。 以下情况需要你确认工作区：
  • 原分支已重命名或被其他工作接管；
  • 存在多个同样匹配的工作目录；
  • 原目录和分支已经丢失；
  • 同一份 Change 状态在两个位置出现不同版本。
你可以选择可信目录、从备份恢复，或停止该 Change。Runtime 会保留现有文件，等待明确决定。

​
Archive 事务恢复

Archive 会依次更新正式 Spec、最终状态和验证报告，再把 Change 移入归档目录。Runtime 使用事务记录每一步，因此进程在中途退出后，可以从已经完成的步骤继续。 再次继续同一个 Archive 时，Native 会检查事务和实际文件：
  • 事务与文件一致时，从下一步继续；
  • Change 已归档、工作区收尾失败时，保留归档结果，并返回 Git 恢复动作；
  • active 和 archive 目录同时存在时，保留两侧内容并等待诊断；
  • 多个 Change 修改同一份 Spec 时，等待你确定归档顺序。
工作区收尾失败发生在 Archive 之后，Change 可能已经完成归档或 Git 提交。此时按照返回的 recoveryArgs 检查实际 Git 状态，再继续 merge、push 或 PR 流程。

​
验证报告恢复

verification.md 把 comet-state.yaml 里的验收结论整理成可读报告。报告缺失、写入中断或版本落后时，Native 会根据当前状态重新生成。 报告文件丢失，但状态和本机执行记录仍能证明验证已经通过时，恢复只重建报告。Archive 前的本机执行记录也丢失时，Native 会返回 Verify，重新取得完整验收证据。 这一区分可以保留已经证明的结果，同时确保 Archive 使用当前设备和当前代码上可信的证据。

​
需要用户处理的情况

Native 会在自动判断可能造成错误覆盖、重复副作用或错误归档时暂停。常见情况如下： await-user 表示下一步需要你的选择；blocked 表示当前状态缺少安全推进路径。Runtime 会同时返回原因、负责处理的一方和允许执行的动作。

​
状态查看与诊断

正常恢复由 Native 自动完成。你想查看当前记录或排查阻塞时，可以运行：
show 和 status 展示正式产物、工作区、验收进度和下一步。doctor 检查迁移、事务、目录和状态一致性。doctor --repair 只用于诊断结果明确提供修复动作的情况。 恢复过程中，让 Runtime 管理 comet-state.yaml、本机执行记录、锁和事务。按照 continuation、recoveryArgs 或 doctor 返回的动作继续，可以保留已经确认的进度和故障现场。 继续阅读：任务推进与中断恢复、Native 安全边界、多 Change 并行与冲突控制 和 产物与状态。
最后修改于 2026年9月4日