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

TL;DR 面向 AI agent harness 的持续演进，提出**Harness Handbook** 将行为与代码显式关联，结合 **BGPD** 策略大幅提升行为定位与修改规划效率，显著降低 token 成本。

问题

问题背景

现代 AI 智能体的能力不仅取决于基础模型，还高度依赖其 harness（编排层）—— 负责构建提示、管理状态、调用工具并协调执行流程的代码层。随着模型、API、环境和需求不断变化，harness 必须持续演进，频繁修改以适配新能力或调整现有行为。

现有方法局限

当前，开发者在修改 harness 前，需手动定位所有实现目标行为的代码位置。由于 生产级 harness 代码量大、耦合紧密、行为逻辑分散，而修改请求通常描述“系统应该做什么”，代码库却按文件和模块组织，行为到代码的映射需人工恢复。现有代码搜索、索引和长上下文处理虽然降低了浏览成本，但仍未实现自动化的行为定位，大量时间耗费在手动追溯调用链和理解跨模块交互上。这成为 harness 演化的核心瓶颈。

为什么这个问题难且重要

行为的分散性导致单一修改可能涉及多处代码片段（如 prompt 拼装、状态更新、工具调用序列），且修改请求往往未指明具体修改点。对于人类或编码智能体，理解并修改这类复杂系统不仅需要语义匹配，还需掌握执行逻辑和依赖关系。随着智能体系统日益复杂（如多轮对话、工具链、记忆管理），harness 的维护成本急剧上升，直接影响迭代速度和系统可靠性。业界迫切需要一种方法，将行为与代码自动关联，并在修改时引导定位与验证。

行业类比

这就像维护一个高度模块化的 RAG 流水线：当检索策略需要调整时，开发者必须遍历嵌入生成、索引构建、检索后处理等多个模块找出所有关联代码，而非仅修改一个配置文件。Harness Handbook 试图将这种隐性知识显式化，自动生成可导航的行为——代码映射，显著降低认知负荷。

核心洞察

• **行为-代码映射（behavior-to-code mapping）是演变式智能体框架的核心瓶颈，而手工恢复这一映射极度低效。** 传统方法依赖代码搜索、索引或长上下文处理，但最终仍需开发者从分散的文件和模块中自行拼凑行为逻辑，尤其在跨模块交互或罕见触发路径上极易遗漏。**Harness Handbook** 通过静态分析与 LLM 辅助完成行为中心的结构化合成，将“系统该做什么”的描述直接关联到对应源码位置，从根本上解决了定位前必须理解全局的认知负担，让修改决策有了可操作的锚点。
• **行为引导渐进披露（BGPD）证明了“优先级加载”在代码定位中比“全量加载”更精准、更经济。** 区别于一次性向规划器倾倒大量代码，BGPD 从高层行为阶段开始，沿调用关系逐层下钻并验证候选位置，仅在必要时扩大上下文。实验表明，这种方式不仅定位更准、编辑计划质量更高，而且消耗的 planner token 显著减少，尤其在分散站点、极少执行路径上提升最大，说明定位策略本身对于演变式系统的修改效果起决定性作用，而不仅是编辑生成能力。
• **结构化行为知识能让较弱的规划器匹敌甚至超越更强模型，重塑工具链的设计逻辑。** 在 Handbook 辅助下，一个相对弱的 planner 生成的编辑计划质量达到或超过未使用 Handbook 的强模型。这一反直觉结果表明，对于复杂智能体系统的持续演进，投入工程资源构建可自动维护的行为表示（而非单纯依赖更大模型）能够获得更高的边际收益，提示工程实践应更关注系统内部的可导航性与可编辑性。

方法

输入与目标

给定一个 agent harness 代码库，Harness Handbook 方法将从行为视角而非文件/模块视角组织其结构，建立行为到源代码位置的映射。输入包括：harness 源码、基础模型交互、工具调用和状态管理等代码。输出是一个行为中心化的文档树，称为 Harness Handbook，以及基于此 Handbook 的编辑定位与修改规划流程。

关键模块

1. 静态事实提取 (Phase I)
基于静态分析，从代码中抽取函数签名、调用图、文件依赖、工具引用和状态变量等共享静态事实，形成初始的结构化信息池。

2. 行为组织结构化 (Phase II)

• 函数或文件作为叶子节点：先以函数为最小行为单元，通过 LLM 辅助分类到不同阶段 (Stage)（如预处理、规划、执行、后处理）。对大型文件则构建文件级卡片并推理其阶段归属。
• 迭代审核与收敛：LLM 反复审视分配结果，交叉验证函数与文件行为标签，确保一致性。

3. 层级合成与打包 (Phase III)

• 使用 LLM 对已分类的节点进行自底向上合成，生成 L1（阶段概览）、L2（行为组）、L3（具体行为）三层文档树。每个行为节点包含自然语言描述及直接指向源代码的链接（如文件路径+行号）。
• 构建状态寄存器视图：汇总所有读写状态变量的位置，便于追踪副作用。
• 接地与失效处理：若 LLM 无法可靠关联到源码，则标记并由人工或后续流程完善。

4. 行为引导的渐进式披露 (BGPD)
在进行修改时，agent 或人类开发者按以下步骤使用 Handbook：

• 阶段选择：根据修改意图匹配最相关的顶层阶段。
• 入口选择：在该阶段中选择具体行为条目。
• 调用关系展开：从该行为入口沿静态调用图展开相关函数。
• 源码验证：利用 Handbook 中的源码定位信息，在真实代码中确认候选位置是否确实实现目标行为。

最终，BGPD 输出一个精准的代码位置列表，供后续编辑规划与执行使用。Handbook 本身也会在修改后通过自动再同步 (resynchronization) 更新，保持与代码库一致。

与同类方法的差异

与通用代码搜索或仓库索引工具不同，Harness Handbook 不是对代码文本的组织，而是将“行为”作为第一公民，通过静态分析与 LLM 推理自动构建起行为到代码的显式映射。这使得修改请求中提到的“做什么”能直接对应到“在哪里改”，大幅降低行为定位的认知负荷，尤其对分散在多处的横切关注点和罕见执行路径效果显著。

实验

实验设计

实验在两个开源 agent harness 代码库上收集了一组多样化的修改请求，模拟 harness 在模型、API、需求变化下的真实演进。比较 Handbook-Assisted 规划与直接基于代码搜索 / 长上下文处理的基线，评估行为定位准确度、编辑计划质量、规划 token 开销。

关键发现

• 行为定位与规划质量显著提升：手册辅助在减少规划 token 的同时，提高了代码定位准确性和计划质量；
• 弱势模型可匹配强模型：较弱的基础规划器在手冊帮助下，能达到甚至超越更强模型独立规划的表现；
• 泛化优势：在分散的代码点、低频执行路径、跨模块交互等困难场景中提升最大。

基线对比解读

基线方法依赖通用检索或长上下文，迫使开发者从行为描述手工反推代码位置。Harness Handbook 通过静态分析与 LLM 结构化，自动建立行为到源码的映射，使规划器能聚焦于“改什么”而非“在哪里改”。这说明在复杂 agent 系统演进中，确定修改位置是比生成修改更关键的瓶颈，也验证了行为中心化表示在工程实践中的价值。

行业影响

落地场景

AI Agent 的 harness（提示构建、状态管理、工具调用、执行协调的代码）随着模型与需求迭代需频繁修改，但其代码行为分散、耦合度高，定位修改点耗时。Harness Handbook 可嵌入任何基于 Agent 的业务：

• 客服与对话系统：修改政策应答或升级工具链时，快速定位涉及的状态变量与提示模板。
• 金融交易 Agent：调整风险评估逻辑，确保所有相关分支与验证规则被准确修改。
• 自动驾驶规划器：更新场景决策策略，追踪跨模块调用的行为实现。
• 企业自动化（RPA）：维护复杂的多步骤工作流，减少因遗漏修改点导致的回归错误。

商业价值

• 降本：将行为定位从数小时的手动搜索压缩到分钟级，减少高级开发者的时间投入；BGPD 机制降低规划 token 消耗，节约 LLM API 成本。
• 增效：更高质量的计划（定位准确率提升 + 计划完整度提高）直接缩短迭代周期，让产品更快响应市场变化。
• 体验提升：减少修改引入的缺陷，提升 Agent 行为的稳定性与可预测性，间接改善终端用户体验。

与现有工作流接口

Handbook 以 行为树 + 源代码链接 的形式存在，可作为：

1. IDE 插件 / Copilot 扩展：在开发者提出修改意图时，直接高亮相关代码块并展示调用关系。
2. CI/CD 中的自动文档：每次构建时生成或更新 Handbook，确保修改后立即同步，作为 code review 的辅助依据。
3. Agent 框架内置组件：例如在 LangChain 或 AutoGen 中作为 HandbookTool，让编码 Agent 规划修改时调用 BGPD 流程。

具体用例

• 电商售后 Agent：需要增加“部分退款”功能。开发人员提出修改请求，Handbook 立即定位到 handle_return()、calculate_refund() 等分散在 5 个文件中的 12 个函数，并提示需同步更新状态机 order_state。BGPD 引导规划 agent 只读取关键代码，生成修改计划后被验证，修改时间从 4 小时降至 45 分钟。
• 医疗问诊 Agent：需适配新的诊疗指南。Handbook 展示症状推理链涉及的所有函数与条件分支，避免因遗漏某个边缘病例处理而引发安全风险，使合规修改更可靠。

局限

• 方法高度依赖静态分析与 LLM 的结构化抽取，对于大量使用动态特性（如 `exec` / `eval`、运行时装饰器、动态导入）的 harness 可能遗漏行为或产生错误的代码映射，导致 **Handbook** 的覆盖度和准确性下降。文中虽提及验证步骤，但未量化动态代码场景下的召回率。
• 实验仅在两个开源 harness（OpenHands 和 SWE-agent）上进行，虽然它们具有一定的代表性，但评估范围有限。对于商业系统或多语言混合的 harness（如 Java/TypeScript 工具链）的泛化能力尚未验证；且 **BGPD** 定位效果在更大、更异构的仓库中可能退化。
• **Handbook** 的初始构建需要多轮 LLM 调用与人工审查，成本较高。此外，当 harness 发生重大重构或行为变更时，**Resynchronization** 机制虽支持增量更新，但在大规模、高频演化的生产中仍可能成为瓶颈，且论文未讨论持续维护的人机协作开销。