im.ttalk.agent.chat-model.fallback — im.ttalk/clj-agent-core 0.5.447

主备模型切换（designs/provider-reliability.md §3；Keelson Providers/FallbackChatClient.cs）。

主模型连它自己的重试都耗尽之后，按备用链依次换模型。它是一个 ChatModel 装饰器， 挂在每站 DefaultChatModel（内含重试）的外面、filter 栈的下面：

FallbackChatModel ──┬─ 站 0：主模型（重试 → 取票 → provider）
                    ├─ 站 1：备用（惰性构造）
                    └─ …

• 判据走错误类型（switchable?）：切 5xx 类 :provider-error / :network-error / :timeout-error / :rate-limit-error（重试已耗尽）/ :auth-error / :quota-exhausted-error （额度是逐家的）/ :empty-completion-error / :parse-error；不切 :validation-error （请求本身有错）、:context-overflow-error（换一家照样超长，交压缩恢复）、取消 / 中断。 这一站返回空补全（response/empty-completion?）且还有下一站 → 也切（:switch-on-empty?，缺省真）。
• 流式：只在本站第一个 token 之前切；吐过 token 之后的失败原样抛（同「token 出门不重发」）。
• 跨 provider 剪 thinking：上一站与本站 ref 的 provider 段不同 → 所有消息 dissoc :blocks （Anthropic thinking 签名、Responses reasoning item 等不透明回放载荷，别家原样收到只会 400）。 同家换模型不动。
• 换站去掉 :options :model：备用站用它自己的 model-options，不拿主模型的名字问备胎。
• 惰性构造：:create 轮到才调、每站只调一次；构造抛错 = 这一站自己的配置问题，不看判据、 有下一站就硬切。
• 报账：成功响应 assoc :model-ref ref :fallback report；全链失败原样抛最后一个错误， ex-data 追加 :fallback report。读法 report。

(fallback/fallback-chat-model
  primary-cm
  [{:ref "openai/gpt-4o" :create (fn [] (cm/create-chat-model openai-p {:model "gpt-4o"}))}
   {:ref "deepseek/deepseek-chat" :chat-model ds-cm}]
  {:primary-ref "anthropic/claude-sonnet-4"
   :on-switch (fn [{:keys [from to error]}] (log/warn from "→" to (:message error)))})

fallback-chat-model clj

(fallback-chat-model primary alternatives)

(fallback-chat-model primary alternatives opts)

包一个主模型 + 备用链成 ChatModel。

• primary: 主模型（任意 ChatModel 或 {:chat-fn …} map）
• alternatives: [{:ref "provider/model" :create (fn [] chat-model)} …]，:create 惰性； 也可直接给 :chat-model（现成实例）。按切换次序。空 → 本层等于直通（仍报账）。
• opts:
  • :primary-ref 主模型 ref；缺省从 DefaultChatModel 的 provider-name + :model 推，推不出为 "primary"
  • :switch? (fn [throwable] bool) 覆盖判据（缺省 switchable?）
  • :on-switch (fn [{:keys [from to error]}]) 每次真要换站前通知
  • :switch-on-empty? 本站返回空补全且有下一站时切换（缺省 true）

from-registry clj

(from-registry reg ref {:keys [create alternatives] :as opts})

按注册表（im.ttalk.agent.model.spec）造「主 + 备用链」：备选 = opts 的 :alternatives ?? spec/fallback-chain；每站（含主模型）都经 (create spec) 造 ChatModel——想给备选也套重试 / 票据就在 create 里套。主模型立即造，备选惰性造；没登记的备选 ref 轮到才报错（硬切下一站）。

opts 另可带 fallback-chat-model 的全部 opts。

report clj

(report x)

这一趟的切换账：传响应（成功时）或异常（全链失败时）。没经过本层 → nil。

{:primary 主模型 ref :model 真答话的 ref :switches 换了几次 :attempts [{:ref :error canonical-error} …] :trail ["a → b：原因" …]}

switchable? clj

(switchable? t)

这一类失败值不值得换一家（见 ns 文档）。