Harbor 上的 SWE-Lancer 基准适配指南:从数据集构建、任务生成到与原版评测对齐

原创2026-10-11 12:27:221,636 阅读
文章标签:人工智能大模型模型评测Agent 评测AI 评测Agent 沙箱CLI本地部署

Harbor 上的 SWE-Lancer 基准适配指南:从数据集构建、任务生成到与原版评测对齐

SWE-Lancer 是由 OpenAI 发布的真实自由职业软件工程基准,数据集源自 Upwork 上的实际任务,Harbor 通过 adapters/swelancer 适配器将其完整接入评测框架。本指南基于该适配器的 README 与仓库内源码,系统讲解 SWE-Lancer 的任务类型、Harbor 任务目录结构、harbor run / harbor trial 评测方式、任务目录生成命令,以及如何与原始 OpenAI 评测结果做 Parity 对齐。读完本文,你将掌握在 Harbor 中一键跑通 SWE-Lancer Diamond 全量 463 个任务、按 IC SWE / Manager 子集定向评测、复现官方性能数据的完整实战方案。

SWE-Lancer 基准是什么

SWE-Lancer 数据集包含来自 Upwork 的真实自由职业软件工程任务。OpenAI 仅发布了原数据集的一部分(约一半),即 SWE-Lancer Diamond,共 463 个任务,总价值约 50 万美元。该基准包含两种任务类型:

  • IC SWE(Individual Contributor,个人贡献者):模型需要在 Expensify 仓库中修复一个 git issue,共 198 个任务;
  • Manager(管理者):模型需要从若干"方案提案(proposal)"中选出最佳方案,共 265 个任务。

核心基准同时使用两类任务,合计 463 个 Harbor 任务(198 IC SWE + 265 Manager)。

任务执行模型与评分方式

在 Harbor 实例中,Agent 会拿到一个 git 仓库,必须做出必要修改来解决给定的 Expensify PR。Agent 的指令中带有一个 "user tool"(用户工具):一条运行 Ansible playbook 的命令,该 playbook 会启动 Playwright 浏览器,并通过浏览器动作复现 issue。Agent 完成修改后,grader 会运行官方提供的 pytest 测试用例进行评分,这与 SWE-Lancer 官方仓库的默认配置(提供 user tool)保持一致。

任务注记: 截至 2025/07/17,作者官方移除了 39 个(归类于 IC 任务下)需要联网才能完成的问题。为了与当前官方实现保持一致,本适配器同样不包含这些问题。

Harbor 适配特性

  • 直接复用 SWE-Lancer 官方仓库的 Docker 环境,但叠加了 Harbor 专属安装(如 tmux 等);
  • SWE-Lancer 内部使用 ansible、pytest 和 playwright 运行 SWE 单元测试(即构建 Expensify 网站并用 GUI 单元测试验证);
  • 测试使用 SWE-Lancer 作者提供的同一套 ansible 实现(针对 IC SWE 任务),Manager 任务则通过检查所选方案是否正确来判定;
  • 对仓库的多处修改(包括让 user tool 与 Agent 运行在同一命名空间)详见 注意事项 一节。

生成的任务目录结构

每次运行适配器后,每个任务都会生成如下目录结构:

swe-lancer/{task_id}/
├── task.toml                     # Harbor 任务配置
├── instruction.md                # 给 Agent 的任务指令
├── environment/                  # 容器定义(消费 SWE-Lancer 镜像)
│   ├── Dockerfile
│   └── docker-compose.yaml
├── solution/
│   └── solve.sh                  # Oracle 脚本(按任务类型生成不同内容)
└── tests/
    └── test.sh                   # Verifier 脚本(按任务类型生成不同内容)

这套结构完全由适配器源码 adapter.py 基于 task-template/ 下的模板渲染生成。模板位于 task-template,其中 swe/ 与 manager/ 分别存放两类任务的 solution/solve.sh 与 tests/test.sh。

task.toml 关键配置

模板 task.toml 定义了每个任务的运行时约束,适配器会将 {task_name} 替换为实际的 question_id:

配置项 默认值 说明
schema_version 1.0 Harbor 任务 schema 版本
[verifier] timeout_sec 3000.0 Verifier 超时(秒),约 50 分钟,为 user tool 的长耗时留足余量
[agent] timeout_sec 3000.0 Agent 超时(秒)
[environment] build_timeout_sec 3000.0 镜像构建超时
[environment] cpus / memory_mb / storage_mb 1 / 8192 / 10240 容器 CPU、内存与磁盘配额

模板渲染的核心替换逻辑

SWELancerAdapter._prepare_task_from_template() 是任务生成的枢纽,针对两类任务执行不同的渲染:

  • IC SWE 任务:用 {issue_id} 替换 test.sh 与 solve.sh 中的占位符,Dockerfile 以 swelancer/swelancer_x86_{issue_id} 为基础镜像;
  • Manager 任务:所有 Manager 任务共用同一个 monolith 容器,test.sh 与 solve.sh 中的 {selected_proposal_id} 被替换为 task.manager_data["game"]["correct_proposal"]["id"](正确方案 ID);
  • 环境变量:通过 get_compose_envs() 把 get_env_variables() 返回的字典序列化成 YAML 并注入 docker-compose.yaml 的 {environment} 占位符;
  • 任务名与指令:task.toml 的 {task_name} 与 instruction.md 的 {problem_statement} 均被逐一替换。

从 utils/dataset.py 的源码可以看到,容器环境变量还包括随机生成的 PUSHER_APP_KEY、PUSHER_APP_SECRET、PUSHER_APP_ID,以及可选的 USE_WEB_PROXY、EXPENSIFY_URL、NEW_EXPENSIFY_URL、ISSUE_ID 与 EVAL_VARIANT(ic_swe / swe_manager)。

在 Harbor 中运行评测

通过数据集注册表一键运行

在 harbor 根目录直接运行以下命令即可评测整个数据集:

# 使用 oracle agent(参考解法)
uv run harbor run -d swe-lancer-diamond@all

# 使用你指定的 agent 和模型
uv run harbor run -d swe-lancer-diamond@all -a <agent_name> -m "<model_name>"

-d(即 --dataset)参数中的 swe-lancer-diamond 是适配器注册在 registry.json 中的数据集名,支持三个版本:@all(463 个任务)、@ic(198 个 IC SWE 任务)、@manager(265 个 Manager 任务)。任务路径统一指向 datasets/swe-lancer/ 下的各任务目录。

MacOS 用户注意: SWE-Lancer 镜像设计为 x86_64 架构运行,如果在 MacOS 上构建,可通过平台模拟解决:

# Platform emulation for MacOS to support x86_64
export DOCKER_DEFAULT_PLATFORM=linux/amd64

只运行 Manager 或 IC 任务

# 只运行 198 个 IC SWE 任务
uv run harbor run -d swe-lancer-diamond@ic

# 只运行 265 个 Manager 任务
uv run harbor run -d swe-lancer-diamond@manager

使用 Job 配置运行

如果你在本地生成了任务目录(例如 datasets/swe-lancer),可以参考适配器自带的 Job 配置文件:

# 从仓库根目录执行
# 使用默认适配器配置运行 job
uv run harbor run -c adapters/swelancer/run_swelancer.yaml -a <agent_name> -m "<model_name>"

# 或者不使用配置 YAML,直接指定本地任务目录
uv run harbor run -p datasets/swe-lancer -a <agent_name> -m "<model_name>"

# 恢复之前启动的 job
uv run harbor job resume -p /path/to/jobs/directory

run_swelancer.yaml 是默认 Job 配置,核心字段含义如下:

配置项 默认值 说明
jobs_dir jobs 结果保存目录,可在 YAML 中修改
n_attempts 1 每个任务的尝试次数
timeout_multiplier 1.0 任务超时倍率
orchestrator.type / n_concurrent_trials local / 4 本地并发 trial 数量
environment.type / force_build / delete docker / true / true Docker 环境、强制重建、运行后删除容器
agents oracle 默认 agent(可按需替换为 claude-code 并指定 model_name)
datasets datasets/swe-lancer 数据集路径

运行单个 Trial

快速测试或调试单个任务时使用:

# 使用 oracle(预写解法)运行单个 trial
uv run harbor trial start -p datasets/swe-lancer/<task_id>

# 使用指定 agent 和模型运行单个 trial
uv run harbor trial start -p datasets/swe-lancer/<task_id> -a <agent_name> -m "<model_name>"

Trial 输出默认保存在 trials/ 目录,可通过 --trials-dir 修改。

手动创建任务目录

如果不想从注册表拉取,可以在适配器目录下手动生成任务目录:

# 从适配器目录执行
cd adapters/swelancer

# 默认输出目录:../../datasets/swe-lancer
uv run swelancer

# 可选:只生成指定任务或覆盖输出目录
uv run swelancer \
  --output-dir ../../datasets/swe-lancer \
  --task-ids <id1> <id2> \
  --limit 50

任务写入 datasets/swe-lancer/,每个任务一个目录,结构见上文"生成的任务目录结构"。

生成命令的源码行为

入口脚本 main.py 定义了四个命令行参数:--output-dir(输出目录,默认是仓库根下的 datasets/swe-lancer)、--limit(只生成前 N 个任务)、--overwrite(覆盖已有任务)、--task-ids(只生成指定 task ID)。

结合 adapter.py 的 run() 流程可以理解整个生成管线:

  1. 下载并清洗数据集 CSV:若本地无 CSV,从 SWE-Lancer 官方源下载 all_swelancer_tasks.csv;随后调用 utils/clean.py 中的 clean_swelancer_csv(),用正则 SIGNED_URL_WITH_CREDS 剥离仅含 X-Amz-Credential 的 AWS 预签名 URL 查询参数(其他 URL 保持不变);
  2. 筛选任务 ID:读取全部 question_id,若指定 --task-ids 则只保留匹配项,若指定 --limit 则截取前 N 个;
  3. 逐任务渲染:SWELancerTask.load() 从 CSV 构建任务对象,generate_task() 调用 _prepare_task_from_template() 完成模板渲染。注意 SWELancerTask 通过 ast.literal_eval 安全解析 acceptable_folders 与 manager_data 这类"字符串形式的 Python 字面量",并把 description / proposals 中的 \n 转义还原为真实换行以保证 Markdown 排版;
  4. 清理临时文件:生成完成后删除临时 CSV。

两类任务的指令 Prompt 构造

指令文本由 utils/prompts.py 构造:

  • IC 任务:construct_ic_task_prompt() 拼接四个 Prompt 段——任务陈述(角色设定 + issue title/description + 赏金)、独立脚本执行守则 IMPORTANT_GUIDELINES_PROMPT、user tool 使用说明 USER_TOOL_PROMPT(含 ansible-playbook 命令、output_browser1…n 与 trace.trace 的解析指引、120 秒等待建议等)、以及"逐步执行、通过 tmux 命令求解"的收尾指令;当 use_user_tool=False 时该段会被移除;
  • Manager 任务:construct_manager_task_prompt() 拼接任务陈述(标题、描述、赏金、候选提案列表)与守则、收尾指令,并要求 Agent 将答案以 {"selected_proposal_id": int} 的 JSON 格式写入 /app/expensify/manager_decisions.json。

评分器(Verifier)实现

两类任务的 test.sh 评分逻辑存放在 task-template 中,并由适配器按任务类型写入生成的 tests/ 目录。

IC SWE 评分流程

test.sh 的核心步骤:

  1. 用密码解压受锁定的测试包(unzip -q -P 'secretpasswordhere' -o /app/tests.zip -d /app/tests);
  2. 用 git diff --binary HEAD 生成模型补丁 /tmp/patch.diff;
  3. 参考官方实现,将 N_TEST_RUNS 设为 3(最多 3 轮测试,出现一次通过即判为成功);
  4. 每轮通过 ansible-playbook -i "localhost," --connection=local /app/tests/run_tests.yml -v 运行测试,读取 /app/tests/logs/{issue_id}/pytest_exit_code 判断结果:
    • pytest_exit == 0 → 记为 1.0(成功)并跳出重试循环;
    • pytest_exit >= 2 → 失败,直接写 0 到 /logs/verifier/reward.txt 并退出;
    • pytest_exit == -1 → 记 -1.0(未正常运行);
    • 其他 → 记 0.0。
  5. 只要任一测试轮次成功即输出 SWE LANCER SUCCESS 并将 reward 写为 1,否则输出 SWE LANCER FAILURE。

Manager 评分流程

test.sh 检查 /app/expensify/manager_decisions.json 是否存在且格式正确,并用 Python 读取 selected_proposal_id 与模板中注入的正确方案 ID 比对,一致则成功。

与原版基准的 Parity 对齐

为了证明适配等价性,Harbor 团队复现了 SWE-Lancer 原始实现并与 Harbor 结果对比。实验中创建了一个实现了 Claude Code solver 的 custom fork(其 solver 与 Harbor 内置的 Claude Code solver 类似),用于对照。

Parity 实验结果

Agent Model Metric Number of Runs Dataset Size Original Benchmark Performance Harbor Adapter Performance
claude-code@1.0.53 claude-sonnet-4-20250514 Pass Rate (%) 5 463 tasks (100% of full set) 48.38 ± 0.99 47.56 ± 0.43

实验明细记录在 parity_experiment.json 与 parity_summary.csv 中:原始 harness 的 3 次运行成绩为 [46.44, 49.68, 49.03],Harbor 的 5 次运行成绩为 [47.95, 48.60, 46.65, 48.16, 46.44](即 5 次 Harbor 运行对 3 次原始运行取均值)。从结果看,Harbor 适配器的 Pass Rate 与官方基准处于同一水平,验证了适配的等价性。

复现原始 OpenAI Harness

要复现 Parity 实验,需要使用实现了类似 Harbor 中 Claude Code solver 的官方 harness 自定义 fork。以下安装步骤尽量对齐原始 harness:

# 注意:需要 Python 3.11 或更低版本
# uv venv --python 3.11 && source .venv/bin/activate

# 检出包含自定义 agent 的 SWE Lancer fork(tbench 分支)
git clone <preparedness-fork-repo>
cd preparedness
git checkout tbench
cd project/swelancer

# 安装依赖
UV_GIT_LFS=1 uv sync

在原始 OpenAI Harness 上运行评测:

先用 gold solver 在单个实例上验证环境配置:

uv run python swelancer/run_swelancer.py \
  swelancer.split=diamond \
  swelancer.task_type=ic_swe \
  swelancer.taskset="['32236_652']" \
  swelancer.solver=swelancer.solvers.dummy.solver:DummySolver \
  swelancer.solver.test_user_tool=False \
  swelancer.solver.apply_gold_solution=True \
  swelancer.solver.computer_runtime=nanoeval_alcatraz.alcatraz_computer_interface:AlcatrazComputerRuntime \
  swelancer.solver.computer_runtime.env=alcatraz.clusters.local:LocalConfig \
  swelancer.solver.computer_runtime.env.pull_from_registry=True \
  swelancer.docker_image_prefix=swelancer/swelancer_x86 \
  swelancer.docker_image_tag=releasev1 \
  runner.concurrency=4 \
  runner.experimental_use_multiprocessing=False \
  runner.enable_slackbot=False \
  runner.recorder=nanoeval.recorder:dummy_recorder \
  runner.max_retries=3 \
  swelancer.disable_internet=False \
  swelancer.record_pretty=True

然后分别在 IC SWE 与 Manager 任务上运行 Claude Code。原始 SWE-Lancer 实现要求分两条命令执行:

# 使用 noisy logger
export STRUCTLOG_LEVEL=DEBUG

# 只运行 IC SWE 任务
uv run python swelancer/run_swelancer.py \
  swelancer.split=diamond \
  swelancer.task_type=ic_swe \
  swelancer.solver=swelancer.solvers.claude_agent.solver:ClaudeCodeSolver \
  swelancer.solver.name=claude-sonnet-4-20250514 \
  swelancer.solver.model=claude-sonnet-4-20250514 \
  runner.model_name=claude-sonnet-4-20250514 \
  swelancer.solver.computer_runtime=nanoeval_alcatraz.alcatraz_computer_interface:AlcatrazComputerRuntime \
  swelancer.solver.computer_runtime.env=alcatraz.clusters.local:LocalConfig \
  swelancer.solver.computer_runtime.env.pull_from_registry=True \
  swelancer.docker_image_prefix=swelancer/swelancer_x86 \
  swelancer.docker_image_tag=releasev1 \
  runner.concurrency=4 \
  runner.experimental_use_multiprocessing=False \
  runner.enable_slackbot=False \
  runner.recorder=nanoeval.recorder:dummy_recorder \
  runner.max_retries=3 \
  swelancer.disable_internet=False \
  swelancer.record_pretty=True

# 只运行 Manager 任务
uv run python swelancer/run_swelancer.py \
  swelancer.split=diamond \
  swelancer.task_type=swe_manager \
  swelancer.solver=swelancer.solvers.claude_agent.solver:ClaudeCodeSolver \
  swelancer.solver.name=claude-sonnet-4-20250514 \
  swelancer.solver.model=claude-sonnet-4-20250514 \
  runner.model_name=claude-sonnet-4-20250514 \
  swelancer.solver.computer_runtime=nanoeval_alcatraz.alcatraz_computer_interface:AlcatrazComputerRuntime \
  swelancer.solver.computer_runtime.env=alcatraz.clusters.local:LocalConfig \
  swelancer.solver.computer_runtime.env.pull_from_registry=True \
  swelancer.docker_image_prefix=swelancer/swelancer_x86 \
  swelancer.docker_image_tag=releasev1 \
  swelancer.use_single_image=True \
  runner.concurrency=4 \
  runner.experimental_use_multiprocessing=False \
  runner.enable_slackbot=False \
  runner.recorder=nanoeval.recorder:dummy_recorder \
  runner.max_retries=3 \
  swelancer.disable_internet=False \
  swelancer.record_pretty=True

Prompt 的两处变更

原始 SWE-Lancer 只实现了一个基于 Python 命令的单一 agent。为适配 Harbor,官方提示词做了两处修改:(1) 将 Python 专属指令替换为终端指令;(2) 将"通过输出 <user-tool> token 调用用户工具"的方式替换为"在终端直接运行 user tool 命令"。Parity 测试中两个 harness 均使用更新后的 Prompt。

注意事项与已知问题

  • 容器超过 200GB: 所有任务都基于 SWE-Lancer 官方预构建 Dockerfile(swelancer/swelancer_x86_*,tag releasev1)构建,并叠加额外安装步骤。全部 200 个 docker 镜像总大小约 200GB,请确保有足够大的 docker cache 才能运行该基准。
  • 部分指令过长的 Manager 任务可能静默失败: 初步运行中发现部分 Manager 任务指令超过 17K 字符,可能撑爆 tmux 缓冲区导致静默失败。这种情况下建议先把指令写入文件,再在 tmux 命令中 pipe 该文件。该问题只出现在 Manager 任务中,--dataset swe-lancer-diamond@ic 下的任务不受影响。
  • 不报告货币价值: SWE-Lancer 为每个任务实例分配了货币价值,并用 pass rate(pass@k)与货币价值加权得到总分。报告该加权平均需要在 Harbor 核心仓库中为单一适配器添加逻辑,因此本适配器不包含;如需恢复,可参考原始数据集中 price 列自行计算。
  • 模型可访问测试逻辑(为运行 user tool): "user tool" 本质上是一组运行任务测试的 pytest,并用 Playwright 把浏览器截图输出到文件夹,这与评分用的 pytest 是同一套。在原始实现中,模型输出 <user-tool> token 后由代码以密码解压测试包、运行测试再重新打包,模型只能看到测试输出而非测试本身。由于 Harbor 没有特权用户在 Agent 命名空间之外执行命令,本适配器将测试(非密码压缩)复制到容器,把运行命令交给模型并指示其查看输出——这是在不越权前提下最忠实的 user tool 提供方式。
  • user tool 可能耗时超过 5 分钟: 许多 agent 对命令有默认超时(如 Claude Code 默认 5 分钟),而 user tool 通常需要 10 分钟以上(要拉起全新 server、浏览器并执行操作)。建议将 agent 的每条命令默认超时设为 20 分钟。Harbor 通过 Dockerfile 中写入 ~/.claude/settings.json(BASH_DEFAULT_TIMEOUT_MS: 300000、BASH_MAX_TIMEOUT_MS: 1200000)为 Claude Code 专门支持该配置。

Dockerfile 中的其他关键改造

environment/Dockerfile 是理解容器行为的关键:基础镜像为 swelancer/swelancer_x86_{issue_id}:releasev1;额外安装 git tmux asciinema curl 与 uv 0.7.13;修改 /app/tests/run_tests.yml,使 pgrep -f node && pkill -f node 仅清理 webpack-dev 相关进程(避免误杀运行 npm 的 agent);创建 /logs/verifier 目录;将测试包以密码 secretpasswordhere 压缩为 /app/tests.zip;通过环境变量 DISABLE_INTERNET 控制网络;最后重建 git 仓库并创建临时 commit,以便只追踪模型改动。

引用

@article{miserendino2025swe,
  title={SWE-Lancer: Can Frontier LLMs Earn $1 Million from Real-World Freelance Software Engineering?},
  author={Miserendino, Samuel and Wang, Michele and Patwardhan, Tejal and Heidecke, Johannes},
  journal={arXiv preprint arXiv:2502.12115},
  year={2025}
}

适配器信息与贡献

该适配器由 Harbor 团队的 David Heineman(davidh@allenai.org)开发与维护,项目配置见 pyproject.toml(Python 版本要求 >=3.13,依赖 pandas、pydantic、python-dotenv、pyyaml,并提供 swelancer 命令行入口),适配器元数据与 Parity 详情见 adapter_metadata.json。问题与贡献请提交到主仓库,并遵循项目的编码风格与提交规范。

登录后查看全文
harbor