Agent智能体工程

本文最初发表在Addy Osmani的博客上，经授权转载。

核心观点：每当发现智能体犯错，都应花时间设计一种解决方案，确保该错误不再发生。

过去两年，我们一直在争论模型：哪个最聪明、哪个能写出最干净的React代码、哪个幻觉更少。这种讨论虽有一定价值，但忽略了系统的另一半。模型只是运行中智能体的一个输入，其余部分是约束框架（harness）：围绕模型的提示、工具、上下文策略、钩子、沙箱、子智能体、反馈循环和恢复路径，以便智能体真正完成一些任务。

一个中等模型搭配优秀的约束框架，效果胜过顶级模型搭配糟糕的约束框架。我多次在自己的工作中观察到这一点。越来越有趣且重要的工程不在于选择模型，而在于设计模型周围的“脚手架”。

如今这一学科有了名称。Viv Trivedy创造了“约束框架工程”这一术语，他的《智能体约束框架解剖》一文清晰阐述了约束框架是什么以及各部分存在的原因。Dex Horthy持续跟踪这一模式。HumanLayer将大多数智能体失败归结为“技能问题”，即配置问题而非模型权重问题。Anthropic的工程团队发布了我认为最好的关于如何为长期运行任务设计约束框架的公开分析。Birgitta Böckeler从用户角度也提供了很好的概述。

本文尝试将这些线索整合起来。

究竟什么是约束框架？

Viv的一句话概括了大部分内容：智能体 = 模型 + 约束框架。如果你不是模型，你就是约束框架。

约束框架是除模型本身之外的所有代码、配置和执行逻辑。原始模型不是智能体，只有约束框架赋予其状态、工具执行、反馈循环和可执行约束时，它才成为智能体。

具体而言，约束框架包括：系统提示、CLAUDE.md、AGENTS.md、技能文件和子智能体提示；工具、技能、MCP服务器及其描述；捆绑的基础设施（文件系统、沙箱、浏览器）；编排逻辑（子智能体生成、交接、模型路由）；用于确定性执行的钩子和中间件（压缩、续领、lint检查）；可观测性（日志、追踪、成本和延迟计量）。

Simon Willison将循环部分精炼为：智能体是“循环运行工具以实现目标的系统”。技巧在于工具和循环的设计。

如果这听起来像很大的表面积，确实如此。但这是你的表面积，而非模型提供商的。Claude Code、Cursor、Codex、Aider、Cline——这些都是约束框架。底层模型有时相同，但你体验到的行为主要由约束框架决定。

编码智能体 = AI模型 + 约束框架。这个由Viv阐述并被HumanLayer回应的等式，是实际工作所在。关于等式左边的讨论声音很大，但实际上大部分杠杆作用在右边。

“技能问题”的重新定义

我观察到一种模式：工程师陷入其中。智能体做了蠢事，工程师责怪模型，然后将责备归档为“等待下一版本”。

约束框架工程的心态拒绝这种默认做法。失败通常是可理解的。智能体不知道某个约定，那就将其添加到AGENTS.md中。智能体运行了破坏性命令，那就添加钩子阻止它。智能体在40步任务中迷失，那就将其拆分为规划器和执行器。智能体不断“完成”损坏的代码，那就将类型检查反向压力信号接入循环。

HumanLayer说：“这不是模型问题，而是配置问题。”约束框架工程就是你认真对待这句话时发生的事情。

在Viv的文章和HumanLayer中都出现了一个引人注目的数据点。在Terminal Bench 2.0上，运行在Claude Code中的Claude Opus 4.6得分远低于同一模型运行在定制约束框架中的得分。Viv的团队仅通过更改约束框架，就将一个编码智能体从Top 30提升到Top 5。模型经过后训练后与它们训练时所针对的约束框架耦合在一起。将它们迁移到不同的约束框架——具有更好的代码库工具、更紧凑的提示和更锐利的反向压力——可以释放原始约束框架未充分利用的能力。

这与“只需等待GPT-6”的叙事相反。当今模型能力与你所见到的能力之间的差距，很大程度上是约束框架的差距。

棘轮：每次错误都变成规则

约束框架工程中最重要的习惯是将智能体错误视为永久信号。不是可以一笑置之的趣闻，不是可以重试的“坏运行”，而是信号。

如果智能体提交了一个带有被注释掉的测试的PR，而我意外合并了它，那就是一个输入。我的AGENTS.md下一个版本会说“永远不要注释测试；删除它们或修复它们。”我的预提交钩子下一个版本会扫描diff中的“.skip(”和“xit(”。我的审阅子智能体下一个版本会将注释掉的测试标记为阻塞项。

只在看到实际失败时才添加约束。只在有能力的模型使约束变得多余时才移除它们。好的AGENTS.md中的每一行都应该能追溯到某个具体出错的事情。

这也是约束框架工程是一门学科而非框架的原因。适合你代码库的约束框架是由你的失败历史塑造的。你无法下载它。

从期望行为反向设计

我发现Viv的框架在实际设计约束框架时最有用：从你期望的行为出发，推导出能够实现该行为的约束框架部分。他的模式：期望的行为（或希望修正的行为）→ 帮助模型实现该目标的约束框架设计。

这样推导的有用之处在于，每个约束框架组件都有特定职责。如果你无法说出某个组件所服务的行为，它可能就不应该存在。

本节其余部分大致按照Viv的顺序介绍各个部分，并附上我发现值得借鉴的具体模式。

文件系统和Git：持久状态

文件系统是最基础的原始构件，但由于其平淡无奇常常被低估。模型只能直接操作上下文中的内容。没有文件系统，你只能复制粘贴到聊天窗口，那不是工作流程。

有了文件系统，智能体就获得了读取数据、代码和文档的工作空间；将中间工作卸载到文件系统而非保留在上下文中的地方；以及多个智能体与人类通过共享文件协调的表面。在此基础上添加Git，便免费获得了版本控制，因此智能体可以跟踪进度、回滚错误和分支实验。

大多数其他约束框架原始构件最终都指向文件系统。

Bash和代码执行：通用工具

当前主要智能体循环是ReAct循环：模型推理，通过工具调用采取行动，观察结果，然后重复。但约束框架只能执行它有逻辑的工具。你可以尝试为每个可能动作预构建工具，或者给智能体Bash，让它自己动态构建所需工具。

Willison的观点是，智能体已经擅长shell命令；大多数任务归结为几个精心选择的CLI调用。约束框架仍然提供专门的工具，但Bash加代码执行已成为自主解决问题的默认通用策略。这就像教一个人使用单个厨房用具与给整个厨房的区别。

沙箱和默认工具

Bash只有在安全的地方运行时才有用。在笔记本电脑上运行智能体生成的代码有风险，并且单个本地环境无法扩展到大量并行智能体。

沙箱为智能体提供隔离的操作环境。约束框架连接到沙箱来运行代码、检查文件、安装依赖和验证工作，而不是在本地执行。你可以允许列表命令、强制网络隔离、按需创建新环境并在任务完成后拆除。

好的沙箱附带好的默认配置：预装语言运行时和包、Git和测试CLI、用于Web交互的无头浏览器。浏览器、日志、截图和测试运行器让智能体观察自己的工作并关闭自我验证循环。

模型不配置其执行环境。决定智能体在哪里运行、哪些可用以及如何验证输出，都是约束框架层面的事情。

记忆和搜索：持续学习

模型除了权重和当前上下文中的内容外没有额外知识。无法编辑权重的情况下，添加知识的唯一方法是通过上下文注入。

文件系统再次是原始构件。约束框架支持类似AGENTS.md的记忆文件标准，每次启动时注入。随着智能体编辑该文件，约束框架重新加载它，一个会话中的知识就传递到下一个会话。这是一种原始但有效的持续学习形式。

对于训练时不存在的知识（新版库、当前文档、今日数据），Web搜索和Context7等MCP工具弥补了截止点。将这些工具内置到约束框架中比留给用户更有用。

对抗上下文衰退

上下文衰退是指随着上下文窗口填满，模型推理和完成任务的能力变差的现象。上下文稀缺，约束框架在很大程度上是良好上下文工程的交付机制。

三种技术反复出现：

压缩。当窗口接近满载时，必须有所取舍。让API出错对于生产环境约束框架不可行，因此约束框架智能地总结并卸载较旧的上下文，使智能体继续工作。

工具调用卸载。大型工具输出（如2000行日志文件）会干扰上下文而不增加多少信号。约束框架保留高于阈值的头尾令牌，将完整输出卸载到文件系统，智能体可以按需读取。

渐进式披露技能。在启动时将每个工具和MCP加载到上下文中会在智能体采取任何行动之前就降低性能。技能让约束框架仅在任务实际需要时才揭示指令和工具。

Anthropic的约束框架文章为非常长的任务添加了另一种技术：完全上下文重置，即约束框架拆除会话并从紧凑的交接文件重建。他们明确指出，仅靠压缩对长任务不够；有时需要从结构化简报重新开始。这更接近人类入职新工程师的方式，而不是我们通常对“记忆”的看法。

长期执行：Ralph循环、规划、验证

自主长期工作是圣杯，也是最难做对的事情。当今模型存在提前停止、复杂问题分解能力差以及工作跨越多个上下文窗口时的不连贯性。约束框架必须围绕所有这些进行设计。

我之前在自我改进智能体和2026趋势文章中写过像Ralph循环这样的自主编码循环，但在本框架中值得重申：钩子截获模型退出意图，将原始提示重新注入新的上下文窗口，强迫智能体继续朝着完成目标工作。每次迭代从干净状态开始，但通过文件系统读取前一次的状态。这是一个将单会话智能体转变为多会话智能体的惊人简单技巧，是仅凭“使用更智能的模型”永远推导不出的原始构件。

规划是指模型将目标分解为一系列步骤，通常写入磁盘上的计划文件。约束框架通过提示和关于如何使用计划文件的提醒来支持这一点。