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

# Native 命令概览

> Native 工作流的命令清单：创建变更、查看状态、保存进度、推进阶段、验证和归档。

`comet native` 是 Native 工作流的命令入口。Native 工作流把一次需求拆成 Shape、Build、Verify、Archive 四个阶段，这些命令负责创建和管理每次变更、推进阶段、保存进度和归档。

大多数用户不需要直接敲这些命令——在 Agent 平台里输入 `/comet` 时，Skill 会自动调用它们。这一页帮你了解每条命令在做什么，以及排障或自动化时怎么用。

## 命令一览

| 命令                           | 做什么               |
| ---------------------------- | ----------------- |
| `comet native new`           | 创建一次新的变更          |
| `comet native status`        | 看当前变更走到哪一步        |
| `comet native show`          | 看某次变更的需求和规格       |
| `comet native select`        | 多个变更并存时，指定当前要处理哪个 |
| `comet native checkpoint`    | 在阶段中途保存进度         |
| `comet native check`         | 跑 Comet 内置的只读检查   |
| `comet native receipt`       | 记录一次验证步骤的结果       |
| `comet native next`          | 推进到下一个阶段          |
| `comet native archive`       | 把完成的变更归档          |
| `comet native doctor`        | 诊断和修复状态问题         |
| `comet native init` / `root` | 配置 Native 的产物目录   |

所有命令都支持 `--json`，输出结构化结果，方便脚本和 CI 解析。

## 创建和查看变更

开始一次新需求时创建变更。`new` 会建立变更目录、捕获项目当前文件快照，并把它选为当前变更：

```bash theme={null}
comet native new add-user-avatar
```

想看现在进展到哪了：

```bash theme={null}
comet native status                  # 所有活跃变更的列表
comet native status add-user-avatar  # 某个变更的当前阶段和下一步
```

`status` 不带变更名时列出全部活跃变更；带上变更名时显示它的阶段、验证状态和恢复建议。加 `--details` 可以看更详细的检查项和验收进度。

`show` 用来读某次变更里写下的需求和目标规格：

```bash theme={null}
comet native show add-user-avatar
```

## 保存进度

一次变更可能要分多轮才能做完。`checkpoint` 在不推进阶段的前提下，保存你目前做了什么、下一步该做什么，以及产生了哪些文件：

```bash theme={null}
comet native checkpoint add-user-avatar \
  --summary "完成了头像上传接口" \
  --next-action "处理前端裁剪和压缩"
```

会话中断后，从 `status` 返回的进度继续，而不是依赖聊天记录。

## 检查和验证

`check` 跑 Comet 内置的只读检查，看代码是否满足这次变更的目标规格。它不调用你的测试命令、不改任何文件，只在 Verify 阶段给出一份检查报告：

```bash theme={null}
comet native check add-user-avatar
```

`receipt` 用来记录一次具体的验证动作。分两种：`manual` 记录你手工执行的步骤和观察；`automated` 记录一条真实命令及其退出结果：

```bash theme={null}
# 记录手动验证
comet native receipt manual add-user-avatar \
  --acceptance upload-returns-url \
  --step "上传 2MB 图片" \
  --observation "返回了 CDN 地址"

# 记录自动验证（运行真实命令并捕获结果）
comet native receipt automated add-user-avatar \
  --acceptance upload-returns-url \
  -- npm test
```

## 推进阶段

`next` 把变更推进到下一个阶段。它会校验当前阶段的证据是否齐全，齐全才放行：

```bash theme={null}
comet native next add-user-avatar --summary "需求已澄清，目标规格完整"
```

Native 的四个阶段这样推进：

| 当前阶段       | 推进需要                  | 推进结果        |
| ---------- | --------------------- | ----------- |
| Shape      | 需求清晰、目标规格完整           | 进入 Build    |
| Build      | 产出了真实代码，或说明了不需要改代码的原因 | 进入 Verify   |
| Verify     | 验证报告通过                | 进入 Archive  |
| Verify 未通过 | —                     | 退回 Build 修复 |

验证失败会自动退回 Build，并把没通过的检查项告诉你，修完再重新验证。

## 归档

变更完成后用 `archive` 归档。归档分两步，先预演确认没有冲突，再正式提交：

```bash theme={null}
# 第一步：预演，拿到一个 hash
comet native archive add-user-avatar --dry-run

# 第二步：用这个 hash 正式归档
comet native archive add-user-avatar --expect-preflight <上一步的hash>
```

归档会把这次变更的目标规格合并进项目，并把变更产物收进归档目录。两步设计是为了保证预演和正式提交之间事实没发生变化。

## 诊断和修复

状态异常时先用 `doctor` 诊断。不带参数只检查、不改文件：

```bash theme={null}
comet native doctor                  # 检查整个项目
comet native doctor add-user-avatar  # 检查某个变更
```

确认要修复时加 `--repair`，它只处理能证明安全的事项，比如清理过期锁、恢复中断的事务，不会改写你的需求、规格或代码：

```bash theme={null}
comet native doctor add-user-avatar --repair
```

## 配置产物目录

`init` 配置 Native 把产物（变更目录、状态、证据）放在哪，默认是项目下的 `docs/comet/`。通常首次创建变更时会自动生成默认配置，不需要手动跑：

```bash theme={null}
comet native init                 # 用默认目录 docs/comet/
comet native init --root .        # 改放到 <项目>/comet/
comet native init --language zh-CN # 设置后续新建变更的默认语言
```

已经配置过的项目想换目录，用 `root move` 事务化迁移，不要直接改配置文件：

```bash theme={null}
comet native root show            # 看当前目录
comet native root move artifacts  # 迁移到 <项目>/artifacts/comet/
```

## 没有 comet 命令时

如果环境里没装 `comet` CLI（只有 Skill 文件），可以直接调随包发布的 Runtime，参数和退出码跟 `comet native` 完全一致：

```bash theme={null}
node <comet-native-skill-root>/scripts/comet-native-runtime.mjs <command> [options]
```