> ## 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.
# 评估系统概览（进阶）
> 理解自己的 Skill 如何被 comet eval 发现、运行、评分和产出报告，再理解 /comet-any 如何把 eval 证据接入发布 readiness。
这是进阶内容。如果你只想快速跑通一次评估，先看[快速上手：评估一个
Skill](/zh/eval/quickstart)。
本页适合需要查看 Eval 内部机制的源码维护者。普通用户不需要 clone Comet 或进入 `eval/`
目录；请使用已安装的 `comet eval` 和用户级 `.env`。只有修改 harness、使用 `--project`
或复现实验时，才需要拉取源码。
`comet eval` 是 Comet 的通用 Skill 评估入口。它先回答一个问题：**你手里的 Skill，作为一个产品能力，能不能通过真实任务评估？**
这篇概览分两块：
1. 先看自己的 Skill 怎么被评估：入口、任务、评分、报告和失败归因。
2. 再看 `/comet-any` 如何把 eval 结果接入发布 readiness。
## 从这里开始
| 你想完成什么 | 先看 |
| ------------------------------ | --------------------------------------------------- |
| 第一次跑评估 | [快速上手：评估一个 Skill](/zh/eval/quickstart) |
| 不知道传 manifest 还是目录 | [入口怎么选](#入口怎么选) |
| 看不懂报告里的失败原因 | [读取评估报告](/zh/eval/reports) |
| 想理解 pass\@k、pass^k、rubric | [评分指标与双 Agent 评测](/zh/eval/scoring) |
| 想写自己的评估任务 | [配置评估与自定义 Task](/zh/eval/configuration) |
| 想知道 `/comet-any` 如何用 eval 证据发布 | [第二块：/comet-any 如何连接 eval](#第二块comet-any-如何连接-eval) |
## 它解决什么问题
日常使用不需要理解 pytest、task registry、profile、treatment 或 Docker 细节。`comet eval` 封装了本地 eval harness 的启动路径、任务发现、profile 选择和报告生成，让你从项目根目录就能跑评估，而不是手工切到 `eval/` 目录拼命令行参数。
## 两套评估系统，不要混淆
Comet 有两套评估系统，名字相近但完全不同：
| 系统 | 命令 | 评估对象 | 是发布证据吗 |
| --------- | ------------------- | -------------------------- | ------ |
| **创建期评估** | `comet eval` | Skill 包或 `comet/eval.yaml` | **是** |
| **运行期检查** | `comet skill check` | 某次 Skill 运行 | 否 |
`comet eval` 回答"这个 Skill 作为产品能力能不能通过评估"，通过共享 eval harness 执行真实模型任务。`comet skill check` 回答"这次 Skill 运行是否缺文件或状态"，只检查运行期检查项，不跑模型。详见 [Runtime check](/zh/eval/runtime)。
`comet eval` 产出发布前证据，`comet skill check` 只检查某次 Skill
运行是否完整，两者不要混用
## 第一块：自己的 Skill 怎么被评估
从用户视角，`comet eval` 做四件事：
1. 找到你的 Skill。
2. 找到应该跑哪些评估任务。
3. 在隔离环境里让模型执行任务，并用校验器检查结果。
4. 生成报告，告诉你通过、失败原因和下一步。
```mermaid theme={null}
%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
flowchart TB
subgraph Input["你的 Skill"]
A["任意本地 Skill 目录
默认 quick smoke"]
B["有 comet/eval.yaml
完整包评估（发布证据）"]
end
subgraph Discover["发现和准备"]
C["解析入口
manifest 或 skill-path"]
D["选择 profile 和 task
决定评估维度"]
E["collect
只做发现预检查"]
end
subgraph Run["真实评估"]
F["run --html
执行模型任务"]
G["校验 artifacts / scripts
判断硬通过"]
H["rubric / pass@k
提供诊断信号"]
end
subgraph Output["结果"]
I["summary.html
可浏览报告"]
J["failure attribution
harness / workflow / task / model"]
end
A --> C
B --> C
C --> D --> E --> F --> G --> I
F --> H --> I
G --> J
```
## 入口怎么选
`comet eval [target]` 根据 target 自动判断入口：传目录或 `SKILL.md` 走 skill-path，传 `comet/eval.yaml` 走 manifest。两者也可以用 `--skill-path` / `--manifest` 显式指定，显式入口互斥。
| 场景 | 命令 | 适合 |
| ------------------- | ----------------------------------------------------- | ---------------------------- |
| 任意本地 Skill 目录（默认） | `comet eval ./my-skill --html` | 评估自己的 Skill，一条命令跑通 Docker 评估 |
| `/comet-any` 生成的完整包 | `comet eval ./generated-skill/comet/eval.yaml --html` | 跑完整 profile 任务集，作为发布证据 |
传目录时会自动发现 manifest；没有 manifest 时普通运行会从 Skill 快照生成并缓存 2–4 个受限任务，`--quick` 才是固定的 `generic-skill-smoke` 冒烟。`--skill-name` 会从目录名自动推断。不需要 `comet/eval.yaml`，也不需要 clone Comet 仓库——npm 包自带 eval harness。
直接评估本地 Skill 不等于发布评估。`--quick` 只验证"Skill
能被注入、被调用、产出文件"；普通运行会生成与 Skill 内容相关的受限任务。发布
readiness 需要评估 /comet-any 生成的完整包（带{" "}
comet/eval.yaml）。
## 为什么先 collect
`collect` 是用户最便宜的排错入口。它只做发现和预检查，不执行模型或 Docker 任务，适合快速发现路径、manifest、任务缓存和配置问题。
```bash theme={null}
comet eval ./generated-skill/comet/eval.yaml --collect
```
它主要回答：
* `comet/eval.yaml` 路径是否正确
* eval harness 是否能读到这个 manifest
* manifest 里的推荐任务是否能被发现
* 当前仓库的 eval 依赖路径是否可用
它不应该先跑完整模型评估，也不应该先消耗长时间任务。失败时，通常先修 manifest、路径或任务发现问题。
## comet/eval.yaml 清单格式
`comet/eval.yaml` 是发布前完整评估的清单。它告诉 eval harness：Skill 在哪里、用哪个 profile、推荐跑哪些任务、期望哪些 evidence 和 artifacts。它的格式（由 harness 的 `manifests.py` 解析）：
```yaml theme={null}
apiVersion: comet.eval/v1alpha1 # 必填，必须精确等于这个值
kind: SkillEvalManifest # 必填，必须精确等于这个值
metadata:
name: my-skill
description: 一个 PR 评审助手
skill:
name: my-skill
source: ".." # 相对 eval.yaml 的 Skill 目录，默认 ".."
profile: authoring-skill # 可选，覆盖 profile
evaluation:
recommendedTasks: # 推荐任务列表
- authoring-skill-smoke
- workflow-route-conformance
baselineTreatments: [CONTROL]
qualityGates:
minWeightedScore: 0.8
minPassAt1: 0.6
maxInstabilityGap: 0.4
requiredOutputSchemas: []
expectedEvidence: []
requiredSkills: [writing-plans, requesting-code-review]
expectedArtifacts:
- reference/resolved-skills.json
- reference/workflow-protocol.json
interaction:
mode: none # none 或 auto_user，默认 none
maxTurns: 8 # auto_user 下 subject/simulator 外层往返上限，默认 12
simulatorPrompt: "" # 可选
```
apiVersion 和 kind 是强校验：不等于{" "}
comet.eval/v1alpha1 / comet.eval/SkillEvalManifest{" "}
会直接报错。日常使用通常不需要手写这个文件，/comet-any 会生成。
`/comet-any` 生成的 eval.yaml 默认用 `authoring-skill` profile。普通 workflow-kernel 会推荐 `generic-skill-smoke`、`authoring-skill-smoke` 和 `workflow-route-conformance`；基于 `/comet` 的 overlay 会额外推荐 `workflow-overlay-contract` 和经典 Comet workflow 任务，用来检查 Output Schema、预期 evidence 和 overlay 路由。
## Profile 体系
eval harness 内置三个 profile，每个决定 rubric 维度、默认交互模式和评分器：
| Profile | 维度数 | 默认交互 | 适合 |
| ----------------- | --- | ------------------------------- | ---------------------- |
| `generic` | 7 | `mode=none`, `maxTurns=12` | 通用 Skill 冒烟 |
| `comet-workflow` | 9 | `mode=auto_user`, `maxTurns=12` | 经典 `/comet` 五阶段评估 |
| `authoring-skill` | 11 | `mode=auto_user`, `maxTurns=8` | `/comet-any` 生成的 Skill |
Profile 解析优先级：`--profile` 覆盖 > manifest 的 `skill.profile` > task 的 `evaluation.profile` > `generic`。
maxTurns 不是 Agent 内部消息数或工具调用数。它只在 auto\_user 模式下生效，限制"被测 Agent 跑到决策点 -> 用户模拟器回复 -> 被测 Agent 用 --resume 继续"这种外层往返最多发生多少次。
comet-\* 开头的任务或 metadata.category=comet{" "}
的任务会自动推断为 comet-workflow profile，并自动把交互模式切到{" "}
auto\_user（两个 Agent 自动交互：一个跑被测
Skill，另一个模拟用户在决策点回复）。
## 评分指标：rubric + pass\@k/pass^k
eval 是**指标驱动**的评测，不只给通过/失败：
* **rubric 多维评分**：把 Skill 质量拆成多个维度（如五阶段的 main\_flow/gate\_guard、通用 Skill 的 safety\_boundary），每维度 0.0–1.0，加权汇总成 `weighted_score`。**信息性**，用于诊断。
* **pass\@k / pass^k**：区分**能力上限**（k 次里至少成功一次）和**可靠性下限**（k 次全部成功）。基于多次重复运行（`--count N`）算。**信息性**。
* **任务校验器通过/失败**：这次实现到底对不对（`target_artifacts` + `test_scripts`）。**这才是硬判定的 pass/fail**。
完整的维度细则、权重、公式、双 Agent 交互循环见[评分指标与双 Agent 评测](/zh/eval/scoring)。
## Task 体系
eval harness 内置一组任务，每个任务是一个目录（含 `instruction.md`、`task.toml`、`environment/`、`validation/`）。常见任务：
| Task | 类别 | 说明 |
| ---------------------------- | ------- | ----------------------------- |
| `generic-skill-smoke` | generic | 通用 Skill 冒烟，产出并校验 `result.md` |
| `authoring-skill-smoke` | generic | 生成 Skill 包冒烟，校验 Engine 包完整性 |
| `workflow-route-conformance` | - | 校验生成的 Skill 是否按预期 stage 顺序运行 |
| `comet-full-workflow` 等 | comet | 经典五阶段的不同维度评估 |
**`recommended`** 不是任务名，而是 CLI 的默认解析路径：用 `--manifest` 时读 manifest 的 `recommendedTasks`；没有 manifest 时跑每个 task 的 `default_treatments`。
## skill-path 默认入口跑什么
传一个本地 Skill 目录时，普通运行会根据 Skill 快照生成并缓存受限任务；需要固定的 quick smoke 时，显式使用 `--quick`：
```bash theme={null}
comet eval ./my-skill --html
```
它验证：
* Skill 目录是否可读取
* eval harness 是否能把它当作动态 Skill 注入
* 通用 smoke task 是否能跑起来并产出 `result.md`
这是评估自己 Skill 的默认入口，轻量但真实。它**不等于**发布前完整证据——发布 readiness 需要评估 `/comet-any` 生成的完整包（带 `comet/eval.yaml`）。
## 第二块：/comet-any 如何连接 eval
`/comet-any` 负责创建或优化 Skill，`comet eval` 负责验证这个 Skill 是否能被 eval harness 发现、运行并产出报告。两者的连接点是生成物里的 `comet/eval.yaml` 和评估后的 Eval evidence。
```mermaid theme={null}
%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
flowchart TB
subgraph Create["创建 Skill"]
A["/comet-any
创建或优化 Skill"]
B["生成 comet/eval.yaml
评估清单"]
A --> B
end
subgraph Eval["评估 Skill"]
C["comet eval --collect
发现和预检查"]
D["comet eval --html
真实评估和 HTML 报告"]
E["Eval evidence
绑定当前 draft hash"]
C --> D --> E
end
subgraph Publish["进入发布准备"]
F["comet creator status / next
查看 readiness 和下一步"]
G["comet publish
review / approve / run / distribute"]
F --> G
end
B --> C
E --> F
```
完整链路：
```text theme={null}
/comet-any 生成 Skill
-> 产出 comet/eval.yaml
-> comet eval --collect 做发现预检查
-> comet eval --html 执行真实评估
-> comet creator 读取评估结果并进入 readiness / review / publish / distribute
```
`comet eval` 不负责发布。发布仍然由 creator / publish 命令处理：创建和恢复状态通过 [comet creator](/zh/cli/creator) 暴露，发布和分发通过 [comet publish](/zh/cli/publish) 暴露。eval 的职责是提供发布前证据。
## 推荐路径：评估 /comet-any 生成的 Skill
当 `/comet-any` 生成了 Skill 后，优先找这个文件：
```text theme={null}
generated-skill/
comet/
eval.yaml
```
然后按两步跑：
```bash theme={null}
comet eval ./generated-skill/comet/eval.yaml --collect
comet eval ./generated-skill/comet/eval.yaml --html
```
第一步 `collect` 只确认"能不能发现任务"，适合刚生成完 Skill 后做低成本预检查。第二步 `run --html` 才执行真实评估并生成可浏览报告。
## Eval 结果如何进入 publish readiness
`/comet-any` 或 creator / publish 后端在记录 Eval 结果后，会把它并入 publish readiness。用户需要知道的只有两点：
1. `comet eval` 产出的结果会成为 `Publish readiness:` 的证据来源。
2. 当前 hash 缺少 Eval 证据时，`User next steps:` 必须先指向补齐评估，而不是继续发布。
通常顺序是：
```bash theme={null}
comet eval ./generated-skill/comet/eval.yaml --collect
comet eval ./generated-skill/comet/eval.yaml --html
comet creator next --json
```
`comet creator next` 只输出当前推荐的一步用户命令；`comet publish review` 会把 `Publish readiness:`、`User next steps:`、`Readiness:`、`Blockers:`、`Warnings:` 和 `Evidence:` 展示给用户。
## /comet-any 如何使用 eval 结果
从用户视角，eval 结束后把结果交回 `/comet-any` 继续推进即可。`/comet-any` 会把 eval 证据纳入 readiness：
| 情况 | 能否 publish |
| --------------------------------------------- | ------------------------ |
| 没有 eval 证据 | 不能 |
| eval 失败 | 不能 |
| eval 证据对应旧 hash | 不能 |
| `.comet/skill-preferences.yaml` 变化且 strict 模式 | 不能，必须重新确认或重新生成 |
| eval 通过且 hash 匹配 | 可以进入 review / publish 判断 |
用户不需要手工编辑内部状态，也不应该手工把报告路径写进 JSON。`/comet-any` 会通过后端记录结构化证据。
## 用户最少需要记什么
1. `comet eval` 的核心问题是：这个 Skill 作为产品能力能不能通过真实任务评估。
2. 任意本地 Skill 目录都能用 `comet eval ./your-skill` 跑通 Docker 评估；要发布时再评估 `/comet-any` 生成的完整包（带 `comet/eval.yaml`）。
3. 先 `collect`，再 `run --html`。
4. `/comet-any` 生成物会把 eval 结果接入发布 readiness，但 eval 本身不是发布动作。
5. `comet eval`（创建期）和 `comet skill check`（运行期）是两套系统，不要混用。
## 下一步
* [评分指标与双 Agent 评测](/zh/eval/scoring) — rubric 维度细则、pass\@k/pass^k、双 Agent 交互循环
* [Eval harness](/zh/eval/harness) — 理解 collect 和 run 的内部机制、环境变量和报告生成
* [读取评估报告](/zh/eval/reports) — 学会看懂报告信号和失败归因
* [Runtime check](/zh/eval/runtime) — 区分 `comet eval` 和 `comet skill check`
* [comet eval 命令](/zh/cli/eval) — 完整选项和子命令参考