模型 Fallback 机制

model-fallback.ts 实现了完整的模型降级策略。

关键函数

• runWithModelFallback<T>(params) — 文本模型降级
• runWithImageModelFallback<T>(params) — 图像模型降级
• resolveFallbackCandidates(params) — 构建候选列表

降级策略

候选列表构建:
  1. 当前请求的 provider/model（强制包含，不检查 allowlist）
  2. config.agents.defaults.model.fallbacks 列表（检查 allowlist）
  3. 如果无 fallbacksOverride，追加 primary model

执行逻辑:
  for candidate in candidates:
    if all profiles in cooldown → skip
    try: result = await run(candidate)
    catch:
      if AbortError (非 timeout) → 直接抛出
      coerceToFailoverError() → 如果不是 FailoverError → 直接抛出
      记录 attempt → 继续下一个
  throw Error("All models failed")

FailoverError 分类

类型	说明
auth	认证失败
rate_limit	速率限制
timeout	超时
billing	计费问题
context_overflow	上下文溢出
unknown	未知错误

技巧

在 run.ts 中，认证失败会先尝试 profile 轮转，轮转失败后才抛 FailoverError 触发模型降级。这避免了不必要的模型切换。