大模型决定 Agent 能理解什么、推理能到什么程度Agent Harness 则负责把这些能力组织成可执行的系统行为。无论是 Prompt 组装、上下文管理还是工具调用、状态保存和任务循环都由 Harness 统一协调。随着模型、API 和产品需求的不断变化Harness 也在持续演化。原本集中在少数模块中的逻辑逐渐扩展到了更多文件、函数和执行阶段一项行为可能会由多处代码共同完成。当我们想要调整某个 Agent 行为时首先得弄清楚这些实现分布在哪里以及它们之间是如何配合的。论文《Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable》将这一问题概括为行为定位Behavior Localization。围绕这个问题作者提出 Harness Handbook 概念。它是从代码库中自动生成的一套以运行时行为为中心的说明体系连接起 Agent 的行为、执行阶段、共享状态与具体源码位置帮助研发和 Coding Agent 更快地理解 Harness 的运行方式并准确定位和修改相关实现。Agent Harness 的行为定位难题传统代码仓库一般会按照文件、函数和模块组织代码代码修改需求却要以系统行为来描述。例如让 Agent 在确认任务完成后再检查一次然后结束当前循环。上面这句话说明了系统需要发生什么变化但没有指出应该修改哪些文件和函数也无法直接判断这一行为是否同时涉及主循环、状态字段、完成条件和异常处理。在规模较小的项目中研发人员一般可以借助关键词搜索、调用关系和逐文件阅读代码来完成定位。但是生产级 Agent Harness 的情况要复杂得多。看似简单的行为背后可能同时涉及多个位置某个函数负责读取模型返回的完成信号某个状态字段记录任务是否已经确认主循环根据该状态决定继续执行或退出其他分支负责处理超时、工具失败和最大步数测试代码还可能使用不同的初始化路径。如果只找到当中的某一个函数修改计划就可能会遗漏其他关联路径。代码搜索、仓库索引、代码仓库地图、代码摘要和长上下文阅读这些都能帮 Agent 更快地找到相关代码。不过这些方法要按照代码结构来组织信息Agent 还是得自行建立行为描述、执行过程与实现位置之间的对应关系。Harness Handbook 的核心作用就是提前整理这层对应关系。从代码目录到行为地图Harness Handbook 将代码库重新组织为一套三级结构并保留每个行为单元与当前源代码之间的连接。图 1Harness Handbook 的三级结构L1系统总览第一层描述整个 Harness 的架构、执行模型、主要阶段、设计原则和全局数据流。在这一层Handbook 会先梳理 Harness 的整体运行流程包括初始化、规划、工具执行、观察、循环与终止。研发人员可以根据系统总览建立对系统结构和执行逻辑的整体认识再沿着这条主线继续定位具体实现。L2组件与阶段总览第二层围绕具体执行阶段展开说明每个阶段的职责、输入、输出、依赖关系、外部接口和涉及的关键状态。例如在“主循环”阶段Handbook 会进一步梳理这一阶段要如何接收当前状态、模型输出和工具结果包含哪些处理步骤以及哪些信息要传入下一轮执行。L3实现单元详解第三层会深入具体的实现说明某项行为是如何接收输入、读取和更新状态以及遇到异常时该怎样处理。同时它还会标出相关配置、关键函数和源码位置方便研发人员回到代码中核对与修改。L3 采用两种粒度Function-as-leaf以函数或函数中的连续代码区域作为最小单元File-as-leaf以文件作为最小单元。前一种方式适合已经划分清楚执行阶段并且能够承担函数级分析成本的 Harness。后一种方式则适合大型仓库尤其是尚未理清执行阶段或函数级整理会带来过高开销的 Harness。除了这三级文档结构Harness Handbook 还单独梳理了跨阶段流动的状态。一个状态可能在初始化时被写入在主循环中不断更新最终被退出逻辑读取。Agent 可以沿着状态的变化找到分散在不同模块中的相关代码并理解这些实现是如何共同完成一项行为。最终Handbook 提供了一条从系统行为逐步深入到具体代码的导航路径。每项说明都能回到当前源码中进行核对并随着代码变化持续更新。Handbook 的自动构建流程为了让现有仓库生成这套行为地图论文设计了三个阶段。图 2Handbook 的三阶段构建流程静态事实提取系统先使用语言适配器去解析代码提取函数、方法、类、模块、函数签名、源代码位置、调用边和外部边界并生成程序图。这一阶段完全由确定性程序完成不用调用大模型。对于提取出的调用关系能够明确解析的内部调用会被写入程序图无法解析的调用则会被单独记录系统不会去自行猜测其目标。这样的处理为后续生成提供了可验证的代码事实也减少了大模型在底层结构上的自由发挥。行为组织接下来系统会借助大模型判断各个代码单元分别属于 Harness 的哪些执行阶段。在 Function-as-leaf 模式下系统会从已有的执行阶段框架出发结合源码和调用图建立函数与执行阶段之间的对应关系。这个结果还会经过多轮检查和修正。若同一个函数参与了多项行为系统既可以将整个函数归入多个阶段也可以按照连续的代码区域分别归类。在 File-as-leaf 模式下系统会先为每个文件生成一张概要卡片再结合程序图推断 Harness 的执行阶段并将文件归入相应位置。暂时无法归类的文件和仍未解决的结构问题会被单独保留避免在整理过程中被遗漏。在这一过程中大模型负责理解代码在行为层面完成了什么静态分析则提供可核对的调用关系和源码位置。两者结合后原本分散的底层实现就能被整理成围绕运行过程展开的结构。分层合成与打包最后系统会将执行阶段框架与代码映射整合成 L1—L3 三级文档并补充跨阶段的状态关系。每个 L3 条目都会指向静态分析定位到的源码位置后面再与当前仓库进行核对。只有能够在当前版本中重新找到并确认的定位信息才会进入后续的行为定位流程。暂时无法验证的条目会被冻结等待下一次同步更新。这样设计可以确保 Handbook 对实现细节的描述始终以当前源码为准。BGPD 的渐进式行为定位有了 HandbookCoding Agent 不用一次性读完全部内容。论文进一步提出的 Behavior-Guided Progressive DisclosureBGPD概念是让 Agent 沿着“从行为到代码”的路径逐层展开所需信息。收到修改请求后BGPD 会先查看 L1 和 L2判断这项需求主要涉及哪些执行阶段。接着它会沿着状态关系继续追踪补充那些通过共享状态相互关联的阶段。确定范围后系统再进入对应的 L3 单元找到与需求最相关的具体实现和源码位置。不仅如此BGPD 还会根据调用关系扩展候选范围。Function-as-leaf 模式使用函数调用图File-as-leaf 模式使用文件调用图。与外部系统的连接可以帮助补充上下文但不会直接被列为需要修改的位置。完成 Handbook 内部的导航后BGPD 会回到当前仓库对候选代码逐一核对只保留仍然与修改需求相关的部分。最终交给规划器的内容包括文件路径、函数或代码区域的位置标记以及当前版本中的源码片段。整个过程可以概括为自然语言修改请求 ↓相关执行阶段 ↓跨阶段状态关系 ↓相关行为单元 ↓候选代码位置 ↓当前仓库验证 ↓修改计划这样的渐进式展开能够降低一次性阅读整个仓库带来的上下文压力也能让修改计划拥有更清晰的代码依据。与代码同步的动态手册如果 Handbook 只在项目初始化时生成一次它很快就会随着代码的变化而失效。因此论文把自动同步纳入完整修改流程行为定位 → 修改计划 → 执行修改 → 生成 diff → 更新 Handbook只要代码 diff 中出现实际改动系统就会自动启动同步流程。它会重新解析变更后的代码、更新程序图并识别哪些函数或文件被新增、删除或修改。在 Function-as-leaf 模式下系统通过不依赖行号的函数指纹来追踪变化。即使函数移动了位置仍然可以被识别为同一个单元如果函数发生重命名系统还会结合函数体内容进行判断。File-as-leaf 模式则通过文件列表的变化和内容哈希确认哪些文件发生了更新。如果原有的执行阶段框架仍然适用系统只用更新受影响的条目及其上层文档如果原有结构被代码改变系统就会重新运行相应的构建流程。暂时无法解析或准确归类的内容会被冻结或是单独写入覆盖记录避免未经验证的信息进入 Handbook。通过这套同步机制Handbook 可以随着仓库一起演化并持续保持行为说明与实际代码的一致。两个开源 Harness 上的实验论文选择 Terminus-2 和 Codex 两个开源 Agent Harness 进行评估。其中Terminus-2 采用 Function-as-leaf 模式Codex 采用 File-as-leaf 模式。作者分别为这两个项目设计了 30 个以系统行为为目标的修改请求并将它们分为三类Query调整现有行为但不提供对应的代码位置Cross-file增加需要跨越多个文件或模块完成的端到端能力Search-Hostile相关实现较为隐蔽很难通过关键词搜索直接找到。这些请求还按照定位难度划分为 Easy、Medium 和 Hard。实验使用 DeepSeek-V4-Pro 作为只读规划器。基线组直接在代码仓库中查找相关实现Handbook-Assisted 组则在其他条件相同的情况下借助 Handbook 和 BGPD 完成定位。随后作者将两组生成的修改计划交给 GPT-5.5、Opus 4.8 和 DeepSeek-V4-Pro 独立评估考察代码位置是否准确、修改范围是否合理以及计划是否给出了充分依据。结果显示Handbook-Assisted 在两个项目上都取得了更高的计划质量胜率Codex 从 28.3% 提升至 38.3%增加 10.0 个百分点Terminus-2 从 26.7% 提升至 45.6%增加 18.9 个百分点。与此同时规划阶段的平均 Token 消耗也有所下降Codex 每个请求从约 10.2 万 Token 降至 8.9 万减少 12.7%Terminus-2 从约 5.8 万 Token 降至 5.3 万减少 8.6%。图 3计划质量与 Token 成本论文还把规划器预测的编辑位置与 Opus 4.8 和 GPT-5.5 分别生成的参考计划进行了比较。评估覆盖两个 Harness、两种参考模型以及文件级和符号级两个层面。结果显示24 组 Recall、Precision 和 F1 指标全部提升其中 F1 提高了 5.0 至 18.8 个百分点。规划结果与参考位置完全没有重合的情况也有所减少最大降幅达到 25.9 个百分点。按请求类型拆分后六组“项目—请求类型”对比同样全部取得提升增幅介于 16.3 至 33.3 个百分点。尤其是在 Cross-file 和 Search-Hostile 任务中Handbook 的优势更为明显。这说明围绕系统行为组织代码信息可以帮助 Agent 找到跨越多个模块、或很难通过关键词直接搜索到的实现位置。图 4不同请求类型与定位难度下的胜率这组实验主要考察代码定位和修改计划的质量并没有直接评估最终补丁是否正确、测试能否通过以及长期维护成本是否下降。因此当前结果可以说明 Handbook 有助于 Agent 更准确地找到相关代码并制定修改计划完整的软件修改效果还需要结合后续的代码执行和验证继续评估。持续演化 Harness 的可维护性Harness Handbook 关注的是 Agent 工程中一个越来越明显的维护难题随着系统能力不断增加一项行为往往会分散到更多文件、函数和执行阶段仅靠临时搜索和个人经验很难长期维持行为与代码之间的对应关系。代码目录可以告诉研发人员实现位于哪里Handbook 则进一步说明这些实现如何配合共同完成某项行为。当修改需求以自然语言提出时Coding Agent 可以先确定目标行为再沿着执行阶段、状态变化和具体实现逐步定位相关代码。修改完成后系统还会根据代码 diff 更新 Handbook使说明继续与当前仓库保持一致。对研发人员来说这套结构可以降低理解复杂 Harness 的门槛也能减少跨模块排查问题所需的时间。对 Coding Agent 来说Handbook 相当于一份以源码为依据的行为记录可以缩小搜索范围减少缺少方向的仓库探索。自动同步机制则让这份记录能够随着 Harness 一起演化。论文还提出这种围绕系统行为组织代码的方式未来可以继续用于行为审计和回归影响分析。作者希望进一步把 Handbook 作为 Agent 共享的行为记忆将代码定位、修改规划、执行和重新同步连接成完整流程并在此基础上探索 Harness 的自动演化。结语随着 Agent 从简单的 Prompt 和工具调用逐步发展为包含状态管理、执行循环、异常恢复、多阶段协作与外部环境交互的复杂系统Harness 也从一层辅助代码变成了需要持续维护的核心工程部分。Harness Handbook 的价值在于为这套复杂系统补上一层以行为为中心的说明结构。它以静态分析提取的代码事实为基础将系统总览、执行阶段与具体实现串联起来并通过自动同步持续跟随代码变化。借助这套结构研发人员和 Coding Agent 在修改某项行为之前可以先弄清相关实现分布在哪里、彼此如何关联以及改动可能影响哪些路径。当 Harness 仍在持续演化时可读、可查、可改已经成为 Agent 稳定扩展与长期维护的重要基础。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】