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

# Runtime check（进阶）

> 区分 comet eval 和 comet skill check，理解某次 Skill 运行的本地完成度检查、checks.yaml 格式和 pending action 恢复。

<Tip>
  这是进阶内容，主要面向需要调试 Skill 运行（Engine Run）的进阶用户。如果你只做 `comet eval`（创建期评估），可以跳过本页。
</Tip>

<Warning>
  本页是源码/维护者进阶内容，需要理解 Comet Runtime 和源码目录。普通用户只运行
  `comet eval`，不需要 clone Comet；请从[快速上手](/zh/eval/quickstart)开始。
</Warning>

Comet 有两类 eval。名字相似，但用途不同，**不要混用**。

## 对比

| 命令                  | 评估对象                       | 适合的问题                | 是否是发布证据 | 读哪个文件               |
| ------------------- | -------------------------- | -------------------- | ------- | ------------------- |
| `comet eval`        | Skill 包或 `comet/eval.yaml` | 这个 Skill 能不能通过产品级评估  | **是**   | `comet/eval.yaml`   |
| `comet skill check` | 某次 Skill 运行                | 这次运行是否缺 artifact 或状态 | 否       | `comet/checks.yaml` |

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/BZVRznxkRMyQif0t/assets/eval-runtime-illustrations/01-comet-eval-skill-eval-boundary.png?fit=max&auto=format&n=BZVRznxkRMyQif0t&q=85&s=9f7239beb656d875209c2258bce9e003" alt="小鱼把 comet eval 的发布证据和 comet skill check 的 Run 完成度检查分到两张工作台" width="800" data-path="assets/eval-runtime-illustrations/01-comet-eval-skill-eval-boundary.png" />
</p>

<p align="center">comet eval 产出发布证据；comet skill check 只检查某次 Skill 运行是否完整</p>

## 为什么有两类

`comet eval` 面向"这个 Skill 作为产品能力能不能通过评估"，它通过共享 eval harness 执行真实模型任务，产出发布前证据。

`comet skill check` 面向"这次 Skill 运行是否完整"，它只检查当前运行是否满足 `comet/checks.yaml` 里的 runtime checks，**不执行模型任务**，也**不产出发布证据**。

两者服务于不同阶段：`comet skill check` 在 Skill 运行中检查完成度，`comet eval` 在发布前验证产品能力。

## runtime check 的检查格式

runtime check 定义在 Skill 包的 `comet/checks.yaml`（或 `comet/evals.yaml`，两者二选一，不能同时存在）。`/comet-any` 生成物默认用 `checks.yaml`。

```yaml theme={null}
# comet/checks.yaml
runtime:
  - id: completed
    scope: completion
    type: state_equals
    field: status
    equals: completed
```

每个 runtime check 的字段：

| 字段                 | 说明                                                          |
| ------------------ | ----------------------------------------------------------- |
| `id`               | eval 标识                                                     |
| `scope`            | `progress`（按需）/ `step`（每次 outcome 后）/ `completion`（Run 完成时） |
| `type`             | `artifact_exists` 或 `state_equals`                          |
| `artifact`         | `artifact_exists` 时检查的 artifact key                         |
| `field` / `equals` | `state_equals` 时检查 Run state 字段是否等于指定值                      |

### 两种检查类型

| 类型                | 判断方式                       |
| ----------------- | -------------------------- |
| `artifact_exists` | artifacts 存储里有对应的 artifact |
| `state_equals`    | Run state 的某个字段等于指定值       |

### 三个作用域

| scope        | 何时运行                      | 触发方式                                 |
| ------------ | ------------------------- | ------------------------------------ |
| `step`       | 每次提交 action outcome 后自动运行 | 自动                                   |
| `completion` | Run 到达 completed 时自动运行    | 自动                                   |
| `progress`   | 按需运行                      | `comet skill check --scope progress` |

## comet skill check 示例

runtime check 通常配合 `comet skill run` 和 `comet skill continue` 使用：

```bash theme={null}
# 启动一次 Skill 运行
comet skill run my-skill --run-id demo-run --project .

# Agent 执行 pending action，然后用 resume 提交结果
comet skill continue --run-id demo-run --status succeeded --summary "完成"

# 检查这次 Skill 运行的完成度
comet skill check --run-id demo-run --scope completion --json
```

也可以绑定 OpenSpec change 目录：

```bash theme={null}
comet skill run my-skill --change ./changes/demo
comet skill continue --change ./changes/demo --status succeeded --summary "Done" --artifact report=report.md
comet skill check --change ./changes/demo --scope completion
```

Run 可以绑定 `--change` 目录，也可以用 `--run-id` 放到 `.comet/runs/<run-id>` 下。`run` 支持 deterministic Skills；adaptive 执行需要 Agent 候选。

## 什么时候需要 runtime check

Skill 运行（Engine Run）通常出现在这些场景：

* Skill 有多步骤状态。
* 需要 pending action 和 resume。
* 需要检查 artifact 是否存在。
* 需要 guardrails 或恢复语义。
* Skill 是 Engine-enabled（`/comet-any` 为多步骤或高风险生成物生成的 Skill 默认开启 Engine）。

Engine-enabled 生成物会写入 `comet/checks.yaml` 和 `comet/eval.yaml`：

* `comet/checks.yaml`：runtime checks，由 `comet skill check` 使用。
* `comet/eval.yaml`：eval manifest，由 `comet eval` 使用。

## 文本模式的恢复提示

`comet skill` 在文本模式下会直接打印 `Pending action` 和 `Next:` 恢复提示，让你不需要在暂停的 Run 或失败的 eval 后自己猜下一步。

例如 `run` 输出：

```text theme={null}
Run: demo-run
Status: paused
Current step: collect-evidence
Pending action: collect-evidence (tool, step collect-evidence)
Runtime checks: 1
Next: complete the pending action, then run comet skill continue
```

`eval` 失败时会提示：

```text theme={null}
Next: record the missing artifact/state and rerun comet skill check
```

每个 `PASS`/`FAIL` 会带 evidence，例如 `PASS completed: state.status = completed` 或 `FAIL report-exists: artifact report(missing) not found`。

## 怎么选

* 你的问题是"这个 Skill 作为产品能力能不能通过评估"：

  ```bash theme={null}
  comet eval ./generated-skill/comet/eval.yaml --html
  ```

* 你的问题是"这次 Skill 运行是否缺 artifact 或状态"：

  ```bash theme={null}
  comet skill check --run-id <run-id> --scope completion
  ```

<Warning>
  准备发布 Skill 时，<strong>不要</strong>只跑 <code>comet skill check</code>。发布 readiness 需要通用 <code>comet eval</code> 证据。<code>comet skill check</code> 只检查某次 Skill 运行的完成度，不是通用 Skill 评估。
</Warning>

## 下一步

* [comet skill 命令](/zh/cli/skill) — 完整 Skill 包和 Run 工具参考
* [comet eval 命令](/zh/cli/eval) — 完整评估选项
* [Skill 与 Engine（进阶）](/zh/skill-creator/engine) — 理解 Skill 运行（Engine Run）的语义、pending action、不可变快照