Category 路由与多模型回退策略

Category 路由与多模型回退策略

学习目标

• 理解 Category 与 Skill 的解耦设计
• 掌握 8 种内置 Category 的模型映射
• 实现双回退系统（model-fallback + runtime-fallback）
• 识别模型 ID 格式不一致导致的回退失效陷阱

前置知识

本章涉及多模型适配的通用原理，建议先阅读：

• 多模型适配架构

下文假设你已理解 Provider 抽象、认证策略和通用路由模式，直接聚焦 Oh-My-OpenAgent 的具体实现。

项目实践

Category 与 Skill 的解耦

Oh-My-OpenAgent 将 Agent 的配置维度拆分为两个独立概念：

• Category：决定「用哪个模型」——model、variant、temperature、thinking 配置
• Skill：决定「用什么工具和知识」——MCP 服务器、系统指令、工作流

通过 task(category, skills) 组合调用生成最优 Agent。这种解耦使得：

• 新模型出现时只需更新 Category 映射，无需修改所有 Skill
• 新 Skill 出现时无需重新配置模型选择逻辑

8 种内置 Category 映射

Category	默认模型	Variant	适用场景
visual-engineering	google/gemini-3.1-pro	high	前端、UI/UX、设计、动画
ultrabrain	openai/gpt-5.5	xhigh	深度逻辑推理、架构决策
deep	openai/gpt-5.5	medium	自主研究和端到端执行
artistry	google/gemini-3.1-pro	high	高度创意/艺术任务
quick	openai/gpt-5.4-mini	-	单文件修改、错字修复
unspecified-low	anthropic/claude-sonnet-4-6	-	未分类的低难度任务
unspecified-high	anthropic/claude-opus-4-7	max	未分类的高难度任务
writing	kimi-for-coding/k2p5	-	文档、技术写作

当使用 Category 时，系统创建一个特殊 Agent Sisyphus-Junior 来执行任务。Sisyphus-Junior 的模型由 Category 决定，且禁止再委托其他 Agent——防止无限委托链。

双回退系统

Oh-My-OpenAgent 使用两个独立的回退系统：

model-fallback：在调用前根据 provider 健康状态主动选择模型链。适用于已知的 provider 不可用场景。

runtime-fallback：在运行时失败后，按配置的 fallback_models 数组依次重试。支持对象级 fallback——每个 fallback 可指定不同的 variant 和 thinking 配置：

{
  "agents": {
    "sisyphus": {
      "fallback_models": [
        "opencode/glm-5",
        { "model": "openai/gpt-5.5", "variant": "high" },
        { "model": "anthropic/claude-sonnet-4-6", "thinking": { "type": "enabled", "budgetTokens": 64000 } }
      ]
    }
  }
}

问题与规避

模型 ID 格式不一致

问题：不同 Provider 对同一模型的 ID 格式不同（如 anthropic/claude-opus-4-7 vs openai/gpt-5.5），回退链中如果格式不匹配会导致回退失效。

规避：Oh-My-OpenAgent 使用 model-resolver 和 model-normalization 模块统一处理 ID 格式。自定义 fallback 时必须使用 provider/model 格式。

回退模型能力差异

问题：Fallback 模型可能不支持首选模型的工具调用格式或 thinking 模式。

规避：在对象级 fallback 中显式指定兼容的工具格式和 thinking 配置。

设计取舍

Category 路由 vs 直接指定模型

方案	优势	代价
Category 路由	用户无需了解模型，新模型出现时只需更新映射	需要维护 Category 到模型的映射表
直接指定模型	完全控制，无中间层	用户需要了解每个模型的能力差异

推荐：对终端用户使用 Category 路由；对高级用户开放直接指定模型的选项。Oh-My-OpenAgent 同时支持两者。

参考来源

• Oh-My-OpenAgent 配置文档