每日一个开源项目（第171篇）：Harness Handbook - 给 AI Agent 的 Harness 代码库生成一本可导航的行为手册
英文标题：每日一个开源项目（第171篇）：Harness Handbook - 给 AI Agent 的 Harness 代码库生成一本可导航的行为手册
引言 这是"每日一个开源项目"系列的第171篇文章。今天的主角是 Harness Handbook——一个把 AI Agent Harness 代码库转换成可导航行为手册的工具
3.2 KB
589 B
6.3 KB
中文
引言
"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）、三种请求类型、三种难度级别下全部一致。
提升最大的三类情况 ：
- 散布式代码（Scattered Sites）：行为实现在多个非相邻位置
- 低频执行路径（Rarely Executed Paths）：不常触发的代码分支
- 跨模块交互（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/
小型代码库 （需提供 skeleton.yaml）：
cd handbook_generate_small
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
项目地址与资源
总结
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 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。
欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。
English / 原文
引言
"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）、三种请求类型、三种难度级别下全部一致。
提升最大的三类情况 ：
- 散布式代码（Scattered Sites）：行为实现在多个非相邻位置
- 低频执行路径（Rarely Executed Paths）：不常触发的代码分支
- 跨模块交互（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/
小型代码库 （需提供 skeleton.yaml）：
cd handbook_generate_small
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
项目地址与资源
总结
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 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。
欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。