Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable
Ruhan Wang, Yucheng Shi, Zongxia Li, Zhongzhi Li, Yue Yu, Junyao Yang, Kishan Panaganti, Haitao Mi, Dongruo Zhou, Leoweiliang
cs.AI, cs.SE
2026-07-15
给 agent 运行框架自动建一份「行为手册」,把改代码前的行为定位步骤自动化,Terminus-2 上整体胜率从 26.7% 提到 45.6%,token 还省了一成。
现代 AI agent 的能力不只来自底座模型,还来自 harness。harness 是那层负责拼装 prompt、管理状态、调用工具、协调执行的代码。模型、API、需求都在变,harness 也得跟着改。但改之前得先找到实现某个行为的所有代码位置,这件事很难:生产级 harness 动辄上百个函数、跨几十个文件,一个行为往往散落在若干不相邻的位置,靠共享状态串起来。修改需求描述的是「系统该做什么」,而代码库按文件和模块组织,两者对不上。代码搜索、仓库索引、长上下文能帮你看,但「行为到代码」的映射仍要人来补。论文把这道坎叫 behavior localization(行为定位),并认定它是 harness 演进的中心瓶颈。
Harness Handbook 是一份以行为为中心的表示,自动从代码库合成出来。它是个三级文档树:L1 是系统总览,L2 按执行阶段拆组件,L3 把每个单元链回源码位置;再加一个 state-register(状态寄存器)视图,记录跨阶段共享的状态。构建分三步:第一步纯静态分析,确定性抽取函数、边界、调用边,不调模型;第二步靠 LLM 做行为归类,把源码单元映射到执行阶段;第三步合成层级文档。每个 L3 条目的定位器都要回当前仓库校验,对不上就冻结排除。
配合它的是 BGPD(Behavior-Guided Progressive Disclosure,行为引导的渐进披露):从阶段出发、顺着共享状态把耦合的阶段一起纳入、选相关条目、沿调用图扩展候选、最后打开当前仓库逐个校验,只留下真能对上源码的位置。改完之后还有一步自动重同步,让手册跟着代码一起演进。论文给两种叶子粒度:有可靠骨架时按函数拆(Terminus-2),仓库太大或没骨架时按文件拆(Codex)。
在两个开源 harness 上测:Terminus-2(Python,103 个函数)用函数粒度,Codex(Rust 单体仓,2267 个文件、34363 个函数)用文件粒度,各 30 条修改请求,分 Query、跨文件、Search-Hostile 三类。规划器用 DeepSeek-V4-Pro,三位独立 judge(GPT-5.5、Opus 4.8、DeepSeek-V4-Pro)打分。
| 设置 | 基线胜率 | 手册辅助胜率 |
| Codex | 28.3% | 38.3% |
| Terminus-2 | 26.7% | 45.6% |
整体胜率分别升 10.0 和 18.9 个百分点,token 成本同时下降,Codex 降 12.7%、Terminus-2 降 8.6%。和独立参考方案比,定位 F1 普遍拉高:Terminus-2 对 Opus 4.8 参考的 symbol 级 F1 从 64.8 升到 77.1,symbol 级错误率从 24.1% 降到 13.8%;对 GPT-5.5 参考,symbol 级 F1 升到 89.3%。最大的增益出现在实现位置分散、冷路径、跨模块的修改上。结论很直接:一个较弱的规划器配上手册,定位质量能追上更强的模型。
做 agent 框架和 coding agent 的人会直接受益。harness 越大越难改,根因就是行为和代码对不上;手册把这份映射提前算好、还能随代码自动更新,等于给框架加了「行为记忆」。它不替代执行,只管定位和规划,正好卡在最痛的那一步。
手册构建仍要调 LLM 做归类,不是全确定性。function-as-leaf 模式依赖一个靠谱的执行阶段骨架,不是哪个仓库都有。论文只评了定位和规划两步,执行交给另一个 agent,没端到端验证改完的代码到底对不对。两个被测 harness 都是特定项目,通用性还需更多仓库检验。