全面解析AI Agent框架:Harness六大核心组件构建指南
仅凭裸模型存在四大局限:缺乏记忆、无法执行代码、知识陈旧、没有工作环境。Harness通过六大组件逐一解决——文件系统负责存储与版本管理;沙箱环境赋予代码自我验证能力;AGENTS.md无需训练即可注入知识;Web Search与MCP打破知识的时间壁垒;上下文工程对抗信息熵增;编排系统与Hooks保障多智能体协作质量。贯穿始终的系统提示词,则是整套框架的神经中枢。
核心观点在于:模型提供原始智能,而Harness则让智能变得切实可用。如果你并非模型本身,那么你很可能正在构建或使用Harness的一部分。
2025年底,一位创业者在社交媒体上分享的经历迅速引发了技术圈的广泛讨论:
“我花了三个月优化Prompt,模型回答质量提升了20%。然后我花了两周搭建Harness,整体任务完成率从35%飙升到了82%。” 这条动态下,点赞最高的评论仅四个字:方向错了。
过去两年,整个行业似乎都在追逐更庞大的模型、更强的推理能力和更长的上下文窗口。从GPT-4到Claude 3.5,从Gemini Ultra到DeepSeek-V3,参数规模不断刷新纪录,基准测试分数持续攀升。每一次新模型发布,都会掀起一阵“通用人工智能即将到来”的乐观情绪。
然而,一个不容忽视的事实是:在绝大多数真实业务场景中,用户并未感受到与基准分数相匹配的能力跃升。
原因何在?或许是因为关注的焦点出现了偏差。
模型如同一台强大的引擎,但引擎本身并非汽车。一台裸露的引擎放置在地面,它无法载人、无法转向、无法制动,甚至无法自行启动。你需要底盘、变速箱、方向盘、仪表盘、燃油系统……这一整套让引擎“发挥作用”的装备,在AI智能体的世界中,正逐渐被赋予一个日益重要的名称——Harness。
智能体 = 模型 + Harness。 模型负责提供智能,Harness则负责让智能落地产生价值。
这并非一个全新的概念,但它正在成为2026年AI工程领域最核心的共识。本文将从“裸模型的四个硬伤”切入,逐一剖析Harness的六大核心组件——文件系统、Bash与沙箱、记忆系统(AGENTS.md)、Web搜索与MCP、上下文工程、编排与Hooks——旨在揭示AI智能体真正的竞争壁垒并不在模型层,而在Harness层。
阅读本文后,你将重新认识一个事实:你所编写的每一行系统提示词、搭建的每一个工具链、设计的每一套协作逻辑,都是在构建Harness。如果你不是模型本身,那么你就是Harness的一部分。
Agent = Model + Harness:一个被忽视太久的公式
在深入拆解Harness之前,我们有必要先确立一个基础的认知框架。
什么是 Agent?
“Agent”一词在2024年被过度使用。任何能调用API的聊天机器人都自称Agent,任何增加了RAG的问答系统都宣称自己是Agent。但若回归其最本质的定义—— Agent是一个能够自主感知环境、做出决策、执行行动并从结果中学习的智能体。
请注意其中的四个关键动词:感知、决策、执行、学习。裸模型能胜任哪一步?严格来说,它仅能完成“决策”——给定输入,产生输出。它无法主动感知外部世界(缺乏感官),不能真正执行行动(缺乏手脚),更无法进行持久化的学习(缺乏长期记忆)。
因此,一个真正的Agent必然是这样的结构: Agent = Model + Harness
Model是大脑,负责“思考”。Harness则是大脑之外的一切——感官系统、运动系统、记忆系统、能量系统——负责将“思考”转化为“行动”。
Harness 到底是什么?
Harness的英文原意为“挽具”,即套在马上、将马力转化为拉车动力的那套装备。这个类比十分精妙:模型是马,Harness是挽具,而Agent是马、挽具与车辆构成的完整系统。
更技术化地描述,Harness是模型之外的所有工程基础设施的集合。它至少包括:
- 模型如何接收输入(上下文构建)
- 模型的输出如何被解析与执行(工具调用、代码执行)
- 模型如何获取外部信息(搜索、API调用)
- 模型如何记住过往经历(记忆机制)
- 模型如何与其他模型或子系统协作(编排)
- 以及贯穿所有环节的安全、格式与质量约束(Hooks)
Harness不是一个单一的零件,而是一套系统工程。这也解释了为何构建一个真正高效的Agent如此困难——你并非在调整某个参数,而是在设计一整座工程架构。
这张图传达了三个核心信息:第一,Model虽处于中心,但被Harness全方位包围与支撑;第二,六大组件各司其职又相互协同;第三,系统提示词(System Prompt)贯穿所有组件,是Harness的“神经系统”。
裸模型的四个硬伤:为什么光有聪明的大脑远远不够
要理解Harness的价值,必须先正视一个现实:裸模型(Raw Model)存在四个致命的缺陷。
所谓“裸模型”,即没有任何外部工具、文件系统、搜索能力或持久化记忆的纯粹大语言模型。可以将其想象为一个被关在密闭房间里的天才——智商极高,但看不见外界,记不住昨天的对话,发出的指令也无人执行。
硬伤一:无法维持跨会话状态
这是最易被感知的痛点。你与一个裸模型进行了两小时深度对话,讨论了一个复杂的系统架构,绘制了流程图,确定了技术方案。然后你关闭窗口,次日返回——它已忘记了一切。
这并非“记忆力差”,而是根本没有记忆机制。裸模型的每一次对话都是全新的开始,前一轮的所有上下文在会话结束时即刻消失。
对于简单问答,这或许无妨。但对于任何需要持续推进的工作——撰写书籍、开发项目、管理流程——此缺陷是致命的。你需要每次都从头解释背景,重新建立共识,手动输入之前的结论。这并非在与AI协作,而是在训练一位每日失忆的实习生。
硬伤二:无法执行代码
裸模型可以“编写”代码,但不能“运行”代码。它可以生成一段Python脚本,却无法验证这段代码是否能正确执行。它可以告诉你算法的时间复杂度,但不能在真实数据集上运行一遍以证明其分析。
这意味着什么?意味着裸模型的代码输出缺乏自我验证能力。它可能写出语法正确但逻辑错误的代码,可能忽略边界条件,可能对库版本做出错误假设。而所有这些错误,只有在人类手动复制代码到本地环境运行后才会暴露。
更深层的问题是:缺乏代码执行能力,模型便失去了“编写→运行→观察→修复→迭代”的自我验证循环。此循环正是优秀程序员的核心工作方式。一个不能运行自身代码的AI编程助手,犹如一位只会在纸上绘图却从不踏足工地的建筑师——理论上完美,实践中漏洞百出。
硬伤三:无法获取实时知识
大语言模型的知识存在一个“截止日期”。截止日期之后的一切——新发布的API文档、最新的安全漏洞、上周刚更新的框架版本、今日新闻——它一无所知。
在技术领域,此问题尤为严重。前端框架每半年一次大版本更新,云服务商每季度调整产品线,开源库的不兼容变更防不胜防。你询问裸模型“React 19的use() Hook如何使用”,它可能给出基于React 18的答案,甚至虚构一个根本不存在的API。
这正是所谓“幻觉”(Hallucination)的一个重要来源:模型并非“故意”胡说,而是其知识库中根本没有正确答案,于是它基于过时信息或模式匹配,“推理”出一个看似合理实则错误的答案。
硬伤四:无法搭建工作环境
裸模型没有文件系统,没有工作空间,没有项目目录。它不能创建文件,不能组织代码结构,不能管理依赖,不能运行构建工具。
这意味着它无法完成任何“工程级”任务。编写一个独立函数?可行。搭建完整的项目脚手架、配置CI/CD流水线、管理多个微服务间的依赖关系?绝无可能。
工程不仅是编写代码,更是在正确的位置编写正确的代码,并确保其与其他代码正确协作。没有工作环境,“工程”便无从谈起。
四个硬伤的本质
仔细审视这四个硬伤,会发现它们恰好对应了一个完整智能体所需的四种基础能力:
| 硬伤 | 缺失的能力 | Harness 的对应组件 |
|---|---|---|
| 无法维持跨会话状态 | 长期记忆 | 文件系统 + 记忆(AGENTS.md) |
| 无法执行代码 | 行动能力 | Bash + 沙箱 |
| 无法获取实时知识 | 感知能力 | Web Search + MCP |
| 无法搭建工作环境 | 环境操控 | 文件系统 + 上下文工程 + 编排 |
每一个“不能”,都在Harness中有一个对应的组件来补救。Harness并非锦上添花,而是对裸模型致命缺陷的系统性修补。 没有Harness的Model,犹如没有身体的大脑——它可以思考,却无法与世界互动。
组件一:文件系统——最基础的原语
在Harness的六大组件中,文件系统位列第一,并非因其最炫目,恰恰相反——它最朴素,也最基础。基础到许多人并未意识到它是一个独立的“组件”。
然而,正是这个最朴素的组件,决定了Agent能力的天花板。
为什么文件系统是“最基础原语”?
试想人类程序员如何工作。打开电脑后的第一件事是什么?启动IDE,加载项目目录。所有代码文件、配置文件、文档、测试用例、构建脚本……都以文件的形式存在于一个结构化的目录树中。
文件系统是所有工程活动的基石。没有文件系统:
- 代码无处存放
- 中间结果无法持久化
- 多步骤任务无法衔接
- 多智能体之间无法协作
对于AI Agent而言,文件系统的意义甚至超越对人类的重要性。因为人类拥有大脑记忆,可以“记住”部分中间状态。但Agent的上下文窗口是有限的——即使是200K token的上下文,对于一个真实项目也远远不足。文件系统就是Agent的“外置大脑”,是其突破上下文窗口限制的唯一途径。
文件系统的三大核心能力
第一,工作空间与中间结果存储。 Agent在执行复杂任务时,会产生大量中间产物——分析报告的草稿、代码的半成品、数据处理的中间结果、与用户确认的决策记录。这些中间产物需要一个地方存放,以供后续步骤引用。
若无文件系统,Agent必须将所有中间产物塞入上下文窗口——既浪费token,又易超出长度限制。有了文件系统,Agent可将中间产物写入文件,需要时再读取,实现“按需加载”。
第二,智能体协作的基础。 当任务复杂到需要多个Agent协同工作时,文件系统便成为它们之间的“共享白板”。Agent A将分析结果写入文件,Agent B读取文件并在此基础上继续工作。这种基于文件的异步协作模式,简单、可靠且可追溯。
第三,版本追踪与错误回滚。 这一点常被忽略,却可能是文件系统最有价值的能力之一。当文件系统与Git集成后,Agent的每一步操作都可被记录、追溯与回滚。
为何这至关重要?因为Agent会犯错。它可能在重构代码时引入Bug,可能在修改配置时破坏系统。若无版本追踪,错误会像雪球般越滚越大,直至系统崩溃。有了Git,Agent(或监督它的人类)可随时回退到之前的“安全状态”,甚至创建分支进行实验——失败则丢弃分支,成功则合并。
下图示意了文件系统在Agent工作流中的角色:

这里有一个关键洞察:文件系统 + Git 赋予了Agent“试错”的能力。 没有此能力,Agent只能步步为营,不敢冒险。拥有此能力后,Agent可以大胆尝试——反正随时可以回滚。这极大地释放了模型的创造力。
文件系统的设计原则
在实际工程中,为Agent设计文件系统需遵循几个原则:
目录结构要清晰且符合约定。 Agent不擅长处理混乱的文件组织。采用标准化的目录结构(如前端项目的src/components、src/utils约定)能显著降低Agent的认知负担。
文件粒度要适中。 过大的文件(数千行代码)可能超出Agent的处理能力;过小的文件(每个函数一个文件)会增加管理复杂度。一般而言,一个文件对应一个“模块”或“职责单元”是较好的粒度。
元数据要丰富。 文件名应具意义,目录应包含README,关键决策应有ADR(架构决策记录)。这些元数据是Agent理解“为何如此组织”的线索。
组件二:Bash + 沙箱——让 Agent 从“说”到“做”
如果说文件系统为Agent提供了一个“工作台”,那么Bash与沙箱则赋予了它一双“手”。
从“生成代码”到“执行代码”的质变
裸模型只能生成代码文本。但文本并非程序——程序是被执行的文本。在“生成”与“执行”之间,存在一条巨大的鸿沟。
一个终端(Bash)环境意味着Agent可以:
- 运行自己编写的代码
- 安装依赖包
- 执行构建命令
- 运行测试套件
- 查看运行时错误并进行调试
这从根本上改变了Agent的工作模式。没有Bash,Agent是一位“提建议”的顾问;有了Bash,Agent则成为“动手做”的工程师。
自我验证循环:写→跑→看→修→再来
这是Bash赋予Agent的最核心能力——自我验证循环。

此循环看似简单,其意义却是革命性的。没有此循环,Agent的输出质量完全依赖模型的“一次性生成”能力——模型推理正确则成功,推理错误则全盘皆输。有了此循环,Agent便拥有了自我纠错能力,可以从错误中学习(至少在单次会话内)。
实际测试数据表明:在编程任务中,具备自我验证循环的Agent的任务完成率,比“一次性生成”的方式高出40%–60%。此差距并非源于更优的模型,而完全来自Harness层的Bash能力。
为什么必须是“沙箱”?
拥有Bash就足够了吗?不,还需要安全隔离。
Agent执行的代码未必安全。它可能无意中执行了rm -rf /,可能下载了恶意包,可能发起未授权的网络请求。若Agent的代码执行环境是宿主机本身,后果不堪设想。
沙箱(Sandbox)提供了一个隔离的执行环境:
- 资源限制: CPU、内存、磁盘空间均有上限,防止死循环或内存泄漏拖垮系统。
- 网络隔离: 默认禁止外部网络访问,或仅允许白名单地址,防止数据泄露或恶意攻击。
- 文件系统隔离: Agent仅能访问自己的工作目录,无法触及宿主机敏感文件。
- 超时机制: 执行时间超过阈值自动终止,防止资源被长期占用。
沙箱并非可选的“安全加固措施”,而是Bash能力的必要前提。没有沙箱,你不敢让Agent执行代码;不敢让Agent执行代码,Agent便失去自我验证能力;失去自我验证能力,Agent的输出质量将大打折扣。
沙箱技术的选择
在工程实践中,常见的沙箱方案包括:
- Docker 容器: 最主流的方案,隔离性好,生态成熟,镜像管理方便。多数Agent框架(如Devin、OpenHands)采用Docker作为沙箱。
- gVisor / Firecracker: 更轻量的虚拟化方案,启动速度快(毫秒级),适合需频繁创建/销毁沙箱的场景。
- WebAssembly(WASM): 在浏览器端或边缘计算场景中具潜力,但目前对系统调用的支持尚不完善。
- Nix / 纯函数式环境: 通过声明式环境定义,确保每次执行环境完全一致,杜绝“在我机器上能跑”的问题。
选择哪种方案取决于具体需求,但核心原则仅一条:在保证安全的前提下,赋予Agent尽可能大的操作自由度。
组件三:记忆(AGENTS.md)——不改权重也能给模型加知识
这是Harness六大组件中最易被低估,却可能最具长期价值的一个。
模型的“失忆症”
前文已讨论,裸模型无法维持跨会话状态。每次对话结束,所有上下文都会消失。但在真实工作场景中,Agent需要“记住”大量信息:
- 项目的技术栈与架构决策
- 用户的偏好与工作习惯
- 曾经犯过的错误与学到的教训
- 团队的编码规范与设计模式
- 业务领域的专有知识
传统做法是将这些信息写入系统提示词——但系统提示词长度有限,塞入过多信息会稀释重要指令的权重,甚至导致模型“注意力分散”。
AGENTS.md提供了一个优雅的解决方案:将知识写入文件,在需要时自动注入上下文。
AGENTS.md 的工作机制
AGENTS.md的设计理念可概括为:工作中产生知识,存入文件,下次自动注入。
具体而言:
- 写入阶段: 当Agent在工作过程中产生有价值的知识(例如发现某个API存在未文档化的限制,或确认了某种架构方案的优劣),它会将这些知识以结构化方式写入AGENTS.md文件。
- 存储阶段: AGENTS.md文件存放于项目文件系统中,通常在根目录或各子目录下。它本质上是一个Markdown文件,人类可直接阅读与编辑。
- 注入阶段: 下一次Agent启动或切换到新的工作上下文时,Harness会自动读取相关的AGENTS.md文件,并将其内容注入到Agent的上下文中。

“上下文注入 = 不改权重给模型加知识”
这个等式是AGENTS.md最深刻的洞察。
传统上,要给模型“增加知识”,需进行微调——修改模型的权重参数。此过程成本高、周期长,且存在灾难性遗忘的风险。
AGENTS.md提供了一条捷径:不触碰模型权重,仅通过上下文注入来添加知识。 模型仍是原来的模型,但它“看到”的信息变了,因此其行为也随之改变。
这犹如一种“即插即用”的知识扩展机制——今日发现新的最佳实践,写入AGENTS.md,明日Agent便自动具备此知识。无需重新训练,无需等待模型供应商更新,无需任何机器学习专业知识。
这也解释了为何AGENTS.md被称为“记忆”组件——它使Agent拥有了跨会话的长期记忆,且这种记忆是透明的(人类可读可编)、可控的(可随时增删改)、可审计的(结合Git可追溯每次知识变更)。
AGENTS.md 的最佳实践
在实际项目中,AGENTS.md的组织方式通常遵循以下原则:
- 层次化存放: 根目录的AGENTS.md存放全局知识(项目概述、核心架构决策、团队规范);子目录的AGENTS.md存放局部知识(该模块的特殊约定、已知问题、接口规范)。Agent进入某目录工作时,会同时加载全局与局部知识。
- 结构化书写: 优秀的AGENTS.md并非随意笔记,而是具有明确结构的知识库。常见分类包括:项目架构、技术约束、编码规范、已知陷阱、决策记录等。
- 定期清理: 过时的知识比没有知识更危险。随着项目演进,早期约束可能已不适用,某些技术决策可能已被推翻。定期审查与清理AGENTS.md是保持其有效性的关键。
- 双向可编辑: AGENTS.md不仅是Agent写给自己的备忘录,也是人类与Agent之间的“知识契约”。人类可直接编辑AGENTS.md以传达偏好(如“我不喜欢使用三元表达式”)、约束(如“所有API必须采用REST风格”)甚至个人工作习惯(如“代码审查时请重点关注错误处理”)。
组件四:Web Search + MCP——突破知识的“时间牢笼”
裸模型的第三个硬伤是“无法获取实时知识”。Web Search与MCP正是针对此缺陷的解药。
知识的时间壁垒
每个大语言模型都有一个知识截止日期。此日期之后的世界,对模型而言是一片空白。
这在日常闲聊中或许无伤大雅,但在专业工作场景中,这是一个严重的限制。想象以下场景:
- 你让Agent协助调试一个Bug,而此Bug的修复方案在模型训练之后才被社区发布。
- 你让Agent编写一个集成方案,而目标API在上月进行了不兼容变更。
- 你让Agent分析竞品动态,而竞品昨日刚发布了新产品。
在这些场景中,裸模型不仅无法提供帮助,还可能基于过时信息自信地给出错误答案——这比“不知道”更为危险。
Web Search:打开信息的大门
Web Search赋予Agent搜索互联网的能力,使其能够访问训练数据之后的新信息。这从根本上解决了“知识过时”的问题。
但Web Search不仅是“接入一个搜索API”那么简单。一个优秀的Web Search组件需解决以下问题:
- 查询构建: 模型的自然语言表述未必是良好的搜索查询。Harness需协助模型将模糊意图转化为精准的关键词。
- 结果筛选: 搜索引擎返回的结果质量参差不齐。Harness需协助模型过滤低质量来源,优先采用权威文档(如官方文档、RFC、知名技术博客)。
- 内容提取: 网页内容常包含大量无关信息(广告、导航栏、侧边栏)。Harness需提取核心内容并以模型友好的格式呈现。
- 信息整合: 当Agent需综合多个来源信息时,Harness需协助其处理信息冲突、去重与排序。
MCP:从“搜索”到“连接”
如果说Web Search让Agent能“看见”互联网,那么MCP则让Agent能“触及”互联网。
MCP是Anthropic在2024年底推出的开放协议,定义了AI模型与外部工具、数据源之间的标准化交互方式。可将其理解为“AI世界的USB接口”——只要工具遵循MCP规范,即可即插即用地接入任何支持MCP的Agent。
MCP的意义在于:它将Agent的“感知范围”从公开互联网扩展到任何可编程的数据源与服务。数据库、内部Wiki、项目管理工具、代码仓库、监控系统……只要拥有MCP接口,Agent便能直接访问。

Web Search + MCP 的协同效应
Web Search与MCP单独使用均有价值,但二者的组合才真正强大。
举例说明:Agent需修复一个生产环境的Bug。
- MCP连接监控系统 → 获取错误日志与堆栈信息。
- MCP连接代码仓库 → 查看相关代码与近期变更历史。
- Web Search搜索错误信息 → 查找社区中是否存在类似问题的解决方案。
- MCP连接项目管理工具 → 检查是否有相关的已知问题。
- Agent综合所有信息 → 生成修复方案并提交PR。
在整个流程中,Agent如同一位经验丰富的SRE,在多个信息源间穿梭,快速定位并解决问题。此能力并非源于更强的模型,而是来自Harness层的Web Search与MCP组件。
组件五:上下文工程——对抗 AI 系统的“熵增”
如果说前四个组件是为Agent安装四肢与感官,那么上下文工程便是在管理其大脑如何高效运转。
这是Harness中最“软”的一个组件——它不涉及具体工具或协议,而是关于如何构建与维护模型的输入上下文。但恰恰是这个“软”组件,在实践中对Agent表现的影响最为显著。
Context Rot:上下文的“腐烂”
在长时间运行的Agent会话中,一个普遍但少被深入讨论的问题是Context Rot。
随着对话的进行,上下文窗口中会积累越来越多的信息——早期的指令、中间的讨论、工具调用的输入输出、错误信息与修复过程……这些信息如同沉积物般不断堆积,引发几个严重问题:
- 信噪比下降: 真正重要的信息被大量冗余内容淹没。模型的注意力被分散,关键指令的执行质量下降。
- 矛盾信息累积: 早期做出的决定可能已被推翻,但旧信息仍留存在上下文中。模型可能在新旧信息间“摇摆不定”,产生不一致的结果。
- Token 浪费: 大量无用历史信息占据了宝贵的上下文窗口空间,压缩了真正有用信息的空间。
- 推理质量退化: 研究表明,当上下文中充斥大量无关信息时,即使相关信息就在其中,模型的提取与推理能力也会显著下降——此即“大海捞针”问题在实际中的体现。
Context Rot并非理论问题,而是每个长时间运行的Agent都会遇到的实际挑战。如果你曾使用Agent处理复杂任务,很可能有过这种体验:初始阶段Agent表现出色,但随着对话延长,它开始“变笨”——遗忘之前的约定,重复犯过的错误,甚至对同一问题给出前后矛盾的回答。这正是Context Rot在起作用。
上下文工程的核心策略
对抗Context Rot的技术手段统称为“上下文工程”,它包含以下关键策略:
压缩(Compression)。 定期对历史上下文进行摘要压缩。将冗长的工具调用记录替换为简洁的结果摘要,将详细的讨论过程替换为最终结论。这如同为上下文进行“垃圾回收”。
工具输出卸载(Tool Output Offloading)。 工具调用的输出(特别是大段代码、日志、搜索结果)是上下文膨胀的主要来源。上下文工程会将这些输出存储到文件系统中,在上下文中仅保留摘要与文件引用。需要详细信息时,Agent可随时重新读取文件。
技能渐进加载。 不同的任务阶段需要不同的知识与能力。上下文工程会根据当前任务阶段,动态加载与卸载相关的技能定义。例如,在“需求分析”阶段加载产品相关知识,在“编码”阶段加载技术栈相关知识,避免一次性将所有信息塞入上下文。
分层上下文结构。 将上下文分为“核心层”(系统提示词、关键约束,始终保留)、“工作层”(当前任务相关信息,按需更新)、“历史层”(已完成任务的摘要,逐渐压缩)。不同层的信息具有不同的生命周期与更新策略。

上下文工程是 Harness 的“元能力”
上下文工程拥有特殊地位——它并非Harness中一个独立的功能模块,而是影响所有其他组件的“元能力”。
文件系统的读写操作需要上下文工程来决定“读什么”与“何时读”。记忆的注入需要上下文工程来决定“注入多少”与“注入哪些”。Web Search的结果需要上下文工程来决定“保留什么”与“丢弃什么”。编排中的子Agent通信也依赖上下文工程来构建高效的信息传递格式。
可以说,Harness本质上就是优秀上下文工程的实现机制。 Harness的每一个组件,归根结底都在解决同一个问题:如何在正确的时间,以正确的方式,将正确的信息呈现在模型面前。
这也解释了为何“上下文工程”这一概念在2025年底开始取代“提示词工程”,成为AI工程领域的核心议题。提示词工程关注“如何编写指令”,而上下文工程关注“如何构建模型所见的全部信息”——后者的范畴更广,影响也更为深远。
组件六:编排 + Hooks——让单兵作战变成集团军
最后一个组件是编排与Hooks。如果说前五个组件旨在增强单个Agent的能力,那么这个组件则致力于将多个Agent组织成一个协同作战的系统。
为什么需要编排?
当任务复杂度超出单个Agent的处理能力时,便需要将任务分解为多个子任务,分配给不同的“子Agent”处理,再将结果汇总。这便是编排。
编排解决的核心问题包括:
- 子 Agent 调度: 哪个子任务应分配给哪个Agent?它们之间的依赖关系如何?哪些可并行,哪些必须串行?
- 任务分发: 如何将一个模糊的大任务拆解为明确的小任务?如何确保每个子Agent获得足够的上下文以完成其子任务?
- 模型路由: 并非所有子任务都需要最强(也最昂贵)的模型。简单的格式转换可用小模型,复杂的架构设计需要大模型。编排器需根据任务复杂度选择合适的模型,在成本与质量间取得平衡。
- 结果聚合: 当多个子Agent返回结果后,如何检查一致性、解决冲突、合并为最终输出?

Hooks:注入确定性
编排解决了“谁做什么”的问题,Hooks则解决了“做得对不对”的问题。
在软件工程中,Hook是一种在特定事件发生时自动触发的回调机制。在Agent Harness中,Hooks的作用类似——在Agent行为的关键节点插入确定性检查,确保输出符合预期。
Hooks的典型应用场景包括:
- Lint 检查: Agent生成代码后,自动运行linter检查语法与风格是否符合项目规范。若不符合,则自动要求Agent修复。
- 续接(Continuation): 当Agent的单次输出因token限制被截断时,Hook自动检测截断并触发续接请求,确保输出的完整性。
- 格式约束: 确保Agent的输出符合特定格式要求——JSON Schema验证、Markdown结构检查、API响应格式校验等。
- 安全过滤: 在Agent执行敏感操作(如文件删除、数据库写入、外部API调用)前,Hook进行权限检查与安全审计。
- 成本控制: 监控token消耗与API调用频率,在接近预算上限时发出警告或实施限制。
Hooks的核心价值在于:它们用确定性的规则约束了概率性的模型输出。 模型的输出本质上是概率性的——它可能生成正确代码,也可能犯错。Hooks在模型输出的“出口”设置了一道关卡,用确定性规则(如lint规则、格式校验)拦截不合格的输出,要求重新生成。
这种“概率性生成 + 确定性校验”的组合模式,是当前Agent工程中最有效的质量保障策略之一。它既充分利用了模型的创造力与灵活性,又通过工程手段守住了质量底线。
编排模式的演进
Agent编排的方式在过去两年经历了快速演进:
- 线性管道: 最简单的编排方式,Agent A的输出直接作为Agent B的输入,依次传递。适用于步骤明确、依赖关系清晰的任务。
- DAG 编排: 用有向无环图定义任务间的依赖关系,支持并行执行无依赖关系的任务。比线性管道更灵活高效。
- 动态编排: 不预定义完整的任务图,而是由编排器Agent根据上一步结果动态决定下一步行动。最灵活,但也最难控制质量与成本。
- 层级编排: 编排器本身也可层级嵌套——一个高层编排器管理几个中层编排器,每个中层编排器又管理几个执行Agent。适用于超大规模的复杂任务。
选择何种编排模式,取决于任务的复杂度、确定性程度与实时性要求。但无论选择何种模式,Hooks都是不可或缺的质量保障机制。
System Prompt:贯穿所有组件的“神经系统”
在讨论完六大组件后,还有一个贯穿始终的要素值得单独探讨——系统提示词。
系统提示词并非Harness的“第七个组件”,但它是贯穿所有六个组件的“神经系统”。它在Harness架构中扮演着四个关键角色:
定义角色边界
系统提示词告诉模型“你是谁”以及“你不是谁”。这不仅是简单的角色扮演,更是在定义Agent的能力边界与行为约束。
例如:“你是一个专注于React生态的前端开发Agent。当用户提出后端相关需求时,建议他们使用专门的后端Agent。”这样的定义帮助Agent聚焦于其擅长领域,避免在不擅长的领域产出低质量结果。
注入领域知识
系统提示词是“零成本”知识注入的第一入口。项目背景、技术栈选型、核心业务逻辑——这些信息直接写入系统提示词,确保Agent从第一轮对话开始便具备必要的领域知识。
当然,如前所述,系统提示词的容量有限。当领域知识量超出其承载范围时,AGENTS.md便接管了此职责。两者是互补关系:系统提示词装载“必须知道”的知识,AGENTS.md装载“最好知道”的知识。
约束安全规则
系统提示词是Agent安全策略的“第一道防线”。哪些操作被允许,哪些被禁止;哪些数据可读取,哪些是敏感的;遇到不确定情况应如何处理——这些安全规则通过系统提示词直接“刻入”Agent的行为模式。
贯穿所有组件
系统提示词的影响范围不限于模型本身,它通过定义Agent的行为模式,间接影响了所有Harness组件的工作方式:
- 影响文件系统:定义文件的组织规范与命名约定。
- 影响Bash执行:限制可执行的命令范围。
- 影响记忆写入:规定知识记录的格式与标准。
- 影响搜索行为:设置搜索的优先来源与可信度标准。
- 影响上下文管理:定义信息的优先级与压缩策略。
- 影响编排逻辑:规定任务分解的粒度与协作规范。
从这个意义上说,编写系统提示词就是在设计Harness的行为规范。一份优秀的系统提示词如同一部优秀的公司章程——它不直接执行任何事务,但它决定了所有事务的执行方式。
结语:你就是 Harness 的一部分
让我们回到文章开头的公式:
Agent = Model + Harness
如果你是一名AI工程师、产品经理或技术负责人——如果你不是模型本身——那么你就是Harness的一部分。
你编写的系统提示词是Harness的神经系统。你搭建的工具链是Harness的四肢。你设计的记忆机制是Harness的长期记忆。你优化的上下文策略是Harness的注意力管理系统。你编写的Hook规则是Harness的质量底线。
过去两年,行业聚光灯始终打在模型身上——参数规模、基准分数、推理能力。但真正在生产环境中创造价值的,往往不是最强的模型,而是最好的Harness。
模型将继续进步,但进步的速度正在放缓。与此同时,Harness的工程空间几乎尚未被充分探索。文件系统应如何设计才能最大化Agent效率?上下文工程是否存在最优的压缩算法?编排模式如何在成本与质量间取得完美平衡?记忆机制能否实现真正的“终身学习”?
这些问题的答案,不在模型的学术论文中,而在Harness的工程实践里。
模型决定了Agent能力的下限,而Harness决定了其能力的上限。
下一次当你调试Agent表现时,不必急于更换更强的模型。先审视你的Harness:文件系统完善吗?沙箱安全吗?记忆机制在运作吗?上下文是否已“腐烂”?编排合理吗?Hooks在有效兜底吗?
答案或许就在那里。