配置评估与自定义 Task

comet eval 开箱即用就能评测内置任务和任意本地 Skill。但当你想评测自己的 Skill 在自己的场景下表现如何时，就需要自定义 task 了。这篇文章手把手带你走完一遍：从定义一个 task，到配置评估 profile，再到跑出报告。

如果你还没跑过 eval，先看评估任意 Skill · 快速上手把环境装好。本文假设你已经能跑通 comet eval —collect。

本页怎么读

自定义 eval 可以分三层理解。大多数场景先完成 Task，再按需要调整 Profile 或 Treatment。

层级	你要决定什么	必读程度
Task	测什么、给 Agent 什么指令、用什么脚本判定通过	必读
Profile	用 generic、comet-workflow 还是 authoring-skill 评分	常用
Treatment	是否做 A/B 对比、是否加入无 Skill 基线	进阶

最短路径是：写一个 task 目录，注册到 index.yaml，先跑 --collect，再跑 --html。Profile、Treatment 和 auto_user 都可以在第一版 task 跑通后再调整。

eval 配置的全景

一个完整的 eval 由三部分拼起来，理解它们的分工是自定义的基础：

小鱼把 Task、Treatment 和 Profile 配置卡片放入 run 托盘，并整理 score、report 和失败归因输出

Task 决定测什么，Treatment 决定注入什么，Profile 和 Rubric 决定怎么打分

配置	回答的问题	位置
Task	测什么场景？要产出什么？怎么验证对了没？	`local/tasks/<name>/`
Treatment	这次跑注入哪些 Skill（含无 Skill 基线）？	`local/treatments/`
Profile + Rubric	按什么维度打分？	task.toml 的 `[evaluation]`

下面分别讲清楚。

定义一个 Task

每个 task 是 local/tasks/ 下的一个目录，包含四个文件：

local/tasks/my-task/

task.toml

instruction.md

environment/

Dockerfile

validation/

test_my_task.py

Task 目录约定来自 eval harness（eval/），不是你的业务仓库。自定义 task 放在 Comet 仓库的 eval/local/tasks/ 下，注册到 eval/local/tasks/index.yaml。

1. 编写 `task.toml`

task.toml 是 task 的核心配置，分四块：

[metadata]
name = "my-task"
description = "创建一个 markdown 结果文件"
difficulty = "medium"           # easy / medium / hard
category = "generic"            # generic 或 comet
default_treatments = ["CONTROL"]

[environment]
description = "验证环境"
dockerfile = "environment/Dockerfile"
timeout_sec = 600               # Docker 执行超时（秒）

[validation]
test_scripts = ["test_my_task.py"]   # Docker 内运行的验证脚本
target_artifacts = ["result.md"]     # 预期产物（存在性检查）
timeout = 120                        # 验证脚本超时（秒）

[evaluation]
profile = "generic"                       # 评估 profile
expected_artifacts = ["result.md"]        # rubric 检查的产物
required_skills = ["my-skill"]            # 必须调用的 Skill
require_skill_invocation = true           # 未调用时产生硬失败

# 自定义 rubric 标准（传给 LLM judge，可选）
rubric_criteria = [
    "输出包含错误处理",
    "代码遵循项目命名规范",
]

[interaction]
mode = "none"                   # none（单轮）或 auto_user（多轮模拟）
max_turns = 12                  # auto_user 下 subject/simulator 外层往返上限

各块的作用：

块	作用
`[metadata]`	task 的身份信息。`category = "comet"` 或名字以 `comet-` 开头会自动推断为 `comet-workflow` profile
`[environment]`	验证跑在什么 Docker 环境里，超时多久
`[validation]`	用哪些脚本验证、预期哪些产物
`[evaluation]`	用哪个 profile 打分、必须调用哪些 Skill、自定义评判标准
`[interaction]`	单轮还是多轮模拟交互

`[evaluation]` 的关键字段

这几个字段直接决定打分结果，值得单独说明：

字段	作用
`profile`	选 rubric：`generic`（7 维）/ `comet-workflow`（9 维）/ `authoring-skill`（11 维）。维度细节见评分指标与双 Agent 评测
`expected_artifacts`	rubric 的 `artifact_presence` 维度会检查这些产物是否存在（支持 glob）
`required_skills`	列出必须调用的 Skill；`skill_invocation` 维度据此打分
`require_skill_invocation`	设为 `true` 时，必需 Skill 未被调用会产生硬失败（直接判这次运行不通过）
`rubric_criteria`	自定义评判标准，传给 LLM judge 作为额外维度（`custom_0`、`custom_1`……）

require_skill_invocation: true 很有用但要慎用：它要求 agent 真实调用了指定 Skill（从 Claude Code 事件里读，不是从产物反推）。如果你的 Skill 名写错了或没注入，每次运行都会硬失败。

2. 编写 `instruction.md`

这是给 agent 的任务指令，支持 {run_id} 等模板变量：

在当前工作区创建一个文件 `result.md`。

要求：
- 包含标题 `# My Task Result`
- 描述你的实现思路
- 包含至少三个要点

3. 编写验证脚本

验证脚本在 Docker 内运行，结果写入 _test_results.json。这是”这次运行到底做对没”的判定来源：

from pathlib import Path
from scaffold.python.validation.core import write_test_results

def main():
    passed = []
    failed = []

    # 检查产物是否存在
    result = Path("result.md")
    if not result.exists():
        write_test_results({"passed": [], "failed": ["result.md missing"]})
        return

    text = result.read_text(encoding="utf-8")

    # 检查内容
    if "# My Task Result" in text:
        passed.append("heading present")
    else:
        failed.append("heading missing")

    write_test_results({"passed": passed, "failed": failed})

if __name__ == "__main__":
    main()

一次运行”通过”的定义很明确：验证脚本报告的 failed 列表为空。pass@k 和 pass^k 都基于这个判定。

4. 编写 Dockerfile

Dockerfile 提供验证所需的运行时和依赖。一个最小例子：

FROM python:3.11-slim

WORKDIR /workspace
# 安装验证脚本需要的依赖（如果有）
# COPY requirements.txt .
# RUN pip install -r requirements.txt

agent 产出的代码和你的验证脚本会在构建好的镜像里运行。

5. 注册 task

最后在 local/tasks/index.yaml 里登记：

tasks:
  - name: my-task
    category: generic
    default_treatments:
      - CONTROL
    description: 我的自定义任务

注册后就能用 --task my-task 跑它了。

配置 Treatment

Treatment 回答”这次跑注入哪些 Skill”。位于 local/treatments/：

# local/treatments/common/control.yaml
CONTROL:
  description: "无 Skill 基线"
  skills: []

# local/treatments/comet/comet_full_040_beta.yaml
COMET_FULL_040_BETA:
  description: "完整 Comet 工作流"
  skills:
    - name: comet
      skill: 040-beta/comet
      variant: all
      base: benchmarks

Treatment	含义
`CONTROL`	无 Skill 基线——不注入任何 Skill，测的是 agent 裸跑的能力下限
`COMET_FULL_040_BETA`	注入完整 Comet 工作流 Skill 包
自定义	注入你自己的 Skill，用来对比”有 Skill vs 无 Skill”

对比实验的标准做法是 CONTROL（无 Skill）vs 你的 Skill treatment。两者的差值就是你的 Skill 带来的增益。

选择 Profile

Profile 决定用哪套 rubric 打分。选错了 profile，维度分就没有参考价值：

Profile	适合	维度数	交互模式
`generic`	任意通用 Skill 冒烟	7	`none`（单轮）
`comet-workflow`	经典 `/comet` 五阶段	9	`auto_user`（多轮）
`authoring-skill`	`/comet-any` 生成物	11	`auto_user`（多轮）

Profile 解析优先级：—profile 覆盖 > manifest 的 skill.profile > task 的 evaluation.profile > generic。Comet 类任务（category = “comet”）会自动推断为 comet-workflow。

三套 rubric 的维度、权重和检查逻辑见评分指标与双 Agent 评测。

多轮交互：`auto_user` 模式

单轮 task（mode: none）只跑一次，适合”给个指令看结果”的简单场景。但工作流类 Skill 需要在决策点暂停、问用户、拿到回复后继续——单轮测不了。 auto_user 模式解决这个问题：它用两个 Agent 自动交互——一个跑被测 Skill（subject），另一个模拟用户在决策点回复（simulator）。模拟器的行为由提示词文件控制。默认读 eval/simulator-instruction.md，你可以用 BENCH_SIMULATOR_PROMPT_FILE 指向自己的版本，模拟”更挑剔的用户”或”会要求澄清的用户”：

export BENCH_SIMULATOR_PROMPT_FILE=my-simulator-prompt.md

max_turns 控制循环上限（comet-workflow 通常 12 次外层往返，authoring-skill 通常 8 次外层往返）。它不是被测 Agent 内部消息数或工具调用数；一次外层往返指被测 Agent 到达决策点、用户模拟器回复、被测 Agent 用 --resume 继续。命中”完成”信号（如 archive complete）会提前结束。

一次完整的自定义评估

把上面几步串起来，从零评测自己的 Skill：

# 1. 定义 task（按上面四文件 + 注册 index.yaml）

# 2. 先 collect 排错，不消耗 token
comet eval --task my-task --collect

# 3. 真正跑（注入你的 Skill treatment）
comet eval --task my-task --treatment MY_SKILL --html

# 4. 看报告
# eval/local/logs/experiments/<experiment-id>/summary.html

报告里重点看三件事：

pass@1 和 pass^k：能力上限 vs 可靠性下限。详见评分指标。
rubric 各维度分：哪个维度拖了后腿？
失败归因（harness/workflow/task/model）：失败是 Skill 的问题，还是 task/环境的问题？

评测 `/comet-any` 生成的包

/comet-any 生成的 Skill 包自带 comet/eval.yaml manifest，不需要你手写 task.toml。直接用 manifest 跑：

# 发现预检查
comet eval ./generated-skill/comet/eval.yaml --collect

# 真正评估
comet eval ./generated-skill/comet/eval.yaml --html

manifest 会自动选 authoring-skill profile、注入推荐任务和质量门禁。manifest 的完整格式见评估系统概览。

下一步

评分指标与双 Agent 评测 — 三套 rubric 的维度、权重和 pass@k/pass^k
评估系统概览 — manifest 格式、profile 体系和 task 系统
comet eval 命令 — 命令行参数完整参考

​本页怎么读

​eval 配置的全景

​定义一个 Task

​1. 编写 task.toml

​[evaluation] 的关键字段

​2. 编写 instruction.md

​3. 编写验证脚本

​4. 编写 Dockerfile

​5. 注册 task

​配置 Treatment

​选择 Profile

​多轮交互：auto_user 模式

​一次完整的自定义评估

​评测 /comet-any 生成的包

​下一步

本页怎么读

eval 配置的全景

定义一个 Task

1. 编写 `task.toml`

`[evaluation]` 的关键字段

2. 编写 `instruction.md`

3. 编写验证脚本

4. 编写 Dockerfile

5. 注册 task

配置 Treatment

选择 Profile

多轮交互：`auto_user` 模式

一次完整的自定义评估

评测 `/comet-any` 生成的包

下一步