导语：当AI Agent能力日益增强，决定其落地效果的关键不仅在于大模型本身，更在于底层的“Harness”（运行时基础设施）。腾讯混元联合多所高校发布最新论文《Harness Handbook》，旨在解决Agent框架演化中的“行为定位”难题。实验数据显示，该方案使规划胜率最高提升18.9个百分点，Token消耗反而下降12.7%。
一、核心概念：什么是Agent Harness？
在使用Claude Code、Codex等AI编程工具时，常存在“模型强即效果好”的误区。论文明确指出，现代AI Agent的能力取决于基础模型及其Harness。
Harness是包裹在模型外的“运行时基础设施”，负责提示词构造、状态管理、工具调用及流程协调。若将模型比作发动机，Harness则是底盘、变速箱和方向盘。随着模型升级、API变更及应用需求迭代，Harness需持续演化。然而，生产级Harness代码量大、模块耦合度高，导致“行为定位”（Behavior Localization）成为核心瓶颈。
二、痛点分析：修改代码前的“定位难”
面对如“连续三次标记任务完成才提交评分”这类基于行为的修改请求，开发者往往难以直接定位具体代码位置。人类开发者需建立复杂的心智模型，而Coding Agent受限于上下文窗口，易遗漏分散的实现点。
现有工具（代码搜索、仓库索引等）按“文件、函数、模块”组织信息，与基于“行为”描述的修改请求之间存在鸿沟。这一“行为到实现”的映射缺失，被定义为Harness演化的中心瓶颈。
三、解决方案：Harness Handbook
腾讯混元团队提出Harness Handbook，核心理念是按“行为”而非“文件”组织知识。这是一份从代码库自动合成的、以行为为中心的文档，每个行为条目直接链接至源码位置，实现从行为定位到代码直达。
3.1 三大组成部分
| 部分 | 作用 |
| 行为表示 | 围绕运行时行为组织源码，突破传统文件/函数限制 |
| 构建流水线 | 结合静态程序分析与LLM辅助，自动生成手册 |
| 修改工作流 | 指导代码修改，并在仓库变更后自动同步 |
3.2 两种构建模式
- Function-as-Leaf（函数为叶）：适用于Terminus-2等有可靠种子骨架的Harness，L3条目对应具体函数。
- File-as-Leaf（文件为叶）：适用于Codex等大规模单体仓库，L3条目对应文件，自底向上推断阶段骨架。
两种模式均产出统一的读者界面：L1-L3文档树 + 跨阶段状态寄存器视图 + 源码定位器。
3.3 构建三阶段
Phase I：静态事实提取
通过语言特定适配器解析仓库，提取函数、边界、签名及调用边。此阶段完全确定性，不调用LLM，未解析内容写入审计日志。
Phase II：行为组织
将源码单元组织至执行阶段骨架。函数模式基于调用图分配函数；文件模式先总结文件卡片，再推断阶段骨架。
Phase III：分层合成与打包
转换为L1-L3文档树及状态视图。LLM仅用于添加行为解释，严禁篡改文件路径、函数身份等源码事实，确保可追溯性。
3.4 BGPD：行为引导的渐进披露
提出Behavior-Guided Progressive Disclosure (BGPD)流程，引导Agent从高层描述逐步深入细节：
- 阶段选择：从L1/L2概览中匹配执行阶段，补充共享状态耦合阶段。
- 条目选择：在选中阶段内筛选相关L3条目，按需展开摘要与源码定位器。
- 调用关系扩展：沿程序图扩展候选集，排除非编辑点的命名外部边界。
- 源码验证：在真实仓库中解析候选定位器，保留有效站点，确保“手册指路，仓库权威”。
四、实验结果：胜率提升，Token反降
研究在Terminus-2（Python）和Codex（Rust）两个开源Harness上评估，涵盖Query、Cross-file、Search-Hostile三类请求。
4.1 规划质量与效率双优
| 指标 | Codex | Terminus-2 |
| 总体胜率（手册 vs 基线） | 38.3% vs 28.3% | 45.6% vs 26.7% |
| 胜率提升 | +10.0个百分点 | +18.9个百分点 |
| 规划Token变化 | 下降12.7% | 下降8.6% |
多位独立评委证实，胜率提升并非依靠增加Token消耗，而是在更少Token下实现了更高质量的规划。
4.2 弱模型追平强模型
在Recall、Precision、F1等指标上，手册辅助下的表现全面优于基线，F1提升5.0至18.8个百分点。关键的是，完全定位失败率最多下降25.9个百分点，显著减少了“找不到代码”的错误。
4.3 复杂场景增益显著
在所有测试分组中增益均为正。特别是在关键词搜索难以恢复的Search-Hostile场景中，Terminus-2的提升高达33.3个百分点，证明手册在复杂定位场景中价值巨大。
五、专业解读
5.1 拆解“改代码”任务
将任务拆解为“定位→规划→执行”，明确“行为定位”是首要瓶颈。Harness Handbook将隐式的“行为→实现”映射显式化，变“盲目猜测”为“按图索骥”。
5.2 范式转变：从实现中心到行为中心
传统仓库表示以文件、函数为中心，而Harness Handbook以系统“做什么”为中心。这种视角转换对于理解复杂系统更具启发性。
5.3 奠定“Harness自演化”基石
手册可作为共享行为记忆，支持Agent实现“定位→规划→执行→同步”的自主闭环，推动Harness从人工修改向自我改进演进。
5.4 工程务实：确定性打底
解析、哈希、图构建等核心步骤保持确定性，LLM仅用于语义结构化。源码事实具有最高权威，确保文档的可验证性与可靠性，避免LLM幻觉。
六、总结
Harness Handbook通过将行为与实现的连接显式化，让Agent框架演化从“翻遍仓库找代码”转变为“按行为导航直达实现”。实验证明其在提升规划胜率、降低Token消耗及增强弱模型能力方面的显著效果，为复杂Agent系统的可持续演化提供了重要方向。
报告部分截图
编辑：Zero