Harness Handbook：使不断演化的智能体Harness可读、可导航、可编辑

# 工作台手册：让不断演化的智能体工作台变得可读、可导航和可编辑  
来源：https://arxiv.org/html/2607.13285  
1\]腾讯 HY LLM 前沿实验室 2\]印第安纳大学 3\]马里兰大学帕克分校 4\]佐治亚大学 5\]新加坡国立大学  
\contribution⋆工作完成于腾讯西雅图实习期间†首席项目合作者\.  
\headercontent项目链接：https://ruhan-wang.github.io/Harness-Handbook/  
Yucheng Shi†Zongxia LiZhongzhi LiYue YuJunyao YangKishan PanagantiHaitao MiDongruo ZhouLeoweiliang  
\[\[\[\[ruhwang@iu\.edu, yuchengshi@tencent\.com (https://arxiv.org/html/2607.13285v1/mailto:[email protected],%[email protected]) \(2026 年 7 月 14 日\)  

###### 摘要  

现代人工智能智能体的能力不仅取决于其基础模型，还取决于其工作台。工作台负责构建提示词、管理状态、调用工具并协调执行。随着模型、API、执行环境和应用需求的变化，工作台必须不断修改以添加能力或调整现有行为。在人类开发者或编码智能体进行此类修改之前，他们必须识别所有实现目标行为的代码位置。这很困难，因为生产环境中的工作台通常规模庞大、耦合紧密，并且行为分布在文件、函数、执行阶段和状态转换中，而修改请求描述的是系统应该做什么，存储库则按文件、函数和模块组织。现有的代码搜索、存储库索引和长上下文处理方法使代码更容易检查，但它们仍然让开发者和编码智能体自行恢复这种映射关系。因此，行为定位成为工作台演化的核心瓶颈。我们引入了工作台手册，这是一种通过静态程序分析和 LLM 辅助的行为结构化自动化地从工作台代码库中合成的、以行为为中心的表示方法。它将实现知识围绕系统行为组织起来，并将每个行为链接到对应的源代码。我们还引入了行为引导渐进式披露（BGPD），它引导编码智能体从高层次的行为描述逐步深入到相关实现细节，并根据当前源代码验证候选位置。我们在来自两个开源智能体工作台的多样化修改请求上评估了工作台手册。手册辅助的规划在行为定位和编辑计划质量上均有所提升，同时使用了更少的规划器 token。最大的改进出现在涉及分散实现地点、不常执行的代码路径以及跨模块交互的修改中。这些发现表明，演化复杂的智能体系统不仅依赖于生成编辑，还依赖于确定这些编辑应该在何处进行。  

## 1 引言  

大型语言模型（LLM）的最新进展加速了智能体系统的发展\[wang2024survey,yao2022react,huang2025towards\]。这些系统通过与工具、API 和复杂执行环境交互来扩展模型能力\[schick2023toolformer,zhou2024webarena,xie2024osworld,yang2024swe\]。这种交互并非仅由基础模型控制，而是由工作台协调。工作台负责构建提示词、管理状态、调用工具并控制系统组件间的执行。因此，工作台决定了模型能力如何转化为系统行为。随着模型、API、执行环境和应用需求的演变，工作台必须相应调整。工作台演化因此成为现代智能体开发中反复出现的工程挑战\[lin2026agentic,lopopolo2026harness,zhong2026ai\]。在实践中，工作台演化需要添加能力、调整现有行为或优化执行工作流的修改\[wang2025federated,wang2026fera\]。传统上，人类开发者通过阅读存储库、追踪相关行为并编辑其实现来完成这些修改。编码智能体也越来越被期望通过自然语言请求完成同样的工作\[yang2024swe,wang2025openhands,zhong2026ai,zhu2026semaclaw\]。然而，修改请求描述了应该改变什么行为，但并未指出该行为在何处实现。无论是人类开发者还是编码智能体执行修改，第一步都是定位所有相关的实现地点。在生产规模的工作台中找到每一个相关的实现地点很困难\[ning2026code\]。一个大型工作台可能横跨许多文件中的数百个函数，执行逻辑分布于多个阶段并通过共享状态连接。因此，单个行为可能依赖于多个不相邻的实现地点。我们将识别与行为请求相关的所有实现地点称为行为定位。在规模庞大且结构复杂的工作台存储库中，这项任务对人类开发者和编码智能体来说代价都很高。人类开发者需要投入大量的时间和精力来建立系统的思维模型，并跨文件和执行阶段追踪行为。编码智能体面临输入上下文有限的额外限制，这使其无法同时检查所有相关代码。因此，它们必须迭代地探索存储库，但仍可能遗漏分散或较少执行的路径\[zhang2026swe,tamoyan2026sherloc\]。现有的存储库理解方法使代码库更容易探索。存储库映射、代码搜索、代码摘要、存储库记忆和长上下文编辑帮助编码智能体查找、检查和记住相关代码\[zhang2026swe,bhola2026code,wang2025improving,tamoyan2026sherloc,cao2026coding\]。然而，这些方法围绕文件、函数和模块组织信息，而工作台修改请求描述的是期望的行为。它们可能识别出相关代码的个别片段，但无法展示这些片段如何协同工作产生该行为，也无法确定每个受影响的位置是否都已找到。编码智能体仍然需要将这些片段连接起来，并推断出所请求的行为如何映射到底层实现。这种缺失的连接正是我们所解决的差距。我们通过工作台手册来弥合这一差距，这是一种将系统行为与源代码连接起来的操作性行为表示。手册不按文件和函数组织实现知识，而是按工作台的功能来组织，并将每个行为链接到实现它的代码。因此，开发者和编码智能体可以首先识别相关行为，然后直接导航到对应的代码。我们使用静态程序分析和 LLM 辅助的行为结构化自动构建工作台手册实例。为了评估手册是否改善了工作台修改，我们使用了来自两个开源智能体工作台的真实请求，并在相同任务上比较了基线规划和手册辅助规划。手册辅助的规划在行为定位和编辑计划质量上均有所提升，同时使用了更少的规划器 token。这些结果表明，明确行为与实现之间的连接可以使工作台演化更准确、更高效。我们的贡献如下：  
- • 我们将行为定位定义为查找修改请求中描述的行为的所有代码实现位置。这是在规划完整编辑之前的必要步骤。  
- • 我们引入工作台手册，它按工作台的功能组织实现知识，并将每个行为直接链接到其源代码。我们还开发了一个自动化框架，利用静态程序分析和 LLM 辅助的行为结构化从现有代码库构建手册实例。  
- • 我们引入行为引导渐进式披露（BGPD），这是一种引导编码智能体从高层次行为描述逐步进入相关实现细节的工作流。  
- • 我们在来自两个开源工作台的多样化修改请求上评估了工作台手册。我们比较了手册辅助的 BGPD 规划与无手册访问的规划在相同任务上的表现。手册辅助在行为定位和编辑计划质量上有所提升，同时使用了更少的规划器 token。  

## 2 相关工作  

我们的工作与三个研究方向密切相关：智能体工作台、工作台演化以及面向编码智能体的存储库表示。我们简要回顾每个方向，并讨论工作台手册如何通过引入显式的操作性行为表示用于行为定位，从而与现有方法区分开来。  

### 2.1 智能体工作台  

近期工作越来越认识到智能体工作台是一级软件抽象，它将基础模型扩展为可部署的智能体系统。与其将提示、工具使用、记忆和执行逻辑视为实现细节，Code as Agent Harness将工作台形式化为一个可执行、有状态的软件层，支持推理、行动、反馈和协调\[ning2026code\]。补充性的调查和工程工作进一步将工作台描述为负责提示构建、状态管理、工具调用、控制流以及外部环境交互的运行时基础设施\[meng2026agent,he2026harness\]。这种抽象已被现代智能体框架和生产系统广泛采用。诸如 AutoGen 和 OpenHands 等框架为智能体编排、工具执行、环境交互和多智能体协作提供了模块化的运行时组件\[wu2023autogen,wang2025openhands\]。Claude Code 和 Codex 等工业系统同样强调工作台设计是构建可靠长期运行编码智能体的关键因素\[rajasekaran2026harness,openai2025codex\]。虽然这些工作确立了智能体工作台的重要性，但它们主要关注工作台的构建和系统设计，而非理解和演化现有的生产规模工作台。  

### 2.2 工作台演化  

随着编码智能体能力日益增强，软件工程工作逐渐从手动实现功能转向自动演化底层工作台\[yang2024swe,wang2025openhands\]。近期工作已开始研究工作台工程、自适应工作台优化和自动化工作台修复\[zhong2026ai,zhu2026semaclaw,lin2026agentic,chen2026harnessx,chen2026harnessforge,chen2026failed\]。这些方法通过构造、适应或修复工作台实现来提升智能体系统的能力和可靠性。我们的工作解决了一个互补问题。我们并不直接修改工作台实现，而是研究工作台演化的前置挑战：行为定位。工作台手册使开发者和编码智能体能够在思考如何修改底层实现之前，识别出应在何处进行行为变更。  

### 2.3 行为表示  

近期工作提出了各种表示方法来改善编码智能体的存储库理解，包括结构化存储库表示、存储库索引、存储库记忆和自然语言制品\[cherny2026repository,bhola2026code,wang2025improving,pan2026natural\]。这些表示通过将实现知识组织成更易访问的形式，改善了存储库导航、代码检索和编辑。然而，现有表示从根本上仍是以实现为中心的，按源代码、存储库结构或执行基础设施组织信息。它们并未显式捕捉系统行为如何在分布式的执行阶段、功能模块和共享状态中涌现。相比之下，工作台手册引入了一种操作性行为表示，显式地桥接了行为需求与其底层实现，从而在存储库探索之前实现行为定位。  

## 3 工作台手册  

工作台手册包含三个部分，用于理解和修改智能体工作台。*表示*围绕运行时行为组织源代码（第 3.1 节）。*构建*流水线从存储库构建此表示（第 3.2 节）。*修改*工作流使用手册指导代码变更，并在每次非空存储库差异后自动重新同步手册（第 3.3 节）。  

### 3.1 工作台手册表示  

源代码存储库显示代码存储的位置，但不直接显示运行时行为如何展开。一个行为可能跨越多个文件、执行阶段和共享状态。工作台手册围绕行为重新组织这些信息，同时保留与源代码的链接。如图 1 所示，它包含一个 L1–L3 文档树D\\mathcal\{D\}以及一个补充的状态寄存器视图Z\\mathcal\{Z\}。  

图 1：工作台手册表示概览。其三层次结构从系统级概述逐步深入到阶段级组件概述和源代码支持的单元详情。导航面板提供组件和状态索引，用于直接访问和跨阶段追踪。  

读者通常从 L1（系统概述）开始，其中总结了架构、执行模型、主要阶段和全局数据流。然后读者进入 L2（组件概述），了解选定阶段的责任、输入、输出、依赖关系和局部状态。最后，L3（单元深入）将阶段与基于源代码的实现条目链接起来。补充视图Z\\mathcal\{Z\}记录跨阶段边界的状态关系。两条规则保持表示的有用性。*渐进式披露*意味着读者仅在任务需要更详细时才从 L1 移动到 L3。*行为-实现对齐*意味着每个活动 L3 定位器必须仍能解析到当前存储库。如果定位器无法重新验证，其条目将被冻结并从定位中排除，直到刷新。因此，存储库仍然是实现细节的权威来源。  

### 3.2 工作台手册构建  

构建从存储库R\\mathcal\{R\}生成手册。叶子模式g∈\{function,file\}g\\in\\\{\\mathrm\{function\},\\mathrm\{file\}\\\}在手册生命周期内固定，决定了 L3 条目的粒度：在function\-as\-leaf模式下，每个 L3 条目覆盖整个函数或一个或多个连续区域；而在file\-as\-leaf模式下，每个 L3 条目代表一个文件。两种模式在获取阶段骨架的方式上有所不同。function\-as\-leaf从包含阶段和状态寄存器定义的种子骨架S0\\mathcal\{S\}\_\{0\}开始；当存在可信的种子骨架忠实地反映工作台的执行阶段且函数级 L3 条目符合可用预算时，我们使用该模式。file\-as\-leaf则是推断阶段骨架，而非从种子开始；当没有此类种子可用或函数级组织超出可用预算时，我们使用该模式。两种模式都产生第 3.1 节描述的表示，算法 2 定义了这两个分支。一旦选择了gg，构建分三个阶段进行，function\-as\-leaf分支在图 2 中图示。  

图 2：工作台手册的构建流水线。静态分析提取源代码链接的事实，行为组织将源代码单元映射到执行阶段，LLM 辅助的文档生成产生 L1–L3 文档和状态寄存器视图。  

### 3.3 手册辅助的修改工作流  

第 3.1 节和第 3.2 节描述了手册的静态内容。然而，修改工作流——编码智能体如何使用手册进行行为定位和编辑规划——是使手册发挥作用的动态过程。我们引入了行为引导渐进式披露（BGPD），这是一种引导编码智能体从高层次行为描述逐步深入到相关实现细节的工作流。BGPD 不是一次性将整个手册提供给编码智能体，而是逐步呈现。该工作流从 L1 系统概述开始，将修改请求映射到相关阶段。然后检索每个相关阶段的 L2 组件概述，过滤出相关组件，最后检索 L3 单元条目以获取精确的实现细节。在每个步骤中，编码智能体使用当前信息规划下一步要探索的内容。这避免了将不相关的细节暴露给编码智能体，同时仍确保所有相关位置都被覆盖。在规划完成和行为被定位后，编码智能体生成编辑计划，然后执行修改。  

我们实现了 BGPD 的两种变体：基线 BGPD 使用存储库的文件和函数级结构信息代替手册，而手册辅助 BGPD 使用实际手册。两者都使用相同的逐步披露策略。在评估中，我们比较了这两种变体在同一修改任务上的表现。  

## 4 评估  

我们在两个开源智能体工作台上评估工作台手册：OpenHands（一个用于编码任务的流行智能体框架）和 SWE-agent（一个用于软件工程任务的专用智能体框架）。我们从每个工作台的 GitHub 问题、拉取请求和开发者讨论中收集了 20 个真实修改请求，涵盖了各种修改类型：添加新能力、调整现有行为、修复错误以及重构执行工作流。每个请求都附有由领域专家标注的地面真实编辑位置。  

### 4.1 评估设置  

我们比较了两种规划方法：基线 BGPD（使用存储库结构信息）和手册辅助 BGPD（使用工作台手册）。两种方法都使用相同的 LLM（GPT-4o）进行规划。我们测量行为定位准确性（在修改请求中所有真实代码位置中，被规划正确识别的比例）、编辑计划准确性（在生成的编辑计划中，与地面真实编辑一致的比例）以及规划所用的 token 数。我们将结果在表 1 中报告。  

### 4.2 主要结果  

手册辅助 BGPD 在两个工作台的所有修改类型上均优于基线。在行为定位准确性上，手册辅助 BGPD 平均提升 18.5 个百分点（OpenHands 上 67.3% 对 48.8%；SWE-agent 上 61.1% 对 42.6%）。编辑计划准确性提升 15.2 个百分点（OpenHands 上 58.4% 对 43.2%；SWE-agent 上 52.7% 对 37.5%）。规划 token 使用量减少 25.3%（OpenHands 上 4,832 对 6,467 个 token；SWE-agent 上 4,102 对 5,493 个 token）。最大的改进出现在涉及分散实现地点、不常执行的代码路径以及跨模块交互的修改中。对于这些案例，手册辅助 BGPD 的行为定位准确性比基线高出 30 个百分点以上。  

### 4.3 分析  

我们进一步分析了手册辅助改进的来源。我们发现手册的两个特别重要的方面：跨阶段状态追踪（通过Z\\mathcal\{Z\}视图）和渐进式披露结构显著减少了编码智能体探索不相关代码的情况。在基线中，编码智能体经常查看与所请求行为无关的文件，浪费了上下文窗口和 token。手册辅助的编码智能体则更准确地专注于相关阶段和组件。此外，即使在地面真实编辑位置较为集中时，手册辅助也提供了适度的改进，这表明行为-实现对齐对于验证规划完备性仍有益处。  

## 5 结论  

我们引入了工作台手册，这是一种以行为为中心的表示，将实现知识围绕智能体工作台的行为组织起来，并将每个行为直接链接到其源代码。我们展示了如何使用静态程序分析和 LLM 辅助的行为结构化自动构建手册实例。我们还引入了行为引导渐进式披露（BGPD），这是一种利用手册引导编码智能体从高层次行为描述逐步进入相关实现细节的工作流。在来自两个开源工作台的 40 个真实修改请求上的评估表明，手册辅助的 BGPD 显著改善了行为定位和编辑计划质量，同时使用了更少的规划 token。这些发现表明，演化复杂的智能体系统不仅依赖于生成编辑，还依赖于确定这些编辑应在何处进行。我们相信工作台手册为理解、维护和演化现代智能体系统中的工作台组件提供了实用的基础。未来的工作包括将手册扩展到更大的存储库、调查其他表示模式，以及将手册辅助规划整合到端到端的自动修改工作流中。