Harness Handbook：让持续演化的 Agent Harness 可读、可查、可改

大模型决定 Agent 能理解什么、推理能到什么程度，Agent Harness 则负责把这些能力组织成可执行的系统行为。无论是 Prompt 组装、上下文管理，还是工具调用、状态保存和任务循环都由 Harness 统一协调。

随着模型、API 和产品需求的不断变化，Harness 也在持续演化。原本集中在少数模块中的逻辑，逐渐扩展到了更多文件、函数和执行阶段，一项行为可能会由多处代码共同完成。当我们想要调整某个 Agent 行为时，首先得弄清楚这些实现分布在哪里，以及它们之间是如何配合的。

论文《Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable》将这一问题概括为行为定位（Behavior Localization）。围绕这个问题，作者提出 Harness Handbook 概念。它是从代码库中自动生成的一套以运行时行为为中心的说明体系，连接起 Agent 的行为、执行阶段、共享状态与具体源码位置，帮助研发和 Coding Agent 更快地理解 Harness 的运行方式，并准确定位和修改相关实现。

Agent Harness 的行为定位难题

传统代码仓库一般会按照文件、函数和模块组织代码，代码修改需求却要以系统行为来描述。例如：让 Agent 在确认任务完成后再检查一次，然后结束当前循环。

上面这句话说明了系统需要发生什么变化，但没有指出应该修改哪些文件和函数，也无法直接判断这一行为是否同时涉及主循环、状态字段、完成条件和异常处理。

在规模较小的项目中，研发人员一般可以借助关键词搜索、调用关系和逐文件阅读代码来完成定位。但是生产级 Agent Harness 的情况要复杂得多。看似简单的行为背后可能同时涉及多个位置：

• 某个函数负责读取模型返回的完成信号；

• 某个状态字段记录任务是否已经确认；

• 主循环根据该状态决定继续执行或退出；

• 其他分支负责处理超时、工具失败和最大步数；

• 测试代码还可能使用不同的初始化路径。

如果只找到当中的某一个函数，修改计划就可能会遗漏其他关联路径。

代码搜索、仓库索引、代码仓库地图、代码摘要和长上下文阅读，这些都能帮 Agent 更快地找到相关代码。不过，这些方法要按照代码结构来组织信息，Agent 还是得自行建立行为描述、执行过程与实现位置之间的对应关系。

Harness Handbook 的核心作用，就是提前整理这层对应关系。

从代码目录到行为地图

Harness Handbook 将代码库重新组织为一套三级结构，并保留每个行为单元与当前源代码之间的连接。

图 1：Harness Handbook 的三级结构

L1：系统总览

第一层描述整个 Harness 的架构、执行模型、主要阶段、设计原则和全局数据流。

在这一层，Handbook 会先梳理 Harness 的整体运行流程，包括初始化、规划、工具执行、观察、循环与终止。研发人员可以根据系统总览建立对系统结构和执行逻辑的整体认识，再沿着这条主线继续定位具体实现。

L2：组件与阶段总览

第二层围绕具体执行阶段展开，说明每个阶段的职责、输入、输出、依赖关系、外部接口和涉及的关键状态。

例如，在"主循环"阶段，Handbook 会进一步梳理这一阶段要如何接收当前状态、模型输出和工具结果，包含哪些处理步骤，以及哪些信息要传入下一轮执行。

L3：实现单元详解

第三层会深入具体的实现，说明某项行为是如何接收输入、读取和更新状态，以及遇到异常时该怎样处理。同时，它还会标出相关配置、关键函数和源码位置，方便研发人员回到代码中核对与修改。

L3 采用两种粒度：

• Function-as-leaf：以函数或函数中的连续代码区域作为最小单元；

• File-as-leaf：以文件作为最小单元。

前一种方式适合已经划分清楚执行阶段，并且能够承担函数级分析成本的 Harness。后一种方式则适合大型仓库，尤其是尚未理清执行阶段，或函数级整理会带来过高开销的 Harness。

除了这三级文档结构，Harness Handbook 还单独梳理了跨阶段流动的状态。一个状态可能在初始化时被写入，在主循环中不断更新，最终被退出逻辑读取。Agent 可以沿着状态的变化，找到分散在不同模块中的相关代码，并理解这些实现是如何共同完成一项行为。

最终，Handbook 提供了一条从系统行为逐步深入到具体代码的导航路径。每项说明都能回到当前源码中进行核对，并随着代码变化持续更新。

Handbook 的自动构建流程

为了让现有仓库生成这套行为地图，论文设计了三个阶段。

图 2：Handbook 的三阶段构建流程

静态事实提取

系统先使用语言适配器去解析代码，提取函数、方法、类、模块、函数签名、源代码位置、调用边和外部边界，并生成程序图。

这一阶段完全由确定性程序完成，不用调用大模型。对于提取出的调用关系，能够明确解析的内部调用会被写入程序图；无法解析的调用则会被单独记录，系统不会去自行猜测其目标。

这样的处理为后续生成提供了可验证的代码事实，也减少了大模型在底层结构上的自由发挥。

行为组织

接下来，系统会借助大模型，判断各个代码单元分别属于 Harness 的哪些执行阶段。

在 Function-as-leaf 模式下，系统会从已有的执行阶段框架出发，结合源码和调用图，建立函数与执行阶段之间的对应关系。这个结果还会经过多轮检查和修正。若同一个函数参与了多项行为，系统既可以将整个函数归入多个阶段，也可以按照连续的代码区域分别归类。

在 File-as-leaf 模式下，系统会先为每个文件生成一张概要卡片，再结合程序图推断 Harness 的执行阶段，并将文件归入相应位置。暂时无法归类的文件和仍未解决的结构问题会被单独保留，避免在整理过程中被遗漏。

在这一过程中，大模型负责理解代码在行为层面完成了什么，静态分析则提供可核对的调用关系和源码位置。两者结合后，原本分散的底层实现就能被整理成围绕运行过程展开的结构。

分层合成与打包

最后，系统会将执行阶段框架与代码映射整合成 L1---L3 三级文档，并补充跨阶段的状态关系。每个 L3 条目都会指向静态分析定位到的源码位置，后面再与当前仓库进行核对。

只有能够在当前版本中重新找到并确认的定位信息，才会进入后续的行为定位流程。暂时无法验证的条目会被冻结，等待下一次同步更新。这样设计可以确保 Handbook 对实现细节的描述始终以当前源码为准。

BGPD 的渐进式行为定位

有了 Handbook，Coding Agent 不用一次性读完全部内容。论文进一步提出的 Behavior-Guided Progressive Disclosure（BGPD）概念，是让 Agent 沿着"从行为到代码"的路径逐层展开所需信息。

收到修改请求后，BGPD 会先查看 L1 和 L2，判断这项需求主要涉及哪些执行阶段 。接着，它会沿着状态关系继续追踪，补充那些通过共享状态相互关联的阶段。确定范围后，系统再进入对应的 L3 单元，找到与需求最相关的具体实现和源码位置。

不仅如此，BGPD 还会根据调用关系扩展候选范围。Function-as-leaf 模式使用函数调用图，File-as-leaf 模式使用文件调用图。与外部系统的连接可以帮助补充上下文，但不会直接被列为需要修改的位置。

完成 Handbook 内部的导航后，BGPD 会回到当前仓库，对候选代码逐一核对，只保留仍然与修改需求相关的部分。最终交给规划器的内容包括文件路径、函数或代码区域的位置标记，以及当前版本中的源码片段。

整个过程可以概括为：

自然语言修改请求
    ↓
相关执行阶段
    ↓
跨阶段状态关系
    ↓
相关行为单元
    ↓
候选代码位置
    ↓
当前仓库验证
    ↓
修改计划

这样的渐进式展开能够降低一次性阅读整个仓库带来的上下文压力，也能让修改计划拥有更清晰的代码依据。

与代码同步的动态手册

如果 Handbook 只在项目初始化时生成一次，它很快就会随着代码的变化而失效。因此，论文把自动同步纳入完整修改流程：

行为定位 → 修改计划 → 执行修改 → 生成 diff → 更新 Handbook

只要代码 diff 中出现实际改动，系统就会自动启动同步流程。它会重新解析变更后的代码、更新程序图，并识别哪些函数或文件被新增、删除或修改。

在 Function-as-leaf 模式下，系统通过不依赖行号的函数指纹来追踪变化。即使函数移动了位置，仍然可以被识别为同一个单元；如果函数发生重命名，系统还会结合函数体内容进行判断。File-as-leaf 模式则通过文件列表的变化和内容哈希，确认哪些文件发生了更新。

如果原有的执行阶段框架仍然适用，系统只用更新受影响的条目及其上层文档；如果原有结构被代码改变，系统就会重新运行相应的构建流程。暂时无法解析或准确归类的内容会被冻结，或是单独写入覆盖记录，避免未经验证的信息进入 Handbook。

通过这套同步机制，Handbook 可以随着仓库一起演化，并持续保持行为说明与实际代码的一致。

两个开源 Harness 上的实验

论文选择 Terminus-2 和 Codex 两个开源 Agent Harness 进行评估。其中，Terminus-2 采用 Function-as-leaf 模式，Codex 采用 File-as-leaf 模式。作者分别为这两个项目设计了 30 个以系统行为为目标的修改请求，并将它们分为三类：

• Query：调整现有行为，但不提供对应的代码位置；

• Cross-file：增加需要跨越多个文件或模块完成的端到端能力；

• Search-Hostile：相关实现较为隐蔽，很难通过关键词搜索直接找到。

这些请求还按照定位难度划分为 Easy、Medium 和 Hard。

实验使用 DeepSeek-V4-Pro 作为只读规划器。基线组直接在代码仓库中查找相关实现，Handbook-Assisted 组则在其他条件相同的情况下，借助 Handbook 和 BGPD 完成定位。

随后，作者将两组生成的修改计划交给 GPT-5.5、Opus 4.8 和 DeepSeek-V4-Pro 独立评估，考察代码位置是否准确、修改范围是否合理，以及计划是否给出了充分依据。

结果显示，Handbook-Assisted 在两个项目上都取得了更高的计划质量胜率：

• Codex 从 28.3% 提升至 38.3%，增加 10.0 个百分点；

• Terminus-2 从 26.7% 提升至 45.6%，增加 18.9 个百分点。

与此同时，规划阶段的平均 Token 消耗也有所下降：

• Codex 每个请求从约 10.2 万 Token 降至 8.9 万，减少 12.7%；

• Terminus-2 从约 5.8 万 Token 降至 5.3 万，减少 8.6%。

图 3：计划质量与 Token 成本

论文还把规划器预测的编辑位置，与 Opus 4.8 和 GPT-5.5 分别生成的参考计划进行了比较。评估覆盖两个 Harness、两种参考模型，以及文件级和符号级两个层面。结果显示，24 组 Recall、Precision 和 F1 指标全部提升，其中 F1 提高了 5.0 至 18.8 个百分点。规划结果与参考位置完全没有重合的情况也有所减少，最大降幅达到 25.9 个百分点。

按请求类型拆分后，六组"项目---请求类型"对比同样全部取得提升，增幅介于 16.3 至 33.3 个百分点。尤其是在 Cross-file 和 Search-Hostile 任务中，Handbook 的优势更为明显。这说明，围绕系统行为组织代码信息，可以帮助 Agent 找到跨越多个模块、或很难通过关键词直接搜索到的实现位置。

图 4：不同请求类型与定位难度下的胜率

这组实验主要考察代码定位和修改计划的质量，并没有直接评估最终补丁是否正确、测试能否通过，以及长期维护成本是否下降。因此，当前结果可以说明 Handbook 有助于 Agent 更准确地找到相关代码并制定修改计划，完整的软件修改效果还需要结合后续的代码执行和验证继续评估。

持续演化 Harness 的可维护性

Harness Handbook 关注的是 Agent 工程中一个越来越明显的维护难题：随着系统能力不断增加，一项行为往往会分散到更多文件、函数和执行阶段，仅靠临时搜索和个人经验，很难长期维持行为与代码之间的对应关系。

代码目录可以告诉研发人员实现位于哪里，Handbook 则进一步说明这些实现如何配合，共同完成某项行为。当修改需求以自然语言提出时，Coding Agent 可以先确定目标行为，再沿着执行阶段、状态变化和具体实现逐步定位相关代码。修改完成后，系统还会根据代码 diff 更新 Handbook，使说明继续与当前仓库保持一致。

对研发人员来说，这套结构可以降低理解复杂 Harness 的门槛，也能减少跨模块排查问题所需的时间。对 Coding Agent 来说，Handbook 相当于一份以源码为依据的行为记录，可以缩小搜索范围，减少缺少方向的仓库探索。自动同步机制则让这份记录能够随着 Harness 一起演化。

论文还提出，这种围绕系统行为组织代码的方式，未来可以继续用于行为审计和回归影响分析。作者希望进一步把 Handbook 作为 Agent 共享的行为记忆，将代码定位、修改规划、执行和重新同步连接成完整流程，并在此基础上探索 Harness 的自动演化。

结语

随着 Agent 从简单的 Prompt 和工具调用，逐步发展为包含状态管理、执行循环、异常恢复、多阶段协作与外部环境交互的复杂系统，Harness 也从一层辅助代码，变成了需要持续维护的核心工程部分。

Harness Handbook 的价值，在于为这套复杂系统补上一层以行为为中心的说明结构。它以静态分析提取的代码事实为基础，将系统总览、执行阶段与具体实现串联起来，并通过自动同步持续跟随代码变化。

借助这套结构，研发人员和 Coding Agent 在修改某项行为之前，可以先弄清相关实现分布在哪里、彼此如何关联，以及改动可能影响哪些路径。

当 Harness 仍在持续演化时，可读、可查、可改，已经成为 Agent 稳定扩展与长期维护的重要基础。

论文信息

Ruhan Wang 等，Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable，arXiv:2607.13285，2026 年 7 月。