AI代理的控制工程

微信 ezpoda免费咨询：AI编程 | AI模型微调| AI私有化部署 | Tripo 3D | Meshy AI

Anthropic 给 Opus 4.5 一个高层级提示，让它构建一个生产级 Web 应用。它失败了。不是因为模型不好。而是因为它试图一次性完成所有事情（承认吧，你也会这样做），在上下文窗口中留下了半实现的功能，过早地宣布胜利。他们修复了脚手架，添加了进度跟踪和增量工作流：同一个模型开始交付了。他们把这篇文章命名为"针对长期运行 Agent 的有效 Harness"。

TL;DR: Harness > 模型这个说法正确但不完整。让它的机制起作用的是渐进式披露（progressive disclosure）：只在模型需要时展示它需要的内容。同样的模型，仅通过切换到更好的脚手架，CORE-Bench 得分就跃升了 36 分。我经过 8 个月和 5 个生产级应用后的框架：契约胜于直觉，约束胜于工具，每个季度简化一次。附可直接复制的模板。

这个词随后无处不在。OpenAI 发布了 "Harness 工程"。LangChain 只修改了 harness，就把他们的编码代理从 52.8% 提升到了 66.5%。Mitchell Hashimoto 和 Martin Fowler 也写了相关文章。SWE-bench Pro 在大规模上证实了这一点：同样的模型，不同的脚手架，不同的结果。

我看了看我的 CLAUDE.md、我的提示契约（prompt contracts）、我的 CLI 封装，意识到这正是我在 8 个月里在 5 个生产级应用中一直在做的事情。我只是没有一个词来命名它。Harness。就是这个。

所以是的，Harness 比模型更重要。这部分已经确定了。

但知道"harness 很重要"就像知道"健康饮食和锻炼"。如果你不真正去做，这就是毫无用处的，而且这将会催生出一整个过度复杂的框架产业，这些框架都偏离了重点。

我花了八个月时间，把书里提到的每一个错误都犯了一遍。这些是存活下来的经验。

1、每个人都会犯的3个错误

我知道，因为我三个都犯了。

错误 1：堆砌工具而不是编写契约

当我开始构建 OpenClaw（我的多模型 AI agent）时，我连接了 12 个 MCP 工具。搜索、记忆、信用检查、RSS 监控、Discord 告警、cron 状态、用户查询、备份验证。感觉很全面。很专业。

Agent 花在决定调用哪个工具上的时间，比解决实际问题的时间还多。

对于一个简单的"今天早上有什么需要我注意的吗？"查询，它会按顺序触发 4-5 个工具调用，有时会以稍有不同的参数两次调用同一个端点，因为描述模糊到重叠。有一天早上，它调用了 check_users，然后调用了 check_credits，然后又用不同的过滤器调用了 check_users，然后给我一个在段落之间相互矛盾的回答。

我删掉了 8 个工具。将 12 个替换为 4 个，这 4 个工具的精确描述被写成契约。不是"查询信用数据"，而是"查找当前信用余额偏离预期超过 10% 的用户，用偏离幅度标记异常，并按严重程度排序。"底层的代码相同。模型相同。唯一改变的是描述。

工具调用减少了 40%。输出不再自相矛盾。工具描述一直都是问题所在。

我围绕这个原则构建了完整的提示契约框架，这成为我整个工作流程中影响最大的单一改变。你不再与 agent 共享代码。你共享的是意图、约束和预期行为。描述就是契约。

错误 2：在简单方案可行时选择复杂性

47,000 个 token。这是 Phil Schmid 测量的以标准方式集成 6 个 MCP 服务器的成本。仅仅是 schema 定义。在你的 agent 甚至开始思考你的实际问题之前，它就要咀嚼掉四万七千个 token 的 JSON 工具描述。

Manus 通过 CLI 封装来暴露 MCP 工具解决了这个问题。相同的功能。大约 400 个 token。

我在 2025 年底构建我的第一个 MCP 服务器时，并不知道这些数字。每个人都在构建它们。协议是新的，很闪亮，感觉像是正确的抽象。所以我也构建了一个。自定义 OAuth 流程、token 刷新处理、多源数据聚合，应有尽有。

十六次提交。四个小时调试一个会话中途过期的 auth token。我在坎昆的酒店房间里，离泳池只有十米远，却在看日志滚动而不是游泳。最终发布了，现在运行得很好。但后来我也为其他服务构建了做同样事情的 CLI。CLI 需要一个 bash 脚本和一个 JSON 输出。第一次就成功了。

很酷。

Vercel 在大规模上进行了同样的实验。从全面的工具库开始：搜索、代码、文件、API 工具。你想要的每一个功能。Agents 混淆了，做了冗余调用，走了不必要的步骤。他们削减到本质，给 agent 直接的 bash 访问权限。成功率提高到 100%，速度提高了 3.5 倍。

我写了关于为什么对于大多数 agent 设置来说 CLI 比 MCP 更好的文章，反应很疯狂。原来很多构建者都有同样的怀疑，但在整个生态系统都在推动 MCP 作为未来时，说出来感觉很奇怪。

MCP 有它的位置。但首先伸手选择复杂解决方案的本能，正是 harness 在变得有用之前变得臃肿的原因。

错误 3：从不删除任何东西

这个问题很狡猾，因为它感觉是不负责任的。你构建了一个能用的东西。它在生产环境中。删除它感觉就像从高速公路上移除护栏。

但是模型在改进。而你的 harness 不知道这一点。

上个月我从 OpenClaw 中删除了整个记忆子系统。外部上下文检索、embedding 查找、对话历史注入。它花了两周时间构建，四个月时间维护。我在一个星期四删除了它。到星期五，数字告诉了故事：

每次查询的响应延迟下降了 2.3 秒。Agent 停止了幻觉"记住的"上下文——这些实际上是两个月前的陈旧数据。用户对支持互动的满意度提高了，因为 agent 回应的是人们实际说的话，而不是记忆系统认为相关的内容。

模型（Kimi K2.5）已经足够好地维护会话内的上下文，外部记忆层实际上让事情变得更糟。我正在为降低我的产品性能的基础设施付费。

Manus，可能是目前在生产环境中经过最充分实战测试的自主 agent，以艰难的方式五次学到了这一点。他们在六个月内重写了整个 harness 五次。不是因为模型改变了。因为每次重写都剥离了复杂性。

他们的初始版本使用了一个 todo.md 文件，agent 在每一步都重写它以跟踪进度。大约 30% 的所有 token 用于更新该文件。他们将其替换为一个子代理规划器（sub-agent planner），该规划器返回一个结构化对象，仅在需要时注入它。

他们将工具从几十个动态 MCP schema 削减到少于 20 个原子函数：bash、文件系统、代码执行。MCP 工具甚至不在上下文窗口中了。它们通过 CLI 暴露，agent 通过 bash 调用它们。

Peak Ji，他们的首席科学家，直言不讳地说："随着模型变强，我们不应该构建更多的脚手架，我们应该让开模型的路。"

Anthropic 说了同样的话："随着模型能力提高，你的模型曾经需要的工具现在可能正在限制它们。"

如果你的 harness 在三个月内没有缩小，它可能已经太大了。

2、让这一切起作用的一个模式

所有三个错误都有相同的根本原因：过早、过长时间地给模型提供过多信息。当它需要 4 个工具时给了 12 个。当 bash 脚本就行时给了 MCP 开销。记忆系统注入了陈旧的上下文，而模型已经超越了它。

解决方案有一个名字。渐进式披露（progressive disclosure）。只在模型需要时向它展示它需要的内容。隐藏其他所有东西。

Cursor 做得很激进。他们的动态上下文发现系统在任何给定步骤过滤掉大约 47% 的可用 token。不是偶然的，而是通过架构实现的。模型只看到与这个特定任务、这个特定时刻相关的内容。

Claude Code 通过技能（skills）来实现这一点。你创建一个 skills/ 目录，Claude 在会话开始时只看到技能名称和简短描述。只有当它决定需要时才加载完整内容。LLM 的懒加载。

Manus 通过分层操作空间（layered action space）来实现这一点。第 1 层：20 个原子工具，始终可见。第 2 层：通过 bash 调用的沙盒实用程序，永远不会污染上下文。第 3 层：agent 为复杂的链编写自己的脚本，而不是进行三次单独的 LLM 往返。

基准测试的影响是真实的。同样的模型，Claude Opus 4.5，在使用通用脚手架的情况下在 CORE-Bench 上得分为 42%。使用 Claude Code 作为 harness，得分为 78%。这不仅仅是渐进式披露，Claude Code 还带来了更好的工具管理、环境设置和压缩。但运行测试的研究人员直言不讳：脚手架几乎使分数翻倍。模型没有改变。

下面的三个支柱是我在实践中如何应用渐进式披露的方法。工具、配置、维护。

3、框架：契约、约束、清理

不是 47 层架构图。不是有 41 个技能定义和 11 个子代理的 GitHub 仓库。三件实际经受住生产环境考验的东西。

支柱 1：契约胜于直觉

你看到了 OpenClaw 工具描述发生的事情。它起作用的原因是机械的：模型对你的描述进行 token 级别的模式匹配，以决定工具是否与当前查询相关。模糊的描述匹配所有内容。精确的描述只匹配你想要的内容。

我现在用于所有工具定义的模板，我建议你今晚对你的三个最常用的工具也这样做：

name: [tool_name] description: [WHAT specifically it returns, not vague nouns but the actual shape of useful output]. Call this when [specific trigger conditions]. Do NOT call when [common misuse case]. Expected output: [format and key fields].

"不要调用当"（Do NOT call when）这一行是改变一切的关键。没有它，模型将每个工具都视为"可能"。有了它，模型就有了一个契约。

支柱 2：约束胜于工具

每次你想到"我需要一个新工具来解决这个问题"时，停下来。先问：CLAUDE.md 中的一行能解决它吗？

与其用一个 linter MCP 服务器，不如用一个约束："每次提交前运行测试。"与其用一个风格检查 agent，不如用一个约束："遵循 CONVENTIONS.md 中的约定。"与其用一个规划工具，不如用一个约束："在触碰代码前总是先写 plan.md。"

CLAUDE.md 中的约束在运行时成本为零 token，并增加了零故障面。一个工具每次调用时都会花费 token，增加一个模型可能出错的决策点，并且需要维护。一旦你看到它，数学就很明显了。

一个我实际上用作跨项目基础的入门 CLAUDE.md。不是单体，而是指向专门文件的导航层：

Senior engineer. You plan before you code. You test before you push. 1. Read this file + any progress.md at session start 2. Plan first. Write plan.md before implementation. 3. One feature at a time. Commit after each. 4. Run existing tests before AND after changes 5. Update progress.md before session ends ## Constraints - Never overwrite files without showing a diff first - If a task needs more than 3 files changed, break it down - When unsure, ask. Don't guess at business logic. - Keep commits small and descriptive ## Project specifics [Your stack, conventions, key files here] See CONVENTIONS.md for code style rules.

二十行告诉 agent 如何工作，而不是知道什么。Anthropic 自己的长期运行 agent harness 在类似的核心之上使用进度文件、功能列表和结构化的 git 提交。OpenAI 的 Codex 团队以艰难的方式学到了巨大的 AGENTS.md 会失败。他们的建议："给 Codex 一张地图，而不是 1,000 页的说明书。"

关键是将渐进式披露应用于配置：一个简短的 CLAUDE.md，指向 agent 在需要时读取的详细文件。不是它浏览和忽略的 500 行单体。不是什么都不说的 10 行存根。一个导航层。

支柱 3：季度清理

每三个月，我坐下来审视我的 harness，问五个问题：

• 哪些工具在 30 天内未被 agent 调用过？删除它们。
• 哪些 CLAUDE.md 规则的存在是因为旧模型愚蠢？移除它们。
• 哪些护栏现在由模型原生处理？剥离它们。
• 上下文注入仍然必要吗，还是模型的检索能力已经足够好？测试不带它的情况。
• 两个工具可以合并为一个，并带有更好的描述吗？做这件事。

上个季度在 OpenClaw 上：我删除了一个 6 周内未触发的重试不同模型的回退机制（Kimi K2.5 已经变得足够稳定）。我移除了三条关于 JSON 格式的 CLAUDE.md 规则，模型现在原生处理这些规则。我将两个监控工具合并为一个，并带有更具体的契约。

净结果：活动部分减少了 30%。零功能丢失。更快的响应。更少需要维护。

Manus 持续运行这个过程。Peak Ji 的测试：对你的 agent 评估套件运行一个更强的模型。如果性能没有提高，你的 harness 就是在拖累它。仅这个问题就能告诉你一切：你是在构建脚手架还是在构建笼子。

4、这对你今晚意味着什么

十五分钟。这就是你真正开始所需的全部时间。

重写你的三个最常用工具的描述。找到你的 agent 调用最多的工具。打开它们的描述。如果它们说的是工具做什么，而不是何时调用它和预期什么，用上面的契约模板重写它们。每个工具五分钟。影响是立竿见影的，agent 停止猜测并开始遵循指令。

然后将你的 CLAUDE.md 构建为导航层。如果你还没有，粘贴上面的入门模板并填写你的堆栈细节。如果你已经有了，检查：它是单体还是地图？将详细规则移动到单独的文件（CONVENTIONS.md、ARCHITECTURE.md），并将你的 CLAUDE.md 保持在 20-40 行左右。Agent 每次会话都读取 CLAUDE.md。它应该找到方向，而不是百科全书。

然后删除一件事。一个工具。一个 CLAUDE.md 规则。一个中间件钩子。选一个你一个月没碰过的东西。删除它。运行你的正常工作流程。如果什么都没坏，它就不应该在那里。如果某些东西坏了，恭喜，你刚刚了解了你的 harness 中真正重要的东西。这比某人在 X 上发布的任何架构图都更有价值💀

Harness 工程正在流行。给它六个月。会有课程。认证。GitHub 仓库，有 41 个技能定义、11 个子代理，和一个比大多数代码库都长的 README。三千颗星，零生产部署。

与此同时，真正交付 agent 的构建者将继续做这个词存在之前他们一直在做的事情。编写清晰的指令。选择简单的工具。删除停止工作的东西。

Harness 不是一份新工作。它是同一份工作，只是名字更好了。

原文链接: Agent Harness Engineering: What 8 Months in Production Taught Me

汇智网翻译整理，转载请标明出处