Harness Engineering 火了OpenAI 验证过的 5 条原则我们在 Dify 交付中怎么用摘要2026 年 2 月OpenAI 和 Mitchell Hashimoto 几乎同时把「Harness Engineering」推成了 AI 圈热词——模型是大脑harness 是手和脚。LangChain 用数据证明了它的分量同一个 coding agent模型完全没换只改 harnessTerminal 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 Engineering2022-2024怎么问。你告诉马「向左转跑快点」。Context Engineering2025给什么信息。你不只告诉马往哪走还给整片地形图RAG 结果、对话历史、工具定义。Harness Engineering2026整个系统怎么运转。缰绳、马鞍、围栏、跑道、护栏——模型在什么环境里运行、有什么约束、怎么获得反馈、犯错了怎么纠正。三者是包含关系Prompt ⊂ Context ⊂ Harness。Harness 这个词在工程领域其实早有对应物五个领域五种形态马具引导方向和力量、航天电气线束NASA 标准在混乱环境中确保信号准确传递、软件测试的 test harness隔离 受控环境 反馈循环、安全带不限制自由但防止坠落、汽车线束连接一切让零件从孤岛变成系统。AI agent 的 harness 做的是同一件事不替代核心力量而是让核心力量变得可控、可靠、可用。Harness整个运行环境Context给模型的信息Prompt怎么问约束不让模型做错事反馈检查模型做对没记忆让模型不重复犯错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 合并零行人工手写代码。他们在博文里总结了五条原则每一条都有实证支撑原则 1Agent 看不到的等于不存在。“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 更熟犯错更少。原则 5100 行地图哲学。他们的 AGENTS.md 大约 100 行只当目录和指针——项目结构、文件关系、关键约束指向 docs/ 下更深层的文档。他们试过把规则全塞进一个超大文件效果很差。Boris ChernyClaude Code 创建者的 CLAUDE.md 也只有约 100 行他的判断标准是每一行都问自己——删掉它会导致 agent 犯错吗如果不会就删掉。还有一组数据值得单独拿出来。LangChain 在 Terminal Bench 2.0 上测了不同的推理预算分配策略推理配置得分说明全程最高推理53.9%大量任务超时全程高推理63.6%稳定但不够好推理三明治高-中-高66.5%最终方案全程拉满推理得分反而最低——资源分配比资源总量更重要。这个「推理三明治」结论后面在我们的交付中直接派上了用场。Anthropic 的独立评估者实验同样值得关注。他们对比了两种方案$9 跑一个单 Agent20 分钟出结果核心功能不可用$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 world2026-02Mitchell Hashimoto:My AI Adoption Journey2026-02-05LangChain:The Anatomy of an Agent HarnessTerminal Bench 2.0 数据Anthropic: 三 Agent 架构工程博客$9 vs $200 实验Martin Fowler 团队Harness Engineering 分析三支柱框架本文基于真实项目交付经验撰写Dify 1.16.x 环境、数千页设备手册知识库交付实战。文中数据均来自公开资料或我们自己的实测记录。