当我们需要为一个复杂的智能体系统添加新功能或修改现有行为时，面临的第一个挑战往往不是“如何改”，而是“在哪里改”。一个看似简单的需求，其实现代码可能分散在数十个文件、跨越多个执行阶段，并通过共享状态相互关联。无论是人类开发者还是AI编码智能体，都不得不花费大量精力在代码的迷宫中定位所有相关位置。这个过程，被称为“行为定位”，已成为智能体系统演化的主要瓶颈。
最近，腾讯混元的一项名为“Harness Handbook”的研究提出了一种全新的解决方案。它通过静态程序分析和LLM辅助的行为结构化，自动为智能体的“控制层”代码库生成一份以行为为中心的“手册”。这份手册将代码的组织方式从传统的“文件-函数”结构，转变为“系统在运行时做了什么”，并清晰地链接每个行为到其对应的源代码。这不仅让代码库变得可读、可导航，更重要的是，它让修改变得可编辑。
论文标题：Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable
论文链接：https://arxiv.org/pdf/2607.13285
项目地址：https://ruhan-wang.github.io/Harness-Handbook/
研究背景：智能体系统演化的核心难题
现代AI智能体的能力不仅取决于其底层的大语言模型，更依赖于一个被称为“控制层”（Harness）的软件层。这个控制层负责构建提示、管理状态、调用工具、协调执行，是将模型能力转化为系统行为的关键桥梁。
随着模型、API、执行环境和应用需求的不断变化，控制层也必须持续演进：添加新能力、调整现有行为、或优化执行流程。然而，修改一个生产级的控制层代码库并非易事。这些代码库通常规模庞大、模块间耦合紧密，单个行为逻辑往往分布式地横跨多个文件、函数、执行阶段和状态转换。
当接到一个自然语言描述的修改请求时，无论是人类开发者还是编码智能体，都面临一个根本性的鸿沟：请求描述的是“系统应该做什么”，而代码库的组织是基于文件、函数和模块的。现有工具，如代码搜索、仓库索引和长上下文处理，虽然让代码更容易被“看到”，但它们本质上仍是围绕代码结构来组织信息。开发者或智能体仍然需要自己费力地建立起“行为”到“实现”之间的映射关系。
“行为定位”的困难，正是控制层演进的核心瓶颈。Harness Handbook 正是为了解决这一问题而生。
核心创新：从“代码结构”到“行为地图”
Harness Handbook 的核心思想是颠覆传统的代码理解方式。它不再将代码库视为一堆文件和函数的集合，而是将其重构为一份反映系统运行时行为的“操作手册”。
这份手册主要由三部分构成：
L1 - 系统概览：描述整个系统的架构、执行模型、主要阶段和全局数据流。 L2 - 组件概览：针对每个执行阶段，详细说明其职责、输入输出、依赖关系和局部状态。 L3 - 单元详解：将阶段链接到具体的、有源代码支撑的实现单元（函数或文件）。
此外，手册还包含一个状态寄存器视图，专门记录那些跨越阶段边界的状态关系，这对于理解分布式行为至关重要。
手册的构建遵循两个核心原则：渐进式披露（读者只在需要时从高层导航到细节）和行为-实现对齐（每个L3条目中的定位器必须能实时解析到当前仓库中的源代码）。如果某个定位器失效，其条目会被“冻结”并排除在定位过程之外，直到被刷新，从而确保代码仓库始终是实现的权威来源。
构建流程：从代码库自动生成手册
如何将一份传统的代码库自动转化为这样一份行为手册？研究团队设计了一个包含三个阶段的自动化构建流水线。
第一阶段：静态事实提取
这是一个确定性的、无需调用大语言模型的阶段。特定语言的解析器会分析代码仓库，提取出函数、外部边界、源码位置、签名和调用关系图。这个阶段生成的程序图是后续所有工作的基础。
第二阶段：行为组织
这是流水线的核心，根据选择的“叶节点”模式（以函数为单位或以文件为单位），将上一步提取的源单元组织到执行阶段的框架中。
函数为叶模式：适用于拥有可靠阶段框架定义的中小型代码库。该模式利用源码和调用图上下文，将每个函数（或其连续区域）分配到一个或多个执行阶段，并通过迭代审查来优化分配结果。 文件为叶模式：适用于大型代码库，或无现成阶段框架的情况。该模式首先为每个文件生成摘要“卡片”，然后结合程序图推断出阶段框架，再将文件组织到各个阶段中。
第三阶段：分层合成与打包
此阶段将组织好的阶段框架和源单元信息，合成为最终的L1-L3文档树和跨阶段状态寄存器视图。每个L3条目都会链接到一个静态识别的源码位置，并针对当前仓库进行验证，确保手册的可追溯性。最后，流水线渲染出用户可见的手册视图，并打包好用于后续源码定位和再同步所需的结构化数据。
应用与评估：行为引导的渐进式修改
手册构建完成后，如何利用它来指导实际的代码修改呢？研究团队提出了 “行为引导的渐进式披露” 工作流。当收到一个修改请求时，工作流不会直接扎进代码海洋，而是引导编码智能体（或开发者）遵循“由粗到细”的路径：
阶段选择：通过阅读手册的L1和L2，识别与请求直接相关的执行阶段，并借助状态寄存器视图纳入通过共享状态耦合的其他阶段。 条目选择：在相关阶段内，选择最相关的L3条目，获取其源码定位器。 调用关系扩展：沿着程序图中的调用关系，扩展候选位置集合。 源码验证：最后，打开真实的代码仓库，解析每一个候选定位器，只保留那些确实与请求相关的源码位置，形成已验证的证据集。
基于这个证据集，规划器可以生成更精准的编辑计划，然后由执行器应用修改。任何非空的代码变更都会自动触发手册的再同步过程，尽可能只更新受影响的部分，而非重建整个手册，保持了高效性。
为了验证Harness Handbook的有效性，研究团队在两个开源的智能体控制层（Terminus-2 和 Codex）上进行了实验，共使用了60个行为驱动的修改请求。
实验结果令人信服：
1. 以更低的成本获得更优的计划
如图3所示，在Codex和Terminus-2上，使用手册辅助的规划器，其计划质量的整体胜率分别提升了10.0和18.9个百分点。与此同时，平均每个请求消耗的规划器词元数反而下降了12.7%和8.6%。这证明手册带来的提升并非源于更大的计算预算，而是源于更高效的导航和信息组织。
2. 较弱的规划器可匹敌更强的模型
如表1所示，在手册的引导下，一个能力较弱的规划器（DeepSeek-V4-Pro）在定位实现位置时，其表现（召回率、精确率、F1分数）能够与独立生成的、由更强模型（Opus 4.8和GPT-5.5）制定的参考计划高度对齐。在Terminus-2上，其文件级F1分数甚至能达到84.7%和89.3%。这表明手册有效地弥补了规划器本身能力的不足。
3. 增益在不同请求类型和难度下持续存在
如图4所示，无论是修改现有行为的“查询类”请求、添加跨文件端到端能力的“跨文件类”请求，还是定位难度极高的“搜索不友好类”请求，使用手册辅助的规划器均表现更优。同样，在不同标注的定位难度（简单、中等、困难）下，手册带来的优势也 consistently 存在。
结语
Harness Handbook 的研究指出了一个关键问题：在演进复杂的智能体系统时，生成编辑指令固然重要，但确定“在哪里编辑”往往才是真正的挑战。通过引入一种以行为为中心、并与源码保持同步的仓库表示法，该工作成功地在“行为需求”和“分布式实现”之间架起了桥梁。
实验结果表明，让行为与实现之间的关系变得明确，可以在不增加规划成本的前提下，显著提升修改计划的准确性和定位效率。这不仅对AI编码智能体大有裨益，也能极大提升人类开发者的工作效率。
这项工作的价值远不止于辅助修改规划。作为一个与代码同步的行为中心化仓库表示，Harness Handbook 未来还可应用于行为审计、回归影响分析等更广泛的场景。研究团队的下一步计划是将其应用于“控制层自演进”：让智能体以手册作为共享的行为记忆，自主完成定位、规划、执行和再同步的闭环，推动系统朝着自我改进的方向发展。
对于任何正在构建或维护复杂AI智能体系统的团队而言，Harness Handbook 所代表的思想——从运行时行为的角度重新理解和组织代码——或许都将成为提升工程效能的关键一步。
-- 完 --
机智流推荐阅读：
1.
2.
3.
4.
cc | 大模型技术交流群 hf | HuggingFace 高赞论文分享群 lc｜LangChain 技术交流群 code | AI Coding 交流群 具身 | 具身智能交流群 硬件 | AI 硬件交流群 推理 | AI 推理框架交流群 智能体 | Agent 技术交流群
