给野马套上缰绳:Agent Harness 工程实践 ——从范式理论到钉钉AI招聘的真实落地
阿里妹导读
写在前面:这不是一篇"概念科普文"。它是写给所有正在被 Agent 折磨、又离不开 Agent 的开发者——那些一边惊叹于一晚上跑出一个像样的 PR、一边在凌晨三点回滚生产事故的人。
关于引用的一句郑重交代:文中所有第三方数据,已尽量回溯到原始博客或官方文章;个别行业流传的数字,无法核实到一手来源时,已经主动软化或删除,并明确标注。文章的工程判断与实战经验,来自我们团队的真实落地,不依赖任何二手转述。
(文章内容基于作者个人技术实践与独立思考,旨在分享经验,仅代表个人观点。)
一、共鸣时刻:
你是不是也经历过这些瞬间?
↑ 凌晨两点:屏幕上 "ALL TESTS PASSED",红色警告悄悄写着 "3 services deleted"——这就是这两年开发者最熟悉的"虚假胜利"瞬间。野马已经冲出了显示器,而你手里没有缰绳。
凌晨两点,你盯着屏幕。Agent 又一次"自信地"宣布任务完成——测试全绿、CI 全过、PR 描述写得无懈可击。你点开 diff,发现它把一个核心服务"重构"了,顺手删掉了三个它"不理解"的兼容分支。
或者,更扎心的场景:
一个会话里它表现得像高级架构师,下一个会话像刚入职的实习生,因为它压根不记得上次干了什么。 你给它配了 20 个 MCP 工具,它开始在工具列表里"逛超市",逛着逛着就忘了正在干嘛。 它陷入死循环,把同一个错误反复"修复"了十几次,每次都换一种"自信"的说法。 你写了一份 800 行的 AGENTS.md教它做事,它读完前 200 行就开始幻觉。
如果你点头了——欢迎来到 Agent 的"实战时代"。这一年,AI 工程圈终于承认了一件事:
瓶颈不在模型够不够聪明,而在我们有没有把它"装"好。
这就是 Harness Engineering(驾驭工程)——Terraform / HashiCorp 联合创始人、Ghostty 终端作者 Mitchell Hashimoto 在他个人博客《My AI Adoption Journey》中系统阐述的工程范式 [1]。他给这件事的定义朴素到几乎是一句口号:
"anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent will not make that mistake again in the future."
——每当你发现 Agent 犯了一个错,就花时间工程化一个解,让它将来不再犯同样的错。
这句话本身就是 Harness Engineering 的全部精神:Agent 的每一次失败,都不是模型的问题,而是环境设计的债。
二、一个公式,看清楚 Agent 到底是什么
如果你只能记住这篇文章的一句话,请记住这个:
Agent = Model + Harness
这个公式后来被 LangChain 官方在《Improving Deep Agents with Harness Engineering》一文中作为标题级别的论断 [2]:模型负责推理,Harness 负责"剩下的所有事情"——工具系统、上下文管理、权限控制、反馈回路、记忆与协作。
这个公式的颠覆性在于它彻底改变了优化方向。最值得拿出来讲的一手案例,是 LangChain 自己做的实验:
表格数据说明:LangChain 一行来自官方博客 [2],一手可查;Anthropic 一行为行业公认事实;"小团队"一行仅作现象记述,未核实到一手来源。
读到这里你应该意识到一件事:过去几年大量精力放在"换更强的模型"上,但真正的杠杆位置一直在模型之外。
三、范式的三次跃迁:你站在第几代?
↑ 三代范式的进化路径:从"对马喊话"到"给马看地图",再到"给马造高速公路"——这两年里,AI 工程的关注焦点完成了从「话术」到「环境」的彻底跃迁。
这是 AI 工程范式的进化时间轴,对照一下你团队的水位:
| Harness Engineering |
业内一个常被引用的类比是:模型是 CPU,Harness 是操作系统——CPU 再快,OS 拉胯也白搭。这就是为什么 Anthropic 的 Claude Code 能撑起它商业化的重要一极:本质不是更强的模型,而是更好的 Harness。
一张图看懂 Agent + Harness 五层运行时
把 Prompt、Context、Harness 三代范式落到系统层面,本质是一张"围绕 Model 展开的运行时全景图"。你可以把下面这张图当作后文所有铁律、模式、标杆案例的物理地图——每一条最佳实践,都对应图中的某一个位置。
图中两条线索值得反复回看:
- 纵向五层:从 User Interaction 到 MCP,是一次用户请求在系统里流过的完整路径。Workspace 以一个横跨能力层与执行层的容器出现,它不是"某一层",而是所有层次共享的状态基座。
- 左侧 HARNESS 竖栏:Context Engineering / Architecture Constraints / Feedback Loop / Entropy Management,是把"野马"变成"可生产系统"的四根护栏,垂直穿透每一层。真正成熟的团队,不是在某一层做得特别花哨,而是四根护栏在五层里都有落点。
带着这张图往下读,每一条铁律你都能在上面找到坐标。
四、核心精髓:四条"反直觉"的铁律
↑ 四张卡片就是后文所有工程模式的"DNA":上下文要少、Agent 要专、状态要落盘、约束要可执行。每一条都和工程师的本能反着来——而这正是它们值钱的原因。
读了几十篇文章、踩了三个月坑之后,我把 Harness 的精髓提炼为四条反直觉的铁律。之所以"反直觉",是因为它们都和工程师的本能背道而驰。
先用一张表看全貌,再逐条展开:
AGENTS.md 读给它 |
铁律一:上下文越少越好(不是越多越好)
工程师本能:信息越多决策越准。
Harness 真相:**上下文是稀缺资源,会被污染、会相互干扰、会让模型"逛超市"**。
业内多个团队的实测都指向同一个方向:长上下文窗口在实际使用比例超过一定阈值之后,模型的准确率会显著下降——具体阈值因模型、任务、Prompt 结构差异很大,并不存在一个放之四海皆准的"百分比"。
启示:不要把"模型支持 200K"当成"可以塞 200K"。给 Agent 的上下文,必须像 Code Review 一样精挑细选。
铁律二:专才 Agent 永远赢过通才 Agent
工程师本能:"我做一个超级 Agent,什么都会,不就搞定了?"
Harness 真相:通才 Agent 在工具列表里"逛超市",永远跑不过一组职责清晰的专才。
LangChain 在 Terminal Bench 实验里给了一条非常具体的经验:把任务拆给专门的 Sub-Agent,并为每个 Sub-Agent 只装载它真正需要的工具,是排名从第 30 冲进第 5 的关键改动之一 [2]。
启示:Agent 是昂贵的,Skill 是廉价的 [3]——能用 Skill 解决的就别新增 Agent。
铁律三:状态要写文件,不要塞上下文
工程师本能:让 Agent "记住"任务进展。
Harness 真相:上下文是易失存储,文件系统才是持久内存。
成熟的 Agent 系统遵循一个简单原则:Workspace 是真相,Context Window 只是当前工位。任务中间结果、Agent 间协作、跨会话延续、审计回放,全部走文件系统。
启示:把 Workspace 当成"Agent 的 Git 仓库"——每一步操作都可回放、可审计、可断点续传。
铁律四:能写成 Linter 的约束,别写成文档
工程师本能:把规则写进 AGENTS.md 让 Agent 自己读。
Harness 真相:**文档只是"建议",Linter / CI 才是"强制"**。
Mitchell Hashimoto 在他自己的 Ghostty 项目里就给了一个非常硬核的实践:AGENTS.md 里每一条规则,背后都对应一个真实失败案例;而能写成静态检查 / CI 拦截的规则,绝不让它停留在自然语言里——因为自然语言可以被模型"创造性解读",代码不能 [1]。
启示:把规则编码为机器可执行的约束,比"再写一段更详细的 Prompt"更可靠十倍。
五、Context Engineering 的"工程化":
从"喂信息"到"控信号"
Harness Engineering 不是 Context Engineering 的对立面,而是它的工业化升级。同样是"给模型对的信息",工程化版本要做四件事:
一旦上下文变成可审计的"输入信号",你就从"调 Prompt 的玄学"进入了"调系统的工程"——这是 Harness 工程师和 Prompt 工程师最大的分水岭。
六、六大工程模式:
Harness Engineering 的"设计模式手册"
如果说前面的铁律是"心法",下面六个就是"招式"。它们都已经被多家团队在生产环境验证过,可以直接抄。先给一张索引表,每一行对应下面的一个小节:
模式 1:双阶段架构(Initializer + Executor)
Anthropic 在 Claude Code 的实践中给出了一个被广泛复用的模板:把任务拆成两段——
Initializer Agent:理解任务 → 制定计划 → 写入 plan.md → 退出↓Executor Agent :读取 plan.md → 按步执行 → 跨 Context Window 接力
两个 Agent 不共享 Context Window,只通过 Workspace 里的 plan.md 接力。这样做的好处:任务可以跨多次会话延续,不依赖任何一个会话的记忆。
模式 2:工具签名即文档
(Tool-Signature-as-Doc)
Agent 选错工具的最大原因,不是工具太多,而是工具签名写得像一坨胶水。成熟团队的做法:
工具名是动词短语,一眼能读懂:"query_calendar" 而不是 "tool_03"。 参数 schema 里每个字段都带 description,且描述里说清"什么时候用、什么时候别用"。返回值结构稳定,Agent 不需要每次猜格式。
LangChain 在 Terminal Bench 实验里专门提到:仅仅改善工具描述与返回结构,就能带来可观的准确率提升 [2]。
模式 3:Sub-Agent 隔离
(Context-Isolated Sub-Agent)
复杂任务交给 Sub-Agent,**但关键不是"拆",是"隔离"**:
每个 Sub-Agent 有独立 Context Window,不污染主上下文。 每个 Sub-Agent 只看到自己需要的工具,看不到全集。 主 Agent 只接收 Sub-Agent 的结构化输出,不接收它的中间思考。
模式 4:上下游反压
(Upstream-Downstream Backpressure)
防止 Agent 陷入无限循环的工程范式:
上游:给确定性设置 + 一致上下文│▼Agent 执行│▼下游:测试 / 类型检查 / Lint / CI 拒绝无效工作│▼错误信号回传 → 上游调整
关键细节:Linter 的错误信息本身就是上下文工程。它不只说"违反规则 X",而…