/
├── summary.md # 主报告（总是生成）
├── summary.html # HTML 版（--html 时）
├── metadata.json # experiment 元数据
├── events/ # 每次运行的 stream-json 事件
├── raw/ # 原始 stdout/stderr
├── reports/ # 每次运行的 report.json
└── artifacts/ # Agent 产出的文件
```
### summary.md 包含
1. 头部：Experiment ID、开始/完成时间。
2. **Results 表**：每个 treatment 一行，列含 Checks、Turns、Duration、Tools、Tokens、Cost、RubricAvg。
3. **Summary**：总运行数、checks 通过 X/Y（百分比）。
4. **Treatment Details**：每个 treatment 每次运行的详细 metrics、skills invoked、scripts used、通过和失败的 check 列表。
### 每次运行的 report.json
字段包括：`passed`、`checks_passed[]`、`checks_failed[]`、`events_summary`（duration、turns、tool\_calls、tokens、cost、files\_created、skills\_invoked、failure\_attribution）。
## 一次评估内部：Docker 隔离 + 双 Agent + rubric
理解这一段能帮你判断评估结果是否可信。`comet eval ... --html` 内部按 `treatment × task × reps` 跑，每次运行：
```mermaid theme={null}
flowchart TD
A["注入 treatment
(Skills + CLAUDE.md)"] --> B["构建隔离 Docker 环境
(每个 task 的 Dockerfile)"]
B --> Interact{"interaction.mode?"}
Interact -->|none / generic| C1["单轮：claude -p 跑完"]
Interact -->|auto_user / comet、authoring| C2["多轮双 Agent 循环
被测 Agent + 用户模拟 Agent"]
C1 --> D["解析 stream-json 事件"]
C2 --> D
D --> E["跑任务校验器
(target_artifacts + test_scripts)"]
E --> F["跑 profile rubric
输出 [RUBRIC] 各维度分"]
F --> G["计算失败归因
harness/workflow/task/model"]
G --> H["写 report.json + summary"]
```
一次真实评估会在隔离环境里运行 Agent 互动，再用校验器和 rubric 记录证据
关键点：
* 模型在 **Docker 容器**里运行，和你的工作目录隔离。
* **双 Agent 循环**（`auto_user` 模式）：被测 Agent 跑被测 Skill，每个决策点由**用户模拟 Agent**回复（批准合理方案、选默认、推动前进，永不拒绝、不写代码）。被测 Agent 用 `--resume` 续接同一会话，最多 `max_turns` 次外层往返（comet-workflow 通常 12 次、authoring-skill 通常 8 次），命中"完成"提前结束。这里的 `max_turns` 不是被测 Agent 内部消息数或工具调用数。这让多阶段工作流能**自动跑完整条链**。完整循环和决策点检测见[评分指标与双 Agent 评测](/zh/eval/scoring)。
* **rubric 评分**在校验器之后跑，把结果作为 `[RUBRIC]` 信息性检查追加（comet-workflow rubric 永不产生硬失败；generic/authoring 对特定缺失项产生硬失败）。
* 真正的**通过/失败**由任务校验器（expected artifacts 存在 + test\_scripts 通过）决定，rubric 分和 pass\@k 是诊断信息。
## 报告输出配置
报告输出由 `ReportOutputConfig` 控制，优先级：
1. `--report-config `（JSON 或 YAML）
2. `COMET_EVAL_REPORT_CONFIG` 环境变量
3. 默认（只 markdown）
配置格式（顶层或嵌套都接受）：
```json theme={null}
{ "report_outputs": { "markdown": true, "html": false } }
```
`--html` 等价于 `{"markdown": true, "html": true}`，会写一个临时文件传给 pytest。
## 失败归因
报告会帮助区分失败来源。归因逻辑（`attribution.py`）按这个顺序判断每个失败的 check：
| 归因 | 判断条件 | 下一步 |
| ---------- | ---------------------------------------------------------------------------- | ------------------------ |
| `harness` | required skill 完全没被调用；或 generic profile 且没 skill 运行 | 检查依赖、Docker、网络或本地环境 |
| `task` | check 涉及 artifact path / validator / task directory | 检查 eval 任务定义和 fixture |
| `workflow` | check 涉及 `.comet.yaml` / guard / state / transition / archive；或 skill 调用契约失败 | 回到 `/comet-any` 优化 Skill |
| `model` | 其他默认兜底（任务在可观察的工作流执行后失败） | 重跑或降低对非确定行为的依赖 |
这个归因用于判断下一步应该修 Skill、修 eval 配置，还是重跑环境。详见[读取评估报告](/zh/eval/reports)。
## 环境变量参考
| 变量 | 作用 |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` | **必需**，两者都没有时 suite 跳过 |
| `BENCH_CC_MODEL` | 覆盖 Claude 模型 |
| `BENCH_CC_VERSION` | Docker 镜像里的 Claude Code 版本（默认 `latest`） |
| `BENCH_SIMULATOR_PROMPT_FILE` | 自定义用户模拟器提示词文件（默认 `eval/simulator-instruction.md`，相对路径从 `eval/` 解析）。`--simulator-prompt` 命令行参数优先级更高 |
| `BENCH_LLM_JUDGE=1` | 启用可选的 LLM-as-judge 覆盖评分 |
| `COMET_EVAL_REPORT_CONFIG` | 报告输出配置路径 |
| `BENCH_SUITE_ROOT` / `BENCH_TASKS_DIR` / `BENCH_TREATMENTS_DIR` / `BENCH_SKILLS_DIR` / `BENCH_LOGS_DIR` | 路径覆盖 |
| `BENCH_TEST_CONTEXT` / `BENCH_TEST_RESULTS` | 覆盖 host↔Docker 传输文件名 |
LangSmith suite 额外需要 `LANGSMITH_API_KEY`、`LANGSMITH_TRACING=true`、`TRACE_TO_LANGSMITH=true`。用户入口是 `comet eval --suite langsmith`；不需要手工进入 `eval/langsmith/` 执行 pytest。
Langfuse suite 需要 `LANGFUSE_PUBLIC_KEY` 和 `LANGFUSE_SECRET_KEY`。用户入口是 `comet eval --suite langfuse`；`--collect --suite langfuse` 不初始化 SDK、不联网，也不会下载插件。
### 用 Anthropic 兼容代理认证
当 `ANTHROPIC_API_KEY` 未设置时，Docker 内的 `claude` 改用 **Anthropic 兼容代理**（BigModel / mimo / OpenRouter 等）认证。需要的变量：
| 变量 | 作用 |
| --------------------------------------------------------------------------------------------------- | ------------------ |
| `ANTHROPIC_AUTH_TOKEN` | 代理型认证 token |
| `ANTHROPIC_BASE_URL` | 代理的 Anthropic 兼容端点 |
| `ANTHROPIC_MODEL` | 默认模型 |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` | 各档位模型映射 |
| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` / `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | 各档位模型显示名 |
| `CLAUDE_CODE_SUBAGENT_MODEL` | 子 agent 模型 |
这些变量在自动生成的用户级 `.env` 模板里都有占位项。普通用户编辑
`%USERPROFILE%\\.comet\\eval\\.env` / `~/.comet/eval/.env` 即可；源码维护者使用
`--project` 时，才需要在对应源码 checkout 中调试 harness 的 `eval/.env`。
### 自定义用户模拟器提示词
`auto_user` 模式评测里，用户模拟 Agent 的指令由一个提示词文件驱动。默认读 `eval/simulator-instruction.md`：
```text theme={null}
You are simulating a developer user in an automated eval. ...
- Approves the proposed approach / name / plan when asked to confirm
- Picks the most reasonable default option when asked to choose
- Asks for clarification only if the question is truly ambiguous ...
Never refuse; always let the workflow move forward. Do not write code or files.
```
如果你想换一套用户行为（比如更挑剔、会要求澄清更多），把你的版本写到一个文件，再用 `BENCH_SIMULATOR_PROMPT_FILE` 指向它：
```bash theme={null}
# 用户级 ~/.comet/eval/.env
BENCH_SIMULATOR_PROMPT_FILE=my-simulator-prompt.md
```
相对路径从 `eval/` 解析；文件存在才会被读取。命令行 `--simulator-prompt "..."` 的优先级最高，会覆盖文件内容。详见[评分指标与双 Agent 评测 · 用户模拟 Agent 的指令](/zh/eval/scoring#用户模拟-agent-的指令)。
## 不要把 harness 和 runtime check 混淆
`comet eval` 和 `comet skill check` 名字接近，但用途不同：
* `comet eval`：评估一个 Skill 包或 `comet/eval.yaml`，回答"这个 Skill 作为产品能力能不能通过评估"。
* `comet skill check`：检查某次 Skill 运行是否缺 artifact 或状态，回答"这次运行是否完整"。
详见 [Runtime check](/zh/eval/runtime)。
## 下一步
* [评分指标与双 Agent 评测](/zh/eval/scoring) — rubric 维度细则、pass\@k/pass^k、双 Agent 交互循环
* [读取评估报告](/zh/eval/reports) — 学会看懂报告信号和失败归因
* [comet eval 命令](/zh/cli/eval) — 完整选项和子命令参考
* [评估系统概览](/zh/eval/overview) — eval 在流程中的位置和 eval.yaml 格式