Harness Handbook 将智能体行为映射到代码（28分钟阅读）

# Harness Handbook — 让智能体框架可理解、可审计、可编辑 来源：https://ruhan-wang.github.io/Harness-Handbook/ 智能体框架 · 腾讯红海 LLM 前沿 · 2026年6月 让智能体框架变得可理解、可审计且可编辑。 打开一个开源的编码智能体代码库，你可能想了解它实际是如何运行的，验证它是否像文档声称的那样安全，或者将其改编成你自己的智能体。这些目标听起来不同，但一旦你深入代码，它们都会归结为关于行为的具体问题。例如，智能体在删除文件前是否会询问用户？回答这个问题意味着要找到确认逻辑，追踪绕过路径，并识别修改会触及的每个实现点。在一个拥有数千个文件的仓库中，搜索 *delete*、*permission* 或 *confirm* 会返回零散的代码片段——而将它们拼凑成一个完整的行为链条是项艰巨的工作。 问题不在于缺少代码，而在于缺少从行为到实现的路径。我们需要的不是另一个代码索引，而是一张连接两者的地图。Harness Handbook 将分散的实现组织成一份**行为级手册**：它围绕系统行为构建执行结构，并将每个步骤链接到可验证的代码证据。用户可以直接询问他们想要理解、审计或修改的内容，而手册则会定位相关的行为单元、实现站点和后续步骤。随着框架的演进，这张地图使系统保持可理解和可审查——并在整个过程中让人类参与其中。 Ruhan Wang1,2,\* · Yucheng Shi1,† · Zongxia Li1,3 · Zhongzhi Li1,4 · Yue Yu2 · Junyao Yang1,5 · Kishan Panaganti1 · Haitao Mi1 · Dongruo Zhou2 · Leoweiliang1 1腾讯红海 LLM 前沿 · 2印第安纳大学 · 3马里兰大学 · 4佐治亚大学 · 5新加坡国立大学 \*通讯作者：Ruhan Wang ([email protected]) †项目主要合作者 单个行为请求往往跨越多个实现站点。Harness Handbook 将这些分散的位置重新组织成可导航的行为路径，并将每个步骤链接到可验证的代码证据——这样理解、审计和修改就可以共享一张地图。 ## 概览 1. **Harness Handbook 解决的问题。** 框架塑造了智能体行为展开的方式，然而这种行为往往是隐式的，深埋在复杂的代码中。Harness Handbook 将其组织成一张可导航、可验证的行为地图。 2. **阅读框架。** 手册以系统行为的方式解释框架如何运行，然后将这些解释链接回代码证据——这样读者无需从文件树和断开的源码片段开始。 3. **借助编码智能体进行更可靠的框架修改。** 手册将自然语言的修改请求映射到相关的行为单元和实现站点，帮助智能体跳过不相关的搜索，减少遗漏依赖，并生成更紧凑的编辑计划。 4. **在现有框架上构建你自己的智能体。** 通过用自然语言呈现框架的行为和能力，手册让用户能够理解并调整系统，而无需深入低层级代码——从而构建出符合需求的智能体。 第 01 部分 ## 为什么智能体框架需要一份行为级手册？ 当人们谈论 AI 智能体时，通常从模型能力开始。然而，一旦智能体开始执行实际工作，问题就会迅速从“模型能做什么？”转变为“系统允许它做什么？”命令是否执行、删除文件前是否询问用户、以及如何处理失败，这些不仅由模型决定，也由包围它的**框架**所决定。 要理解这些行为是如何产生的，你必须审视框架本身。在生产环境中全面做到这一点非常困难。例如，Codex 协调模型、工具、状态、权限和执行环境，将每个用户请求转化为一系列真实动作——但相关的实现分散在 **2,267 个文件、超过 34,000 个函数和近 160,000 个代码连接**中。在这个规模下，文件树显示代码的位置，但无法展示这些片段如何协同工作以产生行为。 目录和搜索结果本身无法重构一个完整的行为。我们需要一种不同的方式来阅读系统：从行为开始，然后追溯到源代码进行验证。这种方法服务于三个目标。 理解 了解框架如何运行 跟踪一个请求的完整流程：模型接收了什么、何时调用工具、状态如何移动、以及系统如何响应失败。 审计 验证行为是否符合预期 追踪实际的执行路径以检查权限、确认逻辑、沙箱和数据流，包括可能绕过这些保护措施的非正常路径。 适配 构建你自己的智能体 首先查看框架已经提供了哪些能力以及哪些行为和代码支持它们，然后根据自身需求扩展或调整系统。 所有这三个目标都从一个具体的**行为**开始，然后返回**代码**寻找证据。困难在于行为和代码并不是一一对应的：一个行为往往由分散在多个模块中的实现共同决定。 第 02 部分 ## 为什么一个行为会分散在这么多地方？ “在删除文件前询问用户”听起来像一个简单的规则。然而，要在代码中验证它是如何工作的，你必须遵循一个决策链：模型是否请求确认、工具调用能否被拦截、用户的选择记录在哪里、以及在什么条件下最终执行删除。这个链条中的任何一个环节都可能改变结果。 **一个行为，多个实现站点。** “在删除文件前询问用户”并非由单个函数决定。它是由提示词、工具包装器、权限配置、状态管理、沙箱执行和回退路径共同塑造的。理解、审计和修改框架都始于定位这些站点。每个实现站点只控制链条的一部分。没有一个单一的 `confirmBeforeDelete()` 函数能代表完整的行为。你必须跟踪提示词、工具包装器、权限和状态，一直到沙箱执行和回退路径，才能判断请求是会执行、被拒绝还是进入另一个流程。 因此，当你问“它真的会在删除文件前问我吗？”时，你并不是在执行关键词搜索——而是在重构一个行为链，并为其上的每个决策寻找代码证据。我们称之为**行为定位**。你重构这个链条的完整程度决定了解释、风险审查和修改边界。Harness Handbook 将隐藏在代码库中的行为链转化为一张可以逐层浏览并根据源代码验证的地图。 第 03 部分 ## Harness Handbook：一张可导航的行为地图 由于单个行为可能跨越多个实现站点，手册不能简单地重新包装文件树。Harness Handbook 以行为为中心来表示框架，使用 L1、L2 和 L3 层级来逐步缩小问题范围。每个层级都保留可验证的**代码证据**，以便读者可以检查每项解释，并为后续的修改奠定源码基础。 **从系统理解到行为证据。** L1 建立框架的整体视图。L2 将系统组织成行为单元，并描述其职责、输入、输出和依赖关系。L3 详细检查单个单元，将触发器、状态变化、异常路径和代码证据连接起来。这三个层级并非一次性暴露所有内容，而是将一个复杂的框架转化为可导航的行为地图。**L1 · 系统概述**从框架的全局视图开始。它并不是列出文件和函数，而是跟踪一个请求在系统中的流转：请求如何进入、经过哪些阶段、状态如何在它们之间移动、以及模型输出如何变成真实动作。它首先回答：*这个框架整体上是如何运行的？* **L2 · 行为单元概述**然后将系统流程分解为行为单元。每个单元捕捉一类一致的行为，并记录其职责、输入输出、依赖关系和关键状态。在此层级，读者可以看到复杂行为如何被分解，以及各个部分如何在端到端流程中重新连接。 **L3 · 行为单元详情**最后聚焦到一个单元：行为何时被触发、如何执行、状态如何变化、异常或失败后走哪条路径、以及哪些文件和函数提供了证据。在这里，“删除文件前确认”不再是一个独立的规则——而是一个行为链，其各个决策可以逐一验证。 ### 一个 L3 行为单元示例 回到“删除文件前确认”的例子。下面的 L3 条目将那一行规则扩展为一个可以逐项检查的行为单元，涵盖了正常执行路径和需要单独审查的边缘情况。 行为单元 · 工具执行阶段 #### 删除文件前确认 当智能体请求删除文件时，框架不会立即执行操作。它首先检查权限策略和用户确认状态，然后决定是继续、拒绝请求还是返回错误。 触发器模型发出诸如 `delete_file(path)` 之类的删除调用。权限规则权限配置将文件删除标记为高风险操作，需要用户确认后才能执行。状态变化框架记录确认请求和用户响应，然后利用它们决定当前执行是否可以继续。执行路径用户批准 → 在 `sandbox runner` 中运行；拒绝或未授权 → 中止调用并返回错误。边缘情况 `headless` 模式、自动批准策略或回退路径可能改变确认流程，需要单独检查。证据 `tools/file_ops.py` · L32–78`tools/wrapper.py` · L84–128`policy/permissions.py` · L15–66`runtime/sandbox.py` · L40–112`state/manager.py` · L40–61 **一个 L3 行为单元。** L3 不仅仅是陈述删除文件需要确认，而是将决策分解成可验证的部分：什么触发了请求、权限规则如何约束、确认状态如何记录、执行如何继续或停止，以及每个步骤对应哪些代码证据。L3 支持行为理解、绕过风险审计，以及在策略需要修改时定位正确的实现位置。 第 04 部分 ## 行为地图是如何从代码中生成的？ 三层结构决定了手册如何呈现行为，但只有每项解释都能追溯到真实代码，地图才值得信赖。它不能通过让模型逐个总结文件来构建。相反，生成遵循**事实优先**的规则：自然语言解释行为，而每个主张都锚定在代码事实中——而非模型的猜测。 **从代码库到行为级手册。** 静态分析提取程序事实；行为中心化组织将这些事实映射到系统行为上；综合生成三层手册，同时保留每个证据链接。1 ### 提取事实 → 程序图 第一步提取静态程序事实：文件、函数、类、调用关系、状态读写、配置边界和外部 API 调用。它们共同构成一个**程序图**，连接框架中原本分散的实现元素，并为组织行为提供事实基础。 2 ### 按行为组织 → 行为地图 第二步将程序图重新组织为行为地图。它勾勒出框架生命周期的粗略**执行骨架**，然后将函数、模块和代码区域映射到相应的阶段和行为单元。由于初次映射可能不完美，通过**提议者-审查者循环**反复修正，直到阶段、单元边界和代码证据对齐。 3 ### 综合生成手册 → 手册 最后，收敛后的地图被渲染为系统概述、行为单元概述和行为单元详情。解释可能由自然语言生成，但每个源链接、函数引用和代码片段都必须来自提取的程序事实。简而言之，**散文解释；事实锚定**——并且每个行为链都可以在代码中检查。 第 05 部分 ## 如何从行为问题找到代码证据？ 一旦行为地图存在，读者就可以从具体问题出发，逐层找到代码证据——无需先搜索整个代码库。我们称之为**行为导向的渐进式披露**（BGPD）：L1 提供系统上下文，L2 定位相关的行为单元，L3 打开可验证的实现细节。 **从问题到证据。** BGPD 将一个行为问题转化为可追踪的证据路径：L1 建立系统上下文，L2 定位相关的行为单元，L3 揭示触发器、状态变化、执行路径和源链接。理解和审计意味着验证这些证据；修改则将其转化为编辑计划。代码库仍然是事实来源，而手册则减少了无目标的搜索，更快地将读者引向需要验证或修改的站点。行为问题→L1 系统概述→L2 行为单元概述→L3 行为单元详情→代码证据 ### 一条证据路径，三种用途 理解：建立系统级模型 - 从 L1 和 L2 开始：映射框架的整体执行流程、状态转换以及行为单元之间的依赖关系。 - 在打开任何单个文件之前，为目标行为建立系统上下文，以及它如何与上下游阶段连接。 - 有了这张地图，后续的代码细节就能始终与完整流程相关联。 审计：验证行为是否成立 - 审计继续深入 L3，逐一检查单元的触发器、权限规则、状态变化、回退路径和代码证据。 - 以文件删除为例：主路径上的确认并不排除绕过路径。每个真实执行路径仍然必须符合预期策略。 - 结论基于完整行为路径上的可验证实现证据——而非文档中的承诺。 适配：定位修改边界 - 当行为需要改变时，使用手册找到相关的行为单元、实现链接和依赖路径——然后定义修改边界。 - 这个证据路径随后可以成为编辑计划，减少全库搜索和遗漏提示词、权限规则或回退路径的风险。 - 计划引用手册中的证据；编码智能体仍在代码库本身中验证并应用修改。 第 06 部分 ## 手册能帮助编码智能体更准确地找到相关代码吗？ 为了回答这个问题，我们在相同的框架修改请求上运行同一个编码智能体，唯一的变化是是否允许它在定位前查阅手册。实验关注的是编辑前的定位和规划。规划器是一个基于 NexAU 构建的编码智能体，使用 DeepSeek-V4-Pro 作为规划器 LLM。 评估的框架 Terminus-2 和 Codex 两个框架均来自真实生产代码；行为涉及多阶段控制流、工具调用、状态管理和多个模块。 比较设置 有手册 vs. 无手册的智能体 两种条件使用相同的编码智能体、规划器 LLM 和工作流。唯一的区别是规划器是否在定位前阅读手册。 评判设置 三个独立的评判模型 OpenAI GPT-5.5Anthropic Opus 4.8DeepSeek-V4-Pro我们测量的是规划器是否找到了正确的实现站点并提出了范围合理的编辑计划——而不是最终代码是否一次通过。GPT-5.5、Opus 4.8 和 DeepSeek-V4-Pro 各自