一文讲透如何构建Harness——六大组件全解析AI Agent 系统Hooks 是一种事件驱动的扩展机制作为 Agent 运行循环中的“拦截点”允许在会话启停、模型调用前后、工具执行前后等关键节点插入自定义逻辑用于实现安全控制、输入预处理、运行监控及结果验证。裸模型有四大硬伤无记忆、不能执行代码、知识过时、无工作环境。Harness 六大组件逐一补救——文件系统管存储与版本沙箱赋予代码自验证AGENTS.md 无需训练即可注入知识Web SearchMCP 打破知识截止上下文工程对抗信息腐烂编排Hooks 保障多 Agent 协同质量。System Prompt 贯穿始终是整套系统的神经中枢。一句话摘要 模型提供智能Harness 让智能变得有用。如果你不是模型本身那你就是 Harness 的一部分。硬伤缺失的能力Harness 的对应组件无法维持跨会话状态长期记忆文件系统 记忆AGENTS.md无法执行代码行动能力Bash 沙箱无法获取实时知识感知能力Web Search MCP无法搭建工作环境环境操控文件系统 上下文工程 编排03 组件一文件系统——最基础的原语当文件系统与 Git 集成后Agent 的每一步操作都可以被记录、追溯、回滚。文件系统 Git 给了 Agent 试错的能力。04 组件二Bash 沙箱——让 Agent 从说到做一个终端Bash环境意味着 Agent 可以运行它自己写的代码安装依赖包执行构建命令运行测试套件查看运行时错误并调试这从根本上改变了 Agent 的工作模式。没有 BashAgent 是一个提建议的顾问有了 BashAgent 是一个动手做的工程师。4.2 自我验证循环写→跑→看→修→再来4.3 为什么必须是沙箱有了 Bash 就够了吗不还需要安全隔离。沙箱Sandbox提供了一个隔离的执行环境资源限制 CPU、内存、磁盘空间都有上限防止死循环或内存泄漏拖垮系统。网络隔离 默认禁止外部网络访问或只允许白名单内的地址防止数据泄露或恶意攻击。文件系统隔离 Agent 只能访问自己的工作目录不能接触宿主机的敏感文件。超时机制 执行时间超过阈值自动终止防止资源被长期占用。4.4 沙箱技术的选择在工程实践中常见的沙箱方案包括Docker 容器 最主流的方案隔离性好生态成熟镜像管理方便。大多数 Agent 框架如 Devin、OpenHands都采用 Docker 作为沙箱。gVisor / Firecracker 更轻量的虚拟化方案启动速度快毫秒级适合需要频繁创建/销毁沙箱的场景。WebAssemblyWASM 在浏览器端或边缘计算场景中有潜力但目前对系统调用的支持还不够完善。Nix / 纯函数式环境 通过声明式的环境定义确保每次执行的环境完全一致杜绝在我机器上能跑的问题。选择哪种方案取决于你的具体需求但核心原则只有一条在保证安全的前提下给 Agent 尽可能大的自由度。05 组件三记忆AGENTS.md——不改权重也能给模型加知识但在真实的工作场景中Agent 需要记住大量信息项目的技术栈和架构决策用户的偏好和工作习惯之前犯过的错误和学到的教训团队的编码规范和设计模式业务领域的专有知识AGENTS.md 提供了一个优雅的解决方案把知识写入文件在需要时自动注入上下文。5.2 AGENTS.md 的工作机制AGENTS.md 的设计理念可以用一句话概括工作中写入知识存文件下次自动注入。具体来说写入阶段 当 Agent 在工作过程中产生了有价值的知识比如发现某个 API 有一个未文档化的限制或者确定了某种架构方案的优劣它会把这些知识以结构化的方式写入 AGENTS.md 文件。存储阶段 AGENTS.md 文件存放在项目的文件系统中通常是根目录或各子目录下。它本质上就是一个 Markdown 文件人类可以直接阅读和编辑。注入阶段 下一次 Agent 启动或切换到新的工作上下文时Harness 会自动读取相关的 AGENTS.md 文件并将其内容注入到 Agent 的上下文中。它让 Agent 拥有了跨会话的长期记忆而且这种记忆是透明的人类可以阅读和编辑、可控的可以随时增删改、可审计的配合 Git 可以追溯每一次知识变更。5.4 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——突破知识的时间牢笼07 组件五上下文工程——对抗 AI 系统的熵增7.2 上下文工程的核心策略对抗 Context Rot 的技术手段统称为上下文工程Context Engineering它包含以下几个关键策略压缩Compression。 定期对历史上下文进行摘要压缩。把冗长的工具调用记录替换为简洁的结果摘要把详细的讨论过程替换为最终结论。这就像是给上下文做垃圾回收。工具输出卸载Tool Output Offloading。 工具调用的输出特别是大段的代码、日志、搜索结果是上下文膨胀的主要来源。上下文工程会把这些输出存储到文件系统中在上下文中只保留摘要和文件引用。需要详细信息时Agent 可以随时重新读取文件。Skills 渐进加载。 不同的任务阶段需要不同的知识和能力。上下文工程会根据当前任务阶段动态加载和卸载相关的 Skill 定义。例如在需求分析阶段加载产品相关知识在编码阶段加载技术栈相关知识避免一次性把所有信息都塞进上下文。分层上下文结构。 把上下文分为核心层System Prompt、关键约束始终保留、工作层当前任务相关信息按需更新、历史层已完成任务的摘要逐渐压缩。不同层的信息有不同的生命周期和更新策略。08 组件六编排 Hooks——让单兵作战变成集团军最后一个组件是编排Orchestration Hooks。8.1 为什么需要编排当任务复杂度超过单个 Agent 的处理能力时你需要把任务分解为多个子任务分配给不同的子 Agent处理然后把结果汇总。这就是编排。编排解决的核心问题包括子 Agent 调度。 哪个子任务应该分配给哪个 Agent它们之间的依赖关系是什么哪些可以并行哪些必须串行任务分发。 如何把一个模糊的大任务拆解为明确的小任务如何确保每个子 Agent 得到足够的上下文来完成它的子任务模型路由。 不是所有的子任务都需要最强也最贵的模型。简单的格式转换可以用小模型复杂的架构设计需要大模型。编排器需要根据任务复杂度选择合适的模型在成本和质量之间取得平衡。结果聚合。 当多个子 Agent 返回结果后如何检查一致性、解决冲突、合并为最终输出8.2 Hooks注入确定性在 Agent Harness 中Hooks 的作用类似——在 Agent 行为的关键节点插入确定性检查确保输出符合预期。Hooks 的典型应用场景包括Lint 检查。 Agent 生成代码后自动运行 linter 检查语法和风格是否符合项目规范。不符合的话自动要求 Agent 修复。续接Continuation。 当 Agent 的单次输出因为 token 限制被截断时Hook 自动检测截断并触发续接请求确保输出的完整性。格式约束。 确保 Agent 的输出符合特定的格式要求——JSON Schema 验证、Markdown 结构检查、API 响应格式校验等。安全过滤。 在 Agent 执行敏感操作如文件删除、数据库写入、外部 API 调用前Hook 进行权限检查和安全审计。成本控制。 监控 token 消耗和 API 调用频率在接近预算上限时发出警告或限制。09 System Prompt贯穿所有组件的神经系统它在 Harness 架构中扮演着四个关键角色定义角色边界注入领域知识约束安全规则贯穿所有组件--------------------------------------------------------------------------------------------------------Harness 架构本质上是Agent Model Harness这一工程范式的具体落地模型提供推理能力Harness 提供运行环境、约束、工具、记忆、编排和观测让模型从“会回答”变成“能稳定执行任务”。它通常可以拆成下面几块。1. 上下文管理层负责决定模型在这一轮能看到什么信息。包括动态组装上下文把相关文件、历史决策、工具返回结果按需注入上下文压缩对话过长时自动摘要早期内容Token 预算控制控制 system prompt、工具描述、历史消息、检索内容的占比结构化切片把大文档切成可检索的语义块按需加载。2. 工具与执行层负责把模型输出的文本动作变成真实执行。包括工具注册与描述工具名、参数 schema、使用边界工具执行器调用 API、执行代码、读写文件、查询数据库沙箱隔离限制文件系统、网络、权限避免危险操作结构化返回把成功、失败、重试信息标准化地回传给模型。3. 编排与规划层负责把复杂目标拆成可执行的步骤序列。包括ReAct 循环思考 → 行动 → 观察 → 再思考Plan-and-Execute先生成计划再逐步执行必要时重规划多 Agent 协作规划、生成、评估等角色分工任务图调度把任务拆成有依赖关系的执行图。4. 记忆与状态层负责让 Agent 记住自己是谁、做过什么、当前进度到哪里。包括工作记忆当前任务进度、中间变量、执行到哪一步会话记忆本轮对话历史、用户偏好、已确认决策长期记忆经验、文档、历史案例、项目规范状态持久化任务中断后可恢复避免每次重头开始。5. 评估与观测层负责知道 Agent 在干什么、干得好不好、哪里失败。包括调用链路追踪记录每次模型调用、工具调用、返回结果成本与 Token 统计追踪每次任务的消耗质量评估自动检查输出是否满足约束、是否通过测试审计日志保留关键决策、工具调用和人工介入记录。6. 安全与护栏层负责给模型设定不可越界的边界。包括输入过滤检测提示注入、敏感内容输出校验检查格式、权限、合规性权限控制限制可访问的数据和可执行的操作人工介入点在关键决策前强制 Human-in-the-Loop。7. 接入与接口层负责和用户、业务系统、其他服务对接。包括API 网关或 SDK 入口身份认证与权限校验协议转换任务提交、状态查询、结果回调。8. 约束、校验与恢复层负责兜底避免错误扩散。包括执行超时控制失败重试策略幂等处理避免重复执行写操作错误恢复捕获异常后回退到安全状态结果校验对关键输出做二次验证。横切能力除了分层组件Harness 通常还有两个贯穿所有层的能力安全与沙箱隔离执行环境防止越权、误删、泄露治理与持续演进管理模型版本、工具版本、策略变更、审计合规。可以用一句话概括模型决定 Agent 的智力上限Harness 决定它的稳定下限。你是在做选型还是想自己搭一套类似的框架告诉我场景我可以帮你梳理对应的落地方案和工具链。------------------------------------------------------------------参考harness工程二六层架构详解-腾讯云开发者社区-腾讯云 
长河君 · 2026/10/10 2:36:03 · 阅读 1.2k Harness学习
一文讲透如何构建Harness——六大组件全解析AI Agent 系统Hooks 是一种事件驱动的扩展机制作为 Agent 运行循环中的“拦截点”允许在会话启停、模型调用前后、工具执行前后等关键节点插入自定义逻辑用于实现安全控制、输入预处理、运行监控及结果验证。裸模型有四大硬伤无记忆、不能执行代码、知识过时、无工作环境。Harness 六大组件逐一补救——文件系统管存储与版本沙箱赋予代码自验证AGENTS.md 无需训练即可注入知识Web SearchMCP 打破知识截止上下文工程对抗信息腐烂编排Hooks 保障多 Agent 协同质量。System Prompt 贯穿始终是整套系统的神经中枢。一句话摘要 模型提供智能Harness 让智能变得有用。如果你不是模型本身那你就是 Harness 的一部分。硬伤缺失的能力Harness 的对应组件无法维持跨会话状态长期记忆文件系统 记忆AGENTS.md无法执行代码行动能力Bash 沙箱无法获取实时知识感知能力Web Search MCP无法搭建工作环境环境操控文件系统 上下文工程 编排03 组件一文件系统——最基础的原语当文件系统与 Git 集成后Agent 的每一步操作都可以被记录、追溯、回滚。文件系统 Git 给了 Agent 试错的能力。04 组件二Bash 沙箱——让 Agent 从说到做一个终端Bash环境意味着 Agent 可以运行它自己写的代码安装依赖包执行构建命令运行测试套件查看运行时错误并调试这从根本上改变了 Agent 的工作模式。没有 BashAgent 是一个提建议的顾问有了 BashAgent 是一个动手做的工程师。4.2 自我验证循环写→跑→看→修→再来4.3 为什么必须是沙箱有了 Bash 就够了吗不还需要安全隔离。沙箱Sandbox提供了一个隔离的执行环境资源限制 CPU、内存、磁盘空间都有上限防止死循环或内存泄漏拖垮系统。网络隔离 默认禁止外部网络访问或只允许白名单内的地址防止数据泄露或恶意攻击。文件系统隔离 Agent 只能访问自己的工作目录不能接触宿主机的敏感文件。超时机制 执行时间超过阈值自动终止防止资源被长期占用。4.4 沙箱技术的选择在工程实践中常见的沙箱方案包括Docker 容器 最主流的方案隔离性好生态成熟镜像管理方便。大多数 Agent 框架如 Devin、OpenHands都采用 Docker 作为沙箱。gVisor / Firecracker 更轻量的虚拟化方案启动速度快毫秒级适合需要频繁创建/销毁沙箱的场景。WebAssemblyWASM 在浏览器端或边缘计算场景中有潜力但目前对系统调用的支持还不够完善。Nix / 纯函数式环境 通过声明式的环境定义确保每次执行的环境完全一致杜绝在我机器上能跑的问题。选择哪种方案取决于你的具体需求但核心原则只有一条在保证安全的前提下给 Agent 尽可能大的自由度。05 组件三记忆AGENTS.md——不改权重也能给模型加知识但在真实的工作场景中Agent 需要记住大量信息项目的技术栈和架构决策用户的偏好和工作习惯之前犯过的错误和学到的教训团队的编码规范和设计模式业务领域的专有知识AGENTS.md 提供了一个优雅的解决方案把知识写入文件在需要时自动注入上下文。5.2 AGENTS.md 的工作机制AGENTS.md 的设计理念可以用一句话概括工作中写入知识存文件下次自动注入。具体来说写入阶段 当 Agent 在工作过程中产生了有价值的知识比如发现某个 API 有一个未文档化的限制或者确定了某种架构方案的优劣它会把这些知识以结构化的方式写入 AGENTS.md 文件。存储阶段 AGENTS.md 文件存放在项目的文件系统中通常是根目录或各子目录下。它本质上就是一个 Markdown 文件人类可以直接阅读和编辑。注入阶段 下一次 Agent 启动或切换到新的工作上下文时Harness 会自动读取相关的 AGENTS.md 文件并将其内容注入到 Agent 的上下文中。它让 Agent 拥有了跨会话的长期记忆而且这种记忆是透明的人类可以阅读和编辑、可控的可以随时增删改、可审计的配合 Git 可以追溯每一次知识变更。5.4 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——突破知识的时间牢笼07 组件五上下文工程——对抗 AI 系统的熵增7.2 上下文工程的核心策略对抗 Context Rot 的技术手段统称为上下文工程Context Engineering它包含以下几个关键策略压缩Compression。 定期对历史上下文进行摘要压缩。把冗长的工具调用记录替换为简洁的结果摘要把详细的讨论过程替换为最终结论。这就像是给上下文做垃圾回收。工具输出卸载Tool Output Offloading。 工具调用的输出特别是大段的代码、日志、搜索结果是上下文膨胀的主要来源。上下文工程会把这些输出存储到文件系统中在上下文中只保留摘要和文件引用。需要详细信息时Agent 可以随时重新读取文件。Skills 渐进加载。 不同的任务阶段需要不同的知识和能力。上下文工程会根据当前任务阶段动态加载和卸载相关的 Skill 定义。例如在需求分析阶段加载产品相关知识在编码阶段加载技术栈相关知识避免一次性把所有信息都塞进上下文。分层上下文结构。 把上下文分为核心层System Prompt、关键约束始终保留、工作层当前任务相关信息按需更新、历史层已完成任务的摘要逐渐压缩。不同层的信息有不同的生命周期和更新策略。08 组件六编排 Hooks——让单兵作战变成集团军最后一个组件是编排Orchestration Hooks。8.1 为什么需要编排当任务复杂度超过单个 Agent 的处理能力时你需要把任务分解为多个子任务分配给不同的子 Agent处理然后把结果汇总。这就是编排。编排解决的核心问题包括子 Agent 调度。 哪个子任务应该分配给哪个 Agent它们之间的依赖关系是什么哪些可以并行哪些必须串行任务分发。 如何把一个模糊的大任务拆解为明确的小任务如何确保每个子 Agent 得到足够的上下文来完成它的子任务模型路由。 不是所有的子任务都需要最强也最贵的模型。简单的格式转换可以用小模型复杂的架构设计需要大模型。编排器需要根据任务复杂度选择合适的模型在成本和质量之间取得平衡。结果聚合。 当多个子 Agent 返回结果后如何检查一致性、解决冲突、合并为最终输出8.2 Hooks注入确定性在 Agent Harness 中Hooks 的作用类似——在 Agent 行为的关键节点插入确定性检查确保输出符合预期。Hooks 的典型应用场景包括Lint 检查。 Agent 生成代码后自动运行 linter 检查语法和风格是否符合项目规范。不符合的话自动要求 Agent 修复。续接Continuation。 当 Agent 的单次输出因为 token 限制被截断时Hook 自动检测截断并触发续接请求确保输出的完整性。格式约束。 确保 Agent 的输出符合特定的格式要求——JSON Schema 验证、Markdown 结构检查、API 响应格式校验等。安全过滤。 在 Agent 执行敏感操作如文件删除、数据库写入、外部 API 调用前Hook 进行权限检查和安全审计。成本控制。 监控 token 消耗和 API 调用频率在接近预算上限时发出警告或限制。09 System Prompt贯穿所有组件的神经系统它在 Harness 架构中扮演着四个关键角色定义角色边界注入领域知识约束安全规则贯穿所有组件--------------------------------------------------------------------------------------------------------Harness 架构本质上是Agent Model Harness这一工程范式的具体落地模型提供推理能力Harness 提供运行环境、约束、工具、记忆、编排和观测让模型从“会回答”变成“能稳定执行任务”。它通常可以拆成下面几块。1. 上下文管理层负责决定模型在这一轮能看到什么信息。包括动态组装上下文把相关文件、历史决策、工具返回结果按需注入上下文压缩对话过长时自动摘要早期内容Token 预算控制控制 system prompt、工具描述、历史消息、检索内容的占比结构化切片把大文档切成可检索的语义块按需加载。2. 工具与执行层负责把模型输出的文本动作变成真实执行。包括工具注册与描述工具名、参数 schema、使用边界工具执行器调用 API、执行代码、读写文件、查询数据库沙箱隔离限制文件系统、网络、权限避免危险操作结构化返回把成功、失败、重试信息标准化地回传给模型。3. 编排与规划层负责把复杂目标拆成可执行的步骤序列。包括ReAct 循环思考 → 行动 → 观察 → 再思考Plan-and-Execute先生成计划再逐步执行必要时重规划多 Agent 协作规划、生成、评估等角色分工任务图调度把任务拆成有依赖关系的执行图。4. 记忆与状态层负责让 Agent 记住自己是谁、做过什么、当前进度到哪里。包括工作记忆当前任务进度、中间变量、执行到哪一步会话记忆本轮对话历史、用户偏好、已确认决策长期记忆经验、文档、历史案例、项目规范状态持久化任务中断后可恢复避免每次重头开始。5. 评估与观测层负责知道 Agent 在干什么、干得好不好、哪里失败。包括调用链路追踪记录每次模型调用、工具调用、返回结果成本与 Token 统计追踪每次任务的消耗质量评估自动检查输出是否满足约束、是否通过测试审计日志保留关键决策、工具调用和人工介入记录。6. 安全与护栏层负责给模型设定不可越界的边界。包括输入过滤检测提示注入、敏感内容输出校验检查格式、权限、合规性权限控制限制可访问的数据和可执行的操作人工介入点在关键决策前强制 Human-in-the-Loop。7. 接入与接口层负责和用户、业务系统、其他服务对接。包括API 网关或 SDK 入口身份认证与权限校验协议转换任务提交、状态查询、结果回调。8. 约束、校验与恢复层负责兜底避免错误扩散。包括执行超时控制失败重试策略幂等处理避免重复执行写操作错误恢复捕获异常后回退到安全状态结果校验对关键输出做二次验证。横切能力除了分层组件Harness 通常还有两个贯穿所有层的能力安全与沙箱隔离执行环境防止越权、误删、泄露治理与持续演进管理模型版本、工具版本、策略变更、审计合规。可以用一句话概括模型决定 Agent 的智力上限Harness 决定它的稳定下限。你是在做选型还是想自己搭一套类似的框架告诉我场景我可以帮你梳理对应的落地方案和工具链。------------------------------------------------------------------参考harness工程二六层架构详解-腾讯云开发者社区-腾讯云