Skip to main content
Native 的恢复依据是项目配置、正式产物和 Runtime 状态,不是聊天记录。遇到中断或错误时,先做只读诊断,再运行 Runtime 返回的具体恢复动作;不要手工改 phase、hash、journal 或 selection 来绕过检查。

标准诊断顺序

建议按以下顺序判断:
  1. .comet/config.yaml 中启用的 workflow、native.artifact_rootnative.clarification_mode 是否正确;
  2. comet native status 是否能看到目标 change;
  3. .comet/current-change.json 是否选择了正确 workflow/change;
  4. status --details 返回的 phase、findings、checkpoint、acceptance page 和 continuation;
  5. doctor 是否报告未完成事务、陈旧锁、workspace 身份或证据清理问题。
findings 被截断时,先处理已返回项,再重新读取 details。acceptancePage.nextCursor 非空时,使用 --acceptance-cursor 逐页获取;不要把当前页面之外的验收项当作不存在。

跨设备找不到 change

Native 只从配置的 artifact root 发现 change。同步了 docs/comet/changes/...,但另一台设备的 .comet/config.yaml 缺失、仍指向 . 或启用了另一套默认 workflow 时,resume-probe 会正确返回“没有可恢复 change”。change 自己的 comet-state.yaml 不会反向选择项目根目录。 处理步骤:
  1. 确认已同步的真实目录,例如 docs/comet/changes/<name>
  2. 在目标设备通过 comet init --workflow native --root docs 恢复匹配的项目配置和托管资产,或恢复可信的 .comet/config.yaml
  3. 运行 comet native statusshow
  4. 目标无歧义后运行 comet native select <change-name>
  5. 再从 /comet/comet-native 继续。
不要为同一需求新建第二个 change,也不要把产物复制到另一个根目录制造两份可写状态。

未完成 transition

普通 phase 推进会先写 runtime/transition.json,再更新 Run state、comet-state.yaml、trajectory 和 checkpoint。中断后,status 与 doctor 会报告 recovery required。 普通 transition 只支持继续:
journal 畸形或状态两端无法证明一致时,Runtime 会保留文件并停止。此时先备份现场并检查错误,不要手工拼接状态。

Archive 与 root move 中断

Archive 和 artifact root move 是多步骤事务。doctor 会根据 journal 所处阶段说明能否 continuerollback
Archive 写入最终完成标记后已经越过不可回滚边界,只能继续收口。Root move 只有在源、staging、目标与 quarantine 的身份和 hash 能够证明时才会继续或回滚;两棵树不一致时不会删除任意一侧。 如果 .comet/config.yaml 中出现 native.pending_root_move,先运行 doctor。不要手工删除该字段或直接移动目录。

Baseline 或验证证据异常

锁与 evidence retention

普通 newnextarchiveroot move 不会自动接管看似超时的锁。只有显式 doctor --repair 会在本机 owner 已不存在、锁身份未变化且没有冲突事务时接管。活动锁或无法证明来源的锁保持不动。 Evidence retention 默认只报告候选。显式 repair 仅清理 active change 中至少 30 天、每种 evidence kind 最新 32 份之外且依赖闭包证明未引用的派生证据;归档证据、当前引用、未知文件和恢复中的事务不会被清理。

保存状态变化前的快照

如果审计或交接要求保留某次 transition 前的 Runtime 返回,应在状态变化前第一次调用时就使用机器可读模式,并把 stdout 直接保存到目标文件:
确认文件完整后不要在 transition 之后重建或覆盖。该快照只证明生成时 Runtime 实际返回的状态,不代表后续状态。 继续阅读:连续推进与 CheckpointNative 安全与恢复Native CLI
最后修改于 2026年7月22日