1. 智能体运行环境工程是什么

来源：Harness Engineering

预计阅读时间：25 分钟
本篇目标：理解 Harness Engineering 优化的到底是什么，分清它与 Prompt Engineering、Context Engineering 和 Loop Engineering 的边界，并能对一个现有项目做第一次 Harness 体检。

你大概见过这样的场面：同一个 Agent，在演示视频里能连续工作几个小时，到了自己的项目却连启动命令都找不到；让它改一个筛选功能，它先猜技术栈，再猜目录结构，最后改完一句“已经完成”，却没有真正打开页面验证。

遇到这种情况，最自然的反应是继续改提示词：把要求写得更详细，强调“认真检查”，甚至换一个更强的模型。这样有时有效，但它解决不了一个更基础的问题——Agent 所在的工作环境，究竟有没有给它完成任务所需的条件？

Harness Engineering 关心的就是这个问题。

一、先把 Harness 想成“Agent 的工作台”

harness 原本有“挽具、线束、控制装置”的意思。在 Agent 系统里，它通常指包围模型、让模型能够实际工作的那层系统：怎样提供上下文，开放哪些工具，把它放进什么环境，怎样收集运行结果，又用什么规则判断它做完了。

如果把模型比作一位刚加入项目的工程师，那么 Harness 就是他拿到的整套工作条件：

• 入职资料是否说清楚产品和架构；
• 仓库是否容易导航；
• 电脑和依赖能否顺利准备好；
• 启动、测试和检查有没有稳定入口；
• 出错时能否看到日志和运行状态；
• 哪些操作允许直接做，哪些必须先确认；
• 怎样证明一项工作真的完成了。

因此，Harness 不是单独一个文件，也不是某款工具的专有功能。它是一组彼此配合的条件。

我们在这套教程中使用下面这个工作定义：

Harness Engineering，是围绕 Agent 的一次实际运行，系统地设计知识、工具、执行环境、反馈、验证和权限边界，让 Agent 能够更可靠地理解任务、采取行动并证明结果。

OpenAI 在 2026 年发布的 Harness Engineering 实践总结 中提到，他们早期推进缓慢，并不只是 Codex 能力不够，而是环境缺少完成高层目标所需的工具、抽象和内部结构。团队处理失败的方式，也不再只是让 Agent “再努力一点”，而是追问缺少了什么能力，以及怎样让这种能力对 Agent 可见并可执行。

这句话非常重要。Harness Engineering 的起点不是“怎样写出一句万能指令”，而是把一次失败当成环境诊断信号。

二、一次 Agent 运行里，究竟有哪些东西

先看一个简化模型：

                         ┌─────────────────────────────────────────────┐
                         │                 用户目标                    │
                         └──────────────────────┬──────────────────────┘
                                                │ 指令 + 可发现的项目知识
                                                ▼
          ┌─────────────────────────────────────────────────────────────────┐
          │                            模型（决策）                          │
          └───────────────┬───────────────────────────────┬─────────────────┘
                          │ 调用                          │ 观察结果
                          ▼                               ▲
                 ┌─────────────────┐                      │
                 │      工具        │                      │
                 │ 文件 / 终端 /    │                      │
                 │ 浏览器 / 服务    │                      │
                 └────────┬────────┘                      │
                          │ 实际执行                        │ 反馈
                          ▼                               │
          ┌─────────────────────────────────────────────────────────────────┐
          │              运行环境 与 权限边界（约束能做什么）                  │
          └───────────────┬─────────────────────────────────────────────────┘
                          │
                          ▼
          ┌─────────────────────────────────────────────────────────────────┐
          │      反馈层：测试 / 日志 / 页面 / 检查器                          │
          └───────────────┬─────────────────────────────────────────────────┘
                          │
                          ▼
          ┌─────────────────────────────────────────────────────────────────┐
          │        可验证的结果     或     明确停止并求助                      │
          └─────────────────────────────────────────────────────────────────┘

这里至少有六类 Harness 组件。后面的课程会逐一改造它们。

1. 知识：Agent 能否找到项目事实

Agent 需要知道项目做什么、代码怎样组织、哪些规则不能破坏，以及当前任务怎样才算完成。知识可能出现在 AGENTS.md、架构文档、产品规则、代码注释、Schema 和任务说明中。

关键不只是“有没有写”，还包括能否被发现、是否与代码一致、是否适合按需读取。把三万字规范全部塞进一段系统提示，并不比完全没有文档高明多少。

2. 工具：Agent 能否采取必要行动

只让 Agent 看源码，却不给它终端、文件编辑、浏览器或日志查询能力，它就只能根据静态文本猜测运行结果。工具也不是越多越好：每一种工具都需要清楚的用途、输入、输出和权限。

例如，修改一个网页功能至少可能需要：搜索代码、编辑文件、运行测试、启动服务、操作页面、读取控制台错误。缺少其中任何一环，都可能迫使 Agent 用猜测填空。

3. 环境：工具是否真的能稳定运行

同样一条 npm test，在人类电脑上能运行，不代表 Agent 的隔离工作区也能运行。隐含的环境变量、手工安装的全局依赖、只存在于某个人电脑的数据库和未写入仓库的初始化步骤，都会让 Agent 卡住。

Agent 友好的环境应该能重复创建，并且失败时给出足够明确的原因。

4. 反馈：Agent 能否观察到行动的后果

代码改了不等于行为改对了。Agent 需要看得见测试结果、页面状态、结构化日志、网络请求、性能指标或其他运行证据。

OpenAI 的案例中，团队让应用能够在每个 Git worktree 独立启动，并把 DOM、截图、日志、指标和链路追踪暴露给 Agent。这样，“修复页面故障”才不再只是改完代码后的一句自我判断。

5. 验证：谁来定义“完成”

“请把功能做好并仔细检查”不是验证机制。可靠的 Harness 会把关键验收条件变成可重复执行的测试、静态检查、结构检查或用户行为脚本。

更重要的是，执行 Agent 不能拥有随意降低验收标准的权力。否则它可能通过删除测试、弱化断言或跳过检查，让结果表面上变绿。

6. 权限：Agent 能做什么、不能做什么

Harness 还要决定文件访问范围、网络访问、凭据使用、危险命令和外部系统写操作。权限太少，Agent 无法完成任务；权限无限，错误的代价又会被放大。

好的边界不是笼统地写一句“请谨慎”，而是把允许、需要确认和禁止的操作分开，并尽量由沙箱、命令白名单、凭据隔离或审批机制执行。

把这六类放在一起，你就会发现：AGENTS.md 很重要，但它只是知识入口，不是 Harness 的全部。

三、Harness Engineering 与三种相邻概念的区别

这几个术语经常混在一起。与其争论唯一正确的定义，不如看它们分别优化哪一层。

方法	主要问题	典型产物
Prompt Engineering	这一轮怎样把意图表达清楚	一段更明确的任务指令、示例、输出要求
Context Engineering	模型在当前决策前应该看到什么	检索、记忆、上下文选择与压缩策略
Harness Engineering	Agent 怎样在真实环境里完成并验证一次任务	仓库知识、工具、环境、反馈、验证与权限
Loop Engineering	多次 Agent 运行怎样持续推进、恢复和停止	触发器、持久状态、预算、重试、升级与停止条件

它们不是互斥关系。

假设你让 Agent 给 ShelfCare 增加“按标签筛选藏书”功能：

• 把需求、限制和验收条件说清楚，是 Prompt Engineering；
• 决定本轮要加载哪些产品规则、相关代码和历史决策，是 Context Engineering；
• 让 Agent 找得到架构说明，能启动应用、操作页面、运行测试并受权限约束，是 Harness Engineering；
• 如果任务失败后要自动记录状态、重新规划、换一个隔离工作区继续，并在三次失败后转人工，这是 Loop Engineering。

本教程只聚焦第三层。我们会让一次 Agent 运行获得更好的工作条件，但不会搭建无人值守的长期任务循环。这样也能避免把“Agent 内部为了完成一项任务而反复调用工具”和“外部系统反复启动多个 Agent 运行”混为一谈。

四、Harness Engineering 优化的是“一次运行”

这里的“一次运行”不一定只有一个模型请求。编码 Agent 可能在一次任务中连续搜索文件、运行命令、修改代码和重新测试几十次。只要这些动作仍服务于同一个任务，并共享同一段运行上下文，我们就把它看作一次 Agent 运行。

Harness Engineering 想让这次运行具备四个阶段：

理解：找到目标、规则和相关代码
  ↓
行动：在受控环境中使用合适工具
  ↓
观察：读取命令、页面、日志和状态反馈
  ↓
验证：用独立证据判断完成、失败或需要求助

很多糟糕体验并不是 Agent 完全不会写代码，而是链条在中间断了：

• 只有行动，没有理解：改错目录或违背产品规则；
• 只有源码，没有环境：无法复现故障；
• 只有修改，没有观察：不知道页面是否真的可用；
• 只有自述，没有验证：一句“已完成”替代了证据；
• 有工具，没有权限边界：为了通过任务做出越界操作。

所以，衡量 Harness 不能只看最终代码能不能编译。还要看 Agent 是否少走弯路、是否能独立收集证据、是否知道何时停止，以及人在过程中被迫补充了多少隐含信息。

五、一个很常见的误区：什么都写进 AGENTS.md

当人们意识到 Agent 缺上下文时，第一反应往往是写一份越来越长的 AGENTS.md：安装命令、架构细节、所有业务规则、历史坑点、编码风格和当前任务，全堆在一个文件里。

这比没有入口好，但很快会出现三个问题：

1. 重要信息被淹没。 每次任务都加载大量无关内容，真正关键的边界反而不突出。
2. 文档会过期。 命令和代码已经变化，长文档里的旧说法仍在影响 Agent。
3. 文字无法强制执行。 “不要跨层访问数据库”写十遍，也不如一个结构测试可靠。

更有效的做法是把 AGENTS.md 变成一张短地图：告诉 Agent 从哪里开始、常用命令是什么、不同主题应该继续读哪份文档。能由脚本和测试执行的规则，就不要只停留在文字里。

第三篇会专门完成这项改造。现在先记住一句话：文档负责让规则可见，工具负责让规则可执行。

六、先给一个项目做 Harness 体检

在接触 ShelfCare 之前，可以先拿你熟悉的任意仓库做一个十分钟练习。不要启动 Agent，只站在“第一次看到这个项目的人”的角度回答下面的问题。

检查项	你能否在仓库里找到明确答案
项目解决什么问题，核心用户行为是什么	是 / 否
从零开始需要安装什么，支持哪些运行环境	是 / 否
一条命令能否启动项目	是 / 否
一条命令能否运行与当前修改相关的快速测试	是 / 否
完整检查入口是否清楚	是 / 否
主要目录和依赖方向是否有说明	是 / 否
关键产品规则是否写在仓库中	是 / 否
本地示例数据是否可重复创建	是 / 否
页面故障能否从日志或诊断命令中看到	是 / 否
功能完成是否有机器可检查的验收证据	是 / 否
哪些命令或文件属于高风险区域是否明确	是 / 否
文档、命令和实际代码是否有人持续校验	是 / 否

这里不需要计算一个看似科学的总分。更有用的是把所有“否”按六类标记：知识、工具、环境、反馈、验证、权限。

如果大部分问题都答不上来，那么 Agent 每次工作都要临时猜测，或者等人类在对话里补充。换一个更强模型可能缓解部分问题，却不会把这些隐含知识自动变成稳定的项目能力。

反过来，如果仓库的入口清楚、环境可复现、反馈可读取、规则可执行，同一个模型往往就能承担更长的任务。这也是 Harness Engineering 最值得投入的地方：改造结果会被后续很多次运行重复使用，而不是随着一次对话结束而消失。

七、这套教程如何做实战

接下来我们会使用一个叫 ShelfCare 的本地个人藏书管理应用。它不是大型企业系统，功能很直观：记录书名、作者、阅读状态和标签，并支持搜索与筛选。

初始仓库故意保留一些现实中常见的问题：

• 启动方式依赖口头经验；
• 测试命令不够容易发现；
• 业务规则散落在代码和人的脑子里；
• Agent 看得见源码，却看不见页面行为和关键日志；
• 架构边界写在说明里，却没有机器检查；
• “功能完成”的标准模糊。

第二篇，我们会用一个具体任务建立基线：让 Agent 增加“按标签筛选藏书”功能。你需要保留它的操作记录、人工补充、命令失败和最终验证证据。此时不要急着替它修环境，因为我们需要先看清问题。

之后每一篇只改造一层：

第 2 篇：记录失败，建立基线
第 3 篇：整理仓库知识与导航
第 4 篇：统一 setup、dev、test、check 入口
第 5 篇：建立可重复的验收链路
第 6 篇：暴露页面、日志与运行状态
第 7 篇：把架构、安全和偏好变成机器约束
第 8 篇：用原始任务重新测试并做前后对照

最后一篇仍然使用同一个 Agent、同一版模型和同一段任务描述。只有这样，我们才能比较 Harness 改造本身带来的变化，而不是把结果差异偷偷归功于换模型或改提示词。

八、Harness 不是万能药

最后也要把边界说清楚。

Harness 可以帮助 Agent 找到知识、正确使用工具、观察结果和遵守规则，但它不能把模型没有的能力凭空造出来。一个任务如果本身目标含糊、需要重大产品判断、缺少合法数据，或者超出当前模型能处理的复杂度，环境再完善也不保证成功。

同样，不是每个小项目都需要搭建复杂平台。一个人维护的脚本，可能只需要短 README、稳定命令和几条测试；多人协作且大量使用 Agent 的仓库，才值得投入更完整的日志、结构检查、隔离环境和自动验证。

Harness Engineering 的原则不是“组件越多越专业”，而是让每一项投入都对应一种重复出现的失败：

找不到事实     -> 改善知识入口
命令经常失败   -> 改善环境与脚本
不知道改没改对 -> 增加可观察反馈
完成标准含糊   -> 增加独立验证
频繁破坏边界   -> 增加机器约束
操作风险过大   -> 收紧权限并设置确认点

如果一种失败只出现一次，修好任务就够了；如果它会让后续 Agent 一再跌倒，就应该把修复沉淀进 Harness。

本篇检查

读完后，你应该能用自己的话回答四个问题：

1. 为什么 Harness 不等于 Prompt，也不等于 AGENTS.md？
2. 知识、工具、环境、反馈、验证和权限分别解决什么问题？
3. Harness Engineering 与 Loop Engineering 的优化对象有什么不同？
4. 当 Agent 失败时，怎样判断应该改提示词、补 Harness，还是承认任务超出模型能力？

如果这四点已经清楚，就不要继续停留在概念里。下一篇我们会故意给 Agent 一个不友好的项目，让它先失败一次。那次失败不是翻车，而是整套改造最重要的基线。