mini-swe-agent 单实例 SWE-bench 运行脚本 swebench-single 完全指南

导读

swebench-single 是 mini-swe-agent 提供的用于在单个 SWE-bench 任务实例上运行 Agent 的 CLI 入口，专为调试、复现与分析设计：你可以用实例 ID（如 sympy__sympy-15599）或索引号精确定位某一条 issue，并在交互式提示下观察 Agent 逐步完成修复。读完本文，你将掌握该脚本的全部命令行参数、默认配置（swebench.yaml）的行为语义、源码级执行链路（从数据集加载到环境拉起、Agent 运行、轨迹保存），以及如何借助测试用例验证你的用法。

---

一、脚本定位：单实例调试 vs 批量评测

在 mini-swe-agent 的 SWE-bench 支持中，官方提供了两个互补的脚本（见 SWE-bench 使用指南）：

脚本	入口	适用场景
swebench（批量）	mini-extra swebench	在全部/筛选的任务实例上并行运行，产出 preds.json 评测文件
swebench-single（单实例）	mini-extra swebench-single	在单个任务实例上运行，带交互性，适合调试

两者共享同一套数据源与环境构建逻辑：swebench_single.py 从 swebench.py 导入 DATASET_MAPPING 与 get_sb_environment。但二者有一个关键区别：单实例模式不会生成 preds.json，它只输出单条轨迹文件（trajectory），因此不能被直接拿去 SWE-bench 评测——它的价值在于让你"看见"Agent 如何思考、如何执行命令、如何收敛到最终补丁。

从源码结构看（swebench_single.py），该脚本是一个基于 typer 的独立命令应用，main 函数即 CLI 入口，因此既可经 mini-extra swebench-single 调用，也可直接 python src/minisweagent/run/benchmarks/swebench_single.py 执行。

---

二、快速上手：两条最常用的运行命令

先查看帮助：

mini-extra swebench-single --help
# 或直接运行源码入口
python src/minisweagent/run/benchmarks/swebench_single.py --help

按实例 ID 运行（推荐，结果可复现）：

mini-extra swebench-single \
    --subset verified \
    --split test \
    --model anthropic/claude-sonnet-4-5-20250929 \
    -i sympy__sympy-15599

按索引运行（第 0 个实例）：

mini-extra swebench-single \
    --subset verified \
    --split test \
    -m anthropic/claude-sonnet-4-5-20250929 \
    -i 0

⚠️ Docker 架构注意：SWE-bench 官方 Docker 容器假定 x86 Linux 架构，在其他 CPU 架构（如 ARM）上可能无法运行。

💡 如果不希望在 Agent 结束任务时弹出确认提示，请追加 --exit-immediately 标志（下文详述）。

---

三、命令行参数全解

以下参数定义直接取自 swebench_single.py 的 typer 声明，按功能面板归类：

数据选择（Data selection）

参数	默认值	说明
--subset	lite	SWE-bench 子集名称，或一个可直接被 datasets.load_dataset 加载的本地/远程数据集路径
--split	dev	数据集的 split 名称（如 dev、test）
-i, --instance	0	SWE-bench 实例 ID（如 sympy__sympy-15599）或实例索引（数字）

基础（Basic）

参数	默认值	说明
-m, --model	None	使用的模型名称（如 anthropic/claude-sonnet-4-5-20250929）
-c, --config	swebench.yaml（内置基准配置）	配置文件路径/文件名/键值对，可多次指定，多个配置会递归合并
-o, --output	全局配置目录下的 last_swebench_single_run.traj.json	输出轨迹文件路径

高级（Advanced）

参数	默认值	说明
--model-class	None	模型类，如 'anthropic' 或完整路径 minisweagent.models.anthropic.AnthropicModel
--agent-class	None	Agent 类，如 'interactive' 或完整路径 minisweagent.agents.interactive.InteractiveAgent
--environment-class	None	环境类，如 'docker' 或完整路径 minisweagent.environments.docker.DockerEnvironment；推荐 docker 或 singularity
-y, --yolo	False	跳过确认直接运行
-l, --cost-limit	None	成本上限；设为 0 表示禁用
--exit-immediately	False	Agent 想结束时立即退出，不再弹出交互确认

关于 -c/--config 的关键行为（务必注意）

-c 的帮助文本中有一条红色警告（见 swebench_single.py）：

IMPORTANT: 如果你设置了该选项，默认配置文件将不再被使用。 因此你需要显式地把默认配置也带上，例如 -c swebench.yaml <其他选项>。

常见错误示例（缺少默认配置文件）：

# ❌ 错误：这样会丢掉 swebench.yaml 中的提示词模板、步数限制等全部默认设置
mini-extra swebench-single -c model.model_kwargs.temperature=0 ...

正确写法（默认配置 + 覆盖项，多个配置递归合并，后者优先）：

# ✅ 覆盖模型温度
mini-extra swebench-single -c swebench.yaml -c model.model_kwargs.temperature=0.5 ...

# ✅ 切换 Agent 模式
mini-extra swebench-single -c swebench.yaml -c agent.mode=yolo ...

这里的"配置文件解析"由 config/init.py 实现：get_config_from_spec 会先判断 spec 中是否含 =，若含则按 a.b.c=value 的点分路径解析为嵌套字典（值优先按 JSON 解析）；否则调用 get_config_path 依次在 MSWEA_CONFIG_DIR、内置 config/、config/extra/、config/benchmarks/ 中查找 .yaml 文件。合并逻辑见 serialize.py 的 recursive_merge：后续字典覆盖先前字典、嵌套字典递归合并、UNSET 哨兵值被跳过——这正是"命令行覆盖默认配置"机制的底层原理。

---

四、默认配置：swebench.yaml 的核心语义

脚本默认加载 swebench.yaml，它决定了单实例运行时的完整行为。理解它比记住每个参数更重要，因为命令行参数本质上只是对这份配置的覆盖。

agent 段：任务提示词与运行限制

instance_template 使用 Jinja2 模板把任务的 PR 描述（{{task}}）注入系统提示，并给出完整任务指令：要求模型持续与 shell 交互、只修改非测试文件、先复现问题再修复再验证，最终以 git diff 生成补丁并以精确命令 echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT && cat patch.txt 提交。

agent:
  step_limit: 250        # 最大交互步数
  cost_limit: 3.         # 成本上限（美元）

environment 段：容器化运行环境

environment:
  cwd: "/testbed"                        # Agent 的工作目录
  timeout: 60                            # 单条命令超时（秒）
  interpreter: ["bash", "-c"]
  env:
    PAGER: cat
    MANPAGER: cat
    LESS: -R
    PIP_PROGRESS_BAR: "off"
    TQDM_DISABLE: "1"
    BASH_ENV: /root/.bashrc              # 确保容器内 conda activate testbed 生效
  environment_class: docker

BASH_ENV 的注释点出了一个容器细节：bash -c 是非登录 shell，不会自动 source ~/.bashrc，而 SWE-bench 镜像依赖 /root/.bashrc 中的 conda activate testbed 激活正确 Python 环境，因此必须显式指向它。

model 段：观察模板与默认模型

model:
  model_name: "anthropic/claude-sonnet-4-5-20250929"
  model_kwargs:
    drop_params: true
    parallel_tool_calls: true

observation_template 控制命令执行结果的回显格式：正常输出嵌入 <output> 标签；若命令输出超过 10000 字符，则折叠为"头部 5000 字符 + 中间省略计数 + 尾部 5000 字符"并附带警告，防止长输出淹没模型的上下文。format_error_template 则处理两种失败模式：输出 token 用尽（finish_reason == "length"）时提示模型更简洁并恰好以一次 bash 调用收尾；普通工具调用格式错误时给出通用纠错指引。

---

五、源码级执行链路：从数据集到轨迹文件

结合 swebench_single.py 的 main 实现，一次运行共经历五步：

1. 解析 subset 并加载数据集

dataset_path = DATASET_MAPPING.get(subset, subset)
instances = {
    inst["instance_id"]: inst
    for inst in load_dataset(dataset_path, split=split)
}

DATASET_MAPPING（定义于 swebench.py）提供常用别名：

别名	Hugging Face 数据集
full	princeton-nlp/SWE-Bench
verified	princeton-nlp/SWE-Bench_Verified
lite	princeton-nlp/SWE-Bench_Lite
multimodal	princeton-nlp/SWE-Bench_Multimodal
multilingual	swe-bench/SWE-Bench_Multilingual
smith	SWE-bench/SWE-smith
rebench	nebius/SWE-rebench
_test	klieret/swe-bench-dummy-test-dataset（内部测试用）

不在映射中的 --subset 值会被原样当作数据集路径传给 load_dataset，因此只要数据集遵循 SWE-bench 字段格式（含 instance_id、problem_statement），即可跑自定义数据集。

2. 解析实例选择：ID 或索引

if instance_spec.isnumeric():
    instance_spec = sorted(instances.keys())[int(instance_spec)]
instance = instances[instance_spec]

数字被解释为按 instance_id 排序后的下标，非数字则直接作为 ID 查询；查不到会抛 KeyError。

3. 合并配置：CLI 参数 → 嵌套配置

configs = [get_config_from_spec(spec) for spec in config_spec]
configs.append({
    "agent": {
        "agent_class": agent_class or UNSET,
        "mode": "yolo" if yolo else UNSET,
        "cost_limit": cost_limit if cost_limit is not None else UNSET,
        "confirm_exit": False if exit_immediately else UNSET,
        "output_path": output or UNSET,
    },
    "model": {"model_class": model_class or UNSET, "model_name": model_name or UNSET},
    "environment": {"environment_class": environment_class or UNSET},
})
config = recursive_merge(*configs)

注意 UNSET 的用法：未显式指定的 CLI 参数以 UNSET 占位，recursive_merge 会跳过它们，从而不覆盖配置文件中的既有值。这里有一个值得注意的实现细节——exit_immediately 会设置 agent.confirm_exit: False（而非直接设置"退出"动作），而 --exit-immediately 对交互行为的实际生效还依赖 Agent 实现（交互式 Agent 在结束时会询问用户是否确认退出，置 False 即跳过询问）。

测试 test_swebench_single.py 专门验证了 cost_limit=0 在合并后仍被保留（assert mock_get_agent.call_args.args[2]["cost_limit"] == 0）——因为 0 是有效值（表示禁用成本上限），若用 cost_limit or UNSET 这类写法就会被误判为空值而丢弃，源码特意写成 if cost_limit is not None，这正是"显式 0 不丢失"的保障。

4. 构建环境并启动 Agent

env = get_sb_environment(config, instance)
agent = get_agent(get_model(config=config.get("model", {})), env, config.get("agent", {}), default_type="interactive")
agent.run(instance["problem_statement"])

环境构建复用 swebench.py 的 get_sb_environment（swebench.py），其逻辑包括：

• 默认 environment_class 为 docker；
• 镜像名推断：优先取实例自带的 image_name 或 docker_image 字段；否则由 instance_id 生成 docker.io/swebench/sweb.eval.x86_64.<instance_id>:latest（Docker 不允许双下划线，故 __ 会被替换为魔法 token _1776_）；
• 环境类适配：docker / swerex_modal 直接使用镜像名，singularity / contree 则前缀 docker://；
• 若配置中存在 run.env_startup_command，会用 Jinja2 以实例字段为模板变量渲染并预先在环境中执行（如 git clone {{ repo_url }} . --force），返回码非 0 则抛错中止。

与批量脚本不同，单实例模式的默认 Agent 类型是 interactive（见 default_type="interactive"），这正是其"交互调试"定位的体现。

5. 运行与输出

Agent 收到 problem_statement（issue 描述）后开始迭代：思考 → 执行 bash 命令 → 观察输出 → 继续，直至提交补丁或触及 step_limit/cost_limit。运行结束后轨迹默认保存为：

<全局配置目录>/last_swebench_single_run.traj.json

可通过 -o 自定义路径。测试 test_swebench_single.py 展示了端到端验证方式：使用 _test 子集 + DeterministicModel（test_models.py）注入固定模型回复，断言 get_model 被调用且输出轨迹文件存在。

---

六、实践建议与 FAQ 要点

以下要点整理自 SWE-bench 使用指南 FAQ 中与单实例调试直接相关的部分：

• 首拉镜像较慢：首次运行会 docker pull 对应实例的镜像，可能长时间停留在环境初始化。第二次运行即会立即启动；若 docker pull 超时，可在配置中调大 environment.pull_timeout（默认 120 秒）。
• Docker 问题排查：控制台会打印 docker 命令，可手动执行复现；用 docker ps 确认容器在跑，用 docker exec -it <container-id> ls 验证可交互。
• HPC 上无 Docker：将 environment.environment_class 设为 singularity（命令行 --environment-class singularity 或配置文件均可），参考 环境选择指南 与 YAML 配置文档。
• 需要环境预初始化：使用 run.env_startup_command 配置项，例如 apt-get update && apt-get install -y python3-pip，或用实例字段做模板渲染（git clone {{ repo_url }} . --force），这对 bubblewrap 等轻量环境尤为有用。
• 交互确认：默认在 Agent 结束时会弹交互式确认（这也是交互式 Agent 的特性之一）；调试脚本或自动化流程中请加 --exit-immediately。

---

七、与批量脚本的差异速查

维度	swebench（批量）	swebench-single（单实例）
默认 Agent 类型	ProgressTrackingAgent 包装（见 common.py）	interactive（交互式）
实例选择	--slice / --filter / --shuffle / --redo-existing	-i（ID 或索引）
输出	目录：preds.json、<instance_id>.traj.json、minisweagent.log、exit_statuses_*.yaml	单个轨迹文件，默认 last_swebench_single_run.traj.json
并发	-w/--workers 线程池并行	单实例串行
用途	评测跑分	调试、复现、观察单条轨迹

在 tests 中可以看到单实例脚本的三类测试：配置合并保真（cost_limit=0）、确定性模型端到端、--exit-immediately 行为验证——如果你扩展或修改了该脚本，这些测试是回归保障的参照。

---

结语

swebench-single 把"在 SWE-bench 上跑一个 Agent"这一操作收敛到一条可复现、可观测的命令：通过 -i 精确定位任务、-c 递归合并配置、--exit-immediately 去除交互打扰，再配合 swebench.yaml 中的提示词与限制语义，你可以在几分钟内复现任意 SWE-bench 实例的完整修复轨迹。本文覆盖了从参数到源码、从默认配置到测试验证的完整链路，可作为继续阅读 API 参考、SWE-bench 使用指南 与 全局配置文档 的起点。