Harness Handbook：让演化中的智能体脚手架可读、可导航、可编辑 Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable
以行为为中心的代码表示，帮助编码智能体定位脚手架修改位点。
前置知识
Agent Harness（智能体脚手架）
指围绕基础模型构建的可执行、有状态的软件层，负责构造提示、管理状态、调用工具、控制跨组件执行流程。它决定了模型能力如何转化为系统行为，典型代表有 AutoGen、OpenHands、Claude Code、Codex 等。
本文研究对象就是脚手架本身，理解脚手架的构成与演化挑战是读懂全文的前提。
Behavior Localization（行为定位）
本文新定义的前置任务：给定一条描述“改什么行为”的修改请求，找出实现该行为的所有代码位点（文件、函数或连续区域）。它发生在编辑规划之前，是脚手架演化的核心瓶颈。
整篇论文的动机、方法和实验都围绕这一概念展开，不理解它就无法把握 Handbook 的价值定位。
Static Program Analysis（静态程序分析）
在不运行程序的前提下，通过语言相关适配器解析源码，抽取函数/方法、命名外部边界、源位置、签名与调用边，构建程序图 $G$。本文 Phase I 完全依赖它且不调用任何 LLM。
它保证了手册对源码的可追溯性与构建的可控性，是 Handbook 可信度的基石。
Progressive Disclosure（渐进式披露）
一种信息组织原则：读者只在任务需要更多细节时，才从高层概述（L1）逐级下钻到组件层（L2）和源码单元层（L3）。Handbook 由此形成 Behavior-Guided Progressive Disclosure（BGPD）定位流程。
它是手册表示与修改工作流的两条核心规则之一，决定了编码智能体如何在有限上下文下高效定位。
研究动机
生产级智能体脚手架通常横跨数百个函数与多个文件，执行逻辑分布在初始化、主循环、规划、工具执行、观察、终止等多个阶段，并通过共享状态相互连接。因此单个行为往往依赖若干非相邻的实现位点。当开发者或编码智能体收到一条“修改某行为”的自然语言请求时，请求只描述了系统应该“做什么”，并未指明“在哪改”。现有方法如仓库地图、代码搜索、代码摘要、仓库记忆和长上下文编辑虽然让代码更易检视，但仍以文件、函数、模块为单位组织信息，无法展示这些片段如何协同产生行为，也不能保证所有受影响位点都被找到。人类开发者需投入大量时间构建系统心智模型；编码智能体则受输入上下文长度限制，只能迭代探索，并常常漏掉分散或罕见执行的路径。作者把这一痛点称为“行为定位”瓶颈。
本文的目标是本文的目标是为生产级智能体脚手架的演化补上“行为—实现”这一缺失的连接环节。具体而言，作者希望构建一种可自动生成的、以行为为中心的操作型表示，把仓库知识围绕系统行为（而非文件或函数）重新组织，并为每条行为链接到具体的源代码位置，使开发者与编码智能体可以先定位相关行为再导航到对应代码。在此基础上设计完整的修改工作流：先用手册引导的渐进式披露（BGPD）做行为定位，再把证据转成编辑计划，执行后再自动重新同步手册。最终目标是让脚手架的演化既更准确（少漏位点），又更省成本（少花规划 token），并让较弱的规划器在手册辅助下逼近更强模型的实现位点定位能力。
与已有工作不同的是，本文的独特切入点在于显式地把“行为定位”定义为脚手架演化前必须完成的前置步骤——即找出实现某一请求行为的所有代码位点。已有仓库理解工作大多停留在实现层面（按文件、函数、模块或执行基础设施组织），不显式捕获跨分布执行阶段、功能模块与共享状态涌现出的系统行为。Harness Handbook 引入的操作型行为表示明确桥接了行为需求与底层实现，使定位可以在仓库探索之前进行；同时坚持“仓库是实现细节的唯一权威”，所有手册定位点都必须对当前源码重新校验，从而既补上行为视角，又不放弃实现准确性。这种“行为优先、实现校验”的双重视角是与以往工作的本质区别。
核心方法
Harness Handbook 由三部分构成。其一是表示：一棵 L1–L3 文档树 $D$ 加互补的状态寄存器视图 $Z$。L1 是系统总览（架构、执行模型、主要阶段、全局数据流），L2 是某阶段组件总览（职责、输入输出、依赖、本地状态），L3 是与源码锚定的实现单元深挖条目；$Z$ 记录跨阶段状态关系。其二是从仓库 $R$ 构建手册的三阶段流水线（Phase I 静态事实抽取、Phase II 行为组织、Phase III 层次合成与打包），叶节点粒度 $g \in \{\text{function}, \text{file}\}$ 决定 L3 单位。其三是修改工作流（Algorithm 1）：BGPD 定位 → 规划生成 $(P, \Gamma)$ → 执行得 $R'$ → 若 $\Delta \neq \emptyset$ 触发重同步 $\text{Resync}_g$。两条核心规则：渐进式披露（仅在需要细节时下钻）与行为—实现对齐（每个活跃 L3 定位点必须仍能解析到当前仓库）。直觉是“先把仓库翻译成行为地图，再让地图指导改码并自动保持同步”。
核心创新点在于把实现知识从“代码存放在哪”重新组织成“运行时行为如何展开”。一个行为可能跨越多个文件、执行阶段和共享状态，Harness Handbook 在保留源码链接的同时以行为为主轴重组信息，并配合状态寄存器视图 $Z$ 捕获那些结构上相距甚远但通过共享状态耦合的阶段。这与已有的仓库地图、代码摘要、长上下文编辑有本质区别：后者都是实现中心的，只能挑出零散相关片段，需要智能体自行拼装出整体行为；Handbook 则直接给出“行为 → 阶段 → 组件 → 源码”的可导航路径，并在每一步都对当前源码做校验，定位点失效时即冻结并排除。换言之，它把行为级抽象做成了一等公民，又通过“仓库唯一权威”约束防止抽象与代码脱节。
方法步骤详情
构建（图 2）：Phase I 用语言适配器解析仓库，抽取函数、命名外部边界、源位置、签名与调用边，构成程序图 $G$，只保留能解析到内部函数或命名边界的调用，无 LLM。Phase II 按叶模式组织：function-as-leaf 提出“函数→阶段”分配并经 Proposer–Reviewer 循环迭代精修（函数可整体或按区域归到多个阶段）；file-as-leaf 先把文件汇总为卡片并与 $G$ 推断阶段骨架 $S$ 再归并。Phase III 把骨架转为 L1–L3 树，每个 L3 条目静态锚定源位置并校验。修改：BGPD 用 L1、L2 找直接相关阶段，再用 $Z$ 拉入共享状态耦合的阶段，选最相关 L3 条目取定位点，沿调用图扩展候选集，最后打开当前仓库解析并保留仍相关的位点得证据 $bE_q$。规划器把 $bE_q$ 转为编辑计划 $P$ 与动作声明 $\Gamma=(\Gamma_{modify},\Gamma_{add},\Gamma_{remove})$；执行得 $R'$，若 diff $\Delta\neq\emptyset$ 触发 Resync：重解析、刷新 $G$、用不依赖行号的指纹匹配函数（或文件哈希匹配文件）确定增删改单位，骨架有效则只刷受影响条目，否则用相同 $g$ 重跑。重同步内 LLM 仅限分类、文件分配、阶段内组织、描述修订四类语义步骤。
技术新颖性
技术新颖性体现在四点。第一，首次把“行为定位”显式提为脚手架演化的前置瓶颈并给出可操作定义，而非直接改实现。第二，提出以行为为中心的操作型表示，区别于所有实现中心的仓库理解方法（repo map、索引、记忆、自然语言制品），并显式建模跨分布执行阶段、功能模块与共享状态涌现的系统行为。第三，构建流水线是确定性静态分析与受限 LLM 调用的组合：Phase I 完全不用 LLM，重同步阶段模型调用被限制在分类、文件分配、阶段内组织、描述修订四类语义步骤，其余全部确定性，可控且可校验。第四，提供 function-as-leaf 与 file-as-leaf 两种叶模式以适应有无可信种子骨架 $S_0$ 与预算约束，并坚持“仓库是唯一权威”的对齐规则——定位点失效即冻结——这让手册在多次修改后仍与代码同步，是区别于一次性代码摘要的关键。
实验结果
论文围绕三个 RQ 给出一致结论。RQ1（图 3）：总胜率 Codex 38.3% 对 28.3%（+10.0），Terminus-2 45.6% 对 26.7%（+18.9）；三位裁判（GPT-5.5、Opus 4.8、DeepSeek-V4-Pro）一致倾向手册臂。同时平均规划 token 反降：Codex 0.102M→0.089M（−12.7%），Terminus-2 0.058M→0.053M（−8.6%），说明提升不靠更大预算。综合分 $S=0.5S_{Loc}+0.25S_{Scope}+0.25S_{Reason}$。RQ2（表 1）：对 Opus 4.8 与 GPT-5.5 独立参考，24 项 R/P/F1 全部更高，F1 增 5.0~18.8；Terminus-2 文件级 F1 达 84.7%/89.3%、符号级 77.1%/89.3%，对 GPT-5.5 精度 93.3%；完全错配 Wrong 最多降 25.9 点。RQ3（图 5）：6 项“骨架×类型”全正（+16.3~+33.3），6 项“骨架×难度”全正（+3.7~+33.3），不随标注难度单调变化。
查看结构化数据
| 任务 | 指标 | 本文 | 基线 | 提升 |
|---|---|---|---|---|
| 编辑计划总胜率（Codex） | Overall Win Rate（三位裁判聚合，0–100%） | 38.3% | 28.3% | +10.0 个百分点 |
| 编辑计划总胜率（Terminus-2） | Overall Win Rate（三位裁判聚合，0–100%） | 45.6% | 26.7% | +18.9 个百分点 |
| 规划 token 成本（Codex） | 平均 planner tokens / 请求 | 0.089M | 0.102M | −12.7% |
| 规划 token 成本（Terminus-2） | 平均 planner tokens / 请求 | 0.053M | 0.058M | −8.6% |
| 符号级实现位点 F1（Codex vs Opus 4.8 参考） | Symbol-level F1（%） | 57.1% | 38.3% | +18.8 个百分点 |
| 完全错配率（Codex 符号级 vs Opus 4.8） | Wrong ↓（%） | 18.5% | 44.4% | −25.9 个百分点 |
| 文件级实现位点 F1（Terminus-2 vs GPT-5.5 参考） | File-level F1（%） | 89.3% | 76.5% | +12.8 个百分点 |
局限与改进
作者自承与可观察的局限主要有几条。评测范围窄：仅两个开源骨架（Terminus-2、Codex），各 30 条修改请求，样本规模有限，可能不足以覆盖工业级大型生产脚手架的复杂度。只评测了“定位 + 编辑计划”的质量，没有评测实际执行后改动的正确性、测试通过率或回归影响，因此“更好的计划”未必等价于“更好的最终代码”。所有裁判都是闭源大模型（GPT-5.5、Opus 4.8、DeepSeek-V4-Pro），存在同源偏好与系统性偏差风险；参考计划也由模型生成而非人工金标。function-as-leaf 模式依赖可信的种子骨架 $S_0$，种子质量对结果影响大，缺少种子时只能退化到 file-as-leaf。重同步的时间与 token 成本未给出量化。
独立分析的弱点
独立来看，第一，泛化性证据不足——两骨架规模与语言（以 Python 为主）有限，建议在多语言（TypeScript/Rust）、十万行级代码量与更多框架（AutoGen、OpenHands）上验证；改进方向是构造跨语言、跨架构基准。第二，端到端评估缺失，建议把执行后测试通过率、回归 bug 数纳入主指标，否则“定位准但改错”的情况无法暴露。第三，重同步开销未量化，长生命周期多次 diff 后手册漂移与重建成本未知；改进方向是给出增量更新的延迟/token 曲线与失效累积曲线。第四，种子骨架依赖——在 file-as-leaf 下自动推断骨架质量未充分对照；可探索从运行时 trace 自动提取种子。第五，裁判与参考同源风险高，建议引入人工金标子集与开源弱模型裁判做稳健性检验，并报告评判一致性。
未来方向
作者明确提出的下一步是“脚手架自我演化”（harness self-evolving）：把 Handbook 当作共享行为记忆，让智能体自主闭环完成定位—规划—执行—重同步，推动脚手架自我改进。此外作者指出手册还可服务行为审计（behavior auditing）与回归影响分析（regression-impact analysis）。基于本成果可延伸的方向包括：把行为定位扩展到多智能体/多服务的复杂拓扑；与运行时监控结合做动态行为漂移检测；把 BGPD 推广为通用代码库理解工具支持新人 onboarding 与知识转移；以及把“行为—实现对齐”思想用于自动生成回归测试用例与可解释的变更说明，甚至用于代码审查与安全审计场景。
复现评估
可复现性中等偏弱。论文提供了项目主页 https://ruhan-wang.github.io/Harness-Handbook/ ，但未在正文明确给出手册构建框架的代码仓库与数据集下载链接。被评测的两个骨架（Terminus-2、Codex）本身开源，便于构造任务；但所用的规划器（NexAU + DeepSeek-V4-Pro）与三位裁判/参考（GPT-5.5、Opus 4.8、DeepSeek-V4-Pro）均为闭源商业模型，他人难以精确复现数字，且存在版本漂移。60 条修改请求及其类型/难度标注、参考计划的标注流程也未完整公开。算力需求论文未给出。建议作者公开手册构建代码、请求集合与裁判提示模板以提升可复现性。
论文图表
按 Localization、Scope Control、Reasoning 三维分裁判展示胜率；两骨架三维平均均提升，Terminus-2 上 Localization +12.2、Scope +6.7、Reasoning +4.5；Codex 上分别为 +2.2、+1.1、+3.3。
说明质量提升并非只来自定位维度，作用范围与计分公式 $S=0.5S_{Loc}+0.25S_{Scope}+0.25S_{Reason}$ 的权重对应，帮助读者理解提升来源。