评测基准

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 前已解析好的任务材料。
`RunResult`	harness 输出经过 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 就调试失败。

快速开始

核心模块

执行环境

实战指南

Benchmarks 负责什么

任务加载

任务选择

任务准备

评分

核心接口

数据对象

用法：选择单个任务

用法：运行一个类别

Tag 词表

开发者说明

实现 Checklist

相关页面

​Benchmarks 负责什么

任务加载

任务选择

任务准备

评分

​核心接口

​数据对象

​用法：选择单个任务

​用法：运行一个类别

​Tag 词表

​开发者说明

​实现 Checklist

​相关页面

Benchmarks 负责什么

核心接口

数据对象

用法：选择单个任务

用法：运行一个类别

Tag 词表

开发者说明

实现 Checklist

相关页面