引言“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代码变更后如何增量同步手册实测数据在 CodexRust2,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.132852026 年 7 月 14 日License: Apache-2.0语言: Python调用 OpenAI 兼容 API项目数据⭐ GitHub Stars:252 Forks: 25 License: Apache-2.0 arXiv: 2607.13285Handbook 的结构三层文档树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 生成完之后另一个核心贡献是BGPDBehavior-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-2Python6 个文件小型 HarnessCodexOpen Interpreter 的 Rust 版本Rust2,267 个文件大型 Harness指标CodexTerminus-2Handbook win rate38.3%45.6%基线 win rate28.3%26.7%Token 减少12.7%8.6%最大 F1 提升符号级18.8 pts12.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跨越多个文件/组件的能力这三类正好是关键字搜索最容易漏的——它们不在显眼位置散在各处或者躲在异常处理和回退路径里。快速开始安装gitclone https://github.com/Ruhan-Wang/Harness_Handbook.gitcdHarness_Handbook python-mvenv .venvsource.venv/bin/activate pipinstall-rrequirements.txt配置 LLM APIOpenAI 兼容接口exportOPENAI_API_KEYsk-...exportOPENAI_BASE_URLhttps://api.openai.com/v1# 或其他兼容接口exportLLM_MODELgpt-4o生成 Handbook大型代码库无需骨架自动推断cdhandbook_generate_large python run.py--repo/path/to/your/harness/# 输出到 ./output/包含 overview.md、各模块页、module_tree.json小型代码库需提供 skeleton.yamlcdhandbook_generate_small# 编辑 skeleton.yaml 定义阶段结构python run.py--repo/path/to/your/harness/--skeletonskeleton.yaml作为 Agent 规划器cdhandbook_as_helper python planner.py\--handbook/path/to/generated/handbook/\--requestAdd rate limiting to all LLM API calls# 输出精确的编辑计划包含需要修改的文件和函数Resynccdhandbook_as_helper python resync.py\--handbook/path/to/handbook/\--repo/path/to/repo/\--diffchanges.diff# 增量更新 handbook只处理变更部分项目地址与资源GitHub: Ruhan-Wang/Harness_Handbook论文: arXiv:2607.13285项目主页: ruhan-wang.github.io/Harness-HandbookHacker 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 更精准而不是更饶。Stars252还少但这个问题的重要性随着 Harness 代码库规模增长会更突出。2026 年是 Agent Harness 的年份这类工具的需求才刚开始增长。探索 PrimeSkills —— 精选 AI Agent 与技能的市场每一个都经过真实企业工作流验证去掉浮夸留下真正有用的。欢迎访问我的个人主页发现更多有价值的见解和有趣的产品。