> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 评测基准

> Benchmark 的数据加载、任务选择、材料准备、评分和聚合职责。

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 负责什么

<CardGroup cols={2}>
  <Card title="任务加载" icon="list-checks">
    从数据集、本地文件、服务或 benchmark-specific repository 加载 `TaskSpec`。
  </Card>

  <Card title="任务选择" icon="filter">
    应用通用 `sample_ids` filtering，以及 category、split 等 benchmark-specific 参数。
  </Card>

  <Card title="任务准备" icon="package-open">
    把原始 task 转成包含 prompt、media、files、tools、workspace 和 metadata 的 `PreparedTask`。
  </Card>

  <Card title="评分" icon="badge-check">
    对 `RunResult` 评分，写 per-task details，并聚合成 `summary.md`。
  </Card>
</CardGroup>

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 后的结果。                 |

## 用法：选择单个任务

```bash theme={null}
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。

## 用法：运行一个类别

```bash theme={null}
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 参考](/zh/reference/benchmarks/overview)。

## 开发者说明

当 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 就调试失败。

## 相关页面

* [Benchmark 参考](/zh/reference/benchmarks/overview)
* [Data Protocol](/zh/developer/data_protocol)
* [Runtime Extensions](/zh/developer/runtime_extensions)