Agent Harness Engineering:模型之外的工程基础设施
在 Agent 工程中,模型只是系统的一部分。相同的模型放进不同的仓库、工具环境和反馈回路里,最终表现可能有很大差异。与其把每次失败都归因于“模型不够强”,更有效的做法是先检查模型之外的工程基础设施——也就是 Harness。
这里的 Harness 可以理解为:为了让模型稳定完成任务,围绕模型建立的指令、上下文、工具、环境、状态与反馈系统。
为什么先检查 Harness
当 Agent 生成了错误代码,常见反应是更换模型或增加提示词。但失败也可能来自下面这些问题:
- 任务没有明确成功条件,模型只能猜测目标;
- 项目的隐含约定没有写进仓库,上下文天然不完整;
- 依赖、运行时和工具版本不可复现;
- 修改完成后没有测试、静态检查或可观察的反馈;
- 长任务没有状态记录,每次会话都需要重新理解项目。
如果不区分这些原因,更强的模型也只是在更努力地猜。
Harness 的五个子系统
1. 指令系统
指令系统描述“这个项目是什么”以及“在这里工作需要遵守什么”。典型载体包括仓库根目录的 AGENTS.md、CLAUDE.md 或贡献指南。
一份有效的项目指令至少应包含:
- 项目目标和核心技术栈;
- 安装、启动、测试和构建命令;
- 目录职责与关键入口;
- 必须遵守的安全、风格和兼容性约束;
- 需要进一步阅读的设计文档。
指令的价值不在于篇幅,而在于把代码本身无法表达的约定变成可读取的上下文。
2. 上下文系统
上下文系统决定每一轮模型调用能看到什么。它既不能缺少关键事实,也不能把整个仓库无差别塞进上下文窗口。
可以把上下文分成三层:
- 常驻信息:项目目标、硬约束和验证命令;
- 按需信息:当前功能涉及的代码、接口和文档;
- 运行信息:命令输出、测试失败、日志和工具结果。
上下文工程的重点不是“提供更多”,而是让当前决策所需的信息在正确的时机出现。
3. 工具与权限系统
Agent 需要通过工具读取文件、搜索代码、执行命令和修改内容。工具说明是否清晰、结果是否结构化、权限是否合理,都会直接影响决策质量。
工具设计应回答四个问题:
- 工具能够完成什么;
- 哪些场景应该调用;
- 参数和返回值如何解释;
- 操作是否可逆,是否需要人工确认。
只读查询、普通写入和不可逆操作应采用不同的权限策略。最小权限不是单纯限制 Agent,而是减少错误决策的影响范围。
4. 环境与状态系统
执行环境需要能够自我描述和复现。依赖锁文件、固定的运行时版本、容器配置和环境检查脚本,都属于这一部分。
对于跨多轮的任务,还需要保存工作状态。例如在 PROGRESS.md 中记录:
- 已经完成的内容;
- 当前验证结果;
- 尚未解决的问题;
- 下一步动作及其依赖。
这类状态记录可以降低会话切换造成的信息损失,也让人能够接管任务。
5. 反馈系统
反馈系统让 Agent 知道修改究竟是否正确。高价值反馈通常来自:
- 单元测试与集成测试;
- 类型检查、静态分析和格式检查;
- 生产构建;
- 浏览器或运行时行为;
- 性能、日志和错误信息。
验证命令应该显式写入项目文档,并尽量做到快速、确定和可重复。没有反馈回路时,Agent 只能根据代码外观判断结果。
用分层方法定位失败
遇到失败时,可以先把问题归入一个层次:
| 现象 | 优先检查 |
|---|---|
| 实现方向与需求不一致 | 任务规范、成功条件 |
| 违反项目惯例 | 指令和按需上下文 |
| 命令在不同机器表现不同 | 环境和依赖锁定 |
| 修改看似合理但无法运行 | 验证反馈 |
| 长任务反复重新分析 | 状态管理 |
| 工具被误用或操作越界 | 工具描述与权限 |
这种分层方式的好处是可以做控制变量:保持模型不变,只改进一个 Harness 子系统,再比较成功率、返工次数或人工介入次数。
一个最小可用的仓库 Harness
不需要一开始就建设复杂平台。一个项目可以从下面几项开始:
repository/├── AGENTS.md # 项目目标、约束和常用命令├── README.md # 面向使用者的安装与运行说明├── PROGRESS.md # 长任务状态与未决问题├── docs/ # 架构和关键决策├── tests/ # 可重复的行为验证└── lockfile # 确定依赖版本随后再根据真实失败补充工具权限、环境检查、自动化审计和更细的上下文路由。Harness Engineering 的核心不是一次性搭出完美框架,而是让失败能够被定位、修复并沉淀为系统能力。
总结
Agent 的能力上限与模型有关,稳定性却很大程度上取决于模型周围的工程系统。清晰的任务、适量的上下文、边界明确的工具、可复现的环境、连续的状态和快速的反馈,共同决定了 Agent 能否从“偶尔做对”走向“可重复交付”。