Harbor 上的 SWE-Lancer 基准适配指南:从数据集构建、任务生成到与原版评测对齐
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() 流程可以理解整个生成管线:
- 下载并清洗数据集 CSV:若本地无 CSV,从 SWE-Lancer 官方源下载
all_swelancer_tasks.csv;随后调用 utils/clean.py 中的clean_swelancer_csv(),用正则SIGNED_URL_WITH_CREDS剥离仅含X-Amz-Credential的 AWS 预签名 URL 查询参数(其他 URL 保持不变); - 筛选任务 ID:读取全部
question_id,若指定--task-ids则只保留匹配项,若指定--limit则截取前 N 个; - 逐任务渲染:
SWELancerTask.load()从 CSV 构建任务对象,generate_task()调用_prepare_task_from_template()完成模板渲染。注意SWELancerTask通过ast.literal_eval安全解析acceptable_folders与manager_data这类"字符串形式的 Python 字面量",并把description/proposals中的\n转义还原为真实换行以保证 Markdown 排版; - 清理临时文件:生成完成后删除临时 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 的核心步骤:
- 用密码解压受锁定的测试包(
unzip -q -P 'secretpasswordhere' -o /app/tests.zip -d /app/tests); - 用
git diff --binary HEAD生成模型补丁/tmp/patch.diff; - 参考官方实现,将 N_TEST_RUNS 设为 3(最多 3 轮测试,出现一次通过即判为成功);
- 每轮通过
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。
- 只要任一测试轮次成功即输出
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_*,tagreleasev1)构建,并叠加额外安装步骤。全部 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。问题与贡献请提交到主仓库,并遵循项目的编码风格与提交规范。