koyomi315的头像
koyomi315
北京邮电大学硕士,关注后端开发、AI Agent 与 Agent Evaluation。
1483 字
7 分钟

Agent Harness Engineering:模型之外的工程基础设施

在 Agent 工程中,模型只是系统的一部分。相同的模型放进不同的仓库、工具环境和反馈回路里,最终表现可能有很大差异。与其把每次失败都归因于“模型不够强”,更有效的做法是先检查模型之外的工程基础设施——也就是 Harness。

这里的 Harness 可以理解为:为了让模型稳定完成任务,围绕模型建立的指令、上下文、工具、环境、状态与反馈系统。

为什么先检查 Harness#

当 Agent 生成了错误代码,常见反应是更换模型或增加提示词。但失败也可能来自下面这些问题:

  • 任务没有明确成功条件,模型只能猜测目标;
  • 项目的隐含约定没有写进仓库,上下文天然不完整;
  • 依赖、运行时和工具版本不可复现;
  • 修改完成后没有测试、静态检查或可观察的反馈;
  • 长任务没有状态记录,每次会话都需要重新理解项目。

如果不区分这些原因,更强的模型也只是在更努力地猜。

Harness 的五个子系统#

1. 指令系统#

指令系统描述“这个项目是什么”以及“在这里工作需要遵守什么”。典型载体包括仓库根目录的 AGENTS.md、CLAUDE.md 或贡献指南。

一份有效的项目指令至少应包含:

  • 项目目标和核心技术栈;
  • 安装、启动、测试和构建命令;
  • 目录职责与关键入口;
  • 必须遵守的安全、风格和兼容性约束;
  • 需要进一步阅读的设计文档。

指令的价值不在于篇幅,而在于把代码本身无法表达的约定变成可读取的上下文。

2. 上下文系统#

上下文系统决定每一轮模型调用能看到什么。它既不能缺少关键事实,也不能把整个仓库无差别塞进上下文窗口。

可以把上下文分成三层:

  1. 常驻信息:项目目标、硬约束和验证命令;
  2. 按需信息:当前功能涉及的代码、接口和文档;
  3. 运行信息:命令输出、测试失败、日志和工具结果。

上下文工程的重点不是“提供更多”,而是让当前决策所需的信息在正确的时机出现。

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 能否从“偶尔做对”走向“可重复交付”。

Agent Harness Engineering:模型之外的工程基础设施
https://example.com/posts/deepseek-harness/
作者
koyomi315
发布于
2026-07-05
许可协议
CC BY-NC-SA 4.0

一只小鲸鱼正在游过来…

ⓘ
DeepSeek 同人鲸鱼娘

角色原作:上善无形
二次设计:ZipZipPipe
Live2D:氵六青

素材未修改 · CC BY-NC-SA 4.0

模型来源 ↗