让你更懂AI的 2026-11-17 17:38 北京

Doc2Harness首测大模型自建智能体底座

编程智能体的表现,既取决于模型本身,也取决于包在模型外面的 harness:主循环、工具执行、上下文管理、权限、会话状态与故障恢复。
自进化(RSI, recursive self-improvement)要求智能体不断修改约束自身行为的这层基础设施,模型构建 harness 的能力决定了智能体 RSI 的上限。
近日,来自中科院计算所、清华大学、北京大学与东南大学的研究团队提出了 Doc2Harness,这是首个直接评测长程 harness 工程能力的确定性基准。
被测模型依据一份开发文档,从一个只声明接口的契约骨架出发,在隔离容器中构建出完整的候选 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 本身不完成下游任务,必须由模型驱动才能检验其正确性。因此,评测 harness 只能依据它被驱动时的外部行为。

总体设计:在一个容器中构建,在另一个容器中评测

Doc2Harness 分为两个阶段,每个阶段各固定一个组件,以减少混杂因素。
2.1 阶段一:构建
被测的 agent 由构建模型(build model)和一个固定的构建 harness(builder harness)组成。它阅读开发文档,以契约骨架为起点,写出候选 harness。
构建 harness 统一采用开源的 OpenCode。之所以没有使用 Claude Code 或 Codex CLI,是因为它们由模型厂商开发,可能对自家模型存在倾向性。
只有发出提交,构建才算结束。每次提交会触发契约检查(contract check),检查交付物能否编译安装、必需的命令是否齐全、有没有残留占位代码、三个契约接口是否就位。
契约检查只看形式,不运行任何 test case。检查通过,交付物就被冻结为候选 harness,之后不再修改。
检查不通过则退回,被测的 agent 可以修改后再次提交。每次构建最多提交 3 次,墙钟时间上限为 2 小时。
2.2 阶段二:评测
冻结后的候选 harness 被移到与构建环境隔离的容器中运行,每个 test case 使用单独的容器和单独的一份初始文件。
mock 模型按照预设脚本给出回复,驱动候选 harness 走完一次完整的会话。真实大模型的输出带有随机性,会干扰评测;mock 模型的回复完全依照预设脚本,因此每一次判定都是确定的。
每个 test case 从四个可观测通道(observable channel)读取效果:发送给模型的请求、磁盘上的文件、进程退出码和命令输出。
有些 test case 还配有正控(positive control)。一个 test case 只有在自身通过、并且为它把关的每个正控也都通过时,才记为 PASS。
正控本身不计入通过率。构建模型的能力通过候选 harness 在全部 test case 上的通过率间接体现出来,因此 Doc2Harness 排名的是构建模型,而不是某一个 harness。

任务输入:开发文档与契约骨架
两份输入都在尽量减少构建模型对既有知识的依赖,使其依据规格而非记忆完成构建。
3.1 开发文档:整合 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 两个角色承担。
文档因此把只读约束放进权限,把修改的提出与执行放进角色,各自写成独立的条款。
3.2 契约骨架:约 70 行代码,其余由模型编写
契约骨架由 mini-swe-agent 精简而来,只有 5 个 Python 源文件,合计约 70 行,另附一个安装脚本、一个入口脚本和一份项目配置,不包含任何功能实现。
其中三个接口是不可修改的外部契约:命令行接口(CLI)、Headless 入口,以及供自动化评测驱动的 API。
骨架越薄,模型要自己写的部分就越多。一个有代表性的候选 harness 约有 30 个 Python 源文件、16,000 行代码,其中约 99.6% 是构建模型写的。
每次构建都从一个全新的空容器开始,除了指定的模型网关,容器无法访问外网。构建前会做一次预检,确认容器里没有多余的文件、OpenCode 能正常启动,任何一项不满足就中止构建。

test case 合成:三种方法交替使用

每个 test case 都要锚定在开发文档的某条条款上,同时要能区分不同的实现。
研究团队用三种方法交替合成 test case:前两种扩大覆盖面,第三种加深检查的深度;某种方法的边际产出下降后,就换用下一种。
4.1 公开 Issue 挖掘
这个方法基于对缺陷分布的一个判断:大模型是在人类写的代码上训练出来的,成熟 harness 和模型写的 harness 面对的是同样的接口语义和同类的边界条件,所以成熟 harness 多年来暴露过的缺陷,很可能也是模型会犯的错误。
研究团队拉取了四个前沿 harness 公开仓库中的全部 issue:

记录先按与开发文档的相关度排序,逐条审阅;报告同一现象的记录被聚成一类,形成一个候选 test case。
如果两个候选锚定同一条款、观察的效果又过于接近,它们会在同一批实现上同时通过或同时失败,这时只保留材料更完整的那个。
此外,候选必须能写成确定性的断言,并且没有被现有测试集覆盖,才会被保留。
4.2 跨 harness 对比
公开 issue 的数量和质量有限,这个方法则从源码入手。
研究团队按开发文档列出的功能,把一个候选 harness 的源码划分成若干模块,对 Kimi Code、Qwen Code 等成熟 harness 的源码做同样的划分,然后逐个模块比较:哪些功能成熟实现处理了而候选 harness 没有,哪些边界上两者的行为不一样。
实现上的差异不一定是缺陷,也可能只是写法不同,所以每一处差异都要回到开发文档中核对,只有能从某条条款的意图推导出来的差异,才作为候选 test case。
4.3 单变量扩展
这个方法从一个已经证明有区分度的 test case 出发,把它作为种子 test case,每次只改一个变量。
test case 由场景和断言组成,扩展时断言不变,只改场景。可以改的变量有四类:
工具:同一个目的往往可以用多种工具达到,候选 harness 可能只把其中一部分实现对了;
输入形式:例如检查路径逃逸时,输入可以换成指向文件的符号链接、指向目录的符号链接、多级符号链接或相对路径符号链接;
出错的参数:同一种编码错误可能出现在不同参数上,例如把数值 0 当作缺省;
结果出现的位置:同一行为的结果可能出现在标准输出、标准错误或错误信息中。
每个新候选都要做相似性检查,与种子 test case 太接近的会被舍弃,其余保留为 test case,并作为下一轮扩展的种子 test case。
还没有任何 test case 锚定的条款提供不了种子 test case,这部分只能靠前两种方法补上,所以三种方法需要交替使用。

正控:排除空过(vacuous pass)
5.1 空过问题
test case 通过,并不代表候选 harness 一定实现了对应的需求。
以路径逃逸为例:mock 模型的脚本让候选 harness 用 read 工具读取一个指向工作区外部的符号链接,断言外部文件的内容不会出现在发给模型的请求里。
内容没有出现,可能是实现拦截了这次越界读取,也可能只是它连任何文件都无法读取。两种情况下断言都成立,但只有前者满足需求,后一种情况即为空过。
5.2 三类正控
正控正是为排除空过而设计的。它和所把关的 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 个由三个。
文件读写和权限的覆盖率最高,交互终端最低;交付物检查标为 NA,因为这类 test case 要检查的内容,契约检查已经完整核验过。
覆盖面最广的正控一次把关 6 个 test case,它确认的是指向工作区外部的符号链接确实可读。

实验结果
研究团队评测了来自 11 家厂商的 19 个前沿模型,每个模型独立构建三次,三份候选 harness 全部计分,共 57 份构建。
7.1 远未饱和
如文首主图所示,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 通过。
7.2 名次在类别间变化很大

在六个主要类别上,同一个模型的名次最多相差 16 位:Opus 4.6 在直接驱动上排第 3,在权限上排第 19;Grok 4.7 在文件读写上排第 1,在会话状态上排第 11。
但这并不意味着模型在各类别之间此消彼长。
六个类别两两之间的 15 个相关系数全部为正,平均为 +0.521,说明模型之间的差异主要体现在整体能力上,而不是各自擅长不同的类别。
在全部 test case 上计算的 KR-20 系数为 0.913,测试集的内部一致性很高。
7.3 模块划分越细,得分越低

研究团队解析了全部 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 失败,而且失败集中在横切功能如何在模块之间划分这一实现选择上。研究团队希望 Doc2Harness 能够成为衡量这类长程构建能力的基准。



·

跳转微信打开