每日一个开源项目（第171篇）：Harness Handbook - 给 AI Agent 的 Harness 代码库生成一本可导航的行为手册

每日一个开源项目（第171篇）：Harness Handbook - 给 AI 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 一个从行为描述渐进定位到具体代码位置的导航算法。

你将学到什么

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

前置知识

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

项目背景

什么是 Agent Harness

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

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

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

维护 Harness 的核心难题

当产品需求变化时：

 复制代码产品要求："给所有工具调用结果添加用量统计"开发者需要找到：  - 所有工具调用的执行路径（可能有 5-10 个）  - 结果返回给 LLM 之前的处理位置  - 可能的异步路径（普通调用 + 超时重试 + 流式返回）  - 统计数据的存储位置在一个 2,000+ 文件的 Rust 代码库里找全这些位置，靠关键字搜索大概率会漏

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

作者/团队介绍

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

项目数据

1. ⭐ GitHub Stars: 252
2. Forks: 25
3. License: Apache-2.0
4. arXiv: 2607.13285

Handbook 的结构

三层文档树（�）

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

 复制代码L1 — 系统概述    整体架构、执行模型、主要阶段划分、全局数据流    （"这个 Harness 由哪些核心部分组成，它们如何协作"）L2 — 阶段页（per-stage）    每个执行阶段的职责、输入、输出、依赖关系、局部状态    （"这个阶段做什么，接受什么，产出什么，依赖谁"）L3 — 源码锚定条目（source-grounded entries）    每个行为条目链接到精确的文件/函数/代码区域定位符    （"这个行为在代码库的哪个具体位置实现"）

两种叶子模式：

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

状态寄存器视图（�）

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

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

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

 复制代码示例：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 上测试：

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

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

提升最大的三类情况：

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

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

快速开始

安装

 复制代码git clone cd Harness_Handbookpython -m venv .venv && source .venv/bin/activatepip install -r requirements.txt

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

 复制代码export OPENAI_API_KEY=sk-...export OPENAI_BASE_URL=  # 或其他兼容接口export LLM_MODEL=gpt-4o

生成 Handbook

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

 复制代码cd handbook_generate_largepython 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_helperpython planner.py   --handbook /path/to/generated/handbook/   --request "Add rate limiting to all LLM API calls"# 输出：精确的编辑计划，包含需要修改的文件和函数

Resync

 复制代码cd handbook_as_helperpython resync.py   --handbook /path/to/handbook/   --repo /path/to/repo/   --diff changes.diff# 增量更新 handbook，只处理变更部分

项目地址与资源

1. GitHub: Ruhan-Wang/Harness_Handbook
2. 论文: arXiv:2607.13285
3. 项目主页: ruhan-wang.github.io/Harness-Han…
4. 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 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

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