> ## 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 eval --html 生成的报告位置、experiment id、重点字段、失败归因、rubric 评分和下一步判断。

<Tip>
  这是进阶内容。报告没通过时再来这里查失败归因。日常评估看[快速上手](/zh/eval/quickstart)里的"看报告只需要关注三点"即可。
</Tip>

`comet eval ... --html` 会生成可浏览报告。用户不需要逐行读底层日志，先看结果、归因和产物，再决定下一步。

## 报告位置

`--html` 会要求报告同时产出 markdown 和 HTML。CLI 输出里会包含 `Experiment` 和 `Report path`，常见位置：

```text theme={null}
.comet/eval/runs/<experiment-id>/summary.html
```

`<experiment-id>` 的实际格式是 `<experiment_name>_<YYYYMMDD_HHMMSS>`，例如 `authoring_skill_smoke_20260625_143000`。experiment name 来自第一个参数化测试的 task name（`-` 转 `_`，没有测试时默认 `experiment`）。

如果 CLI 输出里显示的是占位符，用同一段输出里的 `Experiment` 值对应查找即可。到下面目录查也能找到对应实验：

```text theme={null}
.comet/eval/runs/
```

## 报告目录结构

<Tree>
  <Tree.Folder name=".comet/eval/runs/<experiment-id>/" defaultOpen>
    <Tree.File name="summary.md" />

    <Tree.File name="summary.html" />

    <Tree.File name="metadata.json" />

    <Tree.Folder name="events/" />

    <Tree.Folder name="raw/" />

    <Tree.Folder name="reports/" />

    <Tree.Folder name="artifacts/" />
  </Tree.Folder>
</Tree>

* `reports/<treatment>_rep<n>_report.json`：每次运行的完整结果，含 `passed`、`checks_passed[]`、`checks_failed[]`、`events_summary`（tokens/cost/skills\_invoked/failure\_attribution）。
* `metadata.json`：`experiment_id`、`started_at`、`completed_at`、`total_runs`、`total_passed`、`treatments[]`、`report_outputs`。

## 优先看什么

打开报告后，优先看这几类信息，而不是逐行读底层日志：

* **评估是否通过**（summary 顶部 / CLI 输出）
* **失败归因**是 harness、workflow、task 还是 model
* 失败用例是否和 Skill 目标相关
* 是否缺少预期 artifact（硬校验）
* 是否是路径、manifest 或环境问题
* token / cost / duration 是否异常

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/piE9AoWsM20071ec/assets/eval-reports-illustrations/01-summary-report-attribution.png?fit=max&auto=format&n=piE9AoWsM20071ec&q=85&s=bf982c9c7f7d722dd4ca3a87211f0e0b" alt="小鱼按 summary、report.json 和 failure attribution 三层报告线索判断下一步" width="800" data-path="assets/eval-reports-illustrations/01-summary-report-attribution.png" />
</p>

<p align="center">
  先看 summary，再查单次 report，最后用 failure attribution 决定下一步
</p>

## 失败归因

`comet eval ... --html` 的输出会提示 failure attribution：报告会把失败归到 harness、workflow、task、model 四个桶里。归因逻辑按顺序判断：

| 归因         | 触发条件                                                                 | 含义                      |
| ---------- | -------------------------------------------------------------------- | ----------------------- |
| `harness`  | required skill 完全没被调用；或 generic profile 且无 skill 运行                  | 环境/依赖/路径问题，Skill 没真正跑起来 |
| `task`     | check 涉及 artifact path / validator / task directory                  | 任务定义或 fixture 问题        |
| `workflow` | check 涉及 `.comet.yaml`/guard/state/transition/archive；或 skill 调用契约失败 | Skill 流程没达预期            |
| `model`    | 默认兜底（任务在可观察的工作流执行后失败）                                                | 模型行为不稳定                 |

## Rubric 评分（信息性）

报告里会有 `[RUBRIC] <dim>: <score> - <reason>` 行和汇总的 `RubricAvg` 列。这是**信息性**评分，不直接决定通过与否。不同 profile 的维度：

| Profile           | 主要维度                                                                                                                                                                                                        |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `generic`         | completion、skill\_invocation、artifact\_presence、instruction\_following、interaction\_compliance、efficiency、safety\_boundary                                                                                  |
| `comet-workflow`  | main\_flow、gate\_guard、skill\_invocation、spec\_drift、completion、efficiency、decision\_point\_compliance、artifact\_quality、recovery\_resilience                                                               |
| `authoring-skill` | completion、generated\_package、resolved\_skill\_evidence、engine\_contract、workflow\_route\_conformance、authoring\_lanes、review\_gate、review\_readiness、skill\_invocation、artifact\_presence、safety\_boundary |

### summary.md 里的 rubric 列

Results 表每个 treatment 一行，列顺序是：`Checks` → 各 rubric 维度列 → `RubricAvg` → `Turns/Duration/Tools/Tokens/Cost`。

* **维度列**：单次运行显示该维度分（0.00–1.00）；多次运行（reps）显示均值。
* **RubricAvg**：该次运行所有维度分（含 `weighted_score` 行）的**简单均分**——是横向快速对比的汇总，和单 rubric 用各自权重算的 `weighted_score` 算法不同。
* **weighted\_score**：rubric 自己输出的加权总分（`Σ(维度分×权重)/Σ(权重)`），作为一列出现。

### reps > 1 时的聚合

用了 `--count N` 重复运行时，summary 会多一个 **"Aggregated by Treatment"** 表：`Reps Passed`（通过的重复数）、`Checks`、`Avg Turns/Duration`、`Tokens`、`Cost`、`Skills`、`Scripts`。每个重复的通过/失败（零 `checks_failed` 即通过）汇总后用于算 pass\@k。

<Note>
  Rubric 是<strong>诊断工具</strong>，不是<strong>通过条件</strong>
  。真正的通过/失败由校验器（expected artifacts、test\_scripts）和"required skill
  是否被调用"决定。Rubric 分低但 check 全过，仍然算通过。
</Note>

## pass\@k / pass^k（对比报告）

pass\@k / pass^k 不在 `summary.md`，而在**对比报告**（`comparison_report.md`，由 `compare_baselines.py` 产出）的 `## pass@k / pass^k — capability vs reliability` 章节：

* **pass\@k**：k 次里至少成功一次的概率（能力上限）
* **pass^k**：k 次全部成功的概率（可靠性下限）
* **gap（pass\@k − pass^k）**：不稳定性——能做但不能保证每次都做对

需要多次重复运行（`--count`）才有意义；单次运行只能算 k=1。完整的公式、含义和对比表的读法见[评分指标与双 Agent 评测](/zh/eval/scoring)。

## 如何决定下一步

| 报告信号                 | 含义                    | 下一步                          |
| -------------------- | --------------------- | ---------------------------- |
| manifest 读取失败        | 路径或文件不存在              | 修 `comet/eval.yaml` 或路径      |
| `harness` 归因         | 环境、依赖、Docker、网络       | 检查 Docker、模型凭证和选定的 Agent CLI |
| `workflow` 归因        | Skill 执行流程没达到预期       | 回到 `/comet-any` 优化 Skill     |
| `task` 归因            | 任务定义、验证条件或 fixture 问题 | 检查 eval 任务定义和 fixture        |
| `model` 归因           | 模型行为或工具使用不稳定          | 重跑或降低对非确定行为的依赖               |
| 缺少 expected artifact | 任务没产出预期文件             | 检查任务定义或 Skill 产出逻辑           |

## 失败时怎么判断是哪个环节

### collect 失败

优先检查：

* manifest 路径是否正确
* `comet/eval.yaml` 是否存在
* manifest 里推荐的 task 是否存在
* 当前是否在 Comet 仓库根目录或传了正确 `--project`

### run 失败

优先看报告里的 failure attribution，按上面的桶定位。再看 `reports/<treatment>_rep<n>_report.json` 里的 `events_summary`：

* `skills_invoked` 为空 → harness 归因，Skill 没跑起来
* `files_created` 缺少 expected artifact → Skill 没产出预期文件
* `total_tokens` 异常低 → 可能 Skill 提前终止

### 评估"瞬间通过"

几乎肯定是环境没准备好导致 suite 被跳过。检查 Docker、模型凭证和选定的 Agent CLI。

### HTML 报告没找到

先看 CLI 输出的 `Experiment` 和 `Report path`。如果路径里有占位符，用实际 experiment id 到 `.comet/eval/runs/` 目录查。

## 报告如何进入发布

**不要**手工编辑 Bundle 状态，也**不要**手工把报告路径写进内部 JSON。让 `/comet-any` 或 Bundle 后端记录 eval 结果，并让 `comet creator status` 读取 readiness。

Eval 证据进入 readiness 的规则：

| 情况               | 能否 publish               |
| ---------------- | ------------------------ |
| 没有 eval 证据       | 不能                       |
| eval 失败          | 不能                       |
| eval 证据对应旧 hash  | 不能                       |
| eval 通过且 hash 匹配 | 可以进入 review / publish 判断 |

## 下一步

* [Runtime check](/zh/eval/runtime) — 区分 `comet eval` 和 `comet skill check`
* [comet eval 命令](/zh/cli/eval) — 完整选项和子命令参考
* [发布和分发 Skill](/zh/skill-creator/publishing) — eval 证据如何驱动 readiness