Harness Handbook：让演化的 Agent Harness 可读、可导航、可编辑

论文概览

现代 AI Agent 的能力不仅取决于基础模型，还取决于 Harness——负责构造提示词、管理状态、调用工具和协调执行的运行时层。随着模型、API 和应用需求持续变化，Harness 需要不断被修改以增加能力或调整行为。但在修改之前，开发者或 Coding Agent 必须先找到实现目标行为的所有代码位置，这一步骤在生产级 Harness 中极其困难。

论文将此问题定义为行为定位（Behavior Localization）：给定一个描述"系统应该做什么"的修改请求，找到所有实现该行为的代码位置。生产级 Harness 通常跨越数百个函数、分布在多个文件中，单个行为可能依赖若干非相邻的实现位置，而修改请求描述的是行为而非代码位置。

Harness Handbook 通过三个核心设计解决这一瓶颈：

1. 行为中心表示：将实现知识按运行时行为而非文件/函数组织，每个行为直接链接到源码
2. 自动构建流水线：静态程序分析 + LLM 辅助行为结构化，三阶段自动从代码库生成 Handbook
3. 行为引导渐进式披露（BGPD）：引导 Coding Agent 从高层行为描述逐级深入到实现细节

核心创新

1. 行为定位问题的形式化定义

论文首次将"找到实现某行为的所有代码位置"定义为行为定位，这是 Harness 演化的前置瓶颈。与传统代码搜索不同，行为定位需要：

• 识别跨文件、跨执行阶段的分散实现位置
• 理解共享状态如何耦合不同模块
• 处理罕见执行路径和跨模块交互

现有方法（仓库地图、代码搜索、长上下文处理）按文件/函数/模块组织信息，而修改请求按行为描述——这一语义鸿沟是核心痛点。

2. 三级文档树 D + 状态寄存器视图 Z

Harness Handbook 的表示包含两个互补组件：

L1–L3 渐进式文档树 D：

状态寄存器视图 Z：记录跨阶段状态依赖关系（如 messages、scratchpad、tool_results），追踪状态如何在执行阶段间流动，捕获结构上相距甚远但通过共享状态耦合的模块。

两条核心规则保证表示的实用性：

• 渐进式披露：仅在任务需要时从 L1 深入到 L3
• 行为-实现对齐：每个 L3 定位器必须可对当前仓库重新验证；无法验证的条目被冻结并排除在定位之外

3. 双模式自动构建流水线

Handbook 支持两种叶节点模式，适应不同场景：

Function-as-Leaf 模式（适用于有可靠种子骨架的场景，如 Terminus-2）：

• 从种子骨架 $S_0$ 出发，将函数分配到执行阶段
• Propose-Review 循环迭代精炼分配
• 函数可整块放置或按连续区域分割

File-as-Leaf 模式（适用于无种子骨架或函数级组织超预算的场景，如 Codex）：

• 先为每个文件生成卡片描述
• 从卡片描述推断阶段骨架 $S$
• 文件分配到主阶段，跨切面文件可附加次要阶段

三阶段构建流程：

Phase I — 静态事实提取（确定性，无 LLM）：

• 语言适配器解析仓库，提取函数、类、模块
• 构建程序图 $G$，保留可解析的内部调用和命名边界
• 未解析调用记入审计日志，不做猜测

Phase II — 行为组织（LLM 辅助）：

• Function-as-Leaf：函数→阶段分配 + Propose-Review 循环
• File-as-Leaf：文件卡片 → 阶段推断 → 文件分配
• 预算控制：超出预算时保留显式缺口记录

Phase III — 层级合成与打包：

• Function-as-Leaf 自顶向下构建（L1→L2→L3）
• File-as-Leaf 自底向上构建（L3→L2→L1）
• 每个 L3 条目链接到静态识别的源码位置
• 验证后渲染并打包为 Handbook

4. BGPD 修改工作流与自动重同步

修改工作流包含四步闭环：

BGPD 行为定位采用粗到细策略：

1. 从 L1/L2 识别直接相关阶段
2. 通过 Z 视图追踪共享状态耦合的阶段
3. 在相关阶段中选择最相关的 L3 条目
4. 沿调用图扩展候选集
5. 打开当前仓库验证候选位置

编辑计划与执行：规划器将证据转化为编辑计划 $P$，每个编辑块记录目标文件、锚点、当前源码摘录和预期变更。动作声明 $\Gamma$ 记录三种操作类型：modify、add、remove。

自动重同步：非空 diff 触发 Resync 过程，优先更新受影响部分而非重建整个 Handbook。重同步中 LLM 调用仅限于四个语义步骤（分类、文件分配、阶段内组织、描述修订），其余操作全部确定性。

实验结果

实验设置

• 测试 Harness：Codex（file-as-leaf）和 Terminus-2（function-as-leaf）
• 修改请求：每个 Harness 30 个行为驱动请求，分为三类：
  • Query (Q)：修改现有行为，不透露目标位置
  • Cross-file (CF)：添加跨文件/模块的端到端能力
  • Search-Hostile (SH)：相关实现位于关键词搜索难以恢复的位置
• 规划器：DeepSeek-V4-Pro（弱模型定位能力测试）
• 评判模型：GPT-5.5、Opus 4.8、DeepSeek-V4-Pro 三方独立评分

RQ1：更优计划、更低成本

三个评判模型方向一致——Codex 上每个评判模型的差距都是 10.0pp，Terminus-2 上差距在 13.3–26.7pp 之间。胜率提升伴随 Token 降低，说明改进不依赖更大的规划预算。

RQ2：弱规划器匹配强模型

以 Opus 4.8 和 GPT-5.5 生成的参考计划为基准，Handbook 辅助下 DeepSeek-V4-Pro 的定位指标全面超越基线：

所有 24 项 Recall/Precision/F1 比较均高于基线，Wrong Rate（零重叠比例）最大降低 25.9pp。Terminus-2 上文件级 Precision 对 GPT-5.5 达到 93.3%。

RQ3：跨请求类型与难度的持续增益

按请求类型分层，六个对比全部偏向 Handbook 辅助：

• Codex 在 Query 请求上提升最大（+26.7pp）
• Terminus-2 在 Search-Hostile 请求上提升最大（+33.3pp）
• Cross-file 请求分别提升 16.3pp 和 20.0pp

按难度分层，六个对比同样全部正向（3.7–33.3pp），且增益不随标注难度单调变化，说明难度标签本身不能解释改进的来源。

启示与思考

核心洞察：Where 比 How 更关键

论文最深刻的贡献在于识别出 Harness 演化的真正瓶颈不是"如何修改代码"，而是"在哪里修改"。现有 Coding Agent 研究大量聚焦于代码生成和编辑能力，但论文数据表明，即使使用弱规划器，只要正确定位实现位置，也能产出与强模型匹敌的编辑计划。

行为中心 vs 实现中心的范式转变

传统仓库理解方法（Repository Map、代码索引、仓库记忆）本质上都是实现中心的——按文件、函数、模块组织信息。Harness Handbook 提出按运行时行为组织，这一转变类似于从"代码在哪里"到"代码做什么"的视角迁移。关键在于行为可能跨多个文件和执行阶段，需要一个中间层来桥接语义鸿沟。

重同步机制的实际价值

每次修改后自动重同步 Handbook 是一个重要的工程贡献。在持续演化的代码库中，静态文档很快过时。Handbook 的设计使仓库始终保持权威地位——L3 定位器无法重新验证时被冻结而非猜测，这避免了"过时文档误导"的经典问题。

局限性与未来方向

论文承认当前的评估聚焦于修改规划阶段，尚未评估执行后的端到端正确性。未来工作方向包括：

• Harness 自演化：使用 Handbook 作为共享行为记忆，Agent 自主完成定位→规划→执行→重同步的闭环
• 行为审计与回归影响分析：Handbook 的行为中心表示天然支持这类应用
• 多 Agent 协作：不同角色（定位 Agent、规划 Agent、执行 Agent）共享同一 Handbook

对 Agent 工程实践的启示

对于构建生产级 Agent 系统的团队，Harness Handbook 提供了可操作的框架：

1. 入门加速：新成员通过 L1 快速理解系统架构，按需深入 L2/L3
2. 修改效率：行为定位从"遍历仓库"变为"查目录"，显著降低认知负荷
3. 知识一致性：自动重同步确保文档与代码同步，消除手动维护负担
4. 弱模型赋能：Handbook 充当外部记忆，使能力较弱的模型也能完成高质量修改