跳转到主要内容
Benchmarks 定义“评测什么”。它们负责 dataset、task id、task filtering、task material preparation、scoring logic 和 aggregate metrics。 Benchmark 应保持 provider-neutral。如果任务需要 Docker image、snapshot、workspace root 或 resource hint，应写入 task metadata，再由 recipe 适配到具体 environment。

​
Benchmarks 负责什么

任务加载

从数据集、本地文件、服务或 benchmark-specific repository 加载 TaskSpec。

任务选择

应用通用 sample_ids filtering，以及 category、split 等 benchmark-specific 参数。

任务准备

把原始 task 转成包含 prompt、media、files、tools、workspace 和 metadata 的 PreparedTask。

评分

对 RunResult 评分，写 per-task details，并聚合成 summary.md。
Benchmark 不运行 agent、不调用 model API，也不管理 provider session。这些分别属于 harness 和 environment。

​
核心接口

Method职责
load_tasks(req)返回当前 request 下所有候选 TaskSpec。
select_tasks(tasks, req)应用 sample_ids 和 benchmark-specific filtering。
build_plan(task, req, environment)为单任务添加 benchmark-side execution metadata。
prepare_task(task, env, req, plan)为 harness 准备 task input。
evaluate(task, prepared, result, req, plan, env)对 harness result 评分并返回增强后的 RunResult。
aggregate_metrics(results, req, config)生成 run-level metrics。

​
数据对象

Object含义
TaskSpec标准化 dataset row，包含 task_id、question、category、ground truth 和 metadata。
TaskInput暴露给 harness 的 prompt、system prompt、media、files、workspace、tools 和 messages。
TaskOutput期望答案或输出文件。
PreparedTask单次 attempt 前已解析好的任务材料。
RunResultharness 输出经过 benchmark scoring 和 metadata enrichment 后的结果。

​
用法：选择单个任务

agentcompass run \
  swebench_verified \
  mini_swe_agent \
  your-model \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
sample_ids 是通用 runtime filtering。它匹配 TaskSpec.task_id，如果 id 不存在会 fail fast。

​
用法：运行一个类别

agentcompass run \
  screenspot \
  qwen3vl_gui \
  qwen3-vl \
  --env <env-provider> \
  --benchmark-params '{"category":"desktop"}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat
category 的语义由 benchmark 定义。对 ScreenSpot 来说，它选择 GUI grounding 子集；其它 benchmark 的支持参数请看对应 reference 页面。

​
Tag 词表

公开文档中的 benchmark 页面按字母序排列。能力维度是 tag，不是互斥分类，因此一个 benchmark 可以同时匹配多个方向。
Tag含义
Agentic Coding仓库修复、代码生成、科学代码或软件工程 workflow。
Deep Research浏览密集、research-agent、general assistant 或 judge-scored research 任务。
GUI Grounding截图、视觉定位或 GUI target-localization 任务。
Productivity长程交付、经济价值任务、skill execution 或 workflow completion。
Terminal在 shell 或 task-specific terminal workspace 中执行命令行任务。
Tool Use显式使用工具、代码执行、web action、文件或终端命令。
Judge-Scored使用 judge model 或 benchmark-specific judging flow 评分。
Verified大 benchmark 的 curated/verified subset。
各 benchmark 的参数说明和运行示例见 Benchmark 参考。

​
开发者说明

当 dataset、scoring 或 task preparation 与现有 benchmark 有实质差异时，新增 benchmark。不要为了改变 provider 设置而新增 benchmark；那应该放在 environment config 或 recipe 中。

​
实现 Checklist

  • 定义稳定 id 和可读 description。
  • load_tasks 返回稳定 public task_id。
  • scoring 字段不要隐藏在 harness-private 假设里。
  • provider hints 放在 task metadata，不直接调用 provider SDK。
  • 支持用 sample_ids 复现单任务。
  • details 中保留足够信息，方便不 rerun 就调试失败。

​
相关页面