Harness AI Agent 教程：从零开始驾驭智能体

先从一个直观的问题切入：你是否好奇，为什么AI对话工具看起来能记住你之前说的内容？多数人误以为AI自带记忆系统，实则恰恰相反——它什么也记不住。

1. 认识 AI 的“瞬时失忆”——为何需要 Harness？

1.1 AI 本质上没有记忆

很多人以为与AI对话时，它会持续记住你讲过的话。但真相是：每次你按下回车键，都会有一个全新的AI实例被唤起。它不认识你，也记不住你们的过往交流。之所以能接上话题，是因为系统把之前的全部对话历史重新塞给它“通读”了一遍。

想象一下这个场景：你在医院就诊，每次进诊室都遇到不同的医生。但每位医生进入前，都会先翻阅你的病历。于是虽然医生换了，但他们看起来都“记得”你的病情。AI正是如此——它本身没有记忆，完全依赖“病历本”（即上下文窗口）来维持对话的连续性。

这种机制在技术上称为模型无状态性。每次API调用都会新建一个AI实例，处理完请求后立即销毁。好比工厂流水线上的临时工，干完自己那一道工序就离开，下一位临时工接着干。

1.2 100个临时工完成同一项任务

来看一个具体场景。当你对AI助手说“帮我修复这个bug”，30秒后它回复“已修复”。这30秒内究竟发生了什么？

第1轮：唤起临时工A → A说“我先读取报错文件” → 系统读取文件 → A消失

第2轮：唤起临时工B → B看到文件内容，说“我再看一下相关测试” → 系统读取测试 → B消失

第3轮：唤起临时工C → C说“找到问题了，我来修改” → 系统写入文件 → C消失

第4轮：唤起临时工D → D说“运行测试验证” → 系统执行测试 → D消失

第5轮：唤起临时工E → E看到测试通过，说“搞定” → 循环结束 → 你看到回复

你只看到最后那句“已修复”，但背后是5个不同的AI实例接力完成。如果任务更复杂，可能需要50轮、100轮对话。假设系统中途崩溃3次、重启3次，最终任务完成，整个过程可能出现过100个不同的AI实例。

关键问题来了：是什么让这100个临时工协作有序、不掉链子？答案就是Harness。

2. Harness 是什么？一句话讲透

2.1 马具的比喻

Harness一词的本义是“马具”——套在马身上的皮带与缰绳。Anthropic公司用这个比喻非常贴切：模型是马，Harness是缰绳。你不需要一根比马更强壮的缰绳，多一根皮带都是累赘。

Harness就是一个让AI能够持续工作的执行框架。它只做三件最核心的事情：

1. 执行工具：模型说“帮我读一下这个文件”，Harness就去读取，并把结果交回
2. 管理上下文：将对话历史、工具结果、错误信息打包，塞给下一个AI
3. 故障恢复：工具调用发生错误时，将错误信息原样返回给模型，让模型自行决定下一步

注意——Harness不负责规划、不判断对错、不评估好坏。模型说干什么它就干什么，干完交回结果。这种设计哲学称为“薄框架”：Harness是哑的，所有智能化部分都在模型里。

2.2 While循环：Harness的核心引擎

Harness的心脏是一个while循环。什么是while循环？想象你在烧水，不清楚水何时烧开，但你知道一件事——水没开之前你得一直守着。所以你做的事是：看一眼壶 → 没开 → 等一会儿 → 再看一眼 → 没开 → 再等……直到水开了，才停下来。

这就是while循环的本质：只要某个条件仍然成立，就持续重复执行同一套动作。

对应到Harness中：

while (任务未完成) {
    唤起新AI → AI决定使用何种工具 → Harness执行工具 → 结果追加到历史 → AI消失
}

循环何时停止？只有三种情况：

• 正常退出：模型说“我完成了”，不再有工具请求
• 兜底退出：达到预设的最大循环次数（防止无限循环消耗资源）
• 异常终止：用户手动中断、断电、程序崩溃

特别注意：工具调用失败不是退出条件。如果AI让Harness去读一个文件，但文件不存在，Harness会把“文件不存在”这条错误信息原样返回给AI。AI看到后自行决定下一步：是换个文件名试试？还是先创建这个文件？——“这条路走不通”本身就是有价值的反馈。

3. Harness的六大核心组件

理解了Harness的基本概念后，我们来拆解它的具体构成。一个完整的Harness系统通常包含六大核心组件，每个组件职责分明。

3.1 Agentic Loop（智能体循环）：系统的心跳

这是Harness最核心的部分，即我们前面讲的while循环。它接收用户输入，然后在返回最终结果之前经历一个完整的循环过程：调用模型 → 模型返回工具请求 → 执行工具 → 把结果塞回上下文 → 再次调用模型 → 继续循环……直到模型说“任务完成”。

这个循环看似简单，但所有复杂的智能行为都从这一简单循环中涌现出来。如同细胞分裂的规则很简单，却能生长出复杂的生命体。该设计思想源自2022年的ReAct论文（Reasoning and Acting），它提出AI Agent应是一个“推理-行动”的循环系统。

3.2 Tool System（工具系统）：AI的双手和双脚

大语言模型本身只能生成文本，但通过工具系统，它能够真正与现实世界交互。工具系统让AI可以读写文件、执行代码、搜索网页、查询数据库、发送消息等。

Claude Code的工具设计哲学尤其值得借鉴：少而精，原子化。它只提供几个最基础的工具：读文件（Read）、写文件（Write）、执行命令（Bash）、搜索内容（Grep）、版本控制（Git）。没有复杂的“代码分析器”或“项目理解引擎”，但通过这几个原子工具的组合，AI能完成极其复杂的任务。

为什么不提供更多工具？因为工具越多，模型的注意力就越分散。每个工具的定义都要占用上下文窗口，工具太多会导致模型“选择困难”。而且，Unix命令行工具已经被程序员使用了50年，模型的训练数据中见过海量使用示例，天然就“会用”这些工具。

3.3 Memory & Context Management（记忆与上下文管理）

还记得我们说的“临时工”比喻吗？每个新唤起的AI都需要看“病历本”才知道之前发生了什么。这个“病历本”就是上下文窗口，而如何管理这个窗口，是Harness最关键的技术之一。

上下文管理面临几个核心挑战：

• 挑战一：窗口容量有限。即使是最新模型，上下文窗口也有上限（比如200K tokens）。一个复杂任务可能产生几百轮对话，如果全部保留，很快就会撑爆。
• 挑战二：信息密度不均。有些对话很重要（如用户的核心需求），有些是临时的（如某次失败的尝试）。如何决定保留什么、丢弃什么？
• 挑战三：上下文污染。如果把所有历史都塞进去，模型可能被无关信息干扰，反而降低性能。

Claude Code在这方面做得尤为出色，它使用了多种技术：上下文压缩（把长对话总结成摘要）、分层存储（重要信息放在主上下文，次要信息放在外部存储）、按需加载（仅在需要时才加载相关文档）。

3.4 Guardrails（护栏）：安全的缰绳

Guardrails是Harness的安全机制，确保AI不会做出危险或不当的操作。它通常包含三种控制策略：

• Allow（允许）：某些操作可以自动执行，无需询问用户。例如读取项目文件、搜索文档等低风险操作。
• Deny（拒绝）：某些操作被明确禁止。例如删除系统文件、访问敏感数据、执行危险命令等。
• Ask（询问）：某些操作需要用户确认。例如写入文件、执行代码、发送网络请求等。这就是为什么你用Claude Code时，它会经常询问“是否允许执行这个操作”。

Guardrails的设计需要在安全性与效率之间找到平衡。如果每个操作都要询问，用户会感到厌烦；如果什么都不问，又可能出现安全风险。好的Guardrails设计应遵循：低风险操作自动执行，高风险操作必须确认，危险操作直接拒绝。

3.5 Hooks（钩子）：质量守卫

Hooks是在特定时机自动触发的检查机制，类似于代码提交前的Git Hooks。它们确保系统在关键节点进行必要的验证。

常见的Hooks包括：

• Pre-execution Hook：在执行工具前检查参数是否合法
• Post-execution Hook：在执行工具后验证结果是否符合预期
• Pre-commit Hook：在提交代码前检查是否包含敏感信息（如API密钥、密码）
• Quality Hook：在任务完成前进行质量检查

举个例子：你让AI帮你写代码并提交到GitHub。Pre-commit Hook会自动检查代码中是否包含.env文件、是否有硬编码的密码。如果发现问题，会阻止提交并提醒AI修复。这种自动化的质量守卫能避免大量低级错误。

3.6 Session（会话）：持久化的工作记录

Session管理解决的是“关闭窗口后还能接着干”的问题。它把工作进度、环境状态、历史记录持久化到硬盘上，即使程序崩溃或重启，新的AI实例也能无缝接续。

一个完整的Session通常包含：

• 对话历史：所有用户输入和AI回复
• 工具调用记录：执行了哪些工具、参数是什么、结果如何
• 环境状态：当前工作目录、已安装的依赖、环境变量等
• 进度标记：哪些任务已完成、哪些正在进行、哪些还未开始

Session的设计让AI Agent从“一次性对话”升级为“可持续工作的系统”。你可以今天让AI启动一个项目，明天继续，后天再调整，就像与真实的团队成员协作一样。

4. Harness解决的五大实际问题

理论讲完了，我们来看看Harness在实际应用中究竟解决了哪些关键问题。这些问题在早期的AI Agent系统中非常普遍，直到Harness的出现才得到系统性解决。

4.1 无限循环——AI陷入死循环怎么办？

场景重现：你让AI帮你调试一个bug，它尝试了一种方法失败，然后又尝试同样的方法，再失败，再尝试……陷入无限循环，API费用疯狂上涨。

Harness的解决方案：

1. 设置最大循环次数：比如限制50轮对话，超过则强制退出
2. 检测重复模式：如果连续3次执行相同的工具调用且都失败，自动中断并提示用户
3. 成本监控：设置预算上限，超过阈值自动暂停

这就像给烧水的人设定一个定时器：如果30分钟还没烧开，说明可能出了问题，别再傻等了。

4.2 上下文爆炸——对话过长导致系统崩溃

场景重现：一个复杂任务需要100轮对话，每轮对话都在上下文窗口中累积。到第80轮时，上下文窗口已经塞满，模型开始“焦虑”——它知道窗口快满了，就草草收尾、提前宣布完成，实际上任务根本没做好。

Harness的解决方案：

1. 上下文压缩：每隔20轮对话，把历史总结成一段摘要，清空详细记录
2. 分层存储：核心信息保留在主上下文，详细日志存到外部文件
3. 智能裁剪：保留最近的对话和最重要的历史，中间的临时信息可以丢弃

想象你在写笔记，笔记本快写满了。你不是把前面的内容全部撕掉，而是把重点提炼成一页摘要，详细内容归档到文件柜里。需要时再去翻阅。

4.3 权限失控——AI执行了不该执行的操作

场景重现：你让AI帮你清理项目中的临时文件，结果它把整个项目目录都删了。或者它在你不知情的情况下，将代码提交到了公开的GitHub仓库，泄露了公司机密。

Harness的解决方案：

1. 权限分级：读操作自动允许，写操作需要确认，删除操作需要二次确认
2. 沙箱环境：AI在隔离的环境中执行操作，不能直接访问系统核心文件
3. 操作审计：所有操作都有日志记录，可以追溯和回滚

这就像给实习生分配任务：看文档随便看，改代码要给我看看，删东西必须经过我批准。

4.4 质量不可控——AI说做完了但实际没做好

场景重现：你让AI实现一个登录功能，它说“已完成”。你一测试，发现密码验证根本不工作，或者界面按钮点了没反应。AI过早宣布胜利，实际上功能有严重缺陷。

Harness的解决方案：

1. 强制测试：功能实现后，必须运行测试用例，测试通过才算完成
2. 独立评估器：用另一个AI实例来验证第一个AI的工作成果
3. 结构化验收：用JSON格式定义功能清单，每个功能必须有明确的status字段

这个设计特别巧妙。为什么要用独立的评估器？因为让运动员自己掐表，总会给自己掐个好成绩。评估器看不到实现过程，只看最终结果，所以更客观。

4.5 成本不透明——不知道花了多少钱

场景重现：你让AI帮你做一个项目，任务完成后发现API账单是预期的10倍。因为中间有很多失败重试、无效循环，但你完全不知情。

Harness的解决方案：

1. 实时成本监控：每次API调用都记录token消耗和费用
2. 预算预警：设置预算上限，达到80%时提醒，达到100%时暂停
3. 成本分析报告：任务完成后，生成详细的成本分析，显示哪些环节最贵

就像打车软件会实时显示费用，让你知道这趟车要花多少钱。如果发现路线不对，可以及时调整。

5. Harness的设计哲学——薄框架与厚技能

理解Harness的设计哲学，能帮助你做出更好的架构决策。这部分我们深入探讨“Thin Harness, Fat Skills”（瘦脚手架，胖技能）的核心思想。

5.1 为什么要“瘦”？

很多人的第一反应是：既然Harness这么重要，是不是应该做得越强大越好？提供越多功能越好？

答案恰恰相反。Harness应该保持简单，只做最核心的事情。

原因有三个：

1. 避免上下文污染
每个工具的定义都要占用上下文窗口。如果你在MCP协议里塞了40多个工具定义，上下文窗口被占满，模型的大部分注意力花在理解工具定义上，而不是做正事。

有个真实数据：Playwright CLI每次浏览器操作100ms，而通过Chrome MCP做同样的事要15秒。75倍的速度差距。为什么？因为MCP的工具定义太复杂，模型需要花大量时间理解和选择。

2. 保持灵活性
模型每年都在变强。今年需要的脚手架明年可能就不再需要。框架越厚，未来拆除的成本越高。

还记得前面讲的吗？当模型从Sonnet 4.5升级到Opus 4.6后，很多原本“必需”的组件直接被删掉了。如果这些组件与核心架构深度耦合，删除会非常困难。

3. 涌现的力量
少而精的原子工具，通过组合能涌现出强大的能力。这比提供一堆专用工具更有效。

Claude Code只有5个基础工具，但能完成极其复杂的任务。为什么？因为这5个工具是精心选择的“原子操作”，它们的组合空间是指数级的。

5.2 什么是“胖技能”？

如果Harness要保持简单，那复杂性去哪了？答案是：转移到Skill文件里。

Skill文件是用自然语言写的“程序”，它教模型“怎么做某件事”。一个好的Skill文件应该：

1. 包含丰富的领域知识
不是简单的步骤列表，而是包含判断标准、边界条件、常见陷阱、最佳实践。

2. 像函数一样可复用
同一个Skill，传不同参数，能产生完全不同的能力。比如/investigate这个Skill：

• 传入“医疗研究数据” → 模型变成医疗分析师
• 传入“财务申报数据” → 模型变成法证调查员

3. 可以持续优化
Skill文件是文本，可以版本控制、可以A/B测试、可以根据反馈持续改进。

这就是“胖技能”的含义：把人的判断和经验固化成可复用的文档。

5.3 潜在空间 vs 确定性执行：画一条清晰的线

Harness设计中最重要的原则之一：清楚地区分什么该AI做，什么该工具做。

潜在空间的事，交给AI：

• 阅读理解
• 判断综合
• 模式识别
• 检测矛盾

确定性执行的事，交给工具：

• SQL查询
• 代码编译
• 数学计算
• 算法分配

经典反面案例：让模型给800人排座位。这是个组合优化问题，需要精确的约束求解。模型会一本正经地给出一份看起来很合理的座位表——但仔细检查就会发现各种冲突。

正确做法：让AI理解每个人的偏好和约束，然后调用专门的优化算法来计算座位分配。AI负责理解，算法负责计算。

混用是AI Agent系统中最常见的架构错误。不是模型不够聪明，是你让它干了不该干的活。

5.4 从Prompt到Context到Harness：三次跃迁

回顾AI工程的演进，我们经历了三次重要的思维跃迁：

2023年：Prompt Engineering
那时候我们研究怎么写prompt：“你是一个很聪明的工程师”，“请你一步一步思考”。核心是让模型理解我们的意图。

2024-2025年：Context Engineering
我们意识到：你给模型什么，就是你能从模型得到的。做企业知识库、做RAG、优化上下文窗口。核心是给模型提供高质量的信息。

2026年：Harness Engineering
现在我们需要的不只是回答问题，而是完成任务。设计循环策略、工具系统、质量审核、权限控制。核心是构建可控的系统。

每一次跃迁都不是否定前一阶段，而是在更高的层次上整合。好的Harness系统仍然需要好的Prompt和Context，但它们现在是更大系统的一部分。

6. 从码农到系统工程师：永不失业的秘诀

在AI时代，有一个残酷的事实：工程师永远不会失业，但码农可能会失业。

什么是码农？就是单纯写代码的人。当Agent可以生成代码的时候，码农的价值就会被替代。

什么是工程师？是能够设计并驾驭复杂系统的人。工程师的核心能力不在于写代码，而在于：

1. 理解系统的复杂性
能看到表面问题背后的系统性原因。比如性能问题不只是代码慢，可能是架构设计有问题；用户体验差不只是界面丑，可能是业务流程有问题。

2. 抽象和结构化思维
能把复杂的问题拆解成清晰的结构。这是设计模式、架构模式、Harness模式的共同基础。抽象能力是工程师最核心的竞争力。

3. 驾驭不确定性
AI Agent是概率系统，不是确定性系统。工程师需要学会在不确定性中做决策：如何设置容错机制？如何平衡成本和质量？如何在失控和过度控制之间找到平衡？

4. 深度理解业务
越是在AI时代，懂业务越重要。AI可以写代码，但它不知道这个功能为什么重要、用户真正需要什么、哪些边界条件必须考虑。这些只有深度理解业务的人才知道。

5. 持续学习能力
技术变化太快，具体的工具和框架会过时，但学习能力不会。能快速理解新概念、能从第一性原理思考、能在混乱中找到规律——这些元能力是永恒的。

7. 结语：Harness是驾驭AI的缰绳

我们从“AI的失忆症”开始，理解了为什么需要Harness。然后深入学习了Harness的六大核心组件、解决的五大问题、演化的四个阶段。我们看到了真实的大规模应用案例，学习了实践指南和设计哲学。最后展望了未来方向和个人成长路径。

如果要用一句话总结Harness的本质，那就是：Harness是我们驾驭AI Agent这个“不确定性系统”的缰绳。

参考链接

https://github.com/deusyu/harness-engineering