> ## 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.

# SWE-bench Pro Verified

SWE-bench Pro Verified 是 [SWE-bench Pro](/zh/user_guide/modules/benchmarks/swebench_pro) 的验证版本，针对轨迹分析中发现的两类评测可靠性问题进行修正：一是由黄金补丁或隐藏评测信息泄漏引发的奖励机制利用（reward hacking），二是误导性问题描述、测试范围不当等任务质量问题（task quality issues）（[论文](https://arxiv.org/abs/2609.08149)、[数据集](https://huggingface.co/datasets/opencompass/SWEBench-Pro-Verified)、[评测脚本](https://github.com/scaleapi/SWE-bench_Pro-os)）。

Benchmark 共包含 731 个任务。仓库重建、测试工件隐藏、元数据过滤与匿名化、网络阻断四项防作弊控制（anti-hacking）应用于全部任务；在此基础上，任务修正（task refinement）进一步处理了 102 个已确认存在质量问题的任务，包括 22 个误导性描述、75 个过窄测试、3 个过宽测试，以及 2 个其他问题。

## 工作原理

每个任务分为独立的推理和评测阶段：

1. **加载并准备任务**：AgentCompass 从数据集中读取 `instance_id`、仓库、基础提交、问题陈述、要求以及新引入的接口。provider Recipe 通常会选择任务预构建镜像，并在 `/app` 暴露仓库。
2. **应用修复后的数据**：AgentCompass 从 `opencompass/SWEBench-Pro-Verified` 的 `swebench_pro_verified.jsonl` 文件加载完整任务数据。
3. **应用防作弊控制**：AgentCompass 删除评测测试文件、将仓库重建为清除 Git 历史的全新提交，并通过黑名单阻断代码托管域名，并对 `instance_id` 等任务元数据进行过滤与匿名化。
4. **运行编程 agent**：[mini-SWE-agent](/zh/user_guide/modules/harnesses/mini_swe_agent) 或 [OpenHands](/zh/user_guide/modules/harnesses/openhands) 等 Harness 接收问题描述，在检出目录后的仓库中修改代码。使用标准 Recipe 时，最终统一差异补丁必须写入 `/app/patch.txt`。
5. **启动全新的评测环境**：推理工作区的改动不会直接用于评测。AgentCompass 从任务镜像启动新环境，把 `/app` 重置到 `base_commit`，再应用被测补丁。
6. **运行官方实例脚本**：Benchmark 从本地 `run_scripts/<instance_id>/` 加载该任务的 `run_script.sh` 与 `parser.py`；缺失时从 `SWE-bench_Pro-os` 下载。解析器把测试日志转换为结构化结果。
7. **判定是否解决**：只有所有要求的 `FAIL_TO_PASS` 与 `PASS_TO_PASS` 测试都出现在已通过测试集合中，任务才是 `resolved=true`。

### 环境

目前暂不支持在 Daytona 或 Modal 上运行本 Benchmark：这两个 provider 均不支持黑名单机制，只支持白名单或完全阻断出网（[Daytona 网络限制文档](https://www.daytona.io/docs/en/network-limits/)、[Modal 沙箱网络文档](https://modal.com/docs/guide/sandbox-networking)）。Docker 是目前唯一能够强制执行黑名单机制的公开 provider，详见[网络配置](/zh/user_guide/modules/environments/configuration/network)。

## 参数

通过 `--benchmark-params '{...}'` 传入 Benchmark 配置，或写入 `--config` 指定 YAML 的 `benchmark.params`；同名字段以命令行为准。

### 参数总览

<div style={{overflowX:'auto'}}>
  <table style={{minWidth:'1040px', width:'100%'}}>
    <colgroup>
      <col width="18%" />

      <col width="12%" />

      <col width="14%" />

      <col width="24%" />

      <col width="32%" />
    </colgroup>

    <thead>
      <tr><th style={{whiteSpace:'nowrap'}}>参数</th><th style={{whiteSpace:'nowrap'}}>类型</th><th style={{whiteSpace:'nowrap'}}>默认值</th><th>可选值 / 取值</th><th>说明</th></tr>
    </thead>

    <tbody>
      <tr><td style={{whiteSpace:'nowrap'}}><code>prepare\_mode</code></td><td>字符串</td><td><code>git\_clone</code></td><td><code>git\_clone</code> / <code>prebaked</code></td><td>推理仓库的准备方式；内置 provider Recipe 通常会改为 <code>prebaked</code>。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>workspace\_root</code></td><td>字符串</td><td><code>/app</code></td><td>环境内绝对路径</td><td>Recipe 覆盖前用于创建任务工作区的根目录。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>repo\_url\_template</code></td><td>字符串</td><td><code>[https://github.com/\&#123;repo\&#125;.git](https://github.com/\&#123;repo\&#125;.git)</code></td><td>包含 <code>\{repo}</code> 的模板</td><td><code>git\_clone</code> 模式使用的仓库克隆 URL。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>scripts\_dir</code></td><td>字符串</td><td><code>""</code></td><td>本地目录</td><td>控制器侧包含 <code>\<instance\_id>/run\_script.sh</code> 与 <code>parser.py</code> 的目录；为空时解析为数据目录下的 <code>run\_scripts/</code>。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>dockerfiles\_dir</code></td><td>字符串</td><td><code>""</code></td><td>本地目录</td><td>控制器侧官方 Dockerfile 根目录，用于恢复任务环境变量；为空时从数据目录解析。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>evaluation\_repo\_dir</code></td><td>字符串</td><td><code>/app</code></td><td>环境内绝对路径</td><td>评测镜像内的仓库路径；内置 Recipe 保持为 <code>/app</code>。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>evaluation\_workspace\_dir</code></td><td>字符串</td><td><code>/app</code></td><td>环境内绝对路径</td><td>评测时写入补丁、脚本、日志与解析器输出的目录。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>eval\_timeout</code></td><td>整数</td><td><code>3600</code></td><td>整数 ≥ 1</td><td>官方评测命令超时，单位为秒。</td></tr>
      <tr><td style={{whiteSpace:'nowrap'}}><code>sample\_ids</code></td><td>列表 / 字符串 / 空值</td><td><code>null</code></td><td>有效实例 ID</td><td>可选的精确任务过滤；出现未知 ID 时直接报错。</td></tr>
    </tbody>
  </table>
</div>

model ID 是 `agentcompass run` 的第三个位置参数，不属于 `--benchmark-params`。本 Benchmark 固定加载公开 `test` 数据划分，不提供 `split` 参数。

### 推理、model 与评测控制

| 限制对象        | mini-SWE-agent                             | OpenHands                                               | SWE-bench Pro Verified                 |
| ----------- | ------------------------------------------ | ------------------------------------------------------- | -------------------------------------- |
| 单次 model 请求 | `--model-params.timeout`（AgentCompass 未设置） | `--model-params.timeout`，否则 `conversation_timeout=3600` | —                                      |
| 单条仓库命令      | `command_timeout=2400`                     | `command_timeout=1800`；无变化软超时为 `600`                    | —                                      |
| agent 循环    | `step_limit=250`、`cost_limit=3.0`          | `max_iterations=250`                                    | —                                      |
| 整题推理        | `--harness-params.timeout=null`            | `--harness-params.timeout=9600`                         | —                                      |
| 全新官方评测      | —                                          | —                                                       | `--benchmark-params.eval_timeout=3600` |
| 多次尝试        | —                                          | —                                                       | `--k`、`--attempt-strategy`             |

`eval_timeout` 只控制补丁回收后在全新环境中执行的 `run_script.sh` 与解析器评测，不能延长推理阶段。思考/推理应写入 `--model-params`；具体协议/provider 格式见 [mini-SWE-agent](/zh/user_guide/modules/harnesses/mini_swe_agent#思考--推理配置) 或 [OpenHands](/zh/user_guide/modules/harnesses/openhands#思考--推理配置)。

## 运行示例

请把 `<instance-id>` 替换为公开数据集中的 `instance_id`。

### 推荐 Harness

[mini-SWE-agent](/zh/user_guide/modules/harnesses/mini_swe_agent) 是 SWE-bench Pro 的推荐 Harness。它使用 Benchmark 专属的 mini-SWE-agent 配置，并在任务环境中执行仓库命令。

<Tabs>
  <Tab title="冒烟测试（单条跑通）">
    运行一个任务，验证推理、补丁回收与官方评测的完整链路。

    ```bash theme={"system"}
    agentcompass run \
      swebench_pro_verified \
      mini_swe_agent \
      "$MODEL_NAME" \
      --env docker \
      --benchmark-params '{
        "sample_ids": ["<instance-id>"],
        "eval_timeout": 3600
      }' \
      --harness-params '{
        "step_limit": 250,
        "cost_limit": 3.0,
        "command_timeout": 2400,
        "timeout": 12000
      }' \
      --model-params '{
        "temperature": 0,
        "max_tokens": 32768,
        "timeout": 3600,
        "reasoning_effort": "high"
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat
    ```
  </Tab>

  <Tab title="自定义参数">
    对一个任务运行三次尝试，并自定义尝试策略、model 请求、命令、整题和评测限制。

    ```bash theme={"system"}
    agentcompass run \
      swebench_pro_verified \
      mini_swe_agent \
      "$MODEL_NAME" \
      --env docker \
      --k 3 \
      --attempt-strategy pass \
      --benchmark-params '{
        "sample_ids": ["<instance-id>"],
        "eval_timeout": 4800
      }' \
      --harness-params '{
        "step_limit": 300,
        "cost_limit": 5.0,
        "command_timeout": 2400,
        "timeout": 14400
      }' \
      --model-params '{
        "temperature": 0,
        "max_tokens": 32768,
        "timeout": 3600,
        "reasoning_effort": "high"
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat
    ```
  </Tab>

  <Tab title="AgentCompass 推荐配置">
    使用显式推理与评测限制运行完整公开数据划分；仅在 provider 容量需要时调整 `--task-concurrency`。

    ```bash theme={"system"}
    agentcompass run \
      swebench_pro_verified \
      mini_swe_agent \
      "$MODEL_NAME" \
      --env docker \
      --benchmark-params '{
        "eval_timeout": 3600
      }' \
      --harness-params '{
        "step_limit": 250,
        "cost_limit": 3.0,
        "command_timeout": 2400,
        "timeout": 12000
      }' \
      --model-params '{
        "temperature": 0,
        "max_tokens": 32768,
        "timeout": 3600,
        "reasoning_effort": "high"
      }' \
      --model-base-url "$MODEL_BASE_URL" \
      --model-api-key "$MODEL_API_KEY" \
      --model-api-protocol openai-chat \
      --task-concurrency 16
    ```
  </Tab>
</Tabs>

### 其他可选 Harness

也可以使用 [OpenHands](/zh/user_guide/modules/harnesses/openhands)。下面的单任务命令分别配置 model 请求、终端命令、agent 循环、整题推理和评测限制：

```bash theme={"system"}
agentcompass run \
  swebench_pro_verified \
  openhands \
  "$MODEL_NAME" \
  --env docker \
  --benchmark-params '{
    "sample_ids": ["<instance-id>"],
    "eval_timeout": 3600
  }' \
  --harness-params '{
    "max_iterations": 250,
    "conversation_timeout": 3600,
    "command_timeout": 1800,
    "terminal_no_change_timeout_seconds": 600,
    "timeout": 12000
  }' \
  --model-params '{
    "temperature": 0,
    "max_output_tokens": 32768,
    "timeout": 3600,
    "reasoning_effort": "high",
    "num_retries": 10,
    "retry_min_wait": 8,
    "retry_max_wait": 64,
    "retry_multiplier": 2
  }' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY" \
  --model-api-protocol openai-chat
```

## 输出

### 聚合指标

Metric Contract 声明二元指标 `correct`，其值来自 evaluator 的 `resolved` 判定。`k=1` 时产生原生序列；`k>1` 时，`avg` 会同时产生 `correct.avg@k` 和 `correct.pass@k`，`pass` 只产生 `correct.pass@k` 并可提前停止。可读结果见 `summary.md`，规范报告见 `metrics.json`。详见[指标与聚合](/zh/user_guide/other_features/results/metrics_aggregation)。

### 单任务详情（details/）

单任务详情写入 `results/swebench_pro/<model>/<run>/details/`。尝试记录包含：

| 字段                             | 含义                                                           |
| ------------------------------ | ------------------------------------------------------------ |
| `metrics.correct`              | 与 `meta.benchmark.eval_raw_data.resolved` 相同的最终解决判定。         |
| `final_answer`                 | 提交的统一差异补丁。                                                   |
| `trajectory`                   | 编程 agent 的 model/工具轨迹。                                       |
| `meta.harness.telemetry`       | 可用时保存 Harness 的工作区、退出、输出文件、Model 与超时诊断。                      |
| `meta.benchmark.eval_raw_data` | `completed`、`resolved`、要求/缺失的 F2P 与 P2P 测试、解析后的测试结果、日志和评测错误。 |

`status=completed` 本身并不等于问题已经解决。是否解决应看 `metrics.correct` 和 `meta.benchmark.eval_raw_data.resolved`；运行、解析器或评测失败则结合 `error`、Benchmark metadata 与 Harness telemetry 排查。