大模型决定 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 将代码库重新组织为一套三级结构，并保留每个行为单元与当前源代码之间的连接。

![](https://developer.qcloudimg.com/http-save/yehe-12464096/2958450f4291527fa51cf408b8051e49.png)

图 1：Harness Handbook 的三级结构

### L1：系统总览

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

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

### L2：组件与阶段总览

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

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

### L3：实现单元详解

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

L3 采用两种粒度：

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

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

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

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

## Handbook 的自动构建流程

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

![](https://developer.qcloudimg.com/http-save/yehe-12464096/fa77528f657e8e12d02202eebdffdb6c.png)

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

整个过程可以概括为：

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

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

## 与代码同步的动态手册

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

```Plain
行为定位 → 修改计划 → 执行修改 → 生成 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%。
    

![](https://developer.qcloudimg.com/http-save/yehe-12464096/cc82ee519c7c59651f519ddc8b5d144c.png)

图 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 找到跨越多个模块、或很难通过关键词直接搜索到的实现位置。

![](https://developer.qcloudimg.com/http-save/yehe-12464096/7c2a3dd8995dc3fcec5e667468199d27.png)

图 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 月。

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

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

本文提出Harness Handbook，一种从代码库自动生成的、以运行时行为为中心的三级文档体系，解决Agent Harness中“行为定位”难题。

人工智能

开发工具

架构设计

AgentHarness通过大模型协调系统行为，而HarnessHandbook解决行为定位难题。它自动生成三级文档结构，连接行为、执行阶段与源码位置，帮助研发人员快速定位和修改代码。实验证明，Handbook能提升修改计划质量并降低Token消耗，支持复杂Agent系统的持续演化与维护。

代码解释

数据流

DeepSeek

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Harness Handbook：让持续演化的 Agent Harness 可读、可查、可改-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐