一句话总结

来自腾讯混元大模型前沿团队、印第安纳大学等机构的研究者提出了Harness Handbook——一种通过静态分析和LLM辅助结构化，从agent harness自动合成的以行为为中心的表示——以及行为引导的渐进式披露（Behavior-Guided Progressive Disclosure），该方法引导编码agent到达相关代码位置，显著提升了行为定位和编辑计划质量，优于先前的代码搜索方法，尤其是对于涉及分散实现位置、极少执行代码路径和跨模块交互的修改。

核心贡献

• Harness Handbook，一种以行为为中心的表示，通过静态分析和LLM辅助的行为结构化，从harness代码库自动合成，将行为需求与其分散的源代码实现关联起来。
• Behavior-Guided Progressive Disclosure（BGPD）引导编码agent从高层行为描述到达相关代码位置，并根据当前源代码验证候选位置，从而在仓库探索之前实现有针对性的行为定位。
• 在Codex和Terminus-2上的实验表明，handbook辅助的计划制定提升了计划质量（总体胜率分别提升10.0和18.9个百分点）和行为定位（全部24项文件和符号级别的召回率、精确率和F1值均提升），同时将planner token用量减少了12.7%和8.6%，最大收益出现在涉及分散实现位置、极少执行代码路径和跨模块交互的修改中。

引言

在现代基于LLM的agent系统中，一个称为harness的软件层负责协调提示词、状态管理、工具调用和执行流程。随着模型、API和需求的变化，harness必须不断修改，使harness演化成为一个核心且反复出现的工程挑战。任何修改请求首先需要找到实现所述行为的每个源代码位置，这一任务被作者称为行为定位。

现有的代码仓库探索工具，如代码搜索、地图和摘要，围绕文件、函数和模块组织信息。它们有助于识别单块相关代码，但无法展示这些代码如何共同产生一个系统行为，也无法保证所有受影响的位置都已被找到。开发者和编码agent只能手动连接分散的实现位置，并推断高层行为请求如何映射到底层源代码，这在大型、生产级harness中代价高昂且易出错。

作者通过Harness Handbook来解决这一缺口，这是一种以行为为中心的表示，直接将harness的行为与其在代码库中的实现位置关联起来。它通过静态程序分析和LLM辅助的行为结构化自动构建。该handbook将仓库知识围绕运行时行为重新组织，而非静态文件结构，从而实现了Behavior-Guided Progressive Disclosure工作流，引导编码agent从高层行为描述走向精确的实现细节。在两个开源harness的真实修改请求上，Handbooks辅助的计划制定提升了行为定位和编辑计划质量，同时使用了更少的planner token，这表明显式建立行为到代码的连接可以使harness演化更加准确和高效。

数据集

作者从一个软件仓库$R$R构建了一个handbook数据集。该handbook是一个结构化、可追溯的文档树，将源代码与执行阶段关联起来，用于下游任务中的源定位和重同步。

• 组成与来源

  • 完全基于单一仓库$R$R构建，使用特定语言的解析。
  • 最终输出：一个三级层次结构（L1阶段、L2组、L3源单元）以及一个跨阶段的状态寄存器视图。
  • L3叶子粒度$g$g固定为按函数为叶子（每个L3条目覆盖整个函数或连续区域）或按文件为叶子（每个L3条目代表一个文件）。

• 处理流程

  • 第一阶段 – 静态事实提取：确定性过程，无LLM调用。提取函数、命名边界、源位置、签名和调用边。仅保留解析到内部函数或命名边界的调用；未解析的调用被记录。
  • 第二阶段 – 行为组织：LLM驱动的提议和审查步骤将源单元分配到执行阶段。
    • 按函数为叶子：使用提供的种子骨架；函数可以被切割成区域以支持多角色行为。
    • 按文件为叶子：从扫描的文件摘要和程序图推断阶段骨架，可选的迭代细化。未被包含的文件和问题被显式记录。
  • 第三阶段 – 层次化合成与打包：将阶段骨架和分配转换为L1–L3文档树和状态寄存器视图。每个L3条目都链接到静态识别的源位置，并根据当前仓库进行验证。管道随后打包结构化数据，用于源定位和未来的重同步。

• 在模型中的用途 handbook作为一种与代码链接的表示，将执行阶段与精确的源位置关联起来。它用于支持下游的源定位任务，并在仓库演进时实现重同步。

方法

作者提出了Harness Handbook，一个旨在通过围绕运行时行为组织源代码来理解和修改agent harness的框架。该系统包含三个核心组件：一个面向行为的表示，一个从仓库构建该表示的构建管道，以及一个使用handbook引导代码变更并自动重同步它的修改工作流。

Harness Handbook表示围绕行为重组仓库信息，同时保留到源码的链接。它由一个L1至L3的文档树和一个补充的状态寄存器视图组成。读者逐步从L1（系统概览）浏览到L2（组件概览），最后到达L3（单元深入），该层将阶段链接到源码基础的实现条目。状态寄存器视图记录跨越阶段边界的状态关系。该表示遵循两条关键规则：渐进式披露，确保读者仅在需要时才获取细节；以及行为-实现对齐，确保每个活跃的L3定位器都能解析到当前仓库。

构建管道以固定的叶子模式$g \in \{function, file\}$g∈{function,file}从仓库构建handbook，该模式决定了L3条目的粒度。管道以三个不同阶段运作，如下图所示：

第一阶段，静态事实提取，使用特定语言的适配器解析仓库，提取函数、边界、源位置、签名和调用边到程序图中，该阶段完全确定性，不需要LLM调用。第二阶段，行为组织，将源单元映射到执行阶段骨架：在按函数为叶子模式下，提出函数到阶段的分配，并通过迭代的提议-审查循环进行细化；在按文件为叶子模式下，先总结文件再推断阶段骨架。第三阶段，层次化合成与打包，将阶段骨架和源组织转换为L1至L3文档树和跨阶段状态寄存器视图，根据仓库验证每个L3条目以确保可追溯性。

构建完成后，handbook通过一个四步工作流引导仓库修改。首先，Behavior-Guided Progressive Disclosure通过浏览handbook从粗略的执行阶段下至具体的L3条目，沿调用关系扩展候选，并根据当前仓库验证它们以产出源码基础的证据，从而定位请求的行为。其次，planner将这些证据转换为编辑计划和行动声明。第三，执行器将计划应用于仓库。最后，任何非空的diff都会触发handbook的重同步。重同步过程重新解析变更的源码，对齐旧版本和新版本以识别修改的单元，并仅更新handbook的受影响部分，将模型调用限制在特定的语义步骤，同时对无法解析的内容进行保守处理。

实验

该评估在两个开源agent harness上，使用30个行为驱动的修改请求，比较了handbook辅助的planner与基线，计划质量由三个独立模型评判。Handbook指导持续提升计划质量、定位准确性和范围控制，同时减少planner token用量，并使较弱的planner更好地与更强模型生成的参考计划对齐，这些收益在不同请求类型和标注难度级别上均保持一致。

为较弱的planner提供handbook指导，始终提升了它与独立参考计划之间的定位一致性。在两个代码库、两个评判模型以及文件和符号两种粒度下，所有F1分数都更高，增益在5到19个点之间，由召回率和精确率的同时提升驱动。该指导还将完全遗漏率降低了最多26个点，表明改善包括消除了真正错误的计划。在全部harness、参考模型和粒度上，handbook辅助将F1分数提升了5.0到18.8个点，召回率和精确率同时上升。在handbook指导下，与参考计划零重叠的请求比例下降了多达25.9个百分比点，衡量了完全定位失败的减少。

为较弱的planner提供handbook指导，在多样化的评估设置（两个代码库、两个评判模型、文件和符号粒度）下始终提升了它与独立参考计划之间的定位一致性。F1分数提升5–19个点源于召回率和精确率的同时提升，零重叠的计划占比下降最多26个点，表明完全定位失败更少。