> ## 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.

# Classic 命令概览

> 使用稳定的 comet state、guard、handoff 和 archive 命令管理状态、阶段检查、交接与归档。

Comet 的 Classic 命令是五阶段工作流的运行时底座。日常使用和 Agent 自动化应优先调用稳定的顶层 CLI；同一套命令在 Windows、macOS 和 Linux 上行为一致，**不需要 Bash、Git Bash 或 WSL**。

```bash theme={null}
comet state <subcommand>
comet guard <change-name> <phase> [--apply]
comet handoff <change-name> [options]
comet archive <change-name> [--dry-run]
```

| 公开命令            | 职责                                     | 详细参考                                       |
| --------------- | -------------------------------------- | ------------------------------------------ |
| `comet state`   | 选择当前 change，读取/设置状态，记录命令证据并解析下一步       | [comet state](/zh/scripts/comet-state)     |
| `comet guard`   | 检查阶段条件；带 `--apply` 时通过合法 transition 推进 | [comet guard](/zh/scripts/comet-guard)     |
| `comet handoff` | 生成交接包或只计算 handoff hash                 | [comet handoff](/zh/scripts/comet-handoff) |
| `comet archive` | 完成最终确认后的 OpenSpec 合并与归档收尾              | [comet archive](/zh/scripts/comet-archive) |

## 内部 launcher 的兼容背景

0.3.x 时代，Comet 的状态、守卫、交接和归档逻辑由 7 个 Bash 脚本承担。这在 macOS 和 Linux 上工作良好，但 Windows 用户必须额外安装 Git Bash 或 WSL 才能跑完整工作流，路径转义和 shell 差异也常常带来隐患。

0.4.0-beta.1 把这些脚本迁移到 Node `.mjs` 运行时；当前发布形态是薄 launcher 加共享的生成 runtime，带来了三点变化：

| 方面   | 0.3.x（Bash）           | 0.4.0-beta.1（Node）                            |
| ---- | --------------------- | --------------------------------------------- |
| 运行依赖 | Bash / Git Bash / WSL | 仅 Node.js 20+                                 |
| 跨平台  | Windows 需要额外 shell    | Windows、macOS、Linux 同一套命令                     |
| 实现来源 | 散落的 shell 逻辑          | 薄 `.mjs` launcher + 生成的共享 `comet-runtime.mjs` |

公开/兼容 launcher 只导入同目录的 `comet-runtime.mjs` 并调用对应命令。共享 runtime 由 TypeScript 源码构建，并把运行依赖一起打包，因此不依赖项目自己的 `node_modules`；排障或复制安装资产时，launcher 与 `comet-runtime.mjs` 必须保持同一版本。

## 随包 launcher 一览

| 脚本                        | 职责                                                   | 详细参考                                       |
| ------------------------- | ---------------------------------------------------- | ------------------------------------------ |
| `comet-env.mjs`           | 脚本定位器：打印脚本目录绝对路径，是其他脚本的引导入口                          | —                                          |
| `comet-state.mjs`         | 读取、设置和转换 `.comet.yaml`，并解析下一步 Skill                  | [comet-state](/zh/scripts/comet-state)     |
| `comet-guard.mjs`         | 检查阶段条件；带 `--apply` 时校验通过后推进状态                        | [comet-guard](/zh/scripts/comet-guard)     |
| `comet-handoff.mjs`       | 生成阶段交接包（design context / spec projection）            | [comet-handoff](/zh/scripts/comet-handoff) |
| `comet-archive.mjs`       | 调用 OpenSpec archive 并完成归档收尾                          | [comet-archive](/zh/scripts/comet-archive) |
| `comet-yaml-validate.mjs` | 校验 `.comet.yaml` 字段、枚举和路径，是阶段检查的预检步骤                 | —                                          |
| `comet-hook-guard.mjs`    | PreToolUse 写入钩子，按当前阶段阻止越界源码写入                        | —                                          |
| `comet-intent.mjs`        | 解析 `/comet` 路由上下文，路由到 full / hotfix / tweak / resume | —                                          |

<Note>
  <code>comet-\*.mjs</code> 是随包分发的内部 launcher，保留给兼容和高级排障。普通用户与 Agent 应使用上面的稳定 CLI；多数用户只需要 <code>/comet</code>、<code>comet status</code> 和 <code>comet doctor</code>。
</Note>

## 兼容模式下如何定位 launcher

Skill 内会先定位 `comet-env.mjs`，再由它打印出脚本目录。这样做是为了**不把用户机器路径硬编码进提示词**——不同平台、不同安装范围的目录结构差异很大。

`comet-env.mjs` 是唯一的非打包启动器，它把目录里的反斜杠统一成正斜杠，保证路径能安全地插值进任何 shell，也能被 Windows 上的 Node 原样接受：

```bash theme={null}
# 引导：找到 comet-env.mjs 后运行一次
COMET_SCRIPTS_DIR="$(node "$COMET_ENV")"

# 从目录派生各个命令脚本
COMET_STATE="$COMET_SCRIPTS_DIR/comet-state.mjs"
COMET_GUARD="$COMET_SCRIPTS_DIR/comet-guard.mjs"
COMET_HANDOFF="$COMET_SCRIPTS_DIR/comet-handoff.mjs"
COMET_ARCHIVE="$COMET_SCRIPTS_DIR/comet-archive.mjs"
```

## 脚本如何协作

一次正常的阶段推进，背后是几个脚本的接力：

```mermaid theme={null}
flowchart LR
    A["YAML 状态预检"] --> B["comet guard<br/>检查阶段条件"]
    B -->|全部 PASS| C{"--apply?"}
    C -->|是| D["comet state transition<br/>推进状态 + 写审计"]
    C -->|否| E["仅报告就绪<br/>不改动状态"]
    D --> F["comet state next<br/>解析下一步 Skill"]
    H["comet-hook-guard<br/>PreToolUse 拦截越界写入"] -.守护.-> B
```

* **`comet guard` 先做 YAML 状态预检**；状态文件结构不合法时直接中止，不会继续检查阶段条件。
* **不带 `--apply`** 时，守卫只报告"是否就绪"，不改任何状态；带 `--apply` 时，校验全过后才会推进 `phase`。
* **`comet state transition` 和 `comet guard --apply` 共享同一份转移语义**，所以两条推进路径的行为一致。
* **`comet-hook-guard`** 作为 PreToolUse 钩子常驻，在 `open`/`design`/`archive` 阶段阻止源码写入，把"提前写实现"挡在发生之前。

## 关键命令与标志

下表汇总最常用的子命令和标志。完整语义见各脚本的专属页面。

| 命令              | 常用调用                                              | 说明                                                       |
| --------------- | ------------------------------------------------- | -------------------------------------------------------- |
| `comet state`   | `select <change>` / `current` / `clear-selection` | 多个 active change 时绑定、查看或清除当前工作目标                         |
| `comet state`   | `transition <change> <event>`                     | 触发状态事件，如 `open-complete`、`design-complete`、`verify-pass` |
| `comet state`   | `record-check <change> <build\|verify> ...`       | 记录真实执行的自定义项目命令与退出结果                                      |
| `comet state`   | `next <change>`                                   | 输出 `NEXT: auto\|manual\|done`、`SKILL:` 和提示               |
| `comet guard`   | `<change> <phase> [--apply]`                      | 检查阶段条件；`--apply` 只在全部通过后推进                               |
| `comet handoff` | `<change> design --write [--full]`                | 生成 compact 或完整交接包                                        |
| `comet handoff` | `<change> --hash-only`                            | 只输出上下文 sha256，不写文件                                       |
| `comet archive` | `<change> [--dry-run]`                            | 执行或预演归档                                                  |

<Warning>
  <code>COMET\_FORCE\_PHASE=1</code> 会绕过状态机的证据检查，只用于修复损坏的状态，不要当作常规推进手段。正常推进请用 <code>comet state transition</code> 或 <code>comet guard --apply</code>。
</Warning>

## 状态文件的三层拆分

0.4.0-beta.1 把每个 change 的状态从单一文件拆成了三份，各司其职：

| 文件                          | 归属    | 内容                                                      |
| --------------------------- | ----- | ------------------------------------------------------- |
| `.comet.yaml`               | 用户可读  | 工作流投影字段（`workflow`/`phase`/`build_mode` 等）+ `run_id` 链接 |
| `.comet/run-state.json`     | 机器管理  | 运行态检查点：当前步骤、迭代、待处理动作、快照引用                               |
| `.comet/state-events.jsonl` | 追加式审计 | 成功转移的完整记录：event、source、from/to 状态、字段 effects            |

* **`.comet.yaml` 保持 YAML 可读**，你可以直接看懂当前在哪个阶段；机器字段不再混在里面，避免手工误改。
* **`.comet/run-state.json`** 由运行时原子写入（临时文件 + 重命名），`comet state set` 会拒绝直接写其中的 machine-owned 字段。
* **`.comet/state-events.jsonl`** 只追加、不覆盖，由 `comet state transition`、`comet guard --apply` 和 `comet archive` 写入，给你一条可追溯的状态历史。

旧 change（Run 字段还嵌在 `.comet.yaml` 里）在首次读取时会自动迁移到拆分结构，无需手动处理。

## 在哪里能看到运行时证据

如果你想知道当前 change 走到了哪一步、状态是否健康，不必直接读这些脚本文件。优先用面向用户的命令：

```bash theme={null}
comet status     # 当前阶段、下一步命令、风险信号
comet doctor     # 版本、安装范围、畸形状态、缺失证据、恢复建议
comet dashboard  # 浏览器里可视化查看阶段进度、产物、任务、风险
```

`status` 和 `doctor` 走的是和脚本相同的运行时证据路径，所以它们报告的问题就是脚本实际会拦截的问题。