> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 恢复中断的工作

> 会话中断、上下文压缩或换设备后，用 /comet 按项目配置恢复 Native 或 Classic。

会话断了、上下文被压缩了、或者换了台设备——**正常情况下你只需要重新输入 `/comet`**。Comet 先读取项目根配置，进入 `/comet-native` 或 `/comet-classic`，再由对应工作流从自己的磁盘状态继续。两边不会扫描、猜测或转换另一侧的 change。

## 最短路径

在 Agent 平台里输入：

```text theme={null}
/comet 继续
```

就这样。Comet 不依赖对话历史：Native 重读 `.comet/config.yaml`、`<artifact-root>/comet/`、实现和验证证据；Classic 重读同一项目配置、OpenSpec、`.comet.yaml` 与运行证据。

<Tip>
  <strong>
    恢复不需要先跑 <code>comet status</code> 或 <code>comet doctor</code>。
  </strong>

  那两个是诊断命令，只在<strong>看起来有问题</strong>时才用（CLI/Skill 装坏了、change
  不路由、证据对不上）。正常恢复就是 <code>/comet</code> 一步到位。
</Tip>

## 也可以直接说“继续”

0.4.0-beta.4 起，`comet init` 和 `comet update` 会把一段 Comet 恢复说明合并进项目的 `AGENTS.md` 和 `CLAUDE.md`。长程任务经过上下文压缩、跨会话或跨设备继续时，Agent 可能已经忘记当前请求原本属于 Comet，而用户也未再次输入 `/comet`。此时 Agent 可以先运行只读的 `comet resume-probe`，判断“继续刚才的登录重构”是否对应现有 change，再决定是否重新进入工作流。

| 场景                               | 探测结果                             |
| -------------------------------- | -------------------------------- |
| 默认工作流只有一个明确目标，状态允许恢复             | 返回 `auto_resume`，进入对应永久入口        |
| 有多个候选、状态损坏或需要用户选择                | 返回 `ask_user`，只问一个问题             |
| 只是问问题、明确不走 Comet，或当前已在 Comet 流程内 | 返回 `out_of_scope`，不重复进入 workflow |
| 没有 active Comet change           | 返回 `none`，不执行恢复                  |

这段说明只约束 Comet 的恢复探测，并会保留文件中已有的用户规则。探针先解析配置，再只检查一套工作流；配置损坏时不会回退。`.comet/config.yaml` 中的 `ambient_resume: false` 可以关闭普通请求触发的探针。它不会影响显式 `/comet`，也不会绕过已有决策点。

详见[恢复探测命令](/zh/cli/resume-probe)。

## Native 如何恢复

<Note>
  这一节解释 <strong>后台原理</strong>：你输入 <code>/comet 继续</code> 之后，Native
  工作流内部是怎么从磁盘状态重建断点的。你不需要照着这里手动执行任何命令。
</Note>

Native 的所有阶段都从永久入口 `/comet-native` 恢复。入口先运行 `status` 和 `show`，读取 brief、完整目标规格、canonical spec、仓库实现和测试，再决定继续 Shape、Build、Verify 还是 Archive。未提交改动只是现场证据，不会单独阻塞恢复；模型仍必须保留无关改动。

`comet native next` 用于满足条件后的状态推进，不是 Ambient Resume 的入口。多个 Native changes 时，用户精确点名优先，其次使用有效 selection；否则探针要求选择，不根据请求内容猜 change。

## Classic 如何恢复

<Note>
  这一节同样是 <strong>后台原理</strong>：解释 <code>/comet-classic</code> 内部重读哪些文件、按什么规则路由到下一个阶段。你只需要输入 <code>/comet 继续</code>，下面的路由由 Comet 自动完成。
</Note>

`/comet-classic` 的恢复能力来自三个机制：

| 机制               | 说明                                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| **重读文件状态，不依赖对话** | 每次恢复都重新执行发现活跃 change + 读 `.comet.yaml`，不靠聊天历史猜阶段                                                                   |
| **文件状态优先，自愈元数据** | 如果 `.comet.yaml` 和实际文件冲突，以文件为准，Comet 自动修正 `.comet.yaml` 后继续                                                        |
| **按阶段确定性路由**     | 根据 `phase`/`workflow`/`verify_result` 等字段，路由到对应的阶段 Skill（含预设：build 阶段 hotfix→`/comet-hotfix`、tweak→`/comet-tweak`） |

恢复时的路由（命中即停，以文件状态为准）：

| 当前状态                                   | `/comet-classic` 路由到                                         |
| -------------------------------------- | ------------------------------------------------------------ |
| `archived: true`                       | 流程已完成                                                        |
| `verify_result: pass`                  | `/comet-archive`（先做归档前确认）                                    |
| `verify_result: fail`                  | 验证失败决策阻塞点（等你选修复或接受偏差）                                        |
| `phase: verify` 或 tasks 全勾             | `/comet-verify`                                              |
| `phase: build`                         | 按 workflow：`/comet-hotfix` / `/comet-tweak` / `/comet-build` |
| `phase: design` 或有 change 无 Design Doc | `/comet-design`                                              |
| `phase: open` 或 `.comet.yaml` 缺失       | `/comet-open`                                                |
| 无活跃 change                             | `/comet-open`                                                |

只要有**一个**活跃 Classic change，`/comet-classic` 会自动选中它；有**多个**时列出清单让你选一个。

如果通过自然语言恢复，多个 active change 不会被自动猜测；恢复探测会返回 `ask_user`，等待你点名目标。

## 换设备/换平台也能恢复

状态完全保存在仓库文件里：两边共享 `.comet/config.yaml`；Native change 使用 `<artifact-root>/comet/` 与 `comet-state.yaml`，Classic change 使用 `.comet.yaml`、OpenSpec 和 `docs/superpowers/`。所以在另一台设备或另一个 Agent 平台打开同一个仓库，`/comet` 能从对应文件恢复。

<Note>
  唯一的注意点：未提交的工作区改动不会跟着 <code>git push</code> 走。跨设备前先把改动 commit
  推上去，否则新设备上会是干净工作区的恢复（<code>tasks.md</code> 的勾选状态仍然有效）。
</Note>

### 跨设备 0 上下文断点恢复现场

下图展示了跨设备、0 上下文的断点恢复现场——不管在哪台设备、哪个平台，只要仓库一致，`/comet` 就能从文件状态重建断点继续，无需任何额外操作或上下文传递：

<img src="https://mintcdn.com/comet-bb5f5294/KBFveG8M9gQs8AYV/img/comet-zero-resume.png?fit=max&auto=format&n=KBFveG8M9gQs8AYV&q=85&s=1aa375368a7fa413293f89df0213b7f5" alt="跨设备 0 上下文断点恢复现场" width="2398" height="1565" data-path="img/comet-zero-resume.png" />

## 上下文压缩后怎么办

如果 Classic change 所在的 Agent 平台自动压缩了上下文，重新输入 `/comet`。项目配置会再次进入 Classic，内部 `/comet-classic` 按恢复协议重载状态；必要时读取 `brainstorm-summary.md`、handoff 交接包和 `.comet/subagent-progress.md`。你不需要手动操作这些文件。

## 从任意阶段入口恢复

Classic 正常恢复使用 `/comet`。阶段和预设入口只用于手动控制或调试：`/comet-open`、`/comet-design`、`/comet-build`、`/comet-verify`、`/comet-archive`、`/comet-hotfix`、`/comet-tweak`。

这是 0.4.0-beta.1 渐进式加载带来的确定性保证：每个子 Skill 进入时都会先通过 `comet/reference/scripts.md` 定位脚本，然后跑自己那个阶段的**入口检查或恢复检查**，而不是从对话历史推断阶段。

```bash theme={null}
comet state check <change-name> <phase> --recover
```

* 如果检查发现实际的 phase、workflow 或证据属于**另一个** Skill，按脚本输出和 `/comet-classic` 路由规则切换——**不要在错误的阶段里继续写状态**。
* 如果工作树有未提交改动，先用 `comet/reference/dirty-worktree.md` 的规则归因。

```mermaid theme={null}
flowchart TD
    A["直接调 /comet-build 等任意入口"] --> B["定位脚本 scripts.md"]
    B --> C["跑该阶段入口/恢复检查 --recover"]
    C --> D{"实际阶段匹配?"}
    D -->|是| E["在当前阶段继续"]
    D -->|否| F["按脚本输出切换到正确 Skill"]
    F --> G["不在错误阶段写状态"]
```

<Tip>
  这条规则让你在 <strong>已知自己在哪个阶段</strong> 时跳过统一入口和 Classic 内部路由，
  的路由开销直接干活，同时保证即使记错了阶段也不会把状态写坏——入口检查会拦住不匹配的进入。
</Tip>

## build 阶段恢复的特殊情况

build 阶段的恢复最复杂，但大多数情况 `/comet-classic` 也能自动处理：

| 情况                                                                | 行为                                           |
| ----------------------------------------------------------------- | -------------------------------------------- |
| `build_pause: plan-ready` 但 `isolation`/`build_mode` 已设           | **自动清除** stale pause，继续执行（你无需操作）             |
| `build_pause: plan-ready` 且 plan 存在，但 `isolation`/`build_mode` 未设 | 回到 plan-ready 恢复点，**让你选**隔离和执行方式（不重新生成 plan） |
| `build_pause: plan-ready` 但 plan 文件缺失                             | 状态损坏，回 `/comet-build` 修复或重新生成 plan           |
| `isolation`/`build_mode`/`tdd_mode` 未设                            | 回 `/comet-build` 对应步骤**让你补选**                |
| 都已设，有未完成任务                                                        | 读 tasks.md 下一个未勾选任务继续执行                      |

subagent 模式（`build_mode: subagent-driven-development`）恢复时，主会话**不会**直接执行任务——它会回到后台子代理调度规则，由主会话只做协调。

## 有未提交改动时

如果工作区有未提交改动，Comet 会自动做**归因**，不需要你先解释改了什么：

* 改动属于当前 change → 折叠进去继续
* 和当前 change 无关 → 暂停问你怎么处理（并入 / 拆新 change / 保留 / 丢弃）
* 来源不确定 → 暂停汇报文件列表和判断依据

构建产物（`node_modules/`、`dist/` 等 `.gitignore` 的）会自动排除，不当用户改动。

<Warning>
  dirty worktree 只代表代码事实，<strong>不会自动推进</strong> <code>.comet.yaml</code> 的{' '}
  <code>phase</code> 或勾选 <code>tasks.md</code>——只有完成归因、验证、过阶段 guard 后才推进状态。
</Warning>

## 真正需要你介入的情况

`/comet-classic` 能自动推进无歧义的衔接，但**决策点**必须等你明确选择。恢复时常见的需要你介入的情况：

* **验证失败**（`verify_result: fail`）——你要决定修复还是接受偏差
* **真正的 plan-ready 暂停**——你要选隔离和执行方式
* **build 决策缺失**——你要补选 `isolation`/`build_mode`/`tdd_mode`
* **无法归因的未提交改动**——你要说明改动归属
* **多个活跃 change**——你要选恢复哪个
* 其余是各阶段固有的停顿点（见[五阶段停顿点](/zh/concepts/decision-points)）

这些之外，`/comet-classic` 都会自己往前走。

## 什么时候才用 comet status / comet doctor

这两个是**诊断工具**，不是恢复的必经步骤：

| 命令             | 什么时候用                                                           |
| -------------- | --------------------------------------------------------------- |
| `comet status` | 想看"我在哪个阶段、声明的产物是否都还在"——`/comet-classic` 路由不对、或证据对不上时            |
| `comet doctor` | 环境或安装出问题——CLI/Skill 缺失、`.comet.yaml` 格式坏掉、`/comet-classic` 起不来时 |

```bash theme={null}
comet status        # 看活跃 change 的 phase/任务/runtime_eval
comet doctor        # 诊断安装、环境、Skill 完整性
```

`runtime_eval` 会告诉你声明的步骤证据是否真在磁盘上——失败时会提示 `run <命令> or restore missing evidence`。

## 下一步

* [恢复探测命令](/zh/cli/resume-probe) — 了解自然语言恢复前的只读探测
* [状态损坏与恢复](/zh/guides/state-recovery) — `/comet-classic` 路由不对或状态坏了怎么办
* [项目文件结构](/zh/guides/project-structure) — 状态都存在哪些文件里
* [自动推进机制](/zh/concepts/auto-transition) — 恢复后的自动衔接
* [五阶段停顿点和用户选择点](/zh/concepts/decision-points) — 哪些地方需要你介入