escalation-governance

升级治理

概述

模型升级（haiku→sonnet→opus）以速度和成本换取推理能力。这种权衡必须有充分理由。

核心原则： 升级是为了处理确实需要更深入推理的任务，而不是为了“也许更聪明的模型能想明白”。

铁律

NO ESCALATION WITHOUT INVESTIGATION FIRST

升级绝不是捷径。如果你还不清楚当前模型为何不够用，升级就为时过早。

何时升级

合理的升级触发条件：

触发条件	描述	示例
确有复杂性	任务本身需要细致判断	安全策略权衡
推理深度	存在不确定性的多步推理	架构决策
新颖模式	没有可用的现有模式	首次实现
高风险	错误成本足以证明能力投入合理	生产环境部署
消除歧义	需要权衡多个有效解释	规范澄清

何时不应升级

不合理的升级触发条件：

反模式	错误之处	应采取的做法
“也许更聪明的模型能想明白”	这是在盲目折腾	调查根本原因
多次尝试失败	这表明方法不对，而非能力不足	质疑自己的假设
时间压力	紧迫性不会改变任务复杂度	系统性调查更快
未调查就感到不确定	你还没有尝试理解问题	先收集证据
“以防万一”	这是虚假的安全感——只会浪费资源	评估实际复杂度

决策框架

升级前，请回答以下问题：

1. 我是否理解了问题？

• 我能否说明当前模型为何不够用？
• 我是否确定了具体缺少哪种推理能力？
• 这是能力缺口还是知识缺口？

如果是知识缺口： 收集更多信息，不要升级。

2. 我是否进行了系统性调查？

• 我是否仔细阅读了错误消息和输出？
• 我是否检查过类似的已解决问题？
• 我是否提出并验证了假设？
• 这个代码库已经通过多少种方式实现了这一关注点， 哪一种是当前使用的？

同一关注点存在两种并行实现，会让任务看起来比实际更难。这属于知识缺口：通过引用搜索统计实现数量，并在升级前阅读两种实现（docs/knowledge-corpus/decoherence.md 将它们称为一个关注点的模型）。

如果尚未调查： 先完成调查。

3. 升级是否是正确的解决方案？

• 在当前模型级别，换一种方法是否可行？
• 任务本身是否复杂，还是我把它复杂化了？
• 将任务拆成更小的部分是否有帮助？

如果可以拆解： 拆分任务，不要升级。

4. 我能否证明这种权衡合理？

• 升级的成本（延迟、令牌、费用）是多少？
• 带来的收益（准确性、安全性、完整性）是什么？
• 收益是否与成本相称？

如果不相称： 不要升级。

升级流程

当升级确有必要时：

1. 记录原因 - 说明当前模型为何不够用
2. 明确范围 - 哪个具体子任务需要更强的能力？
3. 定义成功标准 - 如何判断升级后的任务已成功？
4. 及时返回 - 推理任务完成后，切回高效模型

不足以作为升级理由的情况

升级需要与任务相关的理由。以下常见理由无法通过上述四个步骤，而各自背后的限制说明了原因：

• “这很复杂”需要有尝试过程，证明当前模型能力不足。复杂本身无法预测模型是否会失败。
• “宁可小心，不可后悔”没有指出任何风险。更大的模型只会增加开销，却无法降低一个无人指出的风险。
• “我试过了，但失败了”需要说明尝试次数和失败原因。尚未调查的失败往往是上下文问题，更大的模型也会重蹈覆辙。
• “用户期待高质量”应通过流程来保证：测试、审查和证据。模型规模无法提供这些。
• “就这一次”仍需要有记录在案的理由，因为没有理由的例外一再重复，就会变成默认做法。
• “时间就是金钱”更支持调查。反复尝试更大的模型，比系统地检查当前模型更耗时。

Agent 架构

Agent 可以在 frontmatter 中声明升级提示：

model: haiku
escalation:
  to: sonnet                 # Suggested escalation target
  hints:                     # Advisory triggers (orchestrator may override)
    - security_sensitive     # Touches auth, secrets, permissions
    - ambiguous_input        # Multiple valid interpretations
    - novel_pattern          # No existing patterns apply
    - high_stakes            # Error would be costly

要点：

• 提示仅供参考，并非强制要求
• 编排器拥有最终决定权
• 编排器可以在没有提示时升级（基于更广泛的上下文）
• 编排器可以忽略提示（如果任务实际上很简单）

编排器权限

编排器（通常是 Opus）负责做出最终的升级决定：

可以遵循提示： 当提示与观察到的情况相符时 可以推翻提示并升级： 当上下文要求升级时（即使没有提示） 可以推翻提示并维持当前模型： 当任务比提示所示更简单时 可以升级到高于提示建议的模型： 即使提示建议使用 sonnet，也可以改用 opus

结合对话上下文作出的编排器判断，优先于静态提示。

危险信号 — 停下并调查

如果你发现自己在想：

• “让我换更好的模型试试”
• “这本该很简单，但就是行不通”
• “我什么办法都试过了”（但还没调查原因）
• “更聪明的模型会知道该怎么做”
• “我不明白为什么这行不通”

以上情况都意味着：停下，先调查。

与 Agent 工作流集成

Agent starts task at assigned model
├── Task succeeds → Complete
└── Task struggles →
    ├── Investigate systematically
    │   ├── Root cause found → Fix at current model
    │   └── Genuine capability gap → Escalate with justification
    └── Don't investigate → WRONG PATH
        └── "Maybe escalate?" → NO. Investigate first.

快速参考

情况	操作
任务本身需要细致的推理	升级
Agent 不确定，但尚未调查	先调查
多次尝试均告失败	质疑方法，而非模型
安全或高风险决策	升级
“也许更聪明的模型会知道”	绝不能以此为由升级
提示触发，但任务实际上很简单	推翻提示，继续使用当前模型
没有提示触发，但任务实际上很复杂	推翻提示，升级

模型能力说明

MCP 工具搜索（Claude Code 2.1.7+）：Haiku 模型不支持 MCP 工具搜索。如果工作流使用许多 MCP 工具（其描述超过上下文的 10%），这些工具会在 haiku 上预先加载，而不是延迟加载。这可能会占用大量上下文。对于 MCP 工具繁多的工作流，可以考虑升级到 sonnet；或者确保 haiku Agent 只使用原生工具（Read、Write、Bash 等）。

Claude.ai MCP 连接器（Claude Code 2.1.46+）：配置了 claude.ai 连接器的用户可能会自动加载额外的 MCP 工具，增加工具描述的总占用空间。这会让 haiku Agent 更容易超过 10% 的工具搜索阈值。如果升级决策涉及 MCP 工具繁多的工作流，请通过 /mcp 将 claude.ai 连接器的工具数量纳入考量。 通过调整 effort 代替升级（Opus 4.6 / Claude Code 2.1.32+）：Opus 4.6 引入了自适应思考，支持多个 effort 等级（low、medium、high）。在 2.1.72 中，Opus 4.6 移除了 max 等级，该模型的最高等级变为 high。Claude Code 2.1.111 重新引入了 max，并为 Opus 4.7 单独新增了 xhigh（介于 high 和 max 之间）；在其他模型上，xhigh 会回退到 high。符号：○（low）◐（medium）●（high）◉（xhigh）★（max）。使用 /effort（自 2.1.111 起提供交互式滑块），或使用 /effort auto 重置。在升级模型之前，先考虑调整当前模型的 effort 是否足够：

| 不妨考虑以下做法，而非…… | 适用情况 | |--------------|-------------|------| | Haiku → Sonnet | 留在 Haiku | 任务仍具有确定性，只是需要更多上下文 | | Sonnet → Opus | Opus@medium | 需要中等程度的推理，而非深入的架构分析 | | Opus@medium →“也许再试一次” | Opus@high 或“ultrathink” | 确实复杂，需要更深入的推理 | | Opus 4.7@high → 升级 | Opus 4.7@xhigh 或 @max | 需要对 Opus 4.7 进行深入的架构分析 |

默认 effort 变更（2.1.68+）：Max 和 Team 订阅用户现在默认使用 Opus 4.6 的 medium effort。 使用 /model 更改 effort 等级，或在提示词中输入 “ultrathink”，即可在下一轮启用 high effort。

移除 Opus 4/4.1（2.1.68+）：Opus 4 和 4.1 不再通过一方 API 提供。固定使用这些模型的用户会自动迁移到 Opus 4.6。使用 model frontmatter 的 Agent 无需采取任何操作，因为迁移过程是透明的。

Sonnet 4.5 → 4.6 迁移（2.1.69+）：Pro/Max/Team Premium 订阅中的 Sonnet 4.5 用户会自动迁移到 Sonnet 4.6。Agent 的 model frontmatter 中引用 Sonnet 时会透明地解析到相应版本。--model 标志中的 claude-opus-4-0 和 claude-opus-4-1 现在会正确 解析到 Opus 4.6，而非已弃用的版本。

修复 effort 参数问题（2.1.70+）：修复了使用自定义 Bedrock 推理配置文件或非标准 Claude 模型标识符时出现的 API 400 错误 This model does not support the effort parameter。 现在，effort 控件可在所有部署配置中可靠运行。

提供商默认使用 Opus 4.6（2.1.73+）：Bedrock、 Vertex 和 Microsoft Foundry 现在默认使用 Opus 4.6 （之前为 Opus 4.1）。子 Agent 的 model: opus/sonnet/haiku 别名现在会在所有提供商上解析到当前版本；此前这些别名会被静默降级到 较旧版本（例如，从 Opus 4.6 降到 Opus 4.1）。这项 修复使第三方提供商上的 Agent 调度工作流 与一方 API 的行为保持一致。

modelOverrides 设置（2.1.73+）：将模型 选择器条目映射到提供商专用 ID（Bedrock 推理配置文件 ARN、Vertex 版本名称、Foundry 部署名称）。在将模型选择路由到特定推理配置文件时使用。 配置详情请参阅模型优化 指南。

弃用 /output-style（2.1.73+）：改用 /config。 为更好地支持提示词缓存，输出样式现在会在会话开始时固定。

Agent frontmatter 中的完整模型 ID（2.1.74+）：Agent 的 model: 字段现在除了接受别名（opus、 sonnet、haiku）外，还接受完整模型 ID（例如 claude-opus-4-6）。此前，完整 ID 会被静默忽略。 现在，Agent 接受的值与 --model 相同。

effort 控件不能取代升级治理框架： 它们提供的是一个额外的调节维度。铁律依然适用：更改模型 或 effort 等级之前，都必须先调查问题。

退出标准

• 明确说明决策（升级 / 留在当前模型），并指出“何时升级”或“何时不升级”表格中的具体触发条件，而不是笼统地声称任务复杂。
• 如果建议升级，必须在升级发生前记录具体的目标模型和子任务范围。
• 任何由“也许更聪明的模型能解决”触发的升级，都必须标记为违反 Iron Law，并予以阻止。
• 如果任务可以拆分成更小的部分，且每部分都能由当前模型处理，则应提出拆分方案，而不是升级。