Harness Engineering 火了：OpenAI 验证过的 5 条原则，我们在 Dify 交付中怎么用
摘要：2026 年 2 月，OpenAI 和 Mitchell Hashimoto 几乎同时把「Harness Engineering」推成了 AI 圈热词——模型是大脑，harness 是手和脚。LangChain 用数据证明了它的分量：同一个 coding agent，模型完全没换，只改 harness，Terminal Bench 成绩从 52.8% 涨到 66.5%，排名从 Top 30 跳到 Top 5。这篇文章拆解 OpenAI Codex 团队公开的 5 条 harness 原则，并结合我们用 Dify 交付 RAG 知识库应用的实战（数千页设备手册 → 智能问答），讲清楚每一条原则在我们真实的交付场景里是怎么落地的——以及我们因此踩过哪些坑。
一、场景：客户说「AI 应用越用越不靠谱」
先讲一个我们实际遇到的场景。
客户是一家做网络设备的企业，手里的资料是几千页的技术手册：产品文档、配置指南、故障排查手册，格式五花八门——PDF、Word、Excel，还有带大量拓扑图、指示灯图和告警截图的手册。他们的诉求很直接：把这些手册变成一个 AI 问答应用，让一线工程师「有问题直接问，别翻手册」。
我们交付了第一版。知识库建好、问答链路跑通、演示的时候效果不错。但客户用了一段时间后反馈了几个问题：
- 「答错」：问到手册里没有的内容时，AI 会一本正经地编一个答案；
- 「答非所问」：明明手册里有，但问法稍微口语化一点就召不回；
- 「越用越差」：同样的错误反复出现，知识库更新一次，之前调好的效果又变了。
这些问题的共性是什么？都不是模型不够强。我们当时的第一反应也是「换个更大的模型」，但换了之后问题依旧。后来我们才想明白：问题的根源不在模型，在模型运行的环境——知识库怎么建、检索怎么配、失败怎么兜底、回答怎么验证。这一整套「环境」，2026 年 2 月之后有了一个正式的名字：Harness。
二、Harness 是什么：三次命名简史
Harness 这个词不是 AI 圈发明的。它至少有一百多年的历史，原意是「马具」——一套让马的力气变得有用的装备。缰绳不让马变强，但让马的力量能拉车。
2022 年以来，AI 圈给「怎么让模型可靠地干活」这件事命了三次名：
- Prompt Engineering（2022-2024）：怎么问。你告诉马「向左转，跑快点」。
- Context Engineering（2025）：给什么信息。你不只告诉马往哪走，还给整片地形图（RAG 结果、对话历史、工具定义）。
- Harness Engineering（2026）：整个系统怎么运转。缰绳、马鞍、围栏、跑道、护栏——模型在什么环境里运行、有什么约束、怎么获得反馈、犯错了怎么纠正。
三者是包含关系：Prompt ⊂ Context ⊂ Harness。
Harness 这个词在工程领域其实早有对应物，五个领域五种形态：马具（引导方向和力量）、航天电气线束（NASA 标准，在混乱环境中确保信号准确传递）、软件测试的 test harness（隔离 + 受控环境 + 反馈循环）、安全带（不限制自由，但防止坠落）、汽车线束（连接一切，让零件从孤岛变成系统）。AI agent 的 harness 做的是同一件事：不替代核心力量，而是让核心力量变得可控、可靠、可用。
2026 年 2 月 5 日，Terraform 的创造者 Mitchell Hashimoto 发了一篇博文，给出了一个朴素到极致的定义：「每次 agent 犯错，就工程化一个方案，让它再也犯不了同样的错。」 他给 Ghostty 终端模拟器写的 AGENTS.md，每一行都对应 agent 过去犯过的一次错。
六天后，OpenAI 发正式博文用了同一个词："A harness is the tool shell that allows an AI agent to affect the real world. If the reasoning model is the brain, the harness is the hands and feet."（如果推理模型是大脑，harness 就是手和脚。）
一个月内，这个概念从一个人的博客术语变成了行业共识。
三、OpenAI 验证过的 5 条原则
OpenAI Codex 团队公开了他们的 harness 实践——3 名工程师起步、5 个月、约 100 万行代码、1500 个 PR 合并，零行人工手写代码。他们在博文里总结了五条原则，每一条都有实证支撑：
原则 1：Agent 看不到的等于不存在。
"From the agent's point of view, anything it can't access in-context while running effectively doesn't exist."
他们把 Google Docs 里的规划文档、Slack 里的决策记录全部迁进了代码仓库——因为 agent 只能看到仓库里的东西。你写在别处的需求再详细，agent 一个字都看不到。他们还为此创建了一种叫 ExecPlan 的文档格式：写到初级工程师也能端到端实现的程度，不是给人看的笔记，是给 agent 执行的指令。
原则 2：机械化强制优于文档规范。
"把品位编码进代码库"——自定义 ESLint 规则、CI 结构化测试，让坏模式在静态分析层面就不可能通过。指令是建议，约束是法律：指令说「请注意代码规范」，约束是代码不合规就编译不过。最妙的是，这些 linter 本身也是 Codex 写的——用 agent 约束 agent。
原则 3：给 Agent 装眼睛。
Codex 团队把 agent 连上了 Chrome DevTools Protocol，让它能看到 DOM 快照和截图。每次修改后，agent 自己启动一个隔离实例，比对修改前后的截图和日志，然后决定改得对不对。反馈从「文档里的愿望」变成了「可执行的指令」。
原则 4：问缺什么能力，而非为什么失败。
Agent 卡住了，正常反应是骂模型笨。Codex 团队的反应是：把卡住当信号，检查 agent 的工具箱里少了什么——工具、护栏，还是文档？配套策略是「优先使用无聊技术」：选 API 稳定、训练数据里高频出现的栈，agent 更熟，犯错更少。
原则 5：100 行地图哲学。
他们的 AGENTS.md 大约 100 行，只当目录和指针——项目结构、文件关系、关键约束，指向 docs/ 下更深层的文档。他们试过把规则全塞进一个超大文件，效果很差。Boris Cherny（Claude Code 创建者）的 CLAUDE.md 也只有约 100 行，他的判断标准是：每一行都问自己——删掉它会导致 agent 犯错吗？如果不会，就删掉。
还有一组数据值得单独拿出来。LangChain 在 Terminal Bench 2.0 上测了不同的推理预算分配策略：
| 推理配置 | 得分 | 说明 |
|---|---|---|
| 全程最高推理 | 53.9% | 大量任务超时 |
| 全程高推理 | 63.6% | 稳定但不够好 |
| 推理三明治（高-中-高） | 66.5% | 最终方案 |
全程拉满推理，得分反而最低——资源分配比资源总量更重要。这个「推理三明治」结论，后面在我们的交付中直接派上了用场。
Anthropic 的独立评估者实验同样值得关注。他们对比了两种方案：$9 跑一个单 Agent，20 分钟出结果，核心功能不可用；$200 跑三个 Agent 协作（规划者扩展需求、生成者实现功能、评估者像真人 QA 一样用浏览器交互测试），6 小时出结果，完整可用。成本贵了 20 倍，但质量不是一个量级。灵感来自生成对抗网络（GAN）：与其教一个模型自我批判，不如训练另一个模型专门挑刺——谁都不擅长批评自己的作品，AI 也一样。这条「独立评估者」思路，正是我们验收体系的理论来源。
四、5 条原则在 Dify 交付中怎么落地
看完理论，说实战。我们交付 RAG 知识库应用的载体是 Dify（开源 LLM 应用开发平台，可视化工作流）。对照这 5 条原则，逐条看我们的落地。
4.1 原则 5 的落地：模式库 = 100 行地图
「100 行地图哲学」在代码工程里是 CLAUDE.md，在我们的交付体系里是模式库。
我们接 RAG 应用定制单时，沉淀了一套设计模式体系：应用蓝图（客服/诊断/工单等完整图纸）、拓扑模式（场景最优工作流结构）、节点设计模式（LLM 节点怎么配、IF-ELSE 分支怎么走）、反模式清单（「别踩这些坑」）。入口是一个总索引——一份薄文件，每行一个模式名 + 一句话 + 指向深层文档的链接。
这和 OpenAI 的 AGENTS.md 结构一模一样：薄入口 + 指针，不把规则平铺。早期我们犯过「把所有踩坑经验写进一个大文档」的错——结果文档越来越长，真正生成 DSL 时反而想不起来查。改成索引制后，生成前先查索引、按需展开深层文档，规则才真正被用上。
这条原则对应我们踩过的坑：规则太多 = 没有规则。文档 5000 行没人看，索引 30 行人人用。
4.2 原则 2 的落地：错误兜底 = Dify 版的机械化强制
「机械化强制优于文档规范」在 Dify 里对应的是：把防错逻辑做成节点，而不是写进提示词。
我们的 RAG 工作流里有几个关键防错点，全部用代码节点和条件分支实现硬拦截：
- 检索空结果分支：知识库一个结果都召不回时，显式走「未找到」分支，绝不裸奔进 LLM——否则模型会基于空气编答案（这是原则 1 的镜像：没有上下文时，模型只能编）。
- query 改写兜底：口语化问题改写失败时，回退用原始 query 再检索一次，而不是把改写失败的垃圾 query 送进检索。
- LLM 空输出防护：生成类模型偶发空输出，下游接兜底节点，返回友好提示而不是空白。
提示词里写「如果找不到请说不知道」是建议，模型可能不听；用节点把「找不到」的路堵死是约束，模型不可能不听。这就是 Dify 版的「机械化强制」——把品位编码进流程。
4.3 原则 3 的落地：体检清单 = 给 AI 应用装眼睛
「给 Agent 装眼睛」说的是反馈机制。我们的版本是一套 RAG 应用体检清单——23 项，分三个等级：
- P0 功能质量（缺了应用就「有病」）：检索空结果有显式分支、防编造有效、引用溯源、检索配置正确、多库架构无污染、query 改写有效；
- P1 健壮性（缺了可用但脆）：LLM 空输出有兜底、异常路径不悬空、知识库索引健康、数据质量有基线、忠实度检查；
- P2 增强（差异化）：图片回传、多轮追问、安全增强、成本优化。
为什么这些项能成立？因为每一项背后都是真实踩过的坑——空段命中导致「内容在库却答未找到」、型号词毒化检索、分数窄带导致排序不可信。体检清单的作用和 Codex 的 Chrome DevTools 一样：让应用自己「看见」自己有没有病，而不是等客户用了才发现。
4.4 原则 1 的落地：看不到=不存在，知识必须进库
这是 5 条原则里我们感触最深的一条。
客户的知识分散在三处：手册（PDF/Word/Excel）、老工程师的经验（在脑子里）、客户的历史问题（在聊天记录里）。手册进了知识库，另外两处没进——对 AI 来说它们就不存在。 这就是客户觉得「AI 不如老师傅」的根源：老师傅脑子里有经验，AI 的知识库只有手册。
我们的解法分三层：
- 手册全量入库：几千页手册清洗成结构化语料（分段契约、图片资产化），建多库索引；
- 经验数字化：把常见故障的诊断思路、排查步骤整理成补充语料进库——这部分客户往往一开始没意识到要做，但恰恰是「AI 能不能答出手册之外的答案」的分水岭；
- ExecPlan 思想写需求：需求文档写到「执行者/agent 能直接端到端实现」的程度——写在文档里但没映射进节点和变量配置的信息 = 不存在。我们后来把这条写进了需求文档模板的硬性纪律。
4.5 推理三明治的落地：LLM 节点别全程拉满
LangChain 的推理三明治结论，在我们的工作流里变成了实际的模型选型纪律：
- 入口/规划节点（query 改写、意图理解）→ 用推理强的模型；
- 中间机械节点（格式化、摘要）→ 降配，用快而省的模型；
- 出口节点（最终回答）→ 拉回强模型。
全程拉满的代价我们实测过：响应慢、成本高，而且复杂节点反而更容易超时——和 LangChain 的 53.9% 完全一个道理。资源分配比资源总量更重要，这条在 LLM 应用的成本和体验优化上尤其成立。
五、我们踩过的坑（实战坑表）
原则是事后总结，坑是事前教训。列几个我们在交付中真实踩过、并且直接推动了上述设计的坑：
| 坑 | 现象 | 根因 | 修复 |
|---|---|---|---|
| 检索阈值当结果过滤器用 | rerank 后 0.956 高分段也救不回被阈值过滤的内容 | Dify 的 threshold 作用于候选集（原始分），不是终选结果——0.5 阈值误杀精准段 | 阈值降到 0.3，靠 rerank 精排兜质量（原则 2：配置即约束） |
| 空段污染知识库 | 库内问题答「未找到」，但内容明明在库 | 分段契约不严，产生只有标题没有正文的空段，检索命中空段 | 分段质量检查：空段率 <5% 才允许入库（原则 3：体检前置） |
| 型号词毒化检索 | 带型号的 query 召回满篇「共鸣」段落 | 型号词在手册里高频出现，向量检索被高频噪声带偏 | query 改写节点处理型号词（原则 4：问缺什么，给 agent 补工具） |
| 多段上下文排列 | 召回段越多答案越差 | LLM 对上下文中间位置的文本利用最差（Lost in the Middle 现象） | 高相关段前置/交替摆放，控制候选集大小（原则 3：反馈驱动调整） |
| 长对话上下文膨胀 | 多轮后回答质量下降、成本上升 | 对话历史全量进 LLM，越聊越满 | 记忆窗口策略：滚动最近 N 轮 + 历史总结（原则 2：约束优先于提示） |
六、启示：从「调模型」到「设计环境」
最后说一个认知层面的变化。
Martin Fowler 团队的 Kief Morris 画过一张图，把人在 AI 编程中的位置分成三层：in the loop（逐行审查、手动修改）、on the loop（不碰代码，构建和改进 harness）、out of the loop（只说想要什么，agent 自己搞定）。
区别在你对结果不满意的时候最明显：in the loop 的人去改结果，on the loop 的人去改产生结果的系统，让它下次产出更好的结果。
我们做 AI 应用交付，过去的重心是「把功能做出来」（in the loop）；现在正在往「把环境设计好」迁移（on the loop）。Harness 五组件在我们交付体系里都能找到对应：
| Harness 组件 | 作用 | 我们交付体系里的对应 |
|---|---|---|
| 指令 | 告诉 AI 做什么 | 设计模式库（薄入口索引 + 深层文档） |
| 约束 | 拦住 AI 做错事 | 错误兜底节点、检索配置纪律（机械化强制） |
| 反馈 | 检查 AI 做对没 | 23 项体检清单 + TR 验收（独立评估者） |
| 记忆 | 不重复犯错 | 知识库（手册 + 经验数字化 + 反馈更新） |
| 编排 | 让多个能力协作 | 工作流原子节点 + 子工作流组合 |
- 知识库 = 应用的记忆组件——让 AI 有据可答、不重复犯错；
- 检索调优 = 上下文工程——给模型恰到好处的信息，不是越多越好；
- 错误路径设计 = 约束组件——护栏式设计，事前拦截 + 事后兜底；
- 独立验收 = 反馈组件——让一个独立的评估流程给应用挑刺，而不是让应用自我感觉良好。
这几件事合起来，才是客户真正买的东西：一个可靠的环境，而不是一堆 API 调用。 模型大家都有，环境的设计能力才是交付方的分水岭——OpenAI 的 3 个工程师能驾驭 100 万行代码产出，不是因为他们模型更强，是因为他们把环境设计到了极致。
你所在的团队，是在「调模型」，还是在「设计环境」？欢迎在评论区聊聊你的交付经验。
参考资料
- OpenAI: Harness engineering: leveraging Codex in an agent-first world（2026-02）
- Mitchell Hashimoto: My AI Adoption Journey（2026-02-05）
- LangChain: The Anatomy of an Agent Harness（Terminal Bench 2.0 数据）
- Anthropic: 三 Agent 架构工程博客（$9 vs $200 实验）
- Martin Fowler 团队：Harness Engineering 分析（三支柱框架）
本文基于真实项目交付经验撰写（Dify 1.16.x 环境、数千页设备手册知识库交付实战）。文中数据均来自公开资料或我们自己的实测记录。
