什么是 Agent Harness:给 AI 装上手脚的运行时
什么是 Agent Harness:给 AI 装上手脚的运行时
2026-09-03 教学笔记 | 基于 Harness Engineering(arXiv:2609.00006)
从一个场景说起
你在终端里对 Claude Code 说:「帮我修复这个 bug」。听起来像是直接和 AI 对话,但真正干活的远不止模型本身。
在你按下回车的那一刻,一个运行时系统开始工作:它把你的话、当前目录结构、项目规则文件(AGENTS.md)组装成 prompt 发给模型;模型回复「我要先搜索相关代码」,运行时就调用 ripgrep 执行搜索,把结果塞回对话;模型接着说「问题在第 42 行,我来编辑」,运行时先检查权限——这个文件允许改吗?要不要弹出确认框?——然后执行编辑。模型提出「再跑一下测试」,运行时就执行命令、捕获输出、喂回去。这个「模型提议 → 运行时执行 → 结果反馈 → 模型再提议」的循环不断滚动,直到模型判断 bug 已修复,运行时才停下来把最终答案交给你。
这套把模型接到真实世界的基础设施,就是 harness(马具/挽具)。马具本身不会拉车,但没有它,再壮的马也使不上力。下面把这个比喻拆开:先看 harness 承担的角色,再看一篇把它解剖开的论文。
模型是大脑,harness 是手脚、感官和规则
大语言模型本身只会生成文本。它能「读文件」「改代码」「跑测试」,全靠 harness 把意图翻译成真实操作,再把真实结果翻译回模型能理解的文本。可以说:模型提供智能,harness 提供行动能力、感知能力和行为边界。
一篇 2026 年的论文《Harness Engineering》解剖了 11 个生产级 coding harness(Claude Code、Codex CLI、Aider、OpenHands 等)的源码,发现无论系统大小,都必须回答同样的七个设计问题——这七个子系统就是 harness 的解剖图:
- Agent Loop(推理-行动循环)——什么时候继续、什么时候停、失败了怎么办。类比:一个人的工作节律,知道什么时候该停下来检查成果,而不是闷头蛮干到底。
- LLM Integration(模型接入)——调用哪个模型、prompt 怎么拼、缓存怎么省 token。类比:选哪个顾问咨询、怎么把案情简报说清楚、别每次都从头讲一遍。
- Tools & Actions(工具)——读文件、编辑代码、执行命令的具体方式。类比:手里的工具箱;同样是修水管,用扳手还是用手拧,效率和安全性天差地别。
- Memory & Context(记忆)——上下文窗口有限,什么该记住、什么该压缩、什么跨会话留存。类比:工作台旁边的笔记本,记住昨天做到哪了,而不是每次上班都失忆重来。
- Safety & Permissions(安全与权限)——什么操作直接放行、什么要问人、什么永远禁止。类比:家里哪些柜子孩子能开、哪些上锁;不设防的 agent 就像把电闸交给不懂事的孩子。
- Orchestration(编排)——复杂任务拆给子 agent 并行处理,再汇总结果。类比:包工头把一栋楼拆成水电、木工、油漆几个班组,各干各的,最后验收。
- Extensibility(扩展性)——通过配置、hooks、skills、插件让第三方增强能力。类比:手机的 App Store,基础功能有限,但装上 App 就什么都能干。
论文有个惊人的存在性证明:一个约 100 行的极简 harness(Mini-SWE-Agent)实现了全部七个子系统,跑分和大它三个数量级的系统同一区间。harness 的门槛很低,但生产系统的价值在任务完成之外——安全、恢复、成本控制、可扩展性。换句话说:写下七个子系统只要一个周末,让它们在生产环境中可靠运转才是真正的工程。
没有银弹
最有意思的发现是论文所说的「双缺席」:全部 11 个生产系统,没有一个用 LangChain、AutoGen 之类的通用 agent 框架——循环全是手写的原生异步代码;也没有一个用向量检索来找代码——全靠 ripgrep、glob 这些老牌确定性工具。
为什么?因为当失败模式是「修改真实代码库」时,可调试性和透明度压倒框架的便利。手写的循环出问题能一步步追踪,ripgrep 搜不到东西一眼就知道为什么;而黑盒框架和向量空间里的相似度匹配,出了错连归因都困难。
所以 harness 工程没有银弹:不是「用了某个框架就万事大吉」,而是围绕七个子系统,根据场景做出一连串可审计的、可回滚的朴素选择。
一句话总结
回到开头的场景:你按下回车,模型提议、运行时执行、结果反馈、循环滚动。这副马具由七个子系统构成——循环、接入、工具、记忆、安全、编排、扩展——它的门槛低到百行代码即可起步,但生产级的差距全在任务完成之外:可调试性压倒框架便利,可审计性压倒智能上限。智能很贵,但让智能安全落地的那副马具,才是真正的工程。