编程智能体的表现,既取决于模型本身,也取决于包在模型外面的 harness:主循环、工具执行、上下文管理、权限、会话状态与故障恢复,都属于这层基础设施。
自进化(RSI,recursive self-improvement)要求智能体不断修改约束自身行为的基础设施。模型构建 harness 的能力,也因此影响着智能体 RSI 的上限。
来自中科院计算所、清华大学、北京大学与东南大学的研究团队提出了 Doc2Harness。据研究团队介绍,这是首个直接评测长程 harness 工程能力的确定性基准。
被测模型依据一份开发文档,从只声明接口的契约骨架出发,在隔离容器中构建完整的候选 harness。候选产物随后被冻结,由脚本化的 mock 模型驱动,在 328 个 test case 上接受评测。在 19 个被测模型中,排名第一的 GPT-6 Astra 通过率为 53.05%。

论文标题:Doc2Harness: Benchmarking LLMs on Long-Horizon Harness Engineering of Coding Agents
论文地址: https://arxiv.org/abs/2610.20344
项目主页: https://geyuyao.com/doc2harness/
代码地址: https://github.com/YuyaoGe/doc2harness
动机:为何需要专门评测 Harness 工程
构建 harness 属于软件工程任务,但现有的软件工程基准难以直接评测这项能力。
从数据角度看,SWE-bench Pro、NL2Repo-Bench、Commit0 等基准使用的开源仓库大多是成熟项目,很可能已多次出现在训练语料中;harness 则是近几年才出现的软件,迭代速度快,模型较难单靠记忆完成构建。
从判定方式看,现有基准依靠任务自带的单元测试。但同一功能在 harness 中可以有多种实现,单元测试只能通过固定接口观察行为。
此外,harness 本身不完成下游任务,必须由模型驱动才能检验正确性。因此,评测需要依据它被驱动时表现出的外部行为。
总体设计:分容器构建与评测
Doc2Harness 分为构建和评测两个阶段,每个阶段各固定一个组件,以减少混杂因素。

阶段一:构建
被测 agent 由构建模型(build model)和固定的构建 harness(builder harness)组成。它阅读开发文档,以契约骨架为起点,写出候选 harness。
构建 harness 统一采用开源的 OpenCode。研究团队没有使用 Claude Code 或 Codex CLI,因为它们由模型厂商开发,可能对自家模型存在倾向性。
只有发出提交,构建才算结束。每次提交都会触发契约检查(contract check),检查交付物能否编译安装、必需命令是否齐全、是否残留占位代码,以及三个契约接口是否就位。
契约检查只看形式,不运行任何 test case。检查通过后,交付物就被冻结为候选 harness,不再修改。
检查不通过则退回,被测 agent 可以修改后再次提交。每次构建最多提交 3 次,墙钟时间上限为 2 小时。
阶段二:评测
冻结后的候选 harness 被移到与构建环境隔离的容器中运行。每个 test case 都使用单独的容器和一份独立的初始文件。
mock 模型按照预设脚本给出回复,驱动候选 harness 走完一次完整会话。真实大模型的输出带有随机性,可能干扰评测;mock 模型严格依照脚本回复,使每次判定具有确定性。
每个 test case 从四个可观测通道(observable channel)读取效果:发送给模型的请求、磁盘上的文件、进程退出码和命令输出。
部分 test case 还配有正控(positive control)。只有 test case 自身通过,且为它把关的每个正控也都通过,才记为 PASS。
正控本身不计入通过率。构建模型的能力通过候选 harness 在全部 test case 上的通过率间接体现,因此 Doc2Harness 排名的是构建模型,而不是某一个 harness。
任务输入:开发文档与契约骨架
两份输入都尽量减少构建模型对既有知识的依赖,使其依据规格而非记忆完成构建。
开发文档:整合 12 个前沿 Harness 的功能
开发文档的编写分为三步。
收集功能清单。研究团队爬取了 12 个前沿 harness 的用户文档,包括 Claude Code、Kimi Code、Gemini CLI、Qwen Code、OpenCode、OpenClaw、Codex CLI、Aider、OpenHands、Cline、Crush 和 Cursor。从中提取候选功能后,研究团队逐项补充调用形式、参数语义和边界行为,经过合并、去重、裁剪,形成能力清单。
把清单写成条款。条款是文档的基本单位。文档共 10 章,涵盖交付物与运行接口、内置工具、顶层命令与子命令、权限与角色模式、全局参数、会话内命令与快捷键、持久记忆、约定文件、一致性规则和退出码。
每条条款都规定语法、含义和预期行为,其效果必须能通过四个通道之一观察到。除了契约骨架的三个接口,条款不对实现方式作限定。
消除歧义。12 个来源中的条款难免互相冲突。语义重叠的命令被合并,例如上下文压缩在 Claude Code 中叫 /compact,在 Cursor 中叫 /summarize,文档统一使用 /compact。
同名但含义不同的概念则被拆开。例如,“plan”在 Claude Code 中是六种权限模式之一,意思是只读;在 Aider 中,提出修改和执行修改分别由 architect 和 editor 两个角色承担。
因此,文档把只读约束放进权限,把修改的提出与执行放进角色,各自写成独立条款。
契约骨架:约 70 行代码,其余由模型编写
契约骨架由 mini-swe-agent 精简而来,只有 5 个 Python 源文件,合计约 70 行,另附一个安装脚本、一个入口脚本和一份项目配置,不包含任何功能实现。
其中三个接口是不可修改的外部契约:命令行接口(CLI)、Headless 入口,以及供自动化评测驱动的 API。
骨架越薄,模型需要自己编写的部分就越多。一个有代表性的候选 harness 包含约 30 个 Python 源文件、16,000 行代码,其中约 99.6% 由构建模型编写。
每次构建都从全新的空容器开始。除了指定的模型网关,容器无法访问外网。构建前会进行预检,确认容器里没有多余文件、OpenCode 能正常启动;任何一项不满足,就中止构建。
Test Case 合成:三种方法交替使用
每个 test case 都要锚定开发文档中的某条条款,同时具备区分不同实现的能力。
研究团队交替使用三种方法合成 test case:前两种扩大覆盖面,第三种加深检查深度。某种方法的边际产出下降后,就换用下一种。

公开 Issue 挖掘
这种方法基于研究团队对缺陷分布的判断:大模型在人类编写的代码上训练,成熟 harness 和模型编写的 harness 面对同样的接口语义与同类边界条件,因此成熟 harness 多年来暴露的缺陷,很可能也是模型会犯的错误。
研究团队拉取了四个前沿 harness 公开仓库中的全部 issue:

记录先按与开发文档的相关度排序,再逐条审阅;报告同一现象的记录被聚成一类,形成一个候选 test case。
如果两个候选锚定同一条款、观察效果又过于接近,以至于会在同一批实现上同时通过或同时失败,就只保留材料更完整的那个。
此外,候选必须能写成确定性的断言,且没有被现有测试集覆盖,才会被保留。
跨 Harness 对比
公开 issue 的数量和质量有限,跨 harness 对比则从源码入手。
研究团队按照开发文档列出的功能,将一个候选 harness 的源码划分为若干模块,对 Kimi Code、Qwen Code 等成熟 harness 的源码做同样的划分,然后逐个模块比较:哪些功能在成熟实现中得到了处理,而候选 harness 没有;哪些边界上的行为不一致。
实现差异不一定是缺陷,也可能只是写法不同。因此,每一处差异都要回到开发文档中核对,只有能从某条条款的意图推导出来的差异,才作为候选 test case。
单变量扩展
这种方法从一个已经证明有区分度的 test case 出发,把它作为种子 test case,每次只改变一个变量。
test case 由场景和断言组成。扩展时保持断言不变,只改场景,变量分为四类:
- 工具:同一个目的往往可以用多种工具达到,候选 harness 可能只把其中一部分实现正确。
- 输入形式:例如检查路径逃逸时,输入可以换成指向文件的符号链接、指向目录的符号链接、多级符号链接或相对路径符号链接。
- 出错的参数:同一种编码错误可能出现在不同参数上,例如把数值 0 当作缺省。
- 结果出现的位置:同一行为的结果可能出现在标准输出、标准错误或错误信息中。
每个新候选都要进行相似性检查。与种子 test case 太接近的会被舍弃,其余保留为 test case,并作为下一轮扩展的种子。
还没有任何 test case 锚定的条款无法提供种子,这部分只能靠前两种方法补上,因此三种方法需要交替使用。
正控:排除空过
什么是空过
test case 通过,并不代表候选 harness 一定实现了对应需求。
以路径逃逸为例:mock 模型的脚本让候选 harness 用 read 工具读取一个指向工作区外部的符号链接,并断言外部文件的内容不会出现在发给模型的请求中。
内容没有出现,可能是实现拦截了这次越界读取,也可能只是它根本无法读取任何文件。两种情况下断言都成立,但只有前者满足需求;后一种情况即为空过(vacuous pass)。
三类正控
正控用于排除空过。它与所把关的 test case 共用同一个场景和同一组初始文件,只改变输入或访问途径,换成不受被测条款约束的情形,并断言一个只要观测前提成立就必然出现的结果。
在断言本身正确的前提下,研究团队将空过归为三种成因,分别用三类正控排除。
通道正控(Channel)检查工具结果能否到达被观察的通道:用 read 工具读取普通文件,确认文件内容出现在请求中。
如果这一步失败,说明实现根本没有把工具结果写进该通道。此时禁止的内容没有出现,也不能说明越界读取被拦截。
同形正控(Same form)排除没有被测约束也照样会失败的情况:保持输入形式不变,只更换访问途径,通过 bash 工具访问同一个符号链接,确认它确实解析到工作区外,且文件可读。
路径逃逸条款约束的是文件工具,bash 执行的命令不在其范围内。如果这一步失败,说明实现连不受约束的访问都完成不了;被测访问没有读到内容,也就不能归因于拦截。
反向正控(Reverse)排除实现因其他原因一概拒绝某类输入的情况。拒绝所有符号链接的实现同样能通过上面的 test case,但它也会拒绝指向工作区内部的符号链接,而这种链接在正常使用中是合法的。
把输入换成指向工作区内部的符号链接,执行相同读取,确认内容仍然出现。如果这一步失败,说明原先的通过并不是因为识别出了越界访问。
下图列出了几种典型实现在该 test case 和三类正控上的结果。后三种实现的 test case 本身都通过了,但各有一类正控失败,最终都按空过记为 FAIL。

共用同一观测前提的 test case 归在同一个正控下,有多个前提的 test case 则由多个正控共同把关。正控一旦失败,它把关的 test case 不论自身结果如何,都记为 FAIL。
测试集统计
根据开发文档的内容和契约骨架的三个外部契约,328 个 test case 被分为 9 个互不相交的类别。

具体包括:会话状态 84 个、文件读写 75 个、权限 61 个、Headless 40 个、直接驱动 33 个、交互终端 20 个、交付物检查 7 个、启动 7 个、扩展发现 1 个。
图右侧展示各类别中由正控把关的 test case 比例。130 个 test case 至少有一个正控把关,其中 114 个由一个正控把关,15 个由两个,1 个由三个。
文件读写和权限类中由正控把关的用例数量最多。交互终端类仅有 1 个用例由正控把关;交付物检查标为 NA,因为这类 test case 要检查的内容已由契约检查完整核验。
覆盖面最广的正控一次把关 6 个 test case,确认的是指向工作区外部的符号链接确实可读。
实验结果
研究团队评测了来自 11 家厂商的 19 个前沿模型。每个模型独立构建三次,三份候选 harness 全部计分,共 57 份构建。
整体通过率远未饱和
GPT-6 Astra 的通过率最高,为 53.05%;排在最后的 Hy3 为 27.44%,两者相差约 26 个百分点。即使是排名第一的模型,也有近一半 test case 没有通过。


前两名的差距主要出在边界场景。在普通场景中,Opus 5 以 80.68% 领先 GPT-6 Astra 的 72.46%;到了边界场景,GPT-6 Astra 以 48.97% 领先,Opus 5 降到 37.02%。
各类别区分模型的能力也不同。权限类平均通过率为 43.7%,最强与最弱模型相差 50.8 个百分点,61 个 test case 中有 51 个能区分模型。
文件读写的平均通过率与之相近,为 39.6%,强弱差距却只有 20.9 个百分点。交互终端的平均通过率达到 79.9%,已接近饱和。
另有 56 个 test case 没有被任何一份候选 harness 通过。
名次在类别间变化很大
在六个主要类别上,同一个模型的名次最多相差 16 位:Opus 4.6 在直接驱动上排第 3,在权限上排第 19;Grok 4.7 在文件读写上排第 1,在会话状态上排第 11。

但这并不意味着模型在各类别之间此消彼长。六个类别两两之间的 15 个相关系数全部为正,平均为 +0.521。这表明模型间的差异主要体现在整体能力上,而不是各自擅长不同类别。
在全部 test case 上计算的 KR-20 系数为 0.913,测试集的内部一致性很高。
模块划分与得分的关系
研究团队解析了全部 57 份候选 harness 的源码。下图左侧每个点表示一个模型三份构建的平均,右侧展示每个模型三份构建的分布。

同一模型的三份构建规模相近,不同模型之间则相差很大:代码行数的方差有 95.9% 来自模型之间,代码行数与通过率的相关系数为 0.614。
控制代码行数之后,模块数与通过率的偏相关为 −0.423;逐一剔除单个模型后,该值仍在 −0.484 到 −0.309 之间。每模块行数与通过率的偏相关为 +0.504。
在代码量相当时,把横切功能拆到越多模块里的候选 harness,得分越低。这是实验中的相关性结果,不能单独证明模块划分导致了得分变化。
总结
Doc2Harness 将“模型能否构建一个 harness”转化为可以确定性测量的问题。
被测模型在固定的构建 harness 中,依据整合了 12 个前沿 harness 功能的开发文档,从约 70 行的契约骨架出发,写出完整的候选 harness。
mock 模型再按预设脚本驱动候选产物运行 328 个 test case,从四个通道读取效果,并通过正控排除空过。
构建与评测放在两个隔离阶段,判定只依据外部可观测行为;配有正控的 test case 还要经过相应正控的核验。基于断言的评测普遍存在空过风险,正控提供了一种系统排除空过的方法。
实验结果显示,这项能力距离饱和仍有差距:排名第一的模型也有近一半 test case 失败。研究团队还观察到,横切功能的模块划分与得分存在相关性,并希望 Doc2Harness 能成为衡量这类长程构建能力的基准。