Harbor 拆解:SWE-bench adapter 怎么把 500 道修 bug 题搬进统一评测框架
Harbor 拆解:SWE-bench adapter 怎么把 500 道修 bug 题搬进统一评测框架
评测 SWE-bench 有个烦人的现实:它自带一整套 Docker 构建、日志解析、评分管线,跟你的其他评测脚本互不相认。Harbor 的解法不是重写 SWE-bench,而是写了个 adapter,把 500 道题翻译成自己的 task 格式,让官方的评分逻辑原样跑在里面。
Harbor 是 Terminal-Bench 背后团队做的评测框架,定位一句话:evaluate and optimize agents and models。你可以在上面跑 Claude Code、OpenHands、Codex CLI 这类现成 agent,也可以自己造基准,还能接 Daytona、Modal 这些云沙箱并行跑几千个环境,甚至给 RL 训练生成 rollout。到我查的 2026 年 11 月 18 日,仓库 7,199 stars,Apache 2.0 协议,它还是 Terminal-Bench 2.0 的官方 harness。
而 SWE-bench Verified 是修 bug 评测的事实标准:500 道经人工验证的真实 GitHub issue,一道题一个仓库快照加一份 issue 描述,agent 交补丁,测试通过才算解决。这两样东西都很流行,但格式不通。Harbor 在 adapters/swebench 里放了一个 adapter 专门干翻译这件事。这篇把三样东西拆清楚:SWE-bench 数据长什么样、adapter 为什么需要、Harbor task 格式是什么。
按四件套走:是什么、怎么用、值得学什么、同类怎么比。
本文提纲
- 是什么:SWE-bench 数据格式、Harbor task 格式,两边各要什么
- 怎么用:adapter 干了啥,五份文件怎么生成,三条命令怎么跑
- 值得学什么:借官方评分器保 parity、task 目录即契约、reward 文件约定
- 同类比较:官方 harness、Terminal-Bench 旧 adapter、Kaggle 式封闭 harness
是什么:两边的数据格式
SWE-bench 数据格式
SWE-bench 的每条数据(一个 instance)来自一个真实 GitHub PR,在 HuggingFace 上是 princeton-nlp/SWE-bench_Verified 的 test split,核心字段:
| 字段 | 内容 |
|---|---|
| instance_id | 题目 ID,格式 repo__repo-PR号,如 django__django-13741 |
| repo / base_commit | 仓库名和题目对应的基线 commit |
| version | 仓库版本,决定用哪套测试配置 |
| problem_statement | issue 原文,agent 唯一能看到的题目描述 |
| hints_text | issue 评论区,可当参考线索 |
| patch | 参考答案,修好源码的 unified diff(oracle) |
| test_patch | 验证测试的 diff,只改测试文件 |
| FAIL_TO_PASS / PASS_TO_PASS | 打了补丁必须由红变绿的测试、必须保持绿的测试 |
| environment_setup_commit | 环境安装锚点 |
| difficulty | Verified 新增的人工标注难度 |
格式就一个核心思想:把"改代码"和"验题"拆开。agent 永远拿不到 patch 和 test_patch,评分时才用 test_patch 加两组测试清单来判分。
Harbor task 格式
Harbor 的世界里没有"数据集行",只有 task 目录。一个 task 就是一个自包含的文件夹:
{task_id}/
├── task.toml # 元数据与资源配置
├── instruction.md # 给 agent 的题目指令
├── environment/
│ └── Dockerfile # 环境镜像
├── solution/
│ └── solve.sh # 参考解(oracle),验证题目可解
└── tests/
└── test.sh # 验证脚本,产出 reward
task.toml 的字段在 swebench 模板里长这样:
schema_version = "1.0"
[task]
name = "swe-bench/swebench-verified__{instance_id}"
description = "SWE-bench Verified debugging task."
authors = [...]
keywords = ["debugging", "swe-bench"]
[metadata]
difficulty = "{difficulty}"
category = "debugging"
[verifier]
network_mode = "public"
timeout_sec = 3000 # agent 和 verifier 各自的超时预算
[agent]
network_mode = "public"
timeout_sec = 3000
[environment]
build_timeout_sec = 1800.0
cpus = 1
memory_mb = 4096
storage_mb = 10240
gpus = 0
契约很直接:agent 进容器读 instruction.md 干活;之后 tests/test.sh 在容器里跑,输出写进 /logs/verifier/,其中 reward.txt 里是 1 还是 0 就是一道题的最终得分;solution/solve.sh 是给 oracle agent 用的,用来证明这题可解。任何基准只要能套进这五份文件,就能在 Harbor 上跑。
怎么用:adapter 干了啥
为什么需要它
SWE-bench 官方 harness 是一套独立管线:自己建每题的 Docker 镜像、自己跑 eval 脚本、自己解析日志判分。它不是通用 runner,接不了 Harbor 的 agent 列表、云沙箱编排和统一输出。反过来说,Harbor 不可能为每个基准重写一遍环境构建和评分逻辑,那等于维护另一个 SWE-bench。
adapter 的价值就在中间这层:用 Harbor 的 task 格式包住 SWE-bench 的官方评分逻辑,两边都不用改。翻译完了,SWE-bench 就变成 Harbor 数据集仓库里的一个普通条目,一条命令跟 Terminal-Bench 2.0 用同一套姿势跑。
转换管线
adapter 的实现全在 adapter.py 里,从 HuggingFace 拉数据,逐条渲染五个模板文件:
MERMAID_BLOCK_0
逐份文件看它干了啥:
instruction.md:题目原文直接放进去。 模板全文就一行 {problem_statement},渲染后就是 issue 原文,不加任何花哨包装。repo、version、base_commit 这些字段在渲染时也注入了,但核心就是让 agent 看到和人一样的 bug 报告。
task.toml:超时和资源写死。 默认 agent 和 verifier 各 3000 秒预算(CLI 的 --timeout 可调),1 CPU、4GB 内存、10GB 存储、无 GPU。network_mode 是 public,因为 SWE-bench 的 repo 特定安装命令需要联网装依赖。
environment/Dockerfile:不重造镜像,直接 FROM 官方预构建镜像。 adapter 调 SWE-bench 库的 make_test_spec 算出每题对应的镜像名(swebench 命名空间,强制换 x86_64),模板里一行 FROM {docker_image} 加装 uv、建 /logs 目录就完了。500 道题的环境构建被完全外包给官方镜像。
tests/test.sh:官方评分逻辑原样内嵌。 这是最有价值的一份。脚本先激活 testbed conda 环境,跑 repo 特定的安装命令,然后用 git checkout base_commit 把 test_patch 碰过的被跟踪文件重置干净,删掉 test_patch 创建的未跟踪文件(注意保留了 agent 新写的源码文件),再 git apply test_patch,跑该版本规定的 test_cmd,全程 tee 进日志。接着现场用 uv 起一个内嵌 parser.py,装 swebench==4.0.3,调官方的 get_logs_eval 和 get_resolution_status,按 FAIL_TO_PASS/PASS_TO_PASS 判 resolved,写 /logs/verifier/report.json 和 reward.txt,最后打印 PASSED 或 FAILED。
tests/config.json:原始 instance 原封不动存进去。 评分用的 FAIL_TO_PASS、PASS_TO_PASS、仓库版本这些信息都从这里来,官方 parser 直接读它。数据格式和评分逻辑零转译,parity 是结构上保证的。
solution/solve.sh:oracle patch 用 patch 命令打上去。 把 patch 字段写进 diff 文件,patch --fuzz=5 -p1 应用,就是参考答案。
三条命令
# 生成全部/部分 task 目录
uv run swebench
uv run swebench --instance-id django__django-13741
# 整个数据集跑评测
uv run harbor run -d swebench-verified -a <agent> -m "<model>"
# 单题试跑
uv run harbor trial start -p datasets/swebench-verified/<task_id> -a <agent>
也可以用 adapters/swebench/swebench.yaml 这类 job 配置,指定 orchestrator 并发数、docker 环境和 agent 参数(比如 terminus-2 配 parser: xml 来兼容 SWE-bench 的日志格式)。
Parity 做了三轮验证
adapter README 里最实在的部分:它没有只说"能用",而是跑了对拍。链条分三步:官方 SWE-bench 对 Terminal-Bench 旧 adapter,codex 加 o4-mini 两边都是 53.11%,terminus-1.5-xml 加 opus-4 两边都是 66.4%,openhands 加 sonnet-4 是 66.8% 对 67.0%;Terminal-Bench 旧 adapter 对 Harbor adapter,terminus-2 加 sonnet-4.5 是 70.0% 对 68.6%;最新一轮对着官方榜单的全量跑,mini-swe-agent 加 gpt-5-mini 在 Daytona 上跑三次,官方单次 56.3%,Harbor 三次 53.1%/55.1%/55.3%,均值 54.5% 加减 0.7%(剔除一道 Daytona 上持续超时的 scikit-learn 题,剩 499 题可比)。差距在一个 SEM 量级,可以认为等价。
README 还诚实列了已知问题:4 道题连 oracle 都过不了(astropy 三道、django 一道,属于原始数据集的环境问题),外加 2 道 sphinx 题踩了 SWE-bench 官方 harness 的老 bug(PR #475)。这些坑不是因为搬进 Harbor 才出现的。
值得学什么
借官方评分器,别自己重写判分。 adapter 最聪明的决定是 config.json 存原始数据、test.sh 里现场装 swebench==4.0.3 跑官方 parser。评分逻辑只有一份,基准升级跟一次版本号就行。自己给基准写"简化版判分"是 parity 事故的头号来源。
task 目录即契约。 Harbor 把一道题的全部要素压成五个文件:题目、配置、环境、参考解、验证。没有隐藏的全局状态,换 runner、换云厂商、单题调试都是拷目录的事。自己维护内部评测集的话,这个结构可以直接抄。
reward 文件约定小但关键。 test.sh 不管多复杂,最终交付就是往 /logs/verifier/reward.txt 写 0 或 1。框架不解析你的业务日志,只认这个约定。这让 Harbor 能接任意基准,也让 RL 训练可以直接拿 reward 当信号。
oracle 是题目的单元测试。 solve.sh 不是摆设,Harbor 用它跑 oracle agent 验证每道题可解。adapter README 里那批"oracle 都过不了"的题就是这道防线抓出来的。自建评测集时先跑一遍参考答案,能筛掉一半的烂题。
同类比较
| 方案 | 思路 | 代价 |
|---|---|---|
| SWE-bench 官方 harness | 一条龙管线,自建镜像自评分 | 功能全但自成一体,难跟其他基准统一编排 |
| Harbor swebench adapter | 官方镜像加官方评分器,包成统一 task 格式 | 多一层目录转换,镜像和 swebench 库版本要跟 |
| Terminal-Bench 旧 adapter | Harbor adapter 的前身 | 已被 Harbor adapter 取代,README 明说 |
| Kaggle Gemma 4 Developer Agent | 比赛方自建封闭 harness,工具白名单 | 评测最可控,但数据格式私有、不可复用 |
选型判断:要在多个基准上对比 agent 或模型,Harbor 这条路收益最大,一次学格式处处能跑;只跑 SWE-bench 单基准,官方 harness 也够用,就是结果格式跟别的评测对不上;想造自己的 SWE-bench 类基准,直接从 Harbor task 模板起步,比从零写 harness 省一个量级的工程量。想动手的话,Harbor Cookbook 有端到端示例。
顺带一提,今天早些时候写的 Kaggle Gemma 4 Developer Agent 赛题拆解里那个 12 小时跑约 120 题的封闭 harness,跟 Harbor 是两个极端:一个为比赛公平性锁死一切,一个为研究复用性开放一切,看多了 SWE-bench 系的环境,你会发现所有评测 harness 的设计取舍都在这两个极点之间。
参考文档与链接
- 主仓库:harbor-framework/harbor(Apache 2.0,Python)
- adapter 源码与文档:adapters/swebench(含 adapter.py 与 task-template)
- 基准官网:swebench.com,论文 arXiv 2310.06770
- 数据集:princeton-nlp/SWE-bench_Verified(test split,500 条)
- 文档与示例:harborframework.com/docs、harbor-cookbook
- 延伸阅读:Kaggle Gemma 4 Developer Agent 拆解:这题是啥,怎么解 — 本站同日文章,另一个 SWE 环境的设计样本
你的评测脚本还在自己拼 Docker 命令和 grep 日志吗?还是已经在用统一 task 格式了?评论区聊聊你的评测基建。觉得有用点个赞。
作者: itech001
来源: 公众号:AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客,主页有更多的文章的AI 技术参考:https://www.theaiera.top

浙公网安备 33010602011771号