Harness 工程与 Loop 工程：给 AI 智能体造一副好骨架和一套好步法
为什么模型已经不是瓶颈
2025 年中以后，主流大模型在推理、代码生成、工具调用上的能力已经趋同。Claude Sonnet 4、GPT-4.1、DeepSeek V4 在纯能力测试上差距越来越小。但真实使用中，不同 AI 智能体产品的体验差异巨大——有的能自主完成数小时复杂任务，有的三步就崩。
差异在哪？不在模型，在模型外面那两层工程：
- Harness 工程：静态脚手架——把模型包起来的所有东西
- Loop 工程：动态控制流——模型如何在多次调用中保持连贯
打个比方：模型是 CPU，Harness 是主板+IO+驱动，Loop 是操作系统调度器。CPU 再强，主板烂或调度乱，系统一样跑不动。
第一部分：Harness 工程——给模型造一副好骨架
什么是 Harness
Harness 指的是围绕单次模型调用的所有静态基础设施：
- 工具定义和执行环境
- 上下文组装（system prompt、文件、记忆、检索结果）
- 输出解析和格式约束
- 权限网关和安全检查
- 错误处理和重试逻辑
Anthropic 在 2025 年的多篇工程博客中反复强调：模型是原始引擎，Harness 是让它变得有用的一切其他东西。
核心要素
1. 工具设计
工具是 Harness 中最直接影响模型表现的组件。Anthropic 的《Writing Tools for AI Agents》给出了关键原则：
- 工具描述要写给模型看，不是写给人看——用模型能理解的语言描述参数和返回值
- 返回值要结构化，让模型能直接从中提取下一步需要的信息
- 错误信息要可操作——不要返回 "失败"，要返回 "权限不足，你需要先运行 chmod"
- 工具数量不是问题，工具描述质量才是
2. 上下文组装
上下文是有限资源。Manus 团队在《Context Engineering for AI Agents》中总结了实战经验：
- KV-cache 稳定性：避免频繁修改 system prompt 前部，否则每次调用都要重新计算整个上下文的注意力
- 工具遮蔽而非移除：不用的工具不要从上下文中删除，而是标记为不可用——移除会破坏 cache，遮蔽不会
- 文件系统即记忆：把中间结果写到文件而非塞进上下文，需要时再读取
- 保留错误在上下文中：失败的工具调用结果不要清除，模型需要从中学习调整
3. 安全和权限
Harness 必须在模型和真实世界之间设置安全层：
- 命令审批分级：低风险自动通过，高风险人工确认
- 文件访问沙箱：限制模型可读写的路径
- 网络隔离：限制模型可访问的 API 和域名
- 输出过滤：防止泄露敏感信息
4. 输出解析
模型输出不是纯文本——可能包含工具调用、代码块、结构化数据。Harness 需要：
- 健壮的解析器：处理格式错误、截断、混合输出
- 类型校验：工具参数类型检查
- 回退策略：解析失败时如何恢复
Harness 设计原则
Anthropic 在《Building Effective Agents》中区分了"工作流"（Workflow）和"智能体"（Agent）：
- 工作流：预定义路径，模型在固定步骤中执行——可控、可预测
- 智能体：模型自主决定路径——灵活但不可预测
关键原则：从工作流开始，只在需要灵活性时才引入智能体循环。不要一上来就做全自主 agent，先用固定管线解决问题，再逐步放开模型的自由度。
第二部分：Loop 工程——给模型一套好步法
什么是 Loop
Loop 是智能体的动态控制流——模型如何跨多次调用保持连贯：
观察 → 思考 → 行动（工具调用）→ 获取结果 → 重复
直到满足停止条件或达到步数上限。
核心要素
1. 停止条件
最容易被忽视但最重要的设计：
- 任务完成：模型如何判断任务已完成？需要明确的成功标准
- 步数上限：防止无限循环的安全网
- 用户确认：关键步骤前暂停等待人工确认
- 成本阈值：token 消耗超过预算时停止
OpenAI 在《A Practical Guide to Building Agents》中强调：每个 agent 必须有明确的终止条件，否则它会无限消耗。
2. 状态和上下文管理
Loop 跨越多次调用，状态如何在迭代间传递：
- 短期记忆：当前对话上下文——随迭代增长，需要压缩
- 长期记忆：跨会话的持久化记忆——用户偏好、环境信息
- 上下文压缩：当上下文接近窗口上限时，如何摘要而不丢失关键信息
- 检查点：定期保存状态，支持回滚
3. 反馈质量
工具返回的结果形状直接决定下一轮迭代的质量：
- 返回值要包含模型做下一步决策需要的所有信息
- 错误信息要可操作——不只是 "失败"，而是 "失败原因 + 建议的修复步骤"
- 大量输出要摘要或分页，不要一次性塞满上下文
4. 错误和重试处理
模型调用工具会失败。Loop 需要决定：
- 重试：相同参数再试一次（网络波动？）
- 调整：换一种方式试（权限不足？先修权限）
- 降级：用更简单的方式完成（复杂工具失败？手动步骤替代）
- 中止：放弃并报告失败（不可恢复的错误）
5. 节奏控制
- 一步到位 vs 多步小跑：复杂任务拆成小步更可控
- 并行 vs 串行：独立子任务可以并行，有依赖的必须串行
- 批处理：多个相似操作合并为一次调用
经典 Loop 模式
ReAct 模式
最基础的 agentic loop，来自 Yao 等人的论文：
Thought → Action → Observation → Thought → ...
模型交替进行推理（Thought）和行动（Action），每次行动后观察结果再决定下一步。这是当今大多数 AI agent 的基础范式。
来源：ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al., ICLR 2023)
Reflexion 模式
在 ReAct 基础上加入自我反思：失败后不直接重试，而是先总结失败原因，再带着反思重新尝试。
来源：Reflexion: Language Agents with Verbal Reinforcement Learning (Shinn et al.)
规划-执行模式
先规划完整步骤序列，再逐步执行。适合任务结构清晰但步骤多的场景。可在执行中动态调整计划。
多智能体编排
多个 agent 协作，每个负责不同子任务。Anthropic 的多智能体研究系统是典型案例：编排者 agent 拆分任务，工作 agent 并行执行。
但 Cognition 团队警告：不要急着用多智能体。单线程 agent 共享完整上下文，往往比多个 agent 之间传递碎片化的上下文更有效。
第三部分：Harness 与 Loop 的关系
| 维度 | Harness 工程 | Loop 工程 |
|---|---|---|
| 性质 | 静态脚手架 | 动态控制流 |
| 作用范围 | 单次模型调用 | 跨多次调用 |
| 核心问题 | 输入什么、能做什么、输出什么 | 何时停、如何学、怎样恢复 |
| 比喻 | 房间和工具 | 在房间里如何走动 |
| 设计目标 | 让单次调用做对 | 让多次调用做连贯 |
两者是互补的：好的 Harness 让每次调用都有正确的输入和安全的输出，好的 Loop 让多次调用串成连贯的工作流。缺了 Harness，模型会做出危险或无意义的操作；缺了 Loop，模型会在复杂任务中迷失方向。
真实系统中的例子
- Claude Code：Harness = 工具定义（Bash/Edit/Read/Write）+ 上下文组装 + 权限审批；Loop = ReAct 模式 + 上下文压缩 + 检查点回滚
- Manus：Harness = 工具集 + 文件系统记忆 + KV-cache 管理；Loop = 观察思考行动 + 工具遮蔽 + 错误保留
- Hermes Agent：Harness = 工具注册 + 技能加载 + 安全扫描；Loop = delegate_task 子代理 + 上下文压缩 + cron 调度
第四部分：参考资料精选
基础论文
| 论文 | 核心贡献 | 链接 |
|---|---|---|
| ReAct (Yao et al., 2023) | 推理+行动交替的基础 loop 范式 | arxiv.org/abs/2210.03629 |
| Reflexion (Shinn et al., 2023) | 自我反思 loop，失败后总结再试 | arxiv.org/abs/2303.11366 |
| CoALA (Sumers et al., 2024) | 语言智能体的认知架构分类框架 | arxiv.org/abs/2309.02427 |
| AutoGen (Microsoft) | 多智能体对话框架 | arxiv.org/abs/2308.08155 |
工程实践博客
| 文章 | 亮点 | 链接 |
|---|---|---|
| Anthropic — Building Effective Agents | 工作流 vs 智能体，何时用哪个 | anthropic.com |
| Anthropic — Effective Context Engineering | 上下文是有限预算，just-in-time 检索 | anthropic.com |
| Anthropic — Writing Tools for AI Agents | 工具描述写给模型看，错误信息要可操作 | anthropic.com |
| Manus — Context Engineering Lessons | KV-cache 稳定性、工具遮蔽、文件系统记忆 | manus.im |
| Cognition — Don't Build Multi-Agents | 单线程共享上下文 > 多 agent 传碎片 | cognition.ai |
| Chip Huyen — Agents | 系统性概览：规划、工具使用、失败模式 | huyenchip.com |
| Lilian Weng — LLM Powered Autonomous Agents | 最佳单篇地图：规划+记忆+工具 | lilianweng.github.io |
框架和工具文档
| 文档 | 用途 | 链接 |
|---|---|---|
| Google — Agents 白皮书 | 模型+工具+编排的参考架构 | kaggle.com/whitepaper-agents |
| OpenAI — A Practical Guide to Building Agents | Loop、护栏、交接、停止逻辑 | cdn.openai.com |
| LangGraph | 状态机/图模型 agent loop，持久化检查点 | langchain-ai.github.io/langgraph |
| Model Context Protocol | 工具平面标准 | modelcontextprotocol.io |
设计模式概览
Andrew Ng 总结的四种 agentic 设计模式仍然是最简洁的分类：
- 反思（Reflection）：自我批评并改进
- 工具使用（Tool Use）：调用外部工具扩展能力
- 规划（Planning）：分解任务为子步骤
- 多智能体（Multi-Agent）：多个 agent 协作
第五部分：动手实践建议
如果你在构建自己的 AI agent
- 先做工作流，再加智能体——用固定管线验证核心逻辑，再逐步引入模型自主决策
- 工具描述是你的杠杆——花在工具描述上的时间回报远高于换更大的模型
- 上下文是预算——每 token 都有成本，压缩、摘要、文件系统记忆是必备技能
- 停止条件先于一切——没有终止条件的 agent 是一个会无限烧钱的 loop
- 错误是最好的老师——把失败的工具调用保留在上下文中，模型会从中调整策略
如果你在选择 agent 框架
- 需要完全控制：自己写 Harness + Loop，参考上述资料
- 需要快速原型：LangGraph（状态机模型）或 Claude Agent SDK
- 需要多智能体：AutoGen 或 Anthropic 的多智能体编排模式
- 需要工具生态：MCP 协议 + 兼容工具
结语
Harness 工程和 Loop 工程不是两个独立领域，而是同一个问题的两个面：如何让大模型在真实世界中可靠地工作。
当所有人都在追逐更大的模型时，真正拉开差距的是模型外面这两层工程。Claude Code 为什么好用？不是因为 Claude 模型比别家强多少，而是 Anthropic 在 Harness（工具设计、上下文管理、权限控制）和 Loop（ReAct 循环、上下文压缩、检查点）上做了大量工程。
模型是发动机，Harness 是底盘，Loop 是传动系统。三者匹配，车才跑得快、跑得稳。