一文讲透如何构建Harness——六大组件全解析

一文讲透如何构建Harness——六大组件全解析 一文讲透如何构建Harness——六大组件全解析 Modified April 2 这也是为什么"上下文工程"这个概念在 2025 年底开始取代"Prompt 工程"成为 AI 工程领域的核心话题。Prompt 工程关注的是"怎么写指令"，上下文工程关注的是"怎么构建模型看到的全部信息"——后者的范围大得多，影响也深远得多。 08 组件六：编排 + Hooks——让单兵作战变成集团军 最后一个组件是编排（Orchestration）+ Hooks。如果说前五个组件是在增强单个 Agent 的能力，那么这个组件是在把多个 Agent 组织成一个协同作战的系统。 8.1 为什么需要编排？ 当任务复杂度超过单个 Agent 的处理能力时，你需要把任务分解为多个子任务，分配给不同的"子 Agent"处理，然后把结果汇总。这就是编排。 编排解决的核心问题包括： 子 Agent 调度。 哪个子任务应该分配给哪个 Agent？它们之间的依赖关系是什么？哪些可以并行，哪些必须串行？ 任务分发。 如何把一个模糊的大任务拆解为明确的小任务？如何确保每个子 Agent 得到足够的上下文来完成它的子任务？ 模型路由。 不是所有的子任务都需要最强（也最贵）的模型。简单的格式转换可以用小模型，复杂的架构设计需要大模型。编排器需要根据任务复杂度选择合适的模型，在成本和质量之间取得平衡。 结果聚合。 当多个子 Agent 返回结果后，如何检查一致性、解决冲突、合并为最终输出？ 8.2 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 工程中最有效的质量保障策略之一。它既充分利用了模型的创造力和灵活性，又通过工程手段兜住了质量底线。 8.3 编排模式的演进 Agent 编排 的方式在过去两年经历了快速演进： 线性管道（Sequential Pipeline）。 最简单的编排方式，Agent A 的输出直接作为 Agent B 的输入，依次传递。适用于步骤明确、依赖关系清晰的任务。 DAG 编排（Directed Acyclic Graph）。 用有向无环图定义任务之间的依赖关系，支持并行执行没有依赖关系的任务。比线性管道更灵活高效。 动态编排（Dynamic Orchestration）。 不预定义完整的任务图，而是由编排器 Agent 根据上一步的结果动态决定下一步做什么。最灵活，但也最难控制质量和成本。 层级编排（Hierarchical Orchestration）。 编排器本身也可以层级嵌套——一个高层编排器管理几个中层编排器，每个中层编排器又管理几个执行 Agent。适用于超大规模的复杂任务。 选择哪种编排模式，取决于任务的复杂度、确定性程度和实时性要求。但无论选择哪种模式，Hooks 都是不可或缺的质量保障机制。 09 System Prompt：贯穿所有组件的"神经系统" 在讨论完六大组件后，还有一个贯穿始终的要素值得单独讨论——System Prompt。 System Prompt 不是 Harness 的"第七个组件"，但它是贯穿所有六个组件的"神经系统"。它在 Harness 架构中扮演着四个关键角色： 9.1 定义角色边界 System Prompt 告诉模型"你是谁"和"你不是谁"。这不是简单的角色扮演，而是在定义 Agent 的能力边界和行为约束。 例如："你是一个前端开发 Agent，专注于 React 生态系统。当用户提出后端相关需求时，建议他们使用专门的后端 Agent。"这样的定义帮助 Agent 聚焦在自己擅长的领域，避免在不擅长的领域产出低质量结果。 注入领域知识 System Prompt 是"零成本"知识注入的第一入口。项目背景、技术栈选型、核心业务逻辑——这些信息直接写在 System Prompt 中，确保 Agent 从第一轮对话开始就具备必要的领域知识。 当然，正如前文讨论的，System Prompt 的容量有限。当领域知识量超过 System Prompt 能承载的范围时，AGENTS.md 就接管了这个职责。两者是互补关系：System Prompt 装"必须知道的"，AGENTS.md 装"最好知道的"。 约束安全规则 这也是为什么"上下文工程"这个概念在 2025 年底开始取代"Prompt 工程"成为 AI 工程领域的核心话题。Prompt 工程关注的是"怎么写指令"，上下文工程关注的是"怎么构建模型看到的全部信息"——后者的范围大得多，影响也深远得多。 08 组件六：编排 + Hooks——让单兵作战变成集团军 最后一个组件是编排（Orchestration）+ Hooks。如果说前五个组件是在增强单个 Agent 的能力，那么这个组件是在把多个 Agent 组织成一个协同作战的系统。 8.1 为什么需要编排？ 8.1 为什么需要编排？ 当任务复杂度超过单个 Agent 的处理能力时，你需要把任务分解为多个子任务，分配给不同的"子 Agent"处理，然后把结果汇总。这就是编排。 编排解决的核心问题包括： 子 Agent 调度。 哪个子任务应该分配给哪个 Agent？它们之间的依赖关系是什么？哪些可以并行，哪些必须串行？ 任务分发。 如何把一个模糊的大任务拆解为明确的小任务？如何确保每个子 Agent 得到足够的上下文来完成它的子任务？ 模型路由。 不是所有的子任务都需要最强（也最贵）的模型。简单的格式转换可以用小模型，复杂的架构设计需要大模型。编排器需要根据任务复杂度选择合适的模型，在成本和质量之间取得平衡。 结果聚合。 当多个子 Agent 返回结果后，如何检查一致性、解决冲突、合并为最终输出？ 8.2 Hooks：注入确定性 8.2 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 工程中最有效的质量保障策略之一。它既充分利用了模型的创造力和灵活性，又通过工程手段兜住了质量底线。 8.3 编排模式的演进 8.3 编排模式的演进 Agent 编排 的方式在过去两年经历了快速演进： 线性管道（Sequential Pipeline）。 最简单的编排方式，Agent A 的输出直接作为 Agent B 的输入，依次传递。适用于步骤明确、依赖关系清晰的任务。 DAG 编排（Directed Acyclic Graph）。 用有向无环图定义任务之间的依赖关系，支持并行执行没有依赖关系的任务。比线性管道更灵活高效。 动态编排（Dynamic Orchestration）。 不预定义完整的任务图，而是由编排器 Agent 根据上一步的结果动态决定下一步做什么。最灵活，但也最难控制质量和成本。 层级编排（Hierarchical Orchestration）。 编排器本身也可以层级嵌套——一个高层编排器管理几个中层编排器，每个中层编排器又管理几个执行 Agent。适用于超大规模的复杂任务。 选择哪种编排模式，取决于任务的复杂度、确定性程度和实时性要求。但无论选择哪种模式，Hooks 都是不可或缺的质量保障机制。 09 System Prompt：贯穿所有组件的"神经系统" 在讨论完六大组件后，还有一个贯穿始终的要素值得单独讨论——System Prompt。 System Prompt 不是 Harness 的"第七个组件"，但它是贯穿所有六个组件的"神经系统"。它在 Harness 架构中扮演着四个关键角色： 9.1 定义角色边界 9.1 定义角色边界 System Prompt 告诉模型"你是谁"和"你不是谁"。这不是简单的角色扮演，而是在定义 Agent 的能力边界和行为约束。 例如："你是一个前端开发 Agent，专注于 React 生态系统。当用户提出后端相关需求时，建议他们使用专门的后端 Agent。"这样的定义帮助 Agent 聚焦在自己擅长的领域，避免在不擅长的领域产出低质量结果。 注入领域知识 System Prompt 是"零成本"知识注入的第一入口。项目背景、技术栈选型、核心业务逻辑——这些信息直接写在 System Prompt 中，确保 Agent 从第一轮对话开始就具备必要的领域知识。 当然，正如前文讨论的，System Prompt 的容量有限。当领域知识量超过 System Prompt 能承载的范围时，AGENTS.md 就接管了这个职责。两者是互补关系：System Prompt 装"必须知道的"，AGENTS.md 装"最好知道的"。 约束安全规则 System Prompt 是 Agent 安全策略的"第一道防线"。哪些操作是允许的，哪些是禁止的；哪些数据可以读取，哪些是敏感的；遇到不确定的情况应该怎么处理——这些安全规则通过 System Prompt 直接"刻"进 Agent 的行为模式。 贯穿所有组件 System Prompt 的影响范围不限于模型本身，它通过定义 Agent 的行为模式，间接影响了所有 Harness 组件的工作方式： • 影响文件系统：定义文件的组织规范和命名约定 • 影响 Bash 执行：限制可执行的命令范围 • 影响记忆写入：规定知识记录的格式和标准 • 影响搜索行为：设置搜索的优先来源和可信度标准 • 影响上下文管理：定义信息的优先级和压缩策略 • 影响编排逻辑：规定任务分解的粒度和协作规范 在这个意义上，写 System Prompt 就是在设计 Harness 的行为规范。一个好的 System Prompt 就像一部好的公司章程——它不直接做任何事，但它决定了所有事怎么做。 10 结语：你就是 Harness 的一部分 让我们回到文章开头的那个公式： Agent = Model + Harness 如果你是一名 AI 工程师、产品经理、技术负责人——如果你不是模型本身——那你就是 Harness 的一部分。 你写的 System Prompt 是 Harness 的神经系统。你搭建的工具链是 Harness 的四肢。你设计的记忆机制是 Harness 的长期记忆。你优化的上下文策略是 Harness 的注意力管理。你编写的 Hook 规则是 Harness 的质量底线。 过去两年，行业的聚光灯一直打在模型身上——参数规模、基准分数、推理能力。但真正在生产环境中创造价值的，往往不是那个最强的模型，而是那个最好的 Harness。 模型会继续进步，但进步的速度在放缓。与此同时，Harness 的工程空间还几乎没有被充分探索。文件系统怎么设计才能最大化 Agent 的效率？上下文工程有没有最优的压缩算法？编排模式怎样才能在成本和质量之间取得完美平衡？记忆机制能否实现真正的"终身学习"？ 这些问题的答案，不在模型的论文里，而在 Harness 的工程实践中。 模型决定了 Agent 能力的下限，Harness 决定了 Agent 能力的上限。 下一次当你在调试 Agent 的表现时，不要急着换一个更强的模型。先看看你的 Harness：文件系统完善吗？沙箱安全吗？记忆机制在工作吗？上下文腐烂了吗？编排合理吗？Hooks 在兜底吗？ 也许答案就在那里。 End 原创作者｜ 李伟山 🔗 原文链接： https://mp.weixin.qq.com/s/HwqEaXSG... https://mp.weixin.qq.com/s/HwqEaXSG... 原创 李伟山 李伟山 腾讯云开发者2026年4月1日 08:46 北京 关注腾讯云开发者，一手技术干货提前解锁👇 裸模型有四大硬伤：无记忆、不能执行代码、知识过时、无工作环境。Harness 六大组件逐一补救——文件系统管存储与版本；沙箱赋予代码自验证；AGENTS.md 无需训练即可注入知识；Web Search+MCP 打破知识截止；上下文工程对抗信息腐烂；编排+Hooks 保障多 Agent 协同质量。System Prompt 贯穿始终，是整套系统的神经中枢。 一句话摘要： 模型提供智能，Harness 让智能变得有用。如果你不是模型本身，那你就是 Harness 的一部分。 2025 年底，一位创业者在社交媒体上发了一条动态，迅速引爆了技术圈的讨论—— “我花了三个月调 Prompt，模型回答质量提升了 20%。然后我花了两周搭 Harness，整体任务完成率从 35% 飙到了 82%。” 这条动态下面，点赞最高的评论只有四个字：方向错了。 过去两年，几乎整个行业都在追逐更大的模型、更强的推理能力、更长的上下文窗口。从 GPT 4 到 Claude 3.5，从 Gemini Ultra 到 DeepSeek V3，参数规模一路狂飙，基准测试分数不断刷新。每一次新模型发布，社交媒体上都会涌现一波"AGI 要来了"的狂欢。 但一个令人尴尬的事实是：绝大多数真实业务场景中，用户并没有感受到与基准分数相匹配的能力提升。 为什么？因为大家盯错了地方。 模型就像一颗强大的引擎，但引擎本身不是汽车。一颗裸露的引擎放在地上，它不能载人，不能转向，不能刹车，甚至不能自己启动。你需要底盘、变速箱、方向盘、仪表盘、油路系统……这一整套让引擎"变得有用"的东西，在 AI Agent 的世界里，有一个越来越被重视的名字——Harness。 Agent = Model + Harness。 模型提供智能，Harness 让智能变得有用。 这不是一个新概念，但它正在成为 2026 年 AI 工程领域最核心的共识。本文将从"裸模型的四个硬伤"出发，逐一拆解 Harness 的六大组件——文件系统、Bash + 沙箱、记忆（AGENTS.md）、Web Search + MCP、上下文工程、编排 + Hooks——带你看清 AI Agent 真正的竞争壁垒，不在模型层，而在 Harness 层。 读完这篇文章，你将重新理解一件事：你写的每一行 System Prompt、搭的每一个工具链、设计的每一套编排逻辑，都是在构建 Harness。 如果你不是模型本身，那你就是 Harness 的一部分。 01 Agent = Model + Harness：一个被忽视太久的公式 在正式拆解 Harness 之前，我们需要先厘清一个最基础的认知框架。 1.1 什么是 Agent？ 1.1 什么是 Agent？ "Agent"这个词在 2024 年被用滥了。每一个能调用 API 的聊天机器人都自称 Agent，每一个加了 RAG 的问答系统都宣称自己是 Agent。但如果我们回到最朴素的定义—— Agent 是一个能够自主感知环境、做出决策、执行行动并从结果中学习的智能体。 注意这里的四个关键动词：感知、决策、执行、学习。裸模型能做到哪个？严格来说，它只能做"决策"这一步——给定输入，产出输出。它不能主动感知外部世界（没有眼睛和耳朵），不能真正执行行动（没有手和脚），更不能持久化地学习（没有长期记忆）。 所以，一个真正的 Agent 必须是这样的结构： Agent = Model + Harness Model 是大脑，负责"想"。Harness 是大脑之外的一切——感官系统、运动系统、记忆系统、能量系统——负责让"想"变成"做"。 1.2 Harness 到底是什么？ 1.2 Harness 到底是什么？ Harness 这个词的英文原意是"挽具"，就是套在马身上、让马的力量转化为拉车动力的那套装备。类比非常精准：模型是马，Harness 是挽具，Agent 是马+挽具+车的整体系统。 更技术化地说，Harness 是模型之外的一切工程基础设施。它包括但不限于： • 模型如何接收输入（上下文构建） • 模型的输出如何被解析和执行（工具调用、代码执行） • 模型如何获取外部信息（搜索、API） • 模型如何记住之前发生的事（记忆机制） • 模型如何与其他模型或子系统协作（编排） • 以及贯穿所有环节的安全、格式、质量约束（Hooks） Harness 不是一个单一的组件，而是一个系统。这也是为什么搭建一个真正好用的 Agent 如此之难——你不是在调一个参数，你是在设计一整套工程架构。 下面这张架构图展示了 Model 与 Harness 的关系，以及 Harness 内部六大组件的整体布局： 这张图传达了三个关键信息：第一，Model 处于中心，但它被 Harness 包围和支撑；第二，六大组件各司其职，但彼此协同；第三，System Prompt 贯穿所有组件，它是 Harness 的"神经系统"。 02 裸模型的四个硬伤：为什么光有聪明的大脑远远不够 要理解 Harness 的价值，我们必须先直面一个残酷的现实：裸模型（Raw Model）有四个致命的硬伤。 所谓"裸模型"，就是没有任何外部工具、没有文件系统、没有搜索能力、没有持久化记忆的纯粹大语言模型。你可以把它想象成一个被关在密闭房间里的天才——智商极高，但看不见外面的世界，记不住昨天的对话，说了话也没人去执行。 2.1 硬伤一：无法维持跨会话状态 2.1 硬伤一：无法维持跨会话状态 这是最容易被感知的痛点。你跟一个裸模型聊了两个小时，讨论了一个复杂的系统架构，画了流程图，定了技术方案。然后你关掉窗口，第二天回来——它什么都不记得了。 这不是"记忆力差"的问题，这是根本没有记忆机制的问题。裸模型的每一次对话都是一个全新的开始，前一轮的所有上下文在会话结束的瞬间灰飞烟灭。 对于简单的问答场景，这无所谓。但对于任何需要持续推进的工作——写一本书、开发一个项目、管理一个流程——这个硬伤是致命的。你需要每次都从头解释背景，每次都重新建立共识，每次都把之前的结论手动灌进去。这不是在用 AI 协作，这是在训练一个每天都失忆的实习生。 2.2 硬伤二：无法执行代码 2.2 硬伤二：无法执行代码 裸模型可以"写"代码，但它不能"跑"代码。它可以生成一段 Python 脚本，但它无法验证这段代码是否能正确运行。它可以告诉你算法的时间复杂度，但它不能在真实数据集上跑一遍来证明自己的分析。 这意味着什么？意味着裸模型的代码输出没有自我验证能力。它可能写出语法正确但逻辑错误的代码，可能忽略边界条件，可能对库的版本做出错误假设。而这一切错误，只有在人类手动复制粘贴到本地环境运行之后才会暴露。 更深层的问题是：没有代码执行能力，模型就失去了"写→跑→看→修→再来"的自我验证循环。而这个循环恰恰是优秀程序员最核心的工作方式。一个不能运行自己代码的 AI 编程助手，就像一个只能在纸上画图纸但从来不去工地的建筑师——理论上无懈可击，实践中漏洞百出。 2.3 硬伤三：无法获取实时知识 2.3 硬伤三：无法获取实时知识 大语言模型的知识有一个"截止日期"。截止日期之后发生的一切——新发布的 API 文档、最新的安全漏洞、上周刚更新的框架版本、今天的新闻——它统统不知道。 在技术领域，这个问题尤其严重。前端框架半年一个大版本，云服务商每季度更新一次产品线，开源库的 Breaking Change 防不胜防。你问裸模型"React 19 的 use() Hook 怎么用"，它可能给你一个基于 React 18 的回答，甚至虚构一个根本不存在的 API。 这就是所谓的"幻觉"（Hallucination）的一个重要来源：不是模型"故意"胡说，而是它的知识库里根本没有正确答案，于是它基于过时信息或模式匹配"推理"出了一个看起来合理但实际上错误的答案。 2.4 硬伤四：无法搭建工作环境 2.4 硬伤四：无法搭建工作环境 裸模型没 有文件系统，没有工作空间，没有项目目录。它不能创建文件，不能组织代码结构，不能管理依赖，不能运行构建工具。 这意味着它无法完成任何"工程级"的任务。写一个单独的函数？可以。搭建一个完整的项目脚手架、配置 CI/CD 流水线、管理多个微服务之间的依赖关系？不可能。 工程不是写代码，工程是在正确的位置写正确的代码，并确保它与其他代码正确协作。没有工作环境，"工程"就无从谈起。 2.5 四个硬伤的本质 2.5 四个硬伤的本质 如果你仔细看这四个硬伤，会发现它们恰好对应了一个完整智能体所需的四种基础能力： 硬伤 缺失的能力 Harness 的对应组件 无法维持跨会话状态 长期记忆 文件系统 + 记忆（AGENTS.md） 无法执行代码 行动能力 Bash + 沙箱 无法获取实时知识 感知能力 Web Search + MCP 无法搭建工作环境 环境操控 文件系统 + 上下文工程 + 编排 硬伤 硬伤 缺失的能力 缺失的能力 Harness 的对应组件 Harness 的对应组件 无法维持跨会话状态 无法维持跨会话状态 长期记忆 长期记忆 文件系统 + 记忆（AGENTS.md） 文件系统 + 记忆（AGENTS.md） 无法执行代码 无法执行代码 行动能力 行动能力 Bash + 沙箱 Bash + 沙箱 无法获取实时知识 无法获取实时知识 感知能力 感知能力 Web Search + MCP Web Search + MCP 无法搭建工作环境 无法搭建工作环境 环境操控 环境操控 文件系统 + 上下文工程 + 编排 文件系统 + 上下文工程 + 编排 每一个"不能"，都是 Harness 里的一个组件。 Harness 不是锦上添花，它是对裸模型致命缺陷的系统性补救。没有 Harness 的 Model，就像没有身体的大脑——它可以思考，但无法存在于这个世界。 03 组件一：文件系统——最基础的原语 在 Harness 的六大组件中，文件系统排在第一位，不是因为它最炫酷，恰恰相反——它最朴素，也最基础。基础到很多人压根没意识到它是一个"组件"。 但正是这个最朴素的组件，决定了 Agent 能力的上限。 3.1 为什么文件系统是"最基础原语"？ 3.1 为什么文件系统是"最基础原语"？ 想一想人类程序员是怎么工作的。打开电脑，第一件事是什么？打开 IDE，加载项目目录。所有的代码文件、配置文件、文档、测试用例、构建脚本……都以文件的形式存在于一个结构化的目录树中。 文件系统是一切工程活动的地基。没有文件系统： • 代码无处存放 • 中间结果无法持久化 • 多步骤任务无法衔接 • 多 Agent 之间无法协作 对于 AI Agent 来说，文件系统的意义甚至比对人类更大。因为人类有大脑记忆，可以"记住"一些中间状态。但 Agent 的上下文窗口是有限的——即使是 200K token 的上下文，对于一个真实项目来说也远远不够。文件系统就是 Agent 的"外部大脑"，是它突破上下文窗口限制的唯一途径。 3.2 文件系统的三大核心能力 3.2 文件系统的三大核心能力 第一，工作空间与中间结果存储。 Agent 在执行复杂任务时，会产生大量的中间产物——分析报告的草稿、代码的半成品、数据处理的中间结果、与用户确认的决策记录。这些中间产物需要一个地方存放，以便后续步骤引用。 没有文件系统，Agent 必须把所有中间产物都塞进上下文窗口——这既浪费 token，又容易超出上下文长度限制。有了文件系统，Agent 可以把中间产物写入文件，需要时再读取，实现"按需加载"。 第二，Agent 协作的基础。 当一个任务复杂到需要多个 Agent 协同工作时，文件系统就成了它们之间的"共享白板"。Agent A 把分析结果写入文件，Agent B 读取文件并在此基础上继续工作。这种基于文件的异步协作模式，简单、可靠、可追溯。 第三，版本追踪与错误回滚。 这一点经常被忽略，但它可能是文件系统最有价值的能力之一。当文件系统与 Git 集成后，Agent 的每一步操作都可以被记录、追溯、回滚。 为什么这很重要？因为 Agent 会犯错。它可能在重构代码时引入 Bug，可能在修改配置时破坏了系统。如果没有版本追踪，错误就像雪球一样越滚越大，直到系统彻底崩溃。有了 Git，Agent（或者监督它的人类）可以随时回到之前的"安全状态"，甚至可以开分支做实验——失败了就丢弃分支，成功了就合并。 以下是文件系统在 Agent 工作流中的角色示意： 这里有一个关键洞察：文件系统 + Git 给了 Agent "试错"的能力。 没有这个能力，Agent 只能小心翼翼地一步步走，不敢冒险。有了这个能力，Agent 可以大胆尝试——反正随时可以回滚。这极大地释放了模型的创造力。 3.3 文件系统的设计原则 3.3 文件系统的设计原则 在实际工程中，为 Agent 设计文件系统需要注意几个原则： 目录结构要清晰且约定俗成。 Agent 不擅长处理混乱的文件组织。使用标准化的目录结构（如前端项目的 src/components、src/utils 约定）能显著降低 Agent 的认知负担。 文件粒度要适中。 太大的文件（几千行代码）会超出 Agent 的处理能力；太小的文件（每个函数一个文件）会增加文件管理的复杂度。一般来说，一个文件对应一个"模块"或"职责单元"是比较好的粒度。 元数据要丰富。 文件名要有意义，目录要有 README，关键决策要有 ADR（Architecture Decision Records）。这些元数据是 Agent 理解"为什么这样组织"的线索。 04 组件二：Bash + 沙箱——让 Agent 从"说"到"做" 如果说文件系统给了 Agent 一个"工作台"，那么 Bash + 沙箱就给了它一双"手"。 4.1 从"生成代码"到"执行代码"的质变 4.1 从"生成代码"到"执行代码"的质变 裸模型只能生成代码文本。但文本不是程序——程序是被执行的文本。在"生成"和"执行"之间，存在一条巨大的鸿沟。 一个终端（Bash）环境意味着 Agent 可以： • 运行它自己写的代码 • 安装依赖包 • 执行构建命令 • 运行测试套件 • 查看运行时错误并调试 这从根本上改变了 Agent 的工作模式。没有 Bash，Agent 是一个"提建议"的顾问；有了 Bash，Agent 是一个"动手做"的工程师。 4.2 自我验证循环：写→跑→看→修→再来 4.2 自我验证循环：写→跑→看→修→再来 这是 Bash 赋予 Agent 的最核心能力——自我验证循环。 这个循环看起来简单，但它的意义是革命性的。没有这个循环，Agent 的输出质量完全依赖于模型的"一次性生成"能力——模型推理正确就对了，推理错误就全错。有了这个循环，Agent 拥有了自我纠错能力，它可以从自己的错误中学习（至少在单次会话内）。 实际测试数据表明：在编程任务中，具备自我验证循环的 Agent 的任务完成率比"一次性生成"的方式高出 40%–60%。这个差距不是来自更好的模型，而完全来自 Harness 层的 Bash 能力。 4.3 为什么必须是"沙箱"？ 4.3 为什么必须是"沙箱"？ 有了 Bash 就够了吗？不，还需要安全隔离。 Agent 执行的代码不一定是安全的。它可能无意中执行了 rm rf / ，可能下载了恶意包，可能发起了未授权的网络请求。如果 Agent 的代码执行环境是宿主机本身，后果不堪设想。 沙箱（Sandbox）提供了一个隔离的执行环境： 资源限制： CPU、内存、磁盘空间都有上限，防止死循环或内存泄漏拖垮系统。 网络隔离： 默认禁止外部网络访问，或只允许白名单内的地址，防止数据泄露或恶意攻击。 文件系统隔离： Agent 只能访问自己的工作目录，不能接触宿主机的敏感文件。 超时机制： 执行时间超过阈值自动终止，防止资源被长期占用。 沙箱不是一个可选的"安全加固措施"，它是 Bash 能力的必要前提。没有沙箱，你不敢让 Agent 执行代码；不敢让 Agent 执行代码，Agent 就失去了自我验证能力；失去了自我验证能力，Agent 的输出质量就会大打折扣。 4.4 沙箱技术的选择 4.4 沙箱技术的选择 在工程实践中，常见的沙箱方案包括： Docker 容器： 最主流的方案，隔离性好，生态成熟，镜像管理方便。大多数 Agent 框架（如 Devin、OpenHands）都采用 Docker 作为沙箱。 gVisor / Firecracker： 更轻量的虚拟化方案，启动速度快（毫秒级），适合需要频繁创建/销毁沙箱的场景。 WebAssembly（WASM）： 在浏览器端或边缘计算场景中有潜力，但目前对系统调用的支持还不够完善。 Nix / 纯函数式环境： 通过声明式的环境定义，确保每次执行的环境完全一致，杜绝"在我机器上能跑"的问题。 选择哪种方案取决于 你的具体需求，但核心原则只有一条：在保证安全的前提下，给 Agent 尽可能大的自由度。 05 组件三：记忆（AGENTS.md）——不改权重也能给模型加知识 这是 Harness 六大组件中最容易被低估，但可能最具长期价值的一个。 5.1 模型的"失忆症" 5.1 模型的"失忆症" 我们在前文讨论过，裸模型无法维持跨会话状态。每次对话结束，所有的上下文都会消失。但在真实的工作场景中，Agent 需要"记住"大量信息： • 项目的技术栈和架构决策 • 用户的偏好和工作习惯 • 之前犯过的错误和学到的教训 • 团队的编码规范和设计模式 • 业务领域的专有知识 传统的做法是把这些信息写进 System Prompt——但 System Prompt 的长度是有限的，塞太多信息会稀释重要指令的权重，甚至导致模型"注意力分散"。 AGENTS.md 提供了一个优雅的解决方案：把知识写入文件，在需要时自动注入上下文。 5.2 AGENTS.md 的工作机制 5.2 AGENTS.md 的工作机制 AGENTS.md 的设计理念可以用一句话概括：工作中写入知识，存文件，下次自动注入。 具体来说： 写入阶段： 当 Agent 在工作过程中产生了有价值的知识（比如发现某个 API 有一个未文档化的限制，或者确定了某种架构方案的优劣），它会把这些知识以结构化的方式写入 AGENTS.md 文件。 存储阶段： AGENTS.md 文件存放在项目的文件系统中，通常是根目录或各子目录下。它本质上就是一个 Markdown 文件，人类可以直接阅读和编辑。 注入阶段： 下一次 Agent 启动或切换到新的工作上下文时，Harness 会自动读取相关的 AGENTS.md 文件，并将其内容注入到 Agent 的上下文中。 5.3 "上下文注入 = 不改权重给模型加知识" 5.3 "上下文注入 = 不改权重给模型加知识" 这个等式是 AGENTS.md 最深刻的洞察。 传统上，要给模型"加知识"，你需要微调（Fine tuning）——修改模型的权重参数。这个过程成本高、周期长、且存在灾难性遗忘的风险。 AGENTS.md 提供了一条捷径：不碰模型权重，只通过上下文注入来添加知识。 模型仍然是原来的模型，但它"看到"的信息变了，因此它的行为也变了。 这就像是一种"即插即用"的知识扩展机制——今天你发现了一个新的最佳实践，写进 AGENTS.md，明天 Agent 就自动具备了这个知识。不需要重新训练，不需要等模型供应商更新，不需要任何机器学习的专业知识。 这也解释了为什么 AGENTS.md 被称为"记忆"组件——它让 Agent 拥有了跨会话的长期记忆，而且这种记忆是透明的（人类可以阅读和编辑）、可控的（可以随时增删改）、可审计的（配合 Git 可以追溯每一次知识变更）。 5.4 AGENTS.md 的最佳实践 5.4 AGENTS.md 的最佳实践 在实际项目中，AGENTS.md 的组织方式通常遵循以下原则： 层次化存放。 根目录的 AGENTS.md 存放全局知识（项目概述、核心架构决策、团队规范）；子目录的 AGENTS.md 存放局部知识（该模块的特殊约定、已知问题、接口规范）。Agent 在进入某个目录工作时，会同时加载全局和局部的知识。 结构化书写。 好的 AGENTS.md 不是随意的笔记，而是有明确结构的知识库。常见的分类包括：项目架构、技术约束、编码规范、已知陷阱（Gotchas）、决策记录（ADR）等。 定期清理。 过时的知识比没有知识更危险。随着项目演进，某些早期的约束可能已经不再适用，某些技术决策可能已经被推翻。定期审查和清理 AGENTS.md 是保持其有效性的关键。 双向可编辑。 AGENTS.md 不仅是 Agent 写给自己的备忘录，也是人类与 Agent 之间的"知识契约"。人类可以直接编辑 AGENTS.md 来向 Agent 传达偏好（"我不喜欢使用三元表达式"）、约束（"所有 API 必须使用 REST 风格"）、甚至个人工作习惯（"代码审查时请重点关注错误处理"）。 06 组 件四：Web Search + MCP——突破知识的"时间牢笼" 裸模型的第三个硬伤是"无法获取实时知识"。Web Search + MCP 就是针对这个硬伤的解药。 6.1 AGENTS.md 的最佳实践 6.1 AGENTS.md 的最佳实践 每个大语言模型都有一个知识截止日期。这个日期之后的世界，对模型来说是一片空白。 这在日常闲聊中可能无伤大