一文讲透如何构建 Harness——六大组件全解析
本文是对腾讯云开发者社区文章《一文讲透如何构建 Harness——六大组件全解析》（作者：李伟山）的阅读总结与深度解读。原文详细拆解了 AI Agent 工程中最重要的概念之一——Harness，本文在保留核心观点的同时做了结构化的梳理。
TL;DR
Agent = Model + Harness。模型提供智能，Harness 让智能变得有用。如果你不是模型本身，那你就是 Harness 的一部分。
这句话贯穿了整篇文章的始终。2025 年的一个真实案例：花三个月调 Prompt，任务完成率提升 20%；花两周搭 Harness，完成率飙到 82%。
方向错了——答案不在模型层，在 Harness 层。
裸模型的四个硬伤
在讨论 Harness 之前，先看裸模型（Raw Model）的致命缺陷：
| 硬伤 | 表现 | Harness 对应组件 |
|---|---|---|
| 无跨会话记忆 | 关掉窗口就失忆，每次从头解释 | 文件系统 + AGENTS.md |
| 不能执行代码 | 只能生成代码文本，不能运行验证 | Bash + 沙箱 |
| 知识有截止日期 | 新 API、新框架、新漏洞都不知道 | Web Search + MCP |
| 没有工作环境 | 不能建文件、不能组织项目、不能管理依赖 | 文件系统 + 上下文工程 + 编排 |
每一「不能」，都是 Harness 里的一个组件。Harness 不是锦上添花，是对裸模型致命缺陷的系统性补救。
六大组件逐层拆解
一、文件系统——最基础的原语
文件系统 + Git 给了 Agent「试错」的能力。
文件系统是一切工程活动的地基，也是 Agent 突破上下文窗口限制的唯一途径。
三大核心能力：
- 工作空间与中间结果存储——把中间产物写入文件，需要时再读取，实现按需加载
- Agent 协作的基础——Agent A 写文件，Agent B 读文件，文件就是共享白板
- 版本追踪与错误回滚——结合 Git，Agent 可以大胆尝试，随时回滚
设计原则：
- 目录结构要清晰且约定俗成
- 文件粒度要适中（一个模块一个文件）
- 元数据要丰富（文件名有意义、目录有 README）
二、Bash + 沙箱——从「说」到「做」
没有 Bash，Agent 是一个提建议的顾问；有了 Bash，Agent 是动手做的工程师。
自我验证循环：写 → 跑 → 看 → 修 → 再来
这个循环让 Agent 拥有了自我纠错能力。实测数据显示：具备自我验证循环的 Agent，任务完成率比一次性生成高出 40%–60%——这个差距不来自更好的模型，而完全来自 Harness 层的 Bash。
为什么必须要有沙箱？
- 资源限制（CPU、内存、磁盘上限）
- 网络隔离（默认禁止外部访问）
- 文件系统隔离（只能访问工作目录）
- 超时机制（自动终止长时间执行）
常见的沙箱方案：Docker（最主流）、gVisor/Firecracker（轻量）、WASM（边缘计算）、Nix（确定性环境）。
三、记忆（AGENTS.md）——不改权重给模型加知识
这是六大组件中最容易被低估、但可能最具长期价值的一个。
工作机制：
工作中发现知识 → 写入 AGENTS.md → 下次自动注入上下文
关键洞察：上下文注入 = 不改权重给模型加知识
传统微调成本高、周期长、有灾难性遗忘风险。AGENTS.md 提供了一条捷径——不碰模型权重，只通过上下文注入来添加知识。今天发现的最佳实践，写进 AGENTS.md，明天 Agent 就自动具备了这个知识。
最佳实践：
- 层次化存放——根目录放全局知识，子目录放局部知识
- 结构化书写——不是随意笔记，是有明确结构的知识库
- 定期清理——过时的知识比没有知识更危险
- 双向可编辑——人类可以直接编辑 AGENTS.md 来向 Agent 传达偏好
四、Web Search + MCP——突破知识的「时间牢笼」
Web Search 让 Agent 能「看」互联网，MCP 让 Agent 能「触」互联网。
Web Search 解决的是知识截止日期问题。好的搜索组件不仅要能搜索，还要能构建查询、筛选结果、提取核心内容、整合多源信息。
MCP（Model Context Protocol） 是 Anthropic 推出的开放协议，定义了 AI 模型与外部工具之间的标准化交互方式。可以把 MCP 理解为「AI 世界的数据线」——数据库、Jira、GitHub、监控系统……只要有 MCP 接口，Agent 就能直接访问。
协同效应示例——Debug 生产环境 Bug：
- MCP 连接监控系统 → 获取错误日志
- MCP 连接代码仓库 → 查看相关代码和历史变更
- Web Search 搜索错误信息 → 查找社区解决方案
- MCP 连接项目管理工具 → 检查已知问题
- Agent 综合所有信息 → 生成修复方案并提交 PR
五、上下文工程——对抗 AI 系统的「熵增」
Harness 的本质就是好的上下文工程的交付机制。
Context Rot（上下文腐烂）——长时间运行的 Agent 会话中，大量信息在上下文中积累，导致：
- 信噪比下降，关键指令被稀释
- 矛盾信息累积，输出不一致
- Token 浪费，有效空间被挤压
- 推理质量退化（「大海捞针」问题的实践版）
核心策略：
| 策略 | 做法 |
|---|---|
| 压缩 | 定期摘要历史上下文，将详细过程替换为结论 |
| 工具输出卸载 | 工具输出存文件，上下文中只留摘要和引用 |
| 渐进加载 | 根据当前任务阶段动态加载/卸载知识 |
| 分层结构 | 核心层（始终保留）→ 工作层（按需更新）→ 历史层（逐渐压缩） |
上下文工程在 2025 年底开始取代「Prompt 工程」成为核心话题——Prompt 工程关注「怎么写指令」，上下文工程关注「怎么构建模型看到的全部信息」，后者的范围大得多。
六、编排 + Hooks——让单兵作战变成集团军
前五个组件增强单个 Agent，最后一个组件把多个 Agent 组织成协同作战的系统。
编排解决的核心问题：
- 子 Agent 调度——并行还是串行？依赖关系是什么？
- 任务分发——模糊大任务 → 明确小任务
- 模型路由——简单任务用小模型，复杂任务用大模型
- 结果聚合——检查一致性、解决冲突、合并输出
编排模式的演进：
线性管道 → DAG 编排 → 动态编排 → 层级编排
Hooks——注入确定性： 用确定性的规则约束概率性的模型输出。
典型场景：
- Lint 检查——生成代码后自动运行 Linter
- 续接钩子——输出被截断时自动续接
- 格式约束——JSON Schema 验证、Markdown 结构检查
- 安全过滤——敏感操作前权限检查
- 成本控制——监控 Token 消耗，接近上限时警告
概率性生成 + 确定性校验 = 当前 Agent 工程最有效的质量保障策略。
System Prompt：贯穿所有组件的「神经系统」
System Prompt 不是第七个组件，但它扮演着四个关键角色：
- 定义角色边界——告诉模型「你是谁」和「你不是谁」
- 注入领域知识——零成本知识注入的第一入口
- 约束安全规则——Agent 安全策略的第一道防线
- 贯穿所有组件——间接定义文件组织规范、命令范围、知识格式、搜索标准、压缩策略、任务分解粒度
写 System Prompt 就是在设计 Harness 的行为规范。好的 System Prompt 就像好的公司章程——不直接做任何事，但决定了所有事怎么做。
总结
| 组件 | 一句话概括 |
|---|---|
| 文件系统 | 工程活动的地基，Agent 的外部大脑 |
| Bash + 沙箱 | 从生成到执行，让代码自我验证 |
| AGENTS.md | 不改权重，即插即用的知识注入 |
| Web Search + MCP | 打破知识截止日期，连接外部世界 |
| 上下文工程 | 对抗 Context Rot，管理注意力 |
| 编排 + Hooks | 多 Agent 协同，确定性兜底 |
模型决定了 Agent 能力的下限，Harness 决定了 Agent 能力的上限。
下次调试 Agent 表现时，不要急着换更强的模型——先看看你的 Harness：文件系统完善吗？沙箱安全吗？记忆机制在工作吗？上下文腐烂了吗？编排合理吗？Hooks 在兜底吗？
也许答案就在那里。
原文：一文讲透如何构建 Harness——六大组件全解析 — 腾讯云开发者社区 · 作者：李伟山