一句话总结

腾讯 HY LLM 前沿、印第安纳大学及其同事提出了 Harness Handbook，这是一个以行为为中心的表示，通过静态分析和 LLM 结构化自动合成，将 agent 框架行为映射到源代码；同时提出了行为引导的渐进式揭示（BGPD），该方法引导编码 agent 从高级行为描述到相关的实现细节，从而在针对 AI agent 框架的复杂修改中显著提升行为定位和编辑计划的质量，尤其在变更涉及分散的实现或跨模块交互时更为有效。

核心贡献

• 本文提出了 Harness Handbook，一个从框架代码库通过静态程序分析和 LLM 辅助的行为结构化自动合成的以行为为中心的表示，将每一个系统行为与其分散的源代码实现相关联。
• 本文提出了行为引导的渐进式揭示（BGPD），该方法引导编码 agent 从高级行为描述到相关的实现细节，并根据当前源代码验证候选代码位置。
• 在两个开源 agent 框架上的评估显示，手册辅助的规划在行为定位和编辑计划质量上均有提升，同时使用了更少的规划 token；对于涉及分散实现位置、极少执行的代码路径和跨模块交互的变更，提升最为显著。

引言

作者解决了修改生产规模 agent 框架的挑战，该框架是在基于 LLM 的 agentic 系统中协调提示构建、工具调用、状态管理和执行流的软件层。随着模型和环境的演变，开发人员或编码 agent 必须定位负责实现期望行为更改的每一个实现位置，作者将这一任务称为行为定位。此前的仓库表示，如代码地图、代码搜索和摘要，按文件和函数组织代码，但无法展示分散的代码片段如何共同产生运行时行为；编码 agent 仍然面临迭代且容易出错的探索。为了弥合这一差距，作者提出了 Harness Handbook，一个以行为为中心的表示，明确地将框架的功能与其实现源代码联系起来，通过静态分析和 LLM 辅助的结构化自动构建。他们还提出了 行为引导的渐进式揭示（BGPD），引导 agent 从高级行为描述到具体的代码位置。在两个开源框架上的评估显示，手册辅助的规划在提升行为定位和编辑计划质量的同时，减少了规划 token 的消耗。

数据集

作者从一个现有的代码仓库构建了一个 harness 手册；该手册作为模型使用的结构化知识来源。其组成和处理过程如下：

• 数据集组成和来源

• 唯一的数据来源是一个代码仓库 R（C、C++ 或类似语言），表示一个 agent 框架或固件库。

• 生成的手册是一个三层（L1–L3）的层次化文档，并包含一个跨阶段的状态寄存器概览。

• 提供两种 叶粒度：

• 函数作为叶 – 每个 L3 条目涵盖一个完整函数或函数的连续区域。

• 文件作为叶 – 每个 L3 条目代表整个源文件。

• 各子集/模式的关键细节

• 函数作为叶 模式：

• 当存在可信的、忠实反映执行阶段的种子骨架，并且函数级细节符合预算时使用。

• 种子骨架提供初始的阶段和状态寄存器定义。

• 文件作为叶 模式：

• 当没有可用的种子骨架，或者函数级组织将超出预算时使用。

• 管道从文件摘要和程序图中推断阶段骨架；可选的审查循环优化结构。

• 两种模式都生成相同的 L1–L3 表示，并将未解决的问题标记在单独的问题记录 Y 中。

• 数据的使用方式

• 该手册用作模型的输入，用于 源代码定位 和 重新同步 任务；它提供从行为阶段到具体源代码位置的可追溯映射。

• 训练/使用混合并不是传统的数据划分，而是一个构建好的单一手册；模式根据种子骨架的可信度和预算在每个项目中选择一次。

• 处理与构建管道

1. 静态事实提取（第一阶段）

• 语言特定的适配器解析仓库以提取函数、命名边界、源位置、签名和调用边。
• 程序图 G 仅保留内部调用或对命名边界的调用；未解析的调用被记录，不会猜测。
• 该阶段是确定性的，不使用任何语言模型调用。

2. 行为组织（第二阶段）

• 函数作为叶：利用源代码和调用图上下文提出函数到阶段的分配；分配经过迭代审查，可以将一个函数映射到多个阶段，或将其拆分为连续的区域。
• 文件作为叶：生成文件卡片，将其与程序图结合以推断阶段骨架 S，按阶段组织文件，并可通过提议和审查进行优化。

3. 层次化合成与打包（第三阶段）

• 将阶段骨架和组织转换为 L1–L3 文档树和跨阶段状态寄存器视图。
• 每个 L3 条目都与一个静态确定的源代码位置相关联，并根据当前仓库进行验证，确保可追溯性。
• 生成章节视图 V，并将结构化数据打包，供下游源代码定位和未来的重新同步使用。

方法

作者介绍了 Harness Handbook，一个旨在通过围绕运行时行为组织源代码来理解和修改 agent 框架的系统。该系统由三个核心组件组成：以行为为导向的表示、构建管道和修改工作流。

Harness Handbook 表示 源代码仓库指示代码存储的位置，但并未直接揭示运行时行为如何在文件和阶段之间展开。Harness Handbook 将这些信息围绕行为重新组织，同时保留到源代码的链接。如框架图所示，该表示由一个 L1–L3 文档树 $D$D 和一个互补的状态寄存器视图 $Z$Z 组成。

阅读者通常从 L1（系统概述）开始，该层总结体系结构、执行模型、主要阶段和全局数据流。然后进入 L2（组件概述），了解所选阶段的职责、输入、输出、依赖关系和本地状态。最后，L3（单元深入）将该阶段与基于源代码的实现条目联系起来。互补视图 $Z$Z 记录了跨越阶段边界的状态关系。两条规则维持该表示的效用：渐进式揭示，即阅读者仅在需要更多细节时才从 L1 前进到 L3；行为-实现对齐，确保每个活跃的 L3 定位器都能解析到当前仓库。

构建管道 构建管道使用固定的叶模式 $g \in \{function, file\}$g∈{function,file} 从仓库 $R$R 构建手册，该模式决定了 L3 条目的粒度。一旦选定叶模式，构建过程分三个阶段进行。

第一阶段，静态事实提取，使用语言特定的适配器解析仓库，提取函数、命名外部边界、源位置、签名和调用边。该阶段是确定性的，并生成程序图 $G$G。 第二阶段，行为组织，将源代码单元组织到执行阶段骨架 $S$S 中。在函数作为叶模式下，管道利用源代码和调用图上下文提出函数到阶段的分配，并通过迭代审查进行优化。在文件作为叶模式下，管道将扫描的文件汇总为卡片，并与程序图结合以推断阶段骨架。 第三阶段，层次化合成与打包，将阶段骨架和源代码组织转换为 L1–L3 文档树和跨阶段的状态寄存器视图。每个 L3 条目与一个静态确定的源代码位置链接，并根据当前仓库进行验证。

手册引导的修改与重新同步 构建完成后，手册作为修改仓库的、以行为为导向的指南。给定一个请求 $q$q，工作流使用手册 $H$H 和仓库 $R$R。

工作流从行为引导的渐进式揭示（BGPD）开始，该过程通过从粗到细的手册导航来定位请求的行为。BGPD 利用 L1 和 L2 识别相关的执行阶段，遵循状态寄存器视图 $Z$Z 以纳入关联的阶段，并选择相关的 L3 条目。然后，它沿调用关系扩展候选集，并根据当前仓库验证这些位置，以生成经过验证的证据 $\widehat{E}_{q}$Eq​。

接着，规划器将 $\widehat{E}_{q}$Eq​ 转换为编辑计划 $P$P 和动作声明 $\Gamma$Γ。执行器将 $P$P 应用到仓库，产生更新后的仓库 $R'$R′ 和差异 $\Delta$Δ。

最后，任何非空的差异都会触发手册重新同步。该过程重新解析更改的源文件，刷新程序图，并对齐旧版本和新版本，以识别新增、移除和修改的单元。如果阶段骨架仍然有效，则仅刷新受影响的条目；否则，重新运行构建算法。这确保手册与仓库保持一致和最新。

实验

实验在两个开源的 agent 框架上评估了手册引导的定位在编辑规划中的效果，将直接探索代码的基线与遵循基于手册的导航策略的实验组进行比较。手册辅助在多个评判者和维度上持续提升计划质量，同时减少了规划 token 使用量。它使得较弱的规划器能够达到更强模型的定位准确度，减少完全遗漏，并且这些提升在不同请求类型和难度级别上都能保持。

手册引导在两个框架、两个参考模型以及文件和符号两种粒度上持续改善参考计划的定位指标（召回率、精确率、F1 值），F1 提升最高可达 18.8 个百分点。召回率和精确率同时上升，表明聚焦更佳，而非简单返回更多候选位置；零重叠（错误）的请求占比从未增加，最多下降了 25.9 个百分点，意味着完全定位失败的情况更少。在 Terminus-2 框架上，手册辅助使基于 Opus 4.8 和 GPT-5.5 参考的文件级 F1 分别达到 84.7% 和 89.3%，且在文件和符号粒度上对 GPT-5.5 的精确率均达到 93.3%。错误率（衡量与参考无重叠的请求）最多下降了 25.9 个百分点；在 Codex 框架上，以 Opus 4.8 为参考，错误率从 37.0% 降至 14.8%。

评估在两个框架、两个参考模型以及文件和符号粒度上测量了补充性手册引导对参考计划定位的影响。引导一致地同时提高召回率和精确率，将 F1 得分提升多达 18.8 个百分点，并将完全缺失定位的比例最多降低 25.9 个百分点，表明手册是收窄注意力，而非简单地呈现更多候选项。这些提升在所有设置中均成立，证明该引导能够稳健地提高定位准确性并减少彻底失败。