【中文精读】Agent Harness Engineering(智能体挽具工程)

一、引言:被忽视的另一半系统

过去两年,业界的注意力几乎全在模型上:哪个模型更聪明、写的 React 更干净、幻觉更少。作者指出这忽略了系统的另一半——挽具(harness):包围模型的提示词、工具、上下文策略、hooks、沙箱、子智能体(subagents)、反馈回路和恢复路径。

「harness」这个术语由 Viv Trivedy 在《Anatomy of an Agent Harness》一文中系统提出。作者在文中反复引用的其他源头包括:Dex Horthy 与 HumanLayer 的「skill issue」框架、Anthropic 工程团队关于长时运行挽具的文章(作者评价为「关于这个主题最好的公开分析」)、以及 Birgitta Böckeler 在 martinfowler.com 上从用户视角写的综述。这份引用清单本身就是一张 harness 学习地图。

全文的方法论口号是:每当发现 agent 犯错,就投入工程手段,让它永远不再犯同样的错。

二、什么是挽具(harness)?

Viv 的一句话定义被作者奉为纲领:

"Agent = Model + Harness. If you're not the model, you're the harness."(智能体 = 模型 + 挽具。凡不是模型的部分,都是挽具。)

裸模型不是 agent。只有当挽具赋予它状态、工具执行、反馈回路和可强制执行的约束之后,它才成为 agent。挽具的具体组成清单(原文逐项列出):

• 系统提示词、CLAUDE.md、AGENTS.md、skill 文件、子智能体提示词;
• 工具(tools)、skills、MCP 服务器及其描述文本;
• 捆绑的基础设施:文件系统、沙箱(sandbox)、浏览器;
• 编排逻辑:子智能体生成、交接(handoff)、模型路由;
• Hooks 与中间件:压缩、续跑、lint 检查等确定性执行的环节;
• 可观测性(observability):日志、trace、成本与延迟计量。

Simon Willison 对循环本质的概括也被引用:agent 就是「为达成目标而在循环中运行工具(runs tools in a loop)」的系统。Claude Code、Cursor、Codex、Aider、Cline 都是挽具——底层模型可能完全相同,但使用体验由挽具主导。

三、「Skill issue」的重新定义:失败是配置问题

常见误区:agent 犯错就归咎于模型,然后等下一版模型。挽具思维拒绝这个默认姿势——失败通常是可解读、可修复的:

• agent 不懂你团队的约定?→ 写进 AGENTS.md;
• 跑了破坏性命令?→ 加一个拦截 hook;
• 40 步的任务走到一半迷失?→ 拆成 planner + executor;
• 总是把坏代码宣布为「完成」?→ 接入 typecheck 作为反压(backpressure)信号。

用 HumanLayer 的话说:这不是模型问题,是配置问题(skill issue 在这里被反转:是你的挽具技能问题,不是模型的能力问题)。

支撑这个论断的关键数据点:在 Terminal Bench 2.0 上,Claude Opus 4.6 在 Claude Code 里的得分,明显低于同一个模型在定制挽具里的表现;Viv 的团队只换挽具、不换模型,就把一个编码 agent 从榜单 Top 30 拉到 Top 5。原因:模型的后训练(post-training)与特定挽具深度耦合。结论:今天「模型能力」与「实际表现」之间的差距,很大程度上是挽具差距。

四、棘轮机制(ratchet):每个错误变成一条规则

这是全文最重要的工程习惯:把 agent 的每次错误当作永久信号,用挽具固化下来,像棘轮一样只进不退。原文给了一个完整例子:

agent 提交了一个含有被注释掉的测试的 PR,还被误合并了。于是:① 下一版 AGENTS.md 写明「不许注释掉测试」;② pre-commit hook 对 diff 做 grep,匹配 .skip( 和 xit(;③ reviewer 子智能体把此类情况标记为阻断项(blocking)。同一个失败,三层防线。

两条配套原则:只在见过真实失败后才加约束;只在更强的模型使约束变得冗余后才删除约束。推论:好的 AGENTS.md 里每一行都应能追溯到一次具体的失败。因此挽具工程是一门纪律(discipline)而非框架(framework)——它由你自己的失败历史塑造,无法从别处直接下载。

五、从期望行为反推设计(behavior-first design)

Viv 的设计方法:先写下期望的行为,再反推支撑该行为的挽具组件。每个组件必须有明确职责;说不出某组件对应什么行为,它就不该存在。原文的映射表:

5.1 文件系统与 Git:持久状态

最基础却最被低估的原语。模型只能操作上下文里的内容;没有文件系统,一切都是复制粘贴。文件系统提供:工作区、卸载中间产物的空间、多 agent 与人协作的共享界面。Git 则「免费」提供版本管理:跟踪进度、回滚坏改动、开分支做实验。

5.2 Bash 与代码执行:通用工具

agent 的主循环是 ReAct(推理 → 工具调用 → 观察 → 重复)。与其为每个动作预建专用工具,不如给 agent 一个 bash,让它即时制造自己的工具。Willison 观察到多数任务最终归结为几条精心选择的 CLI 命令。原文的比喻:不是教人用某个单一功能的厨房小家电,而是直接给他整个厨房。

5.3 沙箱与默认工具链

在本地直接跑 agent 生成的代码既有风险,也无法扩展到多个并行 agent。沙箱提供隔离环境:命令白名单、网络隔离、按需创建与销毁。好的沙箱应预装语言运行时、常用包、Git、测试 CLI、无头浏览器。浏览器、日志、截图、测试运行器让 agent 能观察自己的工作、闭合自验证循环。执行环境的所有决策都发生在挽具层。

5.4 记忆与搜索:持续学习

模型的知识仅限于权重和当前上下文,注入上下文是唯一给它加知识的方式。AGENTS.md 这类 memory 文件每次启动被注入;agent 自己编辑它之后,知识就能跨会话传递——粗糙但有效的持续学习。对训练截止日期之后的知识(新库版本、当前文档),用 web 搜索和 Context7 这类 MCP 工具补,且应内建进挽具而不是靠用户临时想起。

5.5 对抗上下文腐化(context rot)

核心事实:上下文越满,模型推理质量越差。业界反复出现的三种对策:

• 压缩(compaction):接近上限时智能摘要并卸载旧上下文——绝不能等到 API 直接报错;
• 工具调用卸载(tool-call offloading):大输出(比如 2000 行日志)只在上下文里保留首尾若干 token,全文写入文件系统,需要时再读;
• Skills 渐进披露(progressive disclosure):不在启动时加载全部工具/MCP 描述,只在任务需要时才揭示。

作者补充了 Anthropic 贡献的第四种:完全上下文重置(full context reset)——通过精简的交接文件(progress 文件 + git 历史)重建一个全新会话。Anthropic 明确指出仅靠压缩不足以支撑长任务;重置更像「给新来的工程师做入职简报」,而不是给老工程师递一份越来越糊的会议纪要。

5.6 长时程执行:Ralph 循环、规划、验证

当前模型在长任务上的三大问题:过早停止、复杂问题分解差、跨多个上下文窗口不连贯。对应机制:

• Ralph 循环(Ralph loop):用 hook 拦截模型的退出企图,把原始提示重新注入一个新的上下文窗口,强制继续;每一轮从文件系统读取上一轮留下的状态。效果是把单会话 agent 变成多会话 agent。
• 规划(planning):让模型把目标分解成写在磁盘上的 plan 文件;挽具用提示与提醒(reminders)支撑执行;每步之后做自验证——hook 自动跑测试套件,把错误文本原样回灌给模型。
• Planner / Generator / Evaluator 拆分:Anthropic 的经验是「生成」与「评估」分离优于自评,因为 agent 给自己打分总是偏乐观——原文的妙喻是「散文界的 GAN」(生成器和判别器必须是两个角色)。相关模式还有 sprint contract(冲刺契约):写代码之前,生成者与评估者先协商好「完成(done)」的定义。作者断言:事先写下完成条件,比任何提示词微调都更能治住范围漂移(scope drift)。

5.7 Hooks:强制执行层

Hook 是挂在生命周期特定点的脚本:工具调用前、文件编辑后、提交前、会话开始时。典型用途:每次编辑后跑 typecheck/lint/测试;拦截 rm -rf、git push --force、DROP TABLE;开 PR 或推 main 前要求人工批准;写入时自动格式化。设计原则(来自 HumanLayer):

成功保持沉默,失败要啰嗦(quiet on success, loud on failure)——检查通过时 agent 什么都听不到(不占上下文);失败时错误文本被注入循环,驱动它自我纠正。

5.8 AGENTS.md 与工具选择

仓库根目录的 markdown 规则手册是杠杆最高的配置点,每一轮都进入系统提示。两条经验:

• 保持简短:HumanLayer 把它控制在 60 行以内。规则越多,每条越不受重视。它应该像飞行员检查单,而不是公司风格指南。
• 每一行都要「挣来」:必须能追溯到一次具体失败或一条硬性外部约束,否则就是噪音。

工具同理:10 个职责清晰的工具胜过 50 个功能重叠的工具。还有一条安全提醒:工具描述会进入提示词,任何安装的 MCP 服务器都是模型会阅读的「可信文本」,恶意 MCP 可以借此实施提示注入(prompt injection)——装 MCP 等于给模型引入一个新的输入信道。

5.9 生产级挽具长什么样

作者引用 Fareed Khan 对 Claude Code 架构的(推测性)拆解图,并用一段话转述图的结论:一个生产级挽具围绕主循环分为七层——输入层(UI、会话管理、权限门)、知识层(skill 注册表、上下文压缩器、任务图、memory store)、集成层(MCP 运行时)、执行层(工具分发、流式运行时、prompt 缓存)、输出层、可观测层(事件总线、后台执行器)、多智能体层(子 agent 生成、mailbox、FSM 协议、worktree 隔离)。前文讲的每个概念都能在图上找到对应组件。结论与 Viv 一致:Claude Code 的成功至少一半归功于挽具。

六、挽具不会缩小,只会迁移

朴素观点认为:模型越强,挽具越薄,最终消失。作者部分承认:Opus 4.6 基本消灭了「上下文焦虑」(Sonnet 4.5 曾经会在接近它自认的上下文极限时过早收工),这让作者半年前写的一批缓解脚手架变成了死代码。但天花板随之上移:新任务带来新失败模式——需要多天记忆策略的任务、需要协调三个专门 agent 的挽具、需要给生成式 UI 做设计质量评估器的场景。

Anthropic 的表述被作者引为本节纲领,值得整句记住:

挽具中的每个组件,都编码了一条「关于模型自身做不到什么」的假设(expiring assumptions,会过期的假设)。假设失效(模型学会了),该组件应当移除;新能力解锁,则需要新的脚手架。

模型—挽具训练循环

Viv 指出的反馈环:挽具中发现有用的原语 → 标准化进产品 → 用于训练下一代模型 → 新模型更擅长该原语 → 循环往复。这解释了为什么 Opus 4.6 在 Claude Code 里的「手感」不同于在其他挽具里;也解释了为什么改动工具逻辑有时会引发奇怪回归——真正通用的模型不该在乎补丁工具叫 apply_patch 还是 str_replace,但联合训练造成了过拟合。启示:挽具是活系统,不是一次性配置;最适合你的挽具未必是模型被训练时所在的那个,而是为你的任务专门设计的那个——Terminal Bench 上 Top 30 → Top 5 的跃升就是证据。

七、Harness-as-a-Service(HaaS,挽具即服务)

Viv 的另一个判断:行业正从「构建于 LLM API 之上」(给你补全)转向「构建于挽具 API 之上」(给你完整运行时)。Claude Agent SDK、Codex SDK、OpenAI Agents SDK 都指向同一方向:开箱即得循环、工具、上下文管理、hooks、沙箱原语;你只需沿四大支柱——系统提示、工具、上下文、子智能体——做配置,把精力投入领域特定的提示与工具设计。这让「skill issue」真正变得可解:不必每次从零重建挽具,只需调优一个已经良好分解的配置面。Viv 关于起步的忠告:好的 agent 构建是迭代练习,没有 v0.1 就无法迭代。

八、走向何方

作者观察:对比顶级编码 agent(Claude Code、Cursor、Codex、Aider、Cline),它们彼此之间的相似度,已经高于它们底层模型之间的相似度——业界正在收敛于一套「承重的脚手架模式」。Viv 列出的三个开放问题:

• 多 agent 在共享代码库上并行协作的编排;
• agent 分析自身 trace、自动识别并修复挽具级失败模式(挽具的自我改进);
• 挽具按任务即时动态组装工具与上下文,而非启动时静态预配置——作者认为这意味着挽具将从「静态配置」演变为「更接近编译器的东西」。

文末作者推介了自己的 O'Reilly 书《Beyond Vibe Coding》,覆盖 specs、harnesses、evals、上下文工程与用 AI 交付生产级软件。