Harness Handbook 论文深度解读：把 Agent Harness 变成可导航、可审计、可编辑的行为地图

自动研究时间：2026-07-17 09:00（Asia/Shanghai）
来源流程：Hugging Face Papers 顶部论文 → Hugging Face 详情页 → arXiv 页面与 PDF/HTML 版本 → 项目页与代码仓库交叉核对
Hugging Face 顶部论文日期：Jul 16，论文 arXiv 提交日期：2026-07-14

执行摘要

Hugging Face Papers 在 Jul 16 的 Daily Papers 列表中将 Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable 排在最顶部，并在详情页标注为 #1 Paper of the day。论文对应 arXiv:2607.13285，作者包括 Ruhan Wang、Yucheng Shi、Zongxia Li、Zhongzhi Li、Yue Yu、Junyao Yang、Kishan Panaganti、Haitao Mi、Dongruo Zhou、Leoweiliang；论文页标注机构为 Tencent HY LLM Frontier、Indiana University、University of Maryland, College Park、University of Georgia、National University of Singapore。

这篇论文研究的是一个很工程化、但在 Agent 系统中越来越关键的问题：当一个 Agent harness 需要演进时，开发者或 coding agent 首先要知道“某个行为到底由哪些代码共同实现”。 文件树、全文搜索、仓库索引和长上下文能帮助看代码，但它们仍然以文件、函数、模块为中心；而真实变更请求往往是行为级的，例如“删除文件前是否一定要求确认”“某条命令的环境变量是否只在本次调用内生效”。一个行为可能横跨 prompt、tool wrapper、permission policy、state manager、sandbox runner、fallback path 等多个位置。

论文提出 Harness Handbook：从代码库自动生成一个以行为为中心的三层手册，把系统运行行为与可验证源码位置连接起来；再提出 Behavior-Guided Progressive Disclosure，BGPD，让 coding agent 从 L1 系统概览逐步下钻到 L2 行为单元和 L3 源码证据，最后生成更准确、更紧凑的 edit plan。实验在两个开源 agent harness（Codex 与 Terminus-2）上进行，每个 harness 30 个行为驱动变更请求。结果显示，Handbook-Assisted planning 在 Codex 上的总体 win rate 从 28.3% 提升到 38.3%，在 Terminus-2 上从 26.7% 提升到 45.6%；同时 planner token 成本分别下降 12.7% 和 8.6%。

一句话概括：Harness Handbook 的核心价值不是替 coding agent 写代码，而是先把“行为到代码”的定位问题显式化，让后续修改有可验证的边界。

1. 基本信息

论文要解决的核心问题

论文把问题定义为 behavior localization：给定一个自然语言行为变更请求，找到所有共同实现该行为的代码位置。这个定义比传统 code search 更严格，因为它要求找到完整行为链，而不是找到一个看起来相关的文件。

举例说，“删除文件前要询问用户确认”并不一定由一个 confirmBeforeDelete() 函数实现。它可能同时依赖：

• 系统提示是否把删除操作标记为高风险动作；
• 工具 schema 是否暴露删除能力；
• tool wrapper 是否能拦截删除调用；
• permission policy 是否要求确认；
• state manager 如何记录确认请求与用户回复；
• sandbox runner 如何执行或拒绝实际删除；
• headless、auto-approval、fallback path 是否绕过主路径。

这就是论文认为“文件树显示代码在哪里，行为地图显示系统怎么运行”的原因。

2. 研究背景和动机

2.1 为什么 Agent Harness 成为第一类工程对象

现代 Agent 的能力不只来自 foundation model，也来自外层 harness。Harness 负责构造 prompt、维护状态、调用工具、管理权限、处理执行结果、协调多轮控制流。相同模型放在不同 harness 中，行为边界和可靠性会明显不同。

相关领域已经形成几个方向：

本论文站在这些工作的交叉点上：Agent harness 已经重要，coding agent 已经能修改代码，但在修改之前，仍缺一个行为级、可验证、可维护的中间表示。

2.2 传统仓库理解工具的缺口

全文搜索、embedding 检索、repo map、symbol index、长上下文读取和自然语言摘要都能降低读代码成本，但它们通常从“实现结构”出发：

• 搜索结果按关键词匹配，而行为可能没有显式关键词；
• repo map 展示模块和调用关系，但不解释用户可感知行为；
• 长上下文能读更多文件，但不能保证读到完整行为链；
• 自然语言摘要容易漂移，如果没有源码锚点，审计价值有限；
• coding agent 的 plan 可能找到主路径，却漏掉镜像实现、冷路径、状态清理、模板提示、fallback 分支。

Harness Handbook 的动机就是把“行为”变成导航入口：先定位行为单元，再回到源码证据。

3. 核心贡献和创新点

论文的贡献可以拆成四项。

3.1 定义 Behavior Localization

论文将 behavior localization 定义为：识别自然语言请求所描述行为的所有实现位置。这个定义让“定位”从普通检索升级为前置工程任务。对复杂 harness 来说，只有完整定位后，edit plan 才可能完整。

3.2 Harness Handbook 表示

Harness Handbook 不是普通 README，也不是文件级摘要，而是一个三层行为手册：

此外，论文还引入 cross-stage state-register view，用来记录跨阶段共享状态。这个设计很关键，因为很多行为不是函数调用链单独决定的，而是由状态读写、配置开关和执行阶段共同决定。

3.3 自动构建 Pipeline

Harness Handbook 由三阶段 pipeline 构建：

flowchart TD
    A[源代码仓库] --> B[Phase I 静态事实抽取]
    B --> C[程序图 Program Graph]
    C --> D[Phase II 行为化组织]
    D --> E[阶段骨架与行为映射]
    E --> F[Phase III 分层手册合成]
    F --> G[L1 系统概览]
    F --> H[L2 行为单元概览]
    F --> I[L3 源码锚定细节]
    F --> J[跨阶段状态视图]
    I --> K[当前源码验证与冻结机制]

Phase I 是确定性的静态分析：抽取函数、类、签名、源码位置、内部调用边、外部边界、状态读写等。论文明确说 unresolved calls 被记录，而不是猜测目标，这降低了 LLM 幻觉进入事实层的风险。

Phase II 负责把程序事实组织成行为结构。论文支持两种 leaf mode：

• function-as-leaf：L3 以函数或函数内连续区域为叶子，适合有可信执行阶段骨架的小到中型 harness；
• file-as-leaf：L3 以文件为叶子，适合没有可信 seed skeleton 或函数级组织超出预算的大型仓库。

Phase III 把阶段骨架和源码组织结果合成为 L1-L3 文档树，并打包定位与未来 resync 所需结构化数据。

3.4 BGPD 与自动 Resynchronization

BGPD 是论文面向 coding agent 的使用流程，全称 Behavior-Guided Progressive Disclosure。它的思想是：不要一开始把所有文件扔给 planner，而是按行为相关性逐步展开上下文。

flowchart LR
    A[自然语言变更请求] --> B[L1 确认系统阶段]
    B --> C[L2 选择相关行为单元]
    C --> D[L3 获取源码 locator]
    D --> E[沿调用关系扩展候选集合]
    E --> F[打开当前仓库验证 locator]
    F --> G[生成 source-grounded evidence]
    G --> H[Planner 生成 edit plan]
    H --> I[Executor 应用修改]
    I --> J{是否产生非空 diff}
    J -->|是| K[局部 resync Handbook]
    J -->|否| L[保持现有 Handbook]

这里有两个细节值得注意：

1. Handbook 只负责引导，当前仓库仍是事实来源。BGPD 必须打开 live source 验证候选 locator，避免手册过期导致错误编辑。
2. 每次非空 diff 都会触发 resynchronization。若 stage skeleton 仍有效，只刷新受影响条目；若结构失效，则按原 leaf mode 重跑组织流程。无法解析或无法分类的内容会被冻结或记录为 coverage issue，而不是让模型硬猜。

4. 技术方法论详解

4.1 表示层：从文件中心到行为中心

传统仓库导航路径通常是：

需求描述 -> 关键词搜索 -> 文件/函数 -> 猜测行为链 -> 编辑

Harness Handbook 的路径是：

需求描述 -> 行为单元 -> 相关实现站点 -> 当前源码验证 -> 编辑计划

这种差异看似只是信息组织方式变化，实际改变了 planner 的错误模式。文件中心方法容易出现两类问题：

• 漏召回：找到主函数，却漏掉同一行为在 prompt、schema、state reset 或 fallback path 中的实现；
• 范围膨胀：为了避免漏掉，planner 打开大量弱相关文件，token 成本上升，plan 也更容易变得宽泛。

行为中心方法希望同时提高 recall 和 precision：用 L1/L2 缩小方向，用 L3 和源码验证保证证据落地。

4.2 构建层：静态事实先行，LLM 负责组织

论文没有把整个代码库直接交给 LLM 摘要，而是采用 facts-first 规则：

1. 静态分析先产生 program graph；
2. LLM 辅助把 program facts 映射到行为阶段；
3. 生成的自然语言解释必须保留源码 locator、函数引用和代码证据；
4. locator 必须能在当前仓库重新解析，否则对应 L3 条目会被冻结。

这使 Harness Handbook 更接近“带自然语言界面的结构化索引”，而不是一次性代码总结。

4.3 修改层：计划质量公式如何理解

论文把 plan quality 拆成三个维度：

• Localization：是否找到所有必要实现位置；
• Scope Control：是否避免无关文件和过宽编辑；
• Reasoning：计划理由是否基于真实代码与请求，而不是空泛猜测。

可以用如下加权形式理解论文的 judge score：

论文说明 Localization 权重最大，因为编辑计划的首要失败模式是没找到该改的位置。两组 plan 的分数相差至少阈值 δ = 3 时才判定胜负，否则记为 tie。这个设计避免把微小 judge 噪声误读成显著胜负。

4.4 定位指标如何解释

论文用独立参考计划来计算 file 和 symbol 粒度的定位指标：

同时报告 Wrong：有效请求中与参考计划零重叠的比例。对 coding agent 来说，Wrong 是特别危险的指标，因为它意味着 planner 进入了完全错误的子系统，即使后续执行器再强也很难补救。

5. 实验设计和主要结果

5.1 实验设置

论文实验聚焦 localization 和 edit planning，而不是最终代码是否一次通过。流程如下：

Codex 使用 file-as-leaf 模式，因为它在仓库规模上更适合推断层级；Terminus-2 使用 function-as-leaf，因为它有可靠 seed skeleton。

5.2 Plan quality 与 token 成本

这个结果很有说服力，因为它同时提升质量并降低 token 成本。换句话说，Handbook 的收益不是“喂更多上下文”，而是减少无效探索，让 planner 更早进入相关实现区域。

5.3 维度拆解

论文报告，按三个 judge 平均后，Handbook-Assisted 在两个 harness 的三个评分维度上都更高：

Terminus-2 的提升更大，可能和 function-as-leaf 表示更细、seed skeleton 更可信有关；Codex 仓库更大，file-as-leaf 更保守，因此收益更稳但幅度较小。

5.4 与强参考计划的定位对比

论文将 DeepSeek-V4-Pro planner 的预测 edit sites 与 Opus 4.8、GPT-5.5 生成的独立参考计划比较。部分关键结果如下：

这些数据支持论文的 RQ2：使用 Handbook 后，一个相对弱的 planner 能更接近强模型参考计划，尤其是在降低 Wrong 和提高 symbol-level F1 上效果明显。

5.5 请求类型和难度上的泛化

论文把请求分为：

• Q，Query：修改已有行为，但请求不透露目标位置；
• CF，Cross-file：新增端到端能力，需要跨 schema、pipeline、runtime、接口等位置；
• SH，Search-Hostile：关键词不友好，相关逻辑藏在镜像实现、fallback、冷路径或间接执行路径中。

实验显示，Handbook 在三类请求和 Easy/Medium/Hard 难度上总体都保持优势。最大价值出现在 scattered sites、rarely executed paths 和 cross-module interactions 上，也就是传统关键词搜索最容易漏的场景。

6. 关键图表和公式解读

6.1 Figure 1：三层渐进披露结构

论文 Figure 1 展示了 Harness Handbook 的 L1-L3 层级。它的重点不是“生成漂亮文档”，而是用不同粒度控制上下文暴露：

• L1 给系统执行全局图，防止 planner 一开始陷入局部文件；
• L2 把阶段和行为单元列出来，帮助定位责任边界；
• L3 才给源码证据、状态变化、异常路径和 locator；
• state-register view 让跨阶段状态成为可导航对象。

这对应一个工程原则：越早的阶段越应该压缩信息，越接近编辑越必须回到源码证据。

6.2 Figure 2：构建流程

Figure 2 的关键是静态分析和 LLM 辅助组织的分工。静态分析负责 facts，LLM 负责 behavior structuring，最终合成的 L3 条目必须能指回真实源码。这个设计比纯 LLM 总结更可审计，也比纯静态分析更贴近自然语言行为请求。

6.3 Figure 3：质量与成本同时改善

Figure 3 的重要结论是：Handbook-Assisted 不只是赢率更高，token 成本也更低。对于生产 coding agent，这一点实际价值很大，因为仓库定位通常是长任务的主要 token 消耗来源之一。更少无效探索意味着：

• 更低推理成本；
• 更短等待时间；
• 更小上下文污染；
• 更少无关文件进入 edit plan。

6.4 Table 1：Wrong 指标比 F1 更警醒

Table 1 中最值得关注的是 Wrong 的下降。例如 Codex symbol 粒度相对 Opus 4.8 参考计划，Wrong 从 44.4% 降到 18.5%。这说明 Handbook 不只是略微提高相似度，而是显著减少“完全跑偏”的计划。对自动代码修改来说，完全跑偏比局部漏召回更危险，因为它可能导致无关编辑、测试失败甚至误改安全边界。

7. 局限性和未来工作

7.1 实验只评估 plan，不评估最终代码成功率

论文有意把 evaluation scope 限定在 localization 和 edit planning。这样能隔离研究问题，但也留下一个问题：更好的 plan 是否稳定转化为更高的最终 patch success rate？Executor、测试覆盖、代码生成质量、review 策略都会影响最终结果。

未来工作应补充端到端指标：

• patch applies rate；
• tests pass rate；
• human review acceptance；
• regression rate；
• merge 后线上回滚率。

7.2 Handbook 质量依赖静态分析覆盖和阶段组织

如果语言适配器不能准确抽取调用关系、状态读写或外部边界，Handbook 的行为地图会不完整。论文通过 unresolved log、coverage record、freeze 等保守策略降低风险，但这也意味着手册可能在关键区域缺失。

多语言 monorepo、动态语言反射、插件加载、运行时生成代码、配置驱动行为和隐式 side effect 都会增加构建难度。

7.3 LLM-assisted structuring 仍可能产生组织误差

虽然源码 locator 和验证机制限制了事实幻觉，但“某个函数属于哪个行为单元”“某个阶段边界如何划分”仍需要模型判断。若行为组织错误，BGPD 可能从一开始就走错阶段。

论文使用 proposer-reviewer loop 和验证步骤缓解，但还需要更系统的质量度量，例如：

• 行为单元覆盖率；
• L3 locator stale rate；
• state-register 完整性；
• stage assignment agreement；
• 人类审计通过率。

7.4 Resynchronization 的成本和稳定性仍需验证

论文提出每次非空 diff 后局部 resync，但在快速演进的大型生产仓库中，resync 的延迟、冲突处理、并发分支、手册版本合并都会变复杂。尤其当多个 agent 同时修改 harness 时，Handbook 可能需要类似代码索引服务的持续更新机制。

7.5 评审模型和参考计划仍有主观性

论文使用 GPT-5.5、Opus 4.8、DeepSeek-V4-Pro 三个 judge，并用强模型生成参考计划。多 judge 能降低单模型偏差，但参考计划不等于唯一正确答案。某些修改存在多种合理定位边界，人工 gold standard 或真实维护者评审仍是更强证据。

8. 实际应用场景和潜在影响

8.1 Coding agent 产品的仓库理解层

对 Codex、Claude Code、OpenHands、SWE-agent 这类 coding agent，Harness Handbook 可以作为仓库级“行为索引”。用户提出“把某个权限策略改成更严格”时，agent 不必先全局 grep，而是先查行为地图，再验证源码。

8.2 Agent 安全审计

很多安全问题不是单点 bug，而是跨路径策略不一致。例如主路径要求确认，fallback path 却绕过确认；CLI 模式要求 sandbox，headless 模式却默认放行。Harness Handbook 的 L3 行为链和 state-register view 适合做安全审计入口。

8.3 企业内部 Agent 平台维护

企业内部常有定制 Agent 平台：权限、审批、工具访问、审计日志、数据边界都由 harness 控制。随着需求变化，平台 team 需要频繁修改行为。行为手册能降低 onboarding 成本，也能让审计、产品、工程在同一个行为对象上沟通。

8.4 人类与 Agent 协同开发

论文项目页提出 Handbook Studio：用户从行为地图选择要改的行为，系统生成 edit plan 和 diff，用户确认后再写入。这种模式把人类控制点放在行为层，而不是让人类直接审查海量搜索结果。

8.5 更广义的软件系统理解

虽然论文聚焦 agent harness，但“行为定位”问题也存在于支付系统、权限系统、工作流引擎、DevOps 平台和大型前端应用中。只要一个用户可见行为横跨多个模块，行为级手册就有价值。

9. 与相关工作的关系

论文的独特位置在于：它既不是单纯搜索器，也不是自动修复器，而是为 harness evolution 提供中间知识层。

10. 批判性评价

10.1 论文最强的地方

1. 问题定义准确：behavior localization 的定义抓住了 coding agent 改复杂系统前的真实瓶颈。
2. 方法工程感强：静态事实抽取、LLM 组织、源码 locator、验证、冻结、resync 都服务于可维护性。
3. 实验指标合理：同时看 plan quality、localization accuracy 和 token cost，比只看最终 pass rate 更能解释机制。
4. 适用场景清晰：最适合行为分散、路径复杂、关键词不友好的 agent harness。
5. 与生产实践接近：Codex 和 Terminus-2 都是 open-source agent harness，任务按 Query、Cross-file、Search-Hostile 分类，贴近真实修改请求。

10.2 需要谨慎看待的地方

1. 最终 patch 成功率仍未证明：计划质量提升是必要条件，不等于代码修改一定成功。
2. 构建成本未充分展开：生成和维护 Handbook 本身需要静态分析、LLM 调用和 resync 管线。
3. 大型动态系统仍难：插件、反射、运行时配置和隐式状态可能让行为地图不完整。
4. 评审仍有模型偏差：多 judge 有帮助，但不是维护者 ground truth。
5. 与现有 IDE / code intelligence 集成仍是工程挑战：要真正进入日常开发，需要持续索引、权限控制、分支同步和 UI 支持。

11. 关键要点总结

• Harness Handbook 把 agent harness 的代码库从“文件树”重组为“行为地图”，核心目标是解决 behavior localization。
• 三层结构 L1/L2/L3 体现 progressive disclosure：先建立系统模型，再定位行为单元，最后回到源码证据。
• BGPD 让 coding agent 以行为为入口定位实现位置，并要求在当前仓库验证 locator，避免过期手册直接误导编辑。
• 实验显示，Handbook-Assisted planning 在 Codex 和 Terminus-2 上同时提高 win rate 并降低 planner token 成本。
• Table 1 中 Wrong 指标显著下降，说明 Handbook 能减少 planner 完全跑到错误子系统的情况。
• 论文没有证明端到端 patch success rate，因此更适合作为“定位与计划层”的证据，而不是完整自动编程闭环的最终结论。
• 对生产 Agent 平台而言，Harness Handbook 可以成为安全审计、权限修改、工具行为演进和人机协作 review 的基础设施。

12. 参考资料

1. Hugging Face Papers: Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable，https://huggingface.co/papers/2607.13285
2. arXiv:2607.13285: Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable，https://arxiv.org/abs/2607.13285
3. Harness Handbook HTML 版本，https://arxiv.org/html/2607.13285
4. Harness Handbook 项目页，https://ruhan-wang.github.io/Harness-Handbook/
5. Harness Handbook GitHub 仓库，https://github.com/Ruhan-Wang/Harness_Handbook
6. Code as Agent Harness，https://arxiv.org/abs/2605.18747
7. Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses，https://arxiv.org/abs/2604.25850
8. SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering，https://arxiv.org/abs/2405.15793
9. OpenHands: An Open Platform for AI Software Developers as Generalist Agents，https://arxiv.org/abs/2407.16741
10. SWE-Explore: Benchmarking How Coding Agents Explore Repositories，https://arxiv.org/abs/2606.07297
11. SHERLOC: Structured Diagnostic Localization for Code Repair Agents，https://arxiv.org/abs/2606.24820
12. Harness engineering: leveraging Codex in an agent-first world，https://openai.com/index/harness-engineering/