🤖 AI

Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable

本文介绍了 Harness Handbook，一种以行为为中心的表示方法和行为引导的渐进式披露（BGPD）方法，该方法能够自动将高层行为需求映射到特定的源代码位置，从而克服定位瓶颈，并提高演进复杂 AI 智能体测试桩（harness）的效率与质量。

原作者： Ruhan Wang, Yucheng Shi, Zongxia Li, Zhongzhi Li, Yue Yu, Junyao Yang, Kishan Panaganti, Haitao Mi, Dongruo Zhou, Leoweiliang

发布于 2026-07-16

📖 1 分钟阅读☕ 轻松阅读

CC BY 4.0

原作者： Ruhan Wang, Yucheng Shi, Zongxia Li, Zhongzhi Li, Yue Yu, Junyao Yang, Kishan Panaganti, Haitao Mi, Dongruo Zhou, Leoweiliang

原始论文采用 CC BY 4.0 许可（http://creativecommons.org/licenses/by/4.0/）。 ✨ 这是对下方论文的AI生成解释。它不是由作者撰写或认可的。如需技术准确性，请参阅原始论文。阅读完整免责声明

想象一下，你刚刚制造了一个超级智能的机器人助手。你给了它一个大脑（一个庞大的 AI 模型），并对它说：“去修理我的电脑！”但仅仅有大脑是不够的。机器人还需要一个身体、一套神经系统，以及一套关于如何移动手指、如何握住螺丝刀以及如何判断是否完成任务的指令。在 AI 的世界里，这个“身体和神经系统”被称为控制框架（harness）。它是软件层，负责告诉 AI 何时说话、何时使用工具，以及如何记住它刚刚做了什么。

现在，想象你想升级那个机器人。也许你想让它在删除文件之前更加谨慎，或者也许你想让它在完成任务前检查三次而不是一次。在过去，人类程序员必须翻遍成千上行的代码，试图弄清楚在机器人的神经系统中，那个“检查你的工作”的规则究竟隐藏在何处。这就像是在试图从一个巨大的、纠缠在一起的毛线球中找到一根特定的神经，却没有任何地图。代码通常分布在许多不同的文件中，与其他的逻辑混杂在一起，难以追踪。如果你漏掉了哪怕一个微小的点，你的机器人仍可能误删文件。这篇论文解决了寻找这些隐藏位置的挫折性问题，以便我们能够安全地升级我们的 AI 助手。

由 Ruhan Wang 及其同事领导的研究团队意识到，最大的瓶颈不在于教 AI 如何进行更改，而在于帮助人类（或其他 AI 智能体）弄清楚在哪里进行更改。他们将这个问题称为行为定位（behavior localization）。为了解决这个问题，他们发明了一种叫做 Harness Handbook（控制框架手册） 的东西。

请不要把 Harness Handbook 仅仅看作是一份文件清单，而要把它看作是机器人的行为用户手册。与其按“文件 A、文件 B、文件 C”（这是代码通常存储的方式）来组织信息，Handbook 是按“机器人实际做了什么”来组织信息的。这就像拥有一本指南，上面写着：“如果你想改变机器人处理‘任务完成’信号的方式，这里是其大脑中处理该信号的三个特定位置，以及它们之间是如何通信的。”

该团队构建了一个系统，通过阅读机器人的代码并使用智能 AI 来绘制连接图，从而自动生成这个 Handbook。他们将使用这种地图的方法称为行为引导式渐进式披露（Behavior-Guided Progressive Disclosure）。想象一下你正在修理一个复杂的时钟。你不是盯着 500 个齿轮和弹簧发呆，而是打开了一本手册，它首先向你展示“计时”部分，然后放大到“时针”齿轮，最后高亮显示你需要转动的那个精确的螺丝。Handbook 对 AI 代码也是如此：它从系统功能的宏观概述开始，然后引导用户深入到需要编辑的具体代码行。

研究人员在两个真实的 AI 系统（称为 Terminus-2 和 Codex）上测试了这个想法。他们要求编程智能体根据简单的请求进行修改，例如：“让机器人在给任务评分前请求确认三次。”他们对比了两组：一组必须用传统方式（搜索文件）来寻找代码，另一组则使用 Harness Handbook。

结果非常明确。使用 Handbook 的那一组在寻找正确编辑位置方面表现得好得多。他们犯的错误更少，不会意外地更改不该更改的内容，而且这一切都使用了更少的计算资源（更少的“token”，即 AI 用来思考的货币）。当代码很混乱、分布在许多文件中，或者隐藏在系统极少运行的部分时，Handbook 显得尤其有用。事实上，使用 Handbook 的智能体在寻找正确代码方面表现得如此出色，以至于一个“较弱”的 AI 模型只要拥有这张地图，就能表现得几乎和“较强”的模型一样好。

论文指出，随着 AI 系统变得越来越复杂，我们不能仅仅依赖更聪明的大脑；我们需要更好的地图。Harness Handbook 证明了，如果我们围绕着系统在做什么而非文件在哪里来组织代码，我们就能让进化这些强大的智能体变得更加安全、快速且可靠。它将理清巨大毛线球的混乱任务，变成了一场在明亮图书馆中受引导的简单旅程。

技术摘要：Harness Handbook（工具架手册）

问题陈述

现代 AI 智能体系统（Agent systems）的演进正日益受到生产级智能体工具架（Harness）中**行为定位（Behavior Localization）**难度的瓶颈限制。工具架是构建提示词、管理状态、调用工具并协调执行的软件层，它有效地将基础模型的各种能力转化为系统行为。随着需求的变更，开发者或编码智能体必须修改这些工具架。然而，识别所有实现特定行为请求的代码位置是非常困难的，因为：

结构复杂性： 行为往往分布在非相邻的文件、函数、执行阶段和共享状态转换中。
表示不匹配： 修改请求描述的是系统“应该做什么”（行为），而代码仓库则是按代码“如何构建”（文件、模块、函数）来组织的。
现有工具的局限性： 当前的方法（代码搜索、代码库索引、长上下文处理）围绕实现产物进行组织。它们有助于定位单个代码片段，但无法显式地映射这些分散的碎片是如何协同工作以产生特定行为的，这使得智能体或开发者必须手动推断这些连接。

这种差距迫使开发者建立系统的心理模型，或使智能体不得不迭代式地探索代码库，从而经常遗漏分散或极少执行的代码路径。

方法论

本文引入了 Harness Handbook——一种从工具架代码库中自动合成的、以行为为中心的表示法，以及 行为引导的渐进式披露（Behavior-Guided Progressive Disclosure, BGPD）——一种利用该表示法的流程。

1. Harness Handbook 表示法

Handbook 将实现知识围绕运行时行为而非文件结构进行重组。它由两个互补的视图组成：

文档树 ( $D$ )： 一个三层级的层次结构（L1–L3），从高层系统概览逐步深入到详细的源码级单元。
- L1（系统概览）： 架构、执行模型、主要阶段和全局数据流。
- L2（组件概览）： 特定执行阶段的职责、输入/输出、依赖关系和局部状态。
- L3（单元深挖）： 与特定代码位置链接的源码级实现条目（函数或文件）。
状态寄存器视图 ( $Z$ )： 一个跨阶段的视图，追踪跨越阶段边界的状态关系，确保即使在结构上相距甚远的情况下，也能捕获依赖于共享状态的行为。

该表示法遵循两条规则：

渐进式披露： 读者仅在任务需要更多细节时，才从 L1 移动到 L3。
行为–实现对齐： 每个活跃的 L3 定位器必须解析到当前的源代码库。如果一个定位器无法被重新验证，它将被冻结以防止幻觉。

2. 构建流水线

Handbook 通过三个阶段从代码库 ( $R$ ) 中自动构建：

第一阶段：静态事实提取： 通过确定性解析提取函数、调用图和状态访问。未解析的调用会被记录而非猜测。
第二阶段：行为组织： 将源码单元映射到一个执行阶段的骨架 ( $S$ $S$ )。该流水线支持两种叶子模式：
- 函数作为叶子（Function-as-leaf）： 从种子骨架开始，并将函数（或连续区域）分配给各个阶段。
- 文件作为叶子（File-as-leaf）： 从文件摘要中推断阶段骨架，并据此组织文件。
第三阶段：层次化合成： 将组织结构转换为 L1–L3 文档树和状态寄存器视图，并验证所有定位器是否与源码一致。

3. 修改工作流 (BGPD)

使用 Handbook 修改工具架的流程包含四个步骤：

定位： 智能体使用 BGPD 从粗粒度（L1/L2）到细粒度（L3）导航 Handbook。它识别相关的阶段和状态寄存器，通过调用图扩展候选集，然后针对当前源代码库验证这些候选对象，以生成经过验证的证据 ($bEq$)。
规划： 规划器将 $bEq $转换为编辑计划 ($ P $) 和动作声明 ($ \Gamma$)。
执行： 执行器将计划应用于代码库。
重同步： 任何非空的差异（diff）都会触发 Handbook 的自动重同步。系统仅更新受影响的部分（使用指纹或内容哈希），而不是重建整个 Handbook，从而确保表示法与不断演进的代码库保持一致。

核心贡献

定义行为定位： 本文正式定义了行为定位是寻找实现行为请求的所有代码位置的先决步骤，且该步骤发生在规划任何编辑之前。
Harness Handbook： 一种新型的、自动生成的表示法，它直接将行为描述与分布式的源码实现相链接，并按“工具架做什么”而非文件结构进行组织。
BGPD 工作流： 一种引导编码智能体从高层行为描述逐步深入到相关实现细节的方法，并在各阶段验证候选对象。
实证验证： 在两个开源工具架（Terminus-2 和 Codex）上的评估表明，基于 Handbook 的规划提高了定位准确性和编辑计划质量，同时降低了 Token 使用量。

实验结果

作者在 60 个修改请求（每个工具架 30 个）中评估了该方法，涵盖三种类型：查询（修改现有行为）、跨文件（添加跨模块的能力）以及搜索对抗型（将实现隐藏在难以发现的路径中）。

计划质量与成本： 与直接探索代码库的基准相比，基于 Handbook 辅助的规划在计划质量方面取得了显著更高的胜率（例如，在 Terminus-2 上提升了 18.9%）。至关重要的是，这种提升是在更少的规划器 Token 下实现的（在 Codex 和 Terminus-2 上分别减少了 12.7% 和 8.6%），这表明其优势在于效率的提高，而非仅仅增加了预算。
定位准确性： 由 Handbook 辅助的较弱规划器（DeepSeek-V4-Pro）在实现位置定位上，达到了显著强于的模型（Opus 4.8, GPT-5.5）的水平。在所有对比中，文件级和符号级定位的 F1 分数提升了 5.0 到 18.8 个百分点。“错误（Wrong）”指标（与参考值零重叠）显著下降，表明完全失败的情况减少了。
鲁棒性： 收益在所有请求类型（查询、跨文件、搜索对抗型）和难度等级（简单、中等、困难）中均持续存在。在涉及分散实现点和跨模块交互的变更中，观察到的改进最为显著。

意义与主张

本文声称，演进复杂的智能体系统不仅取决于生成编辑，还取决于确定应该在哪里进行编辑。通过使行为与实现之间的联系变得显式化，Harness Handbook 解决了行为定位这一核心瓶颈。

作者将这项工作定位为迈向**工具架自我演进（Harness Self-evolving）**的一步。他们指出，一种能够与代码保持同步的、以行为为中心的代码库表示法，可以支持更广泛的应用，如行为审计和回归影响分析。最终目标是使智能体能够自主完成定位、规划、执行和重同步的闭环，推动智能体工具架在无需更大规划 Token 预算的情况下实现自我改进。