> ## 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 两种入口、collect/run 区别、环境准备、失败归因、报告和发布证据的常见疑问。

关于 `comet eval` 评估系统、环境准备、报告解读和发布证据的常见问题。

## 基础概念

<AccordionGroup>
  <Accordion title="comet eval 到底评估什么">
    `comet eval` 通过共享 eval harness 执行真实模型任务，验证一个 Skill 作为产品能力能不能通过评估，产出发布前证据。它封装了 pytest、task registry、profile、报告生成，你不需要手工拼参数。详见[评估系统概览](/zh/eval/overview)。
  </Accordion>

  <Accordion title="comet eval 和 comet skill check 有什么区别">
    `comet eval` 评估 Skill 的产品能力，产出可复查的评估报告。它可以读
    `comet/eval.yaml`（`/comet-any` 生成的完整包），也可以直接吃任意本地 Skill
    目录；没有 manifest 时普通运行会生成并缓存 2–4 个任务，`--quick` 才是固定的
    `generic-skill-smoke` 冒烟。`comet skill check` 检查某次 Skill 运行是否缺
    artifact 或状态，不执行模型任务，不产出发布证据（读
    `comet/checks.yaml`）。发布 readiness 需要完整包的 `comet eval`
    证据。详见[Runtime check](/zh/eval/runtime)。
  </Accordion>

  <Accordion title="我需要懂 pytest 或 Docker 吗">
    不需要。`comet eval` 封装了底层细节，你只需要知道用 `--manifest` 还是
    `--skill-path`。底层细节由 harness 处理。详见[Eval
    harness](/zh/eval/harness)。
  </Accordion>

  <Accordion title="两套评估系统是什么意思">
    创建期评估（`comet eval`，读本地 Skill 目录或 `comet/eval.yaml`）和运行期检查（`comet skill check`，读 `comet/checks.yaml`）。前者是发布证据，后者是 Run 完成度检查。详见[评估系统概览 · 两套评估系统](/zh/eval/overview#两套评估系统不要混淆)。
  </Accordion>
</AccordionGroup>

## 环境准备

<AccordionGroup>
  <Accordion title="运行 eval 需要什么环境">
    需要 `uv`、Python 3.11+、Docker、选定的 Agent CLI 以及对应的模型凭证。核心 Comet 运行时不需要这些，只有 `comet eval` 需要。完整准备步骤见[评估快速上手 · 运行前你需要准备什么](/zh/eval/quickstart#运行前你需要准备什么)。
  </Accordion>

  <Accordion title="评估瞬间&#x22;通过&#x22;但感觉没真跑">
    几乎肯定是环境没准备好：Docker 没起、模型凭证缺失、或选定的 Agent CLI
    不可用。harness 在这些情况下会**跳过**而不是失败。先确认环境就绪。
  </Accordion>

  <Accordion title="怎么安装 uv">
    macOS/Linux：`curl -LsSf https://astral.sh/uv/install.sh | sh`。Windows
    PowerShell：`powershell -ExecutionPolicy ByPass -c "irm
          https://astral.sh/uv/install.ps1 | iex"`。`uv` 会自动管理 Python 版本和
    `eval/.venv`。
  </Accordion>

  <Accordion title="Eval harness is missing 和 uv 缺失有什么区别">
    `Eval harness is missing at ...` 表示 npm 包中的随包 `eval/` 不完整，或
    `--project` 指向了错误仓库；重新安装 `@rpamis/comet` 或修正项目路径。`uv is
          not installed or not in PATH` 表示 harness 已找到，只需要安装或修复 `uv`。npm
    用户通常不需要另行 clone Comet 仓库。
  </Accordion>

  <Accordion title="API key 怎么配">
    `export ANTHROPIC_API_KEY=sk-ant-...`，或在用户级 `%USERPROFILE%\\.comet\\eval\\.env` / `~/.comet/eval/.env` 里配置（`comet eval` 会自动加载）。用代理型凭证（BigModel / OpenRouter）时用 `ANTHROPIC_AUTH_TOKEN`。
  </Accordion>
</AccordionGroup>

## 两种入口

<AccordionGroup>
  <Accordion title="--manifest 和 --skill-path 该用哪个">
    评估任意本地 Skill 目录用 `--skill-path`（传目录即可，没有 manifest 时普通运行会生成任务），这是默认入口。需要固定冒烟时显式加 `--quick`。评估 `/comet-any` 生成的完整包（带 `comet/eval.yaml`）用 `--manifest`，跑完整 profile 任务集，结果才是发布证据。要进入发布 readiness 必须用完整包 manifest。两者互斥。
  </Accordion>

  <Accordion title="manifest 里的 current-bundle-hash 需要手工替换吗">
    不需要。`/comet-any` 生成的 `<current-bundle-hash>` 会在 collect/run 前解析为当前 Bundle draft hash，并写入临时 manifest；源 Bundle 和源 `comet/eval.yaml` 不会被修改。只有 manifest 已离开原 Bundle、找不到 `bundle.yaml` 或 draft 无法加载时才会报错。
  </Accordion>

  <Accordion title="--quick 是什么，默认 task 是什么">
    `--quick` 配合 `--skill-path` 使用，明确选中 `generic-skill-smoke`
    task。普通传目录运行时会根据 Skill 快照生成并缓存 2–4 个任务；`--quick`
    是低成本冒烟，不等于发布前完整证据，准备发布时仍需走完整包 manifest 路径。
  </Accordion>

  <Accordion title="为什么先 collect 再 run">
    `collect` 只做发现预检查（验证
    manifest、task、路径），不消耗模型调用，成本最低，适合刚生成完 Skill
    后排错。`run` 才执行真实评估。先 collect
    能快速发现配置问题，避免浪费模型调用。详见[快速上手](/zh/eval/quickstart)。
  </Accordion>

  <Accordion title="authoring-skill 和 generic profile 有什么区别">
    `authoring-skill`（11 维 rubric，`auto_user` 下 `maxTurns=8` 次外层往返）用于 `/comet-any` 生成的 Skill，检查生成包完整性、resolved-skills 证据、Engine 契约、workflow 路由一致性、authoring lanes、review gate 等。`generic`（7 维 rubric，默认单轮）用于通用 Skill 冒烟。详见[评估系统概览 · Profile 体系](/zh/eval/overview#profile-体系)。
  </Accordion>
</AccordionGroup>

## 报告与失败

<AccordionGroup>
  <Accordion title="报告在哪里找">
    CLI 输出会打印 `Report path`，通常是 `.comet/eval/runs/<experiment-id>/summary.html`。请以本次输出的实际 `Experiment` 和 `Report path` 为准。详见[读取评估报告](/zh/eval/reports)。
  </Accordion>

  <Accordion title="评估失败了，怎么判断问题出在哪">
    看报告里的 failure attribution（失败归因）。`harness`
    说明环境/依赖/路径问题，`workflow` 说明 Skill 流程没达预期，`task`
    说明任务定义/fixture 问题，`model`
    说明模型行为不稳定。归因决定你该改什么。详见[读取评估报告](/zh/eval/reports)。
  </Accordion>

  <Accordion title="collect 报错说找不到目标">
    检查路径是否正确：本地 Skill 目录要含 `SKILL.md`，`comet/eval.yaml` 要指向真实存在的文件。如果不在 Comet 仓库根目录，加 `--project <dir>` 指向正确根目录。
  </Accordion>

  <Accordion title="model 归因失败要重跑吗">
    `model` 归因说明模型行为或工具使用不稳定，重跑通常有效。如果反复失败，考虑降低
    Skill 对非确定行为的依赖。
  </Accordion>

  <Accordion title="Rubric 分很低但 check 全过，算通过吗">
    算通过。Rubric 是**信息性**评分（`[RUBRIC]` 行和 `RubricAvg`），不直接决定通过与否。真正的通过/失败由校验器和 required skill 调用决定。Rubric 分低是诊断信号，可以用来优化 Skill 但不影响发布门禁。
  </Accordion>
</AccordionGroup>

## 发布证据

<AccordionGroup>
  <Accordion title="Eval 通过了就能发布吗">
    Eval 通过只是条件之一。`/comet-any` 或后端会把 eval 证据纳入 readiness：没有证据、失败、对应旧 hash 都不能 publish。通过且 hash 匹配才能进入 review/publish。详见[评估系统概览](/zh/eval/overview)。
  </Accordion>

  <Accordion title="eval 证据对应旧 hash 是什么意思">
    说明 Skill 在上次评估后被修改了（draft hash
    变了），旧评估结果不再有效。需要重新跑 `comet eval ... --html` 生成绑定当前
    hash 的证据。
  </Accordion>

  <Accordion title="我能手工把报告路径写进发布状态吗">
    不要。`/comet-any` 会通过 Bundle 后端记录结构化证据。手工编辑 Bundle
    状态或内部 JSON 会破坏 hash 绑定和 readiness 校验。
  </Accordion>

  <Accordion title="quick smoke 能当发布证据吗">
    不能。`--skill-path --quick` 只是早期冒烟，覆盖范围有限。发布前必须通过 `/comet-any` 生成 `comet/eval.yaml`，再用 `--manifest` 跑完整评估。
  </Accordion>
</AccordionGroup>