Skip to main content

Router 省钱路由

Router 是 PilotDeck 的智能模型路由引擎。它根据任务复杂度自动选择最合适（最经济）的模型，同时提供多 Provider Fallback 容错机制，确保服务持续可用。

核心能力​

TokenSaver 智能降档

分析用户输入的复杂度，自动选择匹配的模型档位，简单任务用便宜模型

Fallback 容错链

主 Provider 不可用时，自动切换到备用 Provider，用户无感知

Scenario 场景路由

根据 Agent 类型（主 Agent / 子 Agent）应用不同的路由策略

Custom Router 扩展

支持自定义路由插件，实现你自己的路由逻辑

路由决策流程​

Router 的每次路由决策经过以下阶段：

User Request1. Custom Routeroptional plugin overridecustom provider/model wins2. Scenario Decisionexplicit / default / subagentexplicit route skips tiering3. TokenSaver Gateenabled, non-explicit, no custom overridereuse sticky tier first; otherwise judge complexityselects provider / model / tierRouterDecision{ provider, model, tier, scenarioType }

TokenSaver 智能降档​

TokenSaver 是 Router 最核心的省钱能力。它通过分析用户消息的复杂度，将请求分配到不同的模型档位 (Tier)。

工作原理​

  1. Judge 判定：使用一个轻量级模型（Judge）分析用户请求的复杂度
  2. 档位匹配：根据判定结果选择对应的模型档位
  3. Sticky 绑定：同一会话的后续请求保持相同档位（除非用户明确切换）

档位示例​

档位适用场景模型示例
high复杂架构设计、多文件重构Claude Sonnet 4.5
medium常规编码、Bug 修复Claude Sonnet
low简单问答、文件查看Claude Haiku

配置 TokenSaver​

router:
  tokenSaver:
    enabled: true
    subagent:
      policy: judge    # skip | judge | always-low
    tiers:
      high:
        provider: anthropic-main
        model: claude-sonnet-4-5
      medium:
        provider: anthropic-main
        model: claude-sonnet-4-20250514
      low:
        provider: anthropic-main
        model: claude-haiku

Fallback 容错链​

当主 Provider 返回错误（超时、限流、服务不可用等）时，Router 自动切换到 Fallback 链中的下一个 Provider。

可触发 Fallback 的错误类型​

  • timeout - 请求超时
  • rate_limit - 达到速率限制
  • server_error - 服务端 5xx 错误
  • network_error - 网络连接问题

配置 Fallback​

router:
  fallback:
    default:
      - provider: openai-backup
        model: gpt-4o
      - provider: deepseek-backup
        model: deepseek-chat

重试策略​

Router 还内置了两种重试机制：

对同一 Provider 的瞬时错误进行指数退避重试：

router:
  transientRetry:
    enabled: true
    maxAttempts: 5
    baseDelayMs: 1000
    maxDelayMs: 30000

Scenario 场景路由​

Router 根据 Agent 角色应用不同的路由策略：

场景类型说明
default默认场景，使用 agent.model 配置的模型
explicit用户或系统明确指定的模型
subagent子 Agent 调用，可应用独立的路由策略

子 Agent 的路由策略通过 tokenSaver.subagent.policy 控制：

  • skip：子 Agent 不经过 TokenSaver，使用默认模型
  • judge：子 Agent 也经过 Judge 判定（默认）
  • always-low：子 Agent 始终使用最低档位

Auto-Orchestrate（自动编排）​

当 TokenSaver 生效时，Router 可以自动调整 System Prompt 和工具列表，针对低档位模型优化任务执行：

router:
  autoOrchestrate:
    enabled: true
    skillExtensionId: "my-skill-extension"
    subagentMaxTokens: 50000

统计面板​

Router 内置 Token 使用统计收集器，记录每次请求的模型选择和 Token 消耗：

// 获取统计数据
const stats = router.stats;
// 包含: sessionId, provider, model, tier, role, usage, timestamps

事件总线​

Router 在关键节点发出事件，便于监控和调试：

事件说明
pilotdeck_router_decision路由决策完成
pilotdeck_router_fallback触发 Fallback 切换
pilotdeck_router_token_saver_failedTokenSaver 判定失败
pilotdeck_router_zero_usage_retry空响应重试
pilotdeck_router_transient_retry瞬时错误重试
pilotdeck_router_execute_failed执行最终失败
pilotdeck_router_custom_failed自定义路由器失败