Harness 工程学习笔记：从提示词工程到可稳定执行的 Agent 系统

提示词工程解决“怎么把任务讲清楚”，上下文工程解决“怎么把信息给对”，Harness 工程解决“怎么让模型在真实执行中持续做对”。

随着大模型应用从简单问答走向真实业务系统，单靠写好提示词已经不够了。模型不仅要理解任务，还要读取上下文、调用工具、维护状态、验证结果，并在失败后恢复。

这时，一个新的工程视角变得越来越重要：Harness 工程。

Harness 可以理解为套在模型外部的一整套“驾驭系统”。它不直接替代模型能力，而是通过上下文管理、工具系统、执行编排、状态记忆、评估观测和约束恢复，让模型在真实环境中更稳定地完成任务。

简单来说：

Model + Harness = Agent

模型提供智能，Harness 提供边界、流程、工具、反馈和治理。两者结合，才构成真正可执行、可交付、可管理的 Agent 系统。

一、从 Prompt Engineering 到 Harness Engineering

大模型应用的发展，可以大致分为三个阶段：

它们不是互相替代的关系，而是层层扩展。

1. 提示词工程：把任务讲清楚

提示词工程关注的是如何向模型表达任务。

它主要解决的问题是：

• 让模型知道要做什么；

• 让模型理解输出格式；

• 给模型设定角色和语气；

• 通过示例引导模型模仿；

• 通过约束减少无关输出。

比如：

你是一位资深产品经理。
请将下面的用户反馈总结为 3 个产品改进建议。
每条建议不超过 30 字。

这类提示词能够明显改善模型输出质量。

但提示词工程也有边界。它擅长澄清任务、约束输出、激发模型已有能力，却不擅长凭空补齐缺失知识，也不擅长管理大量动态信息，更难处理长链路任务中的状态变化。

2. 上下文工程：把信息给对

当任务需要依赖外部知识、历史信息、业务数据或运行时状态时，仅靠提示词就不够了。

这时重点变成：如何把正确的信息提供给模型。

上下文工程关注的是信息供给，包括：

• 哪些信息应该进入上下文；

• 哪些信息应该被过滤；

• 信息应该如何排序；

• 长文本如何压缩；

• 历史对话如何保留；

• 外部知识如何检索。

RAG，也就是检索增强生成，就是上下文工程的一种典型实现。

它不是让模型凭记忆回答，而是先从知识库中检索相关内容，再把这些内容作为上下文提供给模型，让模型基于证据生成答案。

3. Harness 工程：让系统持续做对

当模型进入真实业务场景后，问题会进一步复杂化。

此时模型不只是“回答问题”，而是要完成一条可执行链路：

理解目标 → 判断信息是否充足 → 调用工具补充信息 → 分析结果 → 生成输出 → 检查输出 → 不满足要求时修正

这已经不只是提示词或上下文的问题，而是一个完整系统的工程问题。

Harness 工程关注的是：除了模型本身以外，所有影响 Agent 能否稳定交付的机制。

它包括工具调用、任务编排、状态管理、失败恢复、日志观测、质量评估、安全边界等内容。

二、三类工程的关系

可以用一句话区分三者：

提示词工程：对某一个节点的指令进行工程化。
上下文工程：对链路中的信息传递进行工程化。
Harness 工程：对整个 Agent 系统的执行、检测、约束和治理进行工程化。

三者解决的问题层级不同。

如果只是单轮生成，比如写一段文案、总结一篇文章、改写一句话，提示词非常重要。

如果任务依赖外部知识和运行时信息，比如知识库问答、合同审查、代码库分析，上下文工程就变得关键。

如果模型进入长链路、可执行、低容错的真实业务场景，比如自动修复代码、处理客户工单、执行数据分析、运行端到端任务，Harness 工程就不可避免。

三、什么是 Harness

Harness 原意是“马具、背带、控制装置”。放在 Agent 系统中，可以理解为一套驾驭模型的工程结构。

模型本身负责推理和生成，但 Harness 负责回答这些问题：

• 模型应该看到哪些上下文；

• 模型能调用哪些工具；

• 工具结果如何反馈给模型；

• 当前任务执行到哪一步；

• 输出是否符合要求；

• 出错后应该重试、切换路径还是交给人类；

• 哪些行为必须被禁止；

• 哪些结果需要记录和观测。

因此，Harness 不是一个单独模块，而是一组围绕模型搭建的系统能力。

在一个完整的 Agent 系统中，除了模型以外，所有能决定它能否稳定交付的东西，都可以纳入 Harness 工程的范围。

四、Harness 工程的六个核心层次

Harness 工程可以拆成六个核心层次：

下面逐一说明。

五、第一层：上下文管理，让模型在边界内思考

上下文管理的目标，是让模型看到足够有用的信息，同时避免被无关信息干扰。

很多人以为上下文越多越好，但在真实系统中，上下文不是越多越好，而是越相关越好。

过多上下文会带来三个问题：

好的上下文管理，需要处理三件事。

1. 定义角色、目标和成功标准

模型需要知道自己是谁、要完成什么任务、什么样的结果算成功。

例如，一个代码修复 Agent 不应该只知道“修 bug”，还应该知道：

• 当前 bug 是什么；

• 复现方式是什么；

• 修改范围有哪些限制；

• 修复后需要通过哪些测试；

• 不能破坏哪些已有行为。

2. 选择和裁剪信息

上下文管理不是把所有材料都塞给模型，而是根据任务动态选择相关信息。

例如：

• 代码修复任务需要相关文件、报错日志和测试结果；

• 客服任务需要用户问题、订单状态和平台规则；

• 数据分析任务需要数据字段、指标定义和业务口径。

不相关的信息应该被过滤或压缩。

3. 结构化组织上下文

上下文应该有清晰结构，而不是一整段混乱文本。

一个常见结构是：

系统规则：长期固定的规则和边界
任务目标：当前要完成的任务
运行状态：当前执行到哪一步
外部证据：检索、工具、日志、文件等结果
输出要求：最终结果的格式和验收标准

结构越清楚，模型越容易遵守。

六、第二层：工具系统，让模型具备行动能力

模型本身只能生成文本。要让它完成真实任务，就必须给它工具。

工具可以包括：

• 文件读写；

• 数据库查询；

• 搜索引擎；

• 浏览器操作；

• API 调用；

• 代码执行；

• 日志查询；

• 自动化测试。

工具系统要解决的不只是“给模型什么工具”，还包括“什么时候调用工具”和“工具结果怎么返回给模型”。

1. 该给模型什么工具

工具越多，能力越强，但风险也越高。

因此，工具设计要遵循最小必要原则：只给完成当前任务所需的工具，并为高风险工具设置权限和确认机制。

例如，读取文件和删除文件的风险完全不同；查询数据库和修改数据库的风险也完全不同。

2. 什么时候调用工具

模型不能凭空猜测外部事实。

当任务依赖实时信息、文件内容、运行结果或业务数据时，Harness 应该引导模型调用工具获取证据。

例如：

如果需要判断测试是否通过，不要直接猜测，请运行测试命令。
如果需要分析文件内容，请先读取文件。
如果需要查询订单状态，请调用订单查询接口。

3. 工具结果如何反馈给模型

工具结果不一定要原封不动塞回上下文。

如果结果很长，应该提炼、筛选、保留和任务最相关的信息。

比如测试日志可能有几千行，但模型真正需要的是：

• 哪个测试失败；

• 错误信息是什么；

• 堆栈指向哪里；

• 最近修改了哪些相关代码。

工具系统的关键不是“让模型能调用工具”，而是让工具调用服务于任务闭环。

七、第三层：执行编排，让任务形成闭环

复杂任务往往不能一步完成，需要多个阶段。

一个典型执行链路是：

理解目标
→ 判断信息是否足够
→ 不足就补充信息
→ 继续分析
→ 生成输出
→ 检查输出
→ 不满足要求就修正

这就是执行编排。

为什么需要执行编排

没有编排的 Agent 容易出现三个问题：

执行编排相当于给 Agent 安排工作流程。

常见编排模式

1. 计划-执行-检查

适合代码修复、数据分析、文档生成等任务。

先制定计划 → 再执行操作 → 最后检查结果

2. 检索-生成-验证

适合知识库问答、合规审查、资料总结。

先检索证据 → 再生成答案 → 最后验证答案是否基于证据

3. 失败-诊断-恢复

适合自动化执行和低容错任务。

发现失败 → 定位原因 → 重试或切换方案 → 再验证

编排让 Agent 不只是“会回答”，而是能按流程推进任务。

八、第四层：状态与记忆，让 Agent 不丢上下文

长链路任务最怕状态丢失。

Agent 需要知道：

• 当前任务进行到哪一步；

• 已经做过哪些操作；

• 得到了哪些中间结果；

• 哪些方案已经失败；

• 用户有哪些长期偏好；

• 下一个动作应该是什么。

这些信息构成状态与记忆。

1. 当前任务状态

任务状态记录当前执行进度。

例如：

当前目标：修复登录接口报错
已完成：读取日志、定位到 token 校验模块
当前阻塞：缺少复现请求样例
下一步：读取相关测试文件并补充复现用例

这种状态可以帮助 Agent 在长任务中保持连续性。

2. 会话中间结果

中间结果包括分析结论、工具返回、测试结果、用户确认过的决策等。

这些信息如果不保存，模型可能重复工作，甚至推翻之前已经确认的结论。

3. 长期记忆与偏好

长期记忆更适合记录稳定信息。

例如：

• 用户偏好的输出格式；

• 项目的技术栈；

• 代码风格要求；

• 常用业务术语；

• 团队约定。

长期记忆不能无限堆积，需要定期清理和结构化，否则也会变成上下文噪音。

九、第五层：评估与观测，让结果可验证

模型自信不代表结果正确。

在真实系统中，Harness 必须提供评估与观测能力，让输出可以被检查、追踪和改进。

1. 输出验收

输出验收检查结果是否符合任务要求。

例如：

• JSON 是否合法；

• 必填字段是否存在；

• 摘要是否超过字数；

• 回答是否引用了证据；

• 代码是否通过测试；

• 操作是否真的完成。

2. 环境验证

对于可执行任务，不能只看模型解释，要看真实环境反馈。

比如代码 Agent 修复 bug 后，应该运行测试；浏览器 Agent 修改页面后，应该打开页面检查交互；数据 Agent 生成 SQL 后，应该验证查询结果。

真实环境验证比模型自评更可靠。

3. 日志和指标

系统需要记录关键过程：

• 模型输入；

• 模型输出；

• 工具调用；

• 工具返回；

• 错误信息；

• 重试次数；

• 任务耗时；

• 用户反馈。

这些日志和指标可以帮助开发者定位问题、比较版本、优化流程。

4. 错误归因

当 Agent 失败时，要判断失败原因。

常见原因包括：

• 提示词不清楚；

• 上下文缺失；

• 工具结果错误；

• 编排流程不合理；

• 模型能力不足；

• 输出校验缺失；

• 外部环境异常。

没有错误归因，就无法持续改进系统。

十、第六层：约束校验与失败恢复

Harness 工程不仅要让模型能做事，还要让模型在边界内做事。

这一层主要包括三个关键词：约束、校验、恢复。

1. 约束：明确哪些能做，哪些不能做

约束可以来自安全、权限、业务规则或产品体验。

例如：

• 不能删除用户数据；

• 不能泄露隐私信息；

• 不能修改生产环境；

• 不能编造不存在的政策；

• 不能在未确认时执行高风险操作。

约束必须明确写入系统规则或执行策略中。

2. 校验：检查模型是否遵守约束

有约束还不够，还需要校验机制。

例如：

• 输出格式校验；

• 权限校验；

• 敏感信息检测；

• 测试用例验证；

• 规则引擎检查；

• 人工确认节点。

校验负责发现问题。

3. 恢复：失败后如何处理

失败是必然会发生的。关键不是避免所有失败，而是让系统知道失败后怎么恢复。

常见恢复方式包括：

• 自动重试；

• 改用备用路径；

• 缩小任务范围；

• 请求用户补充信息；

• 回滚上一步操作；

• 转交人工处理。

一个成熟的 Agent 系统，必须有失败恢复能力。否则它只能在理想条件下工作，无法进入真实业务。

十一、Harness 工程中的两个常见难题

在实践中，Harness 工程经常会遇到两个问题：上下文焦虑和自评失真。

1. 上下文焦虑

上下文焦虑指的是模型在长任务中逐渐丢失细节、丢失重点，或者因为上下文压力过大而急于收尾。

常见表现包括：

• 忘记早期约束；

• 重复已经完成的工作；

• 忽略关键错误；

• 为了结束任务而草率给结论。

常规解决方法是压缩上下文，把历史信息总结成更短、更结构化的状态摘要。

更激进的做法，是把任务交接给新的 Agent 执行。新的 Agent 不继承全部冗长历史，只接收一份清晰的任务交接文档，包括目标、已完成事项、关键证据、剩余问题和下一步。

这相当于用“交接”替代“硬撑上下文”。

2. 自评失真

自评失真指的是模型评价自己输出时过于乐观。

模型可能会说“已经修复”“应该没问题”“逻辑正确”，但真实环境中仍然失败。

解决办法是拆分角色和验证来源。

例如：

计划角色：负责制定方案
执行角色：负责修改和操作
测试角色：负责验证结果

测试不应该只看模型自己的解释，而应该结合真实交互、运行环境、测试结果、日志和指标。

对于代码任务，验证不只是“看起来代码没问题”，而是运行测试、复现问题、检查结果是否符合预期。

十二、OpenAI Agent 实践中的启发

从一些 Agent 系统实践中，可以总结出几条对 Harness 工程很重要的经验。

1. 重新设计工作逻辑

不要把 Agent 当成一个“更聪明的聊天框”，而要把它当成一个执行系统。

它需要：

• 拆解任务；

• 补充能力；

• 建立反馈；

• 验证结果；

• 从失败中恢复。

工作逻辑的设计，比单个提示词更重要。

2. 使用渐进式披露

上下文资源有限，不应该一次性把所有工具说明、所有文档、所有规则都给模型。

更好的方式是设计索引目录，让模型先知道“有哪些能力”，再按需要查询具体说明。

这就是渐进式披露。

它可以减少上下文浪费，也能让模型在需要时获取更精确的信息。

3. 让 Agent 看见整个应用

如果 Agent 要修复或操作一个真实应用，它不能只看代码。

它还应该能看到：

• 浏览器中的实际页面；

• 用户交互结果；

• 后端日志；

• 监控指标；

• 测试环境；

• 错误堆栈。

一个更完整的闭环是：

跑起来 → 看结果 → 发现问题 → 修复问题 → 再验证

这也是 Harness 工程区别于单纯提示词工程的地方：它要求模型进入真实反馈循环。

4. 把人类工程师经验写成系统规则

优秀工程师在排查问题时，会不断提出问题：

• 这个错误能复现吗；

• 最近改了什么；

• 日志里最早的异常是什么；

• 测试覆盖到了吗；

• 修复有没有引入新问题。

这些经验可以沉淀为系统规则，让 Agent 在执行时自动遵守。

例如：

在修改代码前，先确认错误复现方式。
在提交修复前，必须运行相关测试。
如果测试失败，先定位失败原因，不要直接假设是测试问题。

Harness 的价值之一，就是把人类专家的工作习惯固化成可重复执行的流程。

十三、什么时候需要 Harness 工程

不是所有大模型任务都需要复杂 Harness。

如果只是单轮、低风险、无需外部信息的生成任务，提示词工程就足够重要。

例如：

• 写标题；

• 改写文案；

• 总结短文；

• 生成创意；

• 翻译一句话。

如果任务依赖外部知识和动态信息，就需要上下文工程。

例如：

• 基于公司知识库回答问题；

• 读取代码文件后解释逻辑；

• 根据数据库查询结果生成分析；

• 根据最新文档回答技术问题。

如果任务具备以下特征，就需要 Harness 工程：

典型场景包括：

• 自动代码修复 Agent；

• 客服工单处理 Agent；

• 数据分析 Agent；

• 企业知识库助手；

• 浏览器自动操作 Agent；

• 运维排障 Agent；

• 低代码工作流 Agent。

十四、总结：Harness 工程的核心任务

Harness 工程的核心任务，是让模型在业务中稳定、持续地做对。

它不是简单地写一段更长的提示词，也不是给模型堆更多上下文，而是围绕模型构建一套完整的执行系统。

可以把 Harness 理解为 Agent 的工程外骨骼：

提示词工程让模型听懂任务，上下文工程让模型拿到信息，Harness 工程让模型进入真实执行闭环。

当大模型从“聊天工具”变成“业务执行者”时，Harness 工程就会成为不可绕开的核心能力。