comet eval 时，CLI 默认使用当前 @rpamis/comet 包中的 eval/；在 Comet 源码仓库开发或需要自定义 harness 时，可以用 --project <repository-root> 显式选择该仓库的 eval/。comet eval 封装了启动路径、任务发现、profile、report config 和 quick smoke，让你不需要手工切目录或拼 pytest 参数。
harness 定位与故障边界
CLI 会先确认 eval 根目录包含pyproject.toml 和任务入口，再检查 uv。因此错误顺序可以直接帮助定位问题：
npm 用户不需要另外 clone Comet 仓库来获得 harness；包版本与 harness 版本保持一致。
harness 目录结构
它封装了什么
comet eval 在内部做这几件事：
- 固定从
<project>/eval根目录启动 harness（用uv run） - 把
--manifest或--skill-path转换成 pytest 参数 - 选择默认 profile（
generic）和 task；没有 manifest 时按 Skill 快照自动生成并缓存受限任务 - 按需生成临时 report config（
--html时） - 打印一组执行信息，便于定位报告
--suite 调用：
comet eval 会替你组装。
collect 和 run
comet eval 是单入口命令，通过 --collect 区分两个阶段：
两者共用同一套参数构建逻辑（
buildEvalArgs），唯一区别是 collect 加 --collect-only，普通执行加 -v。--suite local|langsmith|langfuse 选择入口；--report-config、--html、--quick 用于真实评估路径。
skill-path 模式（默认入口）
传一个本地 Skill 目录或SKILL.md 时，comet eval 走 skill-path，不需要 comet/eval.yaml：
--quick 则明确选择 generic-skill-smoke 冒烟任务。--skill-name 会从目录名自动推断，你也可以用 --task 显式指定任务，或用 --profile 覆盖 profile。
manifest 模式（评估 /comet-any 完整包）
--manifest 适合 /comet-any 生成物，或任何带 comet/eval.yaml 的 Skill 包：
/comet-any 自动生成（不是手写），包含目标 Skill、profile、推荐任务、预期产物和交互配置。Engine-enabled 生成物默认使用 authoring-skill profile 和 authoring-skill-smoke quick eval。这条路径的结果才是发布 readiness 的有效证据；skill-path 的 generic-skill-smoke 只是早期验证，不作为发布证据。
generated manifest 的 draft hash
manifest 的metadata.draftHash 为 <current-bundle-hash> 时，CLI 会定位上层 bundle.yaml、计算当前 draft hash，并在系统临时目录写入一份运行时 manifest。Skill source 会解析为稳定绝对路径；评估结束后临时目录会被清理。
原 manifest 和 Bundle 不会被修改。占位值只适用于仍位于 Bundle draft 内的 generated manifest；离开 Bundle 后应使用具体、可验证的 draft hash。
执行信息
comet eval 在运行前会先打印一组执行信息，让你能定位报告和排查问题：
Eval root：实际从哪个eval/根目录启动Mode：collect或runTarget：当前评估的是 manifest 还是本地 Skill 目录Experiment：本次实验 idProfile：本次评估使用的 profileTask：本次评估任务Report path：报告位置Report config：启用--html时使用的临时报告配置
run 模式还会额外提示：失败归因会被记录到生成的 eval summary 里，按 harness、workflow、task、model 四个桶分类。
报告在哪里、长什么样
Experiment ID
实际落盘的 experiment id 格式是<experiment_name>_<YYYYMMDD_HHMMSS>，例如 comet_fix_median_20260620_143000。experiment name 来自第一个参数化测试的 task name（- 转 _）。
报告目录：
summary.md 包含
- 头部：Experiment ID、开始/完成时间。
- Results 表：每个 treatment 一行，列含 Checks、Turns、Duration、Tools、Tokens、Cost、RubricAvg。
- Summary：总运行数、checks 通过 X/Y（百分比）。
- 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 跑，每次运行：
一次真实评估会在隔离环境里运行 Agent 互动，再用校验器和 rubric 记录证据
关键点：- 模型在 Docker 容器里运行，和你的工作目录隔离。
- 双 Agent 循环（
auto_user模式）：被测 Agent 跑被测 Skill，每个决策点由用户模拟 Agent回复（批准合理方案、选默认、推动前进，永不拒绝、不写代码）。被测 Agent 用--resume续接同一会话，最多max_turns次外层往返（comet-workflow 通常 12 次、authoring-skill 通常 8 次），命中”完成”提前结束。这里的max_turns不是被测 Agent 内部消息数或工具调用数。这让多阶段工作流能自动跑完整条链。完整循环和决策点检测见评分指标与双 Agent 评测。 - rubric 评分在校验器之后跑，把结果作为
[RUBRIC]信息性检查追加（comet-workflow rubric 永不产生硬失败；generic/authoring 对特定缺失项产生硬失败）。 - 真正的通过/失败由任务校验器（expected artifacts 存在 + test_scripts 通过）决定，rubric 分和 pass@k 是诊断信息。
报告输出配置
报告输出由ReportOutputConfig 控制，优先级：
--report-config <path>（JSON 或 YAML）COMET_EVAL_REPORT_CONFIG环境变量- 默认（只 markdown）
--html 等价于 {"markdown": true, "html": true}，会写一个临时文件传给 pytest。
失败归因
报告会帮助区分失败来源。归因逻辑（attribution.py）按这个顺序判断每个失败的 check：
这个归因用于判断下一步应该修 Skill、修 eval 配置，还是重跑环境。详见读取评估报告。
环境变量参考
LangSmith suite 额外需要
LANGSMITH_API_KEY、LANGSMITH_TRACING=true、TRACE_TO_LANGSMITH=true。用户入口是 comet eval <target> --suite langsmith；不需要手工进入 eval/langsmith/ 执行 pytest。
Langfuse suite 需要 LANGFUSE_PUBLIC_KEY 和 LANGFUSE_SECRET_KEY。用户入口是 comet eval <target> --suite langfuse；--collect --suite langfuse 不初始化 SDK、不联网，也不会下载插件。
用 Anthropic 兼容代理认证
当ANTHROPIC_API_KEY 未设置时，Docker 内的 claude 改用 Anthropic 兼容代理（BigModel / mimo / OpenRouter 等）认证。需要的变量：
这些变量在自动生成的用户级
.env 模板里都有占位项。普通用户编辑
%USERPROFILE%\\.comet\\eval\\.env / ~/.comet/eval/.env 即可；源码维护者使用
--project 时，才需要在对应源码 checkout 中调试 harness 的 eval/.env。
自定义用户模拟器提示词
auto_user 模式评测里，用户模拟 Agent 的指令由一个提示词文件驱动。默认读 eval/simulator-instruction.md：
BENCH_SIMULATOR_PROMPT_FILE 指向它：
eval/ 解析；文件存在才会被读取。命令行 --simulator-prompt "..." 的优先级最高，会覆盖文件内容。详见评分指标与双 Agent 评测 · 用户模拟 Agent 的指令。
不要把 harness 和 runtime check 混淆
comet eval 和 comet skill check 名字接近，但用途不同：
comet eval：评估一个 Skill 包或comet/eval.yaml，回答”这个 Skill 作为产品能力能不能通过评估”。comet skill check：检查某次 Skill 运行是否缺 artifact 或状态，回答”这次运行是否完整”。
下一步
- 评分指标与双 Agent 评测 — rubric 维度细则、pass@k/pass^k、双 Agent 交互循环
- 读取评估报告 — 学会看懂报告信号和失败归因
- comet eval 命令 — 完整选项和子命令参考
- 评估系统概览 — eval 在流程中的位置和 eval.yaml 格式