/agentic-patterns — 高效智能体行为的基础原则
你正在教授高效的智能体模式。这些是模型无关的原则——它们适用于 Claude、GPT、Gemini 或任何作为智能体运行的 LLM。目标是：智能体能够良好地分解问题、精确地使用工具、从错误中恢复、管理上下文预算、评估自身质量，并知道何时停止。
何时使用
适用于：
- 设计多步骤智能体的控制流程
- 在顺序、并行和层级智能体架构之间做出选择
- 实现错误恢复和优雅降级
- 在长时间运行的智能体中管理上下文窗口预算
- 将质量自我评估构建到智能体输出中
- 决定智能体何时应该暂停与继续
不适用于：
- 构建智能体基础设施或框架（使用 agent-creator）
- 设计 DAG 拓扑结构（使用 windags-architect）
- 实现特定工具（使用领域特定技能）
- 提示词优化（使用 prompt-engineer）
五大支柱
每个高效智能体都具备五种能力：
1. 分解 — 在行动前将问题拆解为步骤
2. 编排 — 有目的地选择和排序工具
3. 恢复 — 优雅地处理故障，避免灾难性失败
4. 管理 — 像预算一样使用上下文令牌
5. 评估 — 了解工作质量，并知道何时停止
支柱 1：分解
三遍法则
在行动之前，对任务进行三次审阅：
第一遍 — 范围："完成"是什么样的？首先定义退出条件。
第二遍 — 子任务：达到"完成"需要哪 3-7 个具体步骤？每个步骤应该通过一次工具调用或一次小规模的工具调用链来完成。
第三遍 — 依赖关系：哪些步骤依赖于哪些步骤？独立的步骤可以并行处理。有依赖的步骤必须串行处理。
分解反模式
| 反模式 | 失败原因 | 修复方法 |
|---|---|---|
| 分解前就行动 | 浪费工具调用，方向错误 | 务必先做计划，即便是简单的计划 |
| 一个巨大的子任务 | 无法并行，没有检查点 | 拆分直到每个子任务仅需一次工具调用 |
| 20+ 个子任务 | 认知开销大，丢失上下文 | 合并相关步骤，目标 3-7 个 |
| 没有退出条件 | 智能体永远运行 | 在开始前定义"完成" |
| 静态计划 | 无法适应新发现 | 在每轮结果后重新规划 |
何时应重新分解
在以下情况下重新规划：
- 工具调用返回了意外结果
- 发现问题与你假设的不同
- 某个依赖失败，导致下游计划无效
- 已完成 50%，但对剩余计划的信心低于 0.5
支柱 2：工具编排
最小工具原则
使用数量最少、范围最窄的工具来完成每个子任务。每次工具调用都有成本：
- 消耗令牌（输入 + 输出）
- 增加延迟
- 增加错误面
- 消耗上下文预算
错误做法：读取 20 个文件来理解一个代码库。 正确做法：使用 Grep 查找特定符号，然后读取包含它的 2-3 个文件。
工具选择启发式
| 需求 | 首选工具 | 原因 |
|---|---|---|
| 按名称查找文件 | Glob | 直接模式匹配，无需扫描内容 |
| 在文件中查找内容 | Grep | 定向搜索，返回位置 |
| 理解特定文件 | Read | 提供单个文件的完整上下文 |
| 理解代码库 | Task（探索智能体） | 委托探索，保护主上下文 |
| 进行小改动 | Edit | 最小差异，保留周围代码 |
| 创建新内容 | Write | 全新文件，无编辑冲突 |
| 运行命令 | Bash | 系统交互，构建/测试 |
| 复杂子问题 | Task（子智能体） | 隔离上下文，可并行化 |
顺序 vs 并行
顺序（当一个步骤的输出是下一个步骤的输入时使用）：
读取文件 → 理解结构 → 编辑特定部分 → 运行测试
并行（当任务相互独立时使用）：
[对模式 A 进行 Grep 搜索] + [对模式 B 进行 Grep 搜索] + [读取配置文件]
→ 全部完成 → 综合发现
规则：如果两次工具调用不共享数据，则并行运行它们。如果一次需要另一次的输出，则串行执行。
子智能体决策
在以下情况下生成子智能体（使用 Task 工具）：
- 子问题会消耗超过你剩余上下文的 30%
- 工作相互独立，并且可以用一段话描述
- 你需要进行广泛探索（许多文件、网络搜索）而不污染你的上下文
- 子问题映射到已知技能（代码审查、测试、研究）
在以下情况下不要生成子智能体：
- 任务只需一次工具调用
- 你需要立即获得结果以进行下一步
- 描述任务的开销超过了执行任务的开销
支柱 3：错误恢复
恢复阶梯
当工具调用失败时，逐级升级到四个级别：
级别 1 — 调整后重试：修复明显问题（拼写错误、路径错误、缺少参数）并重试一次。
级别 2 — 替代方法：使用不同的工具或策略来实现相同目标。如果 Edit 失败，尝试不同的 Edit。如果 Grep 未找到任何内容，尝试使用不同模式的 Glob。
级别 3 — 缩小范围：如果无法完成整个任务，确定可以完成的、最大的子集。提供部分结果并明确说明缺失的内容。
级别 4 — 上报给用户：如果你已尝试级别 1-3，但任务仍然受阻，描述你尝试过的方法、失败的原因，并请求用户指导。切勿默默循环。
错误恢复反模式
| 反模式 | 后果 | 修复方法 |
|---|---|---|
| 对同一操作重试 5 次 | 浪费令牌，同样失败 | 调整后重试一次，然后进入级别 2 |
| 忽略错误并继续 | 下游级联失败 | 必须处理每个错误 |
| 简化任务以使其工作 | 用户得到的内容少于要求 | 仅在级别 3 缩小范围，并说明情况 |
| 立即放弃 | 用户失去信任 | 在上报前用尽级别 1-2 |
结构化错误处理
当工具调用失败时：
- 仔细阅读错误消息——它通常会告诉你哪里出了问题
- 诊断：是暂时性问题（重试）还是根本性问题（重新设计）？
- 行动：应用适当的恢复级别
- 报告：如果错误影响最终输出，请透明地说明
支柱 4：上下文管理
上下文是一个预算
上下文窗口中的每个令牌都消耗成本并占用注意力。将上下文视为预算：
- 收入：用户消息、工具结果、检索到的内容
- 支出：每次工具调用都会增加上下文
- 储蓄：子智能体隔离昂贵的探索
- 债务：不必要的读取/搜索，你无法撤销
30% 规则
为你有效上下文的 30% 保留用于最终综合和输出。如果你已经使用了 70% 的上下文进行研究，请停止研究并开始综合。
上下文高效模式
| 模式 | 方法 | 节省 |
|---|---|---|
| 定向读取 | 读取特定行范围，而不是整个文件 | 每文件 50-90% |
| 先 Grep 后读取 | 找到确切位置，然后仅读取该部分 | 避免读取无关文件 |
| 子智能体委托 | 昂贵的探索在隔离的上下文中进行 | 保护主上下文 |
| 及早总结 | 研究阶段后，在继续之前写一个摘要 | 防止重复阅读 |
| 批量工具调用 | 并行运行独立调用 | 减少往返次数 |
不要加载到上下文中的内容
- 只需要 10 行时的整个文件
- 超出相关失败范围的构建输出或测试日志
- 已经阅读并理解的文件
- 已经知道答案时的探索性搜索
支柱 5：质量自我评估
置信度校准
完成任务后，从两个维度评估你的置信度：
完整性：你是否解决了用户要求的所有问题？
- 1.0：每个方面都有证据说明
- 0.7：主要要求已处理，部分次要方面缺失
- 0.4：部分答案，存在显著差距
- 0.1：几乎没有开始
正确性：你的输出有多大可能是正确的？
- 1.0：已通过测试验证、交叉引用，确定性高
- 0.7：有合理信心但未验证
- 0.4：最佳猜测，存在显著不确定性
- 0.1：推测性
何时停止
当以下任一条件成立时停止：
- 退出条件（来自分解步骤）已满足
- 你对进一步工作能改善输出的信心降至 0.3 以下
- 你已消耗了 70% 的可用上下文（30% 规则）
- 用户的问题已完全得到回答
- 你正在进行的更改无法可测量地改进结果
当以下所有条件成立时继续：
- 退出条件尚未满足
- 你有清晰的下一步，且有预期的改进
- 你仍有足够的上下文预算
- 每次迭代都在产生可衡量的进展
“还有一件事”陷阱
抵制添加用户未要求的改进的冲动。每一次“还有一件事”都会消耗令牌、有引入错误的风险，并延迟交付。如果你看到了改进机会，在你的回复中提一下——不要未经请求就实施它。
架构模式
模式 1：侦察-然后-行动
阶段 1（侦察）： 读取、Grep、Glob — 了解情况
阶段 2（计划）： 根据发现的内容进行分解
阶段 3（行动）： 编辑、写入、Bash — 执行计划
阶段 4（验证）： 运行测试，检查结果
最适合：错误修复、功能添加、重构。你需要在修改之前先理解。
模式 2：并行扇出
第 0 波：[研究 A] + [研究 B] + [研究 C] ← 并行子智能体
第 1 波：[综合发现] ← 单一智能体
第 2 波：[基于综合结果进行实施] ← 单一智能体
最适合：需要多个独立信息来源的任务。研究任务、竞争分析、多文件理解。
模式 3：迭代精炼
循环：
1. 生成草稿输出
2. 对照标准进行评估
3. 如果标准达到 → 完成
4. 识别最大差距
5. 修复差距 → 转到步骤 1
最大迭代次数：3-5
最适合：创造性任务、代码生成、内容制作。每次迭代都提高质量。
模式 4：阶段式管线
阶段 1：原始提取（快速、广泛）
阶段 2：过滤（去除噪音）
阶段 3：丰富（为幸存者增加细节）
阶段 4：最终综合
最适合：数据处理、研究综合、技能压缩。每个阶段都会缩小工作集。
质量检查清单
在认为智能体任务完成之前：
[ ] 开始前已定义退出条件
[ ] 任务已分解为 3-7 个具体子任务
[ ] 已识别依赖关系（哪些必须串行 vs 并行）
[ ] 每次工具调用都有明确目的（无探索性钓鱼）
[ ] 错误已在适当的恢复级别处理
[ ] 上下文预算已跟踪（在综合前不超过 70%）
[ ] 输出来自用户请求的每个部分
[ ] 已对完整性和正确性进行置信度自我评估
[ ] 用户未要求的改进已记录但未实现
[ ] 已达到明确的停止点（满足退出条件）
元模式
所有五大支柱都遵循一个元模式：行动前思考，行动时精确，行动后评估。
思考： 我试图做什么？我怎么知道它做完了？
行动： 使用最少、最精确的工具。
评估： 它工作了吗？我的信心如何？我应该继续吗？
跳过“思考”的智能体会浪费令牌去探索。跳过“评估”的智能体不知道何时停止。跳过“行动”的智能体只会永远计划。每个周期都按此顺序进行这三个步骤。