引言

“2025 年是 Agent 年，2026 年是 Agent Harness 年。”

这是"每日一个开源项目"系列的第171篇文章。今天的主角是 Harness Handbook——一个把 AI Agent Harness 代码库转换成可导航行为手册的工具，配套 arXiv:2607.13285 论文（2026 年 7 月）。

先解释一个概念：Harness 是围绕基础模型的编排层——构建 Prompt、管理状态、调用工具、协调执行。Claude Code 里的 hook 系统、Open Interpreter 的 Harness 模块、各类 Agent 框架的调度层，都是 Harness。

Harness 的维护是一个持续的工程难题。需求变化时，开发者必须把"我想改变这个行为"翻译成"具体需要改动代码库的哪些地方"。但生产级 Harness 代码库规模大、模块耦合紧、行为分散在多处——一个"添加秘钥脱敏"的需求，可能需要同时改动日志捕获路径、磁盘写入前处理、冷启动回退路径三个非相邻位置。关键字搜索发现不了全部。

Harness Handbook 的方案：先自动生成一本手册，把每个行为映射到代码证据；然后给 Agent 一个从行为描述渐进定位到具体代码位置的导航算法。

你将学到什么

• 什么是 Agent Harness，为什么它难以维护
• Handbook 的三层文档结构（L1/L2/L3）和状态寄存器视图
• BGPD（行为引导渐进展开）算法的四步导航机制
• 为什么散布式代码（Scattered Sites）是 AI 改代码的最大难点
• Resync：代码变更后如何增量同步手册
• 实测数据：在 Codex（Rust，2,267 文件）和 Terminus-2 上的效果

前置知识

• 了解 AI Agent 框架的基本概念（工具调用、状态管理）
• 有维护或使用过 LLM Agent 系统的经验
• 理解代码静态分析的基本概念

---

项目背景

什么是 Agent Harness

用一句话定义：Harness 是基础模型的外壳，把一个 LLM 变成一个能做事的 Agent。

用户输入
    ↓
Harness 层
    ├── 构建 Prompt（插入上下文、工具描述、系统提示）
    ├── 管理状态（对话历史、工具结果、会话变量）
    ├── 工具调用（执行代码、访问文件、调用 API）
    └── 协调执行（多步骤规划、错误重试、结果汇总）
    ↓
基础模型（GPT、Claude、Gemini…）
    ↓
输出

Harness 不是一个独立的组件，而是分散在整个代码库里的逻辑——Prompt 模板在这个文件，工具注册在那个模块，状态持久化在另一个目录。

维护 Harness 的核心难题

当产品需求变化时：

产品要求："给所有工具调用结果添加用量统计"

开发者需要找到：
  - 所有工具调用的执行路径（可能有 5-10 个）
  - 结果返回给 LLM 之前的处理位置
  - 可能的异步路径（普通调用 + 超时重试 + 流式返回）
  - 统计数据的存储位置

在一个 2,000+ 文件的 Rust 代码库里找全这些位置，靠关键字搜索大概率会漏

这就是 Harness Handbook 要解决的问题：编辑定位（Edit Localization）——在行为描述和代码位置之间建立可靠的映射。

作者/团队介绍

• 作者: Ruhan Wang
• 论文: arXiv:2607.13285（2026 年 7 月 14 日）
• License: Apache-2.0
• 语言: Python，调用 OpenAI 兼容 API

项目数据

• ⭐ GitHub Stars: 252
• 🍴 Forks: 25
• 📄 License: Apache-2.0
• 📝 arXiv: 2607.13285

---

Handbook 的结构

三层文档树（𝒟）

Handbook 不是平铺的文档，而是三层分级结构：

L1 — 系统概述
    整体架构、执行模型、主要阶段划分、全局数据流
    （"这个 Harness 由哪些核心部分组成，它们如何协作"）

L2 — 阶段页（per-stage）
    每个执行阶段的职责、输入、输出、依赖关系、局部状态
    （"这个阶段做什么，接受什么，产出什么，依赖谁"）

L3 — 源码锚定条目（source-grounded entries）
    每个行为条目链接到精确的文件/函数/代码区域定位符
    （"这个行为在代码库的哪个具体位置实现"）

两种叶子模式：

• 函数粒度：L3 条目 = 一个函数或连续代码区域，需要预先提供骨架（skeleton.yaml），适合小型代码库
• 文件粒度：L3 条目 = 一个文件，自动推断阶段骨架，适合大型代码库（如 Codex 的 2,267 个文件）

状态寄存器视图（𝒵）

这是 Handbook 最关键的设计之一，专门解决"散布式代码"问题。

对于每个跨阶段共享的状态变量（寄存器），视图记录：

• 所有读取这个状态的位置（跨越所有阶段）
• 所有写入这个状态的位置（跨越所有阶段）

示例：session_context 寄存器

写入位置：
  - auth.rs: authenticate() 函数中初始化
  - session_manager.rs: refresh_token() 中更新

读取位置：
  - tool_executor.rs: execute_tool() 调用前注入
  - response_formatter.rs: format_response() 中读取用户信息
  - audit_logger.rs: log_event() 中记录会话 ID

顶层代码阅读发现不了这种结构性相互依赖——它们在代码库里位置不相邻，但逻辑上是耦合的。状态寄存器视图把这种隐藏依赖显式化。

---

BGPD：行为引导渐进展开

Handbook 生成完之后，另一个核心贡献是 BGPD（Behavior-Guided Progressive Disclosure） 算法——引导代码 Agent 从行为描述渐进定位到具体代码位置。

四步过程：

修改请求："在所有工具执行前验证权限"

Step 1: 阶段选择
    读 L1/L2 → 找到与权限验证相关的阶段
    通过状态寄存器视图 → 追加通过共享状态耦合的相关阶段
    （发现 tool_executor 和 auth 两个阶段都相关）
         ↓
Step 2: 条目选择
    打开相关阶段页面 → 从 L3 条目中找出最相关的
    "按需展开条目体，限制不必要的上下文"
    （只展开 execute_tool、validate_permission 等相关条目）
         ↓
Step 3: 调用关系扩展
    沿函数调用图（或文件调用图）扩展
    边界节点"提供上下文但不作为编辑位置"
    （发现调用链：request_handler → execute_tool → shell_runner）
         ↓
Step 4: 源码验证
    对候选定位符在活跃代码库中验证
    只保留"仍然相关"的位置作为验证证据 Ê_q
    （确认三个需要修改的函数在当前代码库中存在且未变更）

这四步的关键设计：渐进展开，而不是一次性给 Agent 全部内容。L3 条目"按需展开"——在被选中之前，Agent 只看到摘要；在被选中之后，才展开完整的源码链接。这保持了 token 效率。

---

Resync：代码变更后的手册同步

代码在持续演化，Handbook 不能用一次就过期。Resync 模块处理代码变更后的增量同步：

代码变更（diff Δ）进入
        ↓
版本对齐
    重新解析代码库，重建程序图
    用"函数体指纹"（忽略行号）匹配函数
    → 被移动的函数被识别为"未变更"（不是新函数）
        ↓
范围更新
    ├── 阶段骨架未变 → 只刷新受影响的 L3 条目
    └── 骨架失效 → 对受影响部分重跑完整算法
        ↓
保守处理
    无法解析的定位符 → 标记为"冻结"并排除
    （宁可排除，不猜测）
        ↓
验证和打包
    新的 (ℛ′, ℋ′) 对成为下次请求的起点

Resync 中的 LLM 调用限制在四类：分类、文件归属、阶段内组织、描述修订。设计上尽量减少 LLM 调用，能用静态分析做的不用 LLM。

---

评测结果

在两个真实开源 Harness 上测试：

• Terminus-2：Python，6 个文件，小型 Harness
• Codex（Open Interpreter 的 Rust 版本）：Rust，2,267 个文件，大型 Harness

指标	Codex	Terminus-2
Handbook win rate	38.3%	45.6%
基线 win rate	28.3%	26.7%
Token 减少	12.7%	8.6%
最大 F1 提升（符号级）	+18.8 pts	+12.3 pts
最大 Wrong 减少	−25.9 pts	−13.3 pts

效果在三种 Judge 模型（GPT-5.5、Opus 4.8、DeepSeek-V4-Pro）、三种请求类型、三种难度级别下全部一致。

提升最大的三类情况：

1. 散布式代码（Scattered Sites）：行为实现在多个非相邻位置
2. 低频执行路径（Rarely Executed Paths）：不常触发的代码分支
3. 跨模块交互（Cross-Module Interactions）：跨越多个文件/组件的能力

这三类正好是关键字搜索最容易漏的——它们不在显眼位置，散在各处，或者躲在异常处理和回退路径里。

---

快速开始

安装

git clone https://github.com/Ruhan-Wang/Harness_Handbook.git
cd Harness_Handbook
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

配置 LLM API（OpenAI 兼容接口）：

export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1  # 或其他兼容接口
export LLM_MODEL=gpt-4o

生成 Handbook

大型代码库（无需骨架，自动推断）：

cd handbook_generate_large
python run.py --repo /path/to/your/harness/
# 输出到 ./output/，包含 overview.md、各模块页、module_tree.json

小型代码库（需提供 skeleton.yaml）：

cd handbook_generate_small
# 编辑 skeleton.yaml 定义阶段结构
python run.py --repo /path/to/your/harness/ --skeleton skeleton.yaml

作为 Agent 规划器

cd handbook_as_helper
python planner.py \
  --handbook /path/to/generated/handbook/ \
  --request "Add rate limiting to all LLM API calls"
# 输出：精确的编辑计划，包含需要修改的文件和函数

Resync

cd handbook_as_helper
python resync.py \
  --handbook /path/to/handbook/ \
  --repo /path/to/repo/ \
  --diff changes.diff
# 增量更新 handbook，只处理变更部分

---

项目地址与资源

• 🌟 GitHub: Ruhan-Wang/Harness_Handbook
• 📄 论文: arXiv:2607.13285
• 🌐 项目主页: ruhan-wang.github.io/Harness-Handbook
• 📊 Hacker News 讨论: Making Agent Harnesses Understandable, Auditable and Editable

---

总结

Harness Handbook 解决的是一个"AI 改 AI 代码"的精度问题。

用 AI Agent 修改 Harness 代码的最大失败模式不是模型能力不够，而是定位错误——Agent 改了三个位置，漏掉了两个，系统行为部分变化，bug 在角落里潜伏。这种错误靠更大的模型或更多的 token 都解决不了，因为根本原因是信息不够：Agent 不知道"散在各处的相关位置"。

三层文档树 + 状态寄存器视图，把这种隐藏依赖显式化，给 Agent 一张它之前没有的地图。BGPD 的渐进展开让 Agent 在找到足够信息后停止，而不是把整个代码库塞进上下文。Resync 让这张地图保持活跃，不会因为代码更新就作废。

Win rate 45.6% vs 26.7%，token 减少 12.7%——质量提升的同时反而更省 token。这是一个好的信号：Handbook 让 Agent 更精准而不是更饶。

Stars（252）还少，但这个问题的重要性随着 Harness 代码库规模增长会更突出。2026 年是 Agent Harness 的年份，这类工具的需求才刚开始增长。

---

探索 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。