前言¶

在 DeepSeek Harness（DSH）裏跑智能體時，模型請求失敗並不少見：重試耗盡、鑑權錯誤、配額用盡、429 限流等。常見做法是手動改配置或中斷當前任務換模型，步驟繁瑣，也容易打斷正在進行的對話步驟。

下面介紹社區插件 dsh-llm-fallbacks（維護者 omdsh-dev）。它在 DSH 網關側爲當前角色維護一條 provider/model 備用鏈：當請求持續失敗時，沿鏈切換到下一個模型，當前 step/turn 在目標模型上繼續，任務不因模型問題而中斷。

這是什麼¶

dsh-llm-fallbacks 是 DSH 的模型推理類插件，npm 包名 dsh-llm-fallbacks，當前版本 0.3.5，MIT 許可證，要求 Node.js ≥ 22。插件兼容 DSH 0.1.1-rc.2 及 dsh-tui。

它解決的核心問題是：按角色（含根請求與子智能體）定義失敗後的模型切換策略，並支持按時段輪換「有效根鏈」。配置寫入共享的 fallbacks: 命名空間，Web 與終端前端均可編輯。

核心功能¶

失敗時沿備用鏈切換¶

當智能體的 LLM 請求反覆失敗（重試耗盡、auth、quota、rate limit 等），插件按當前角色配置的鏈依次嘗試下一個 provider/model，當前步驟在目標模型上繼續執行。

根鏈與 Default 模型¶

rootChain 定義全天默認鏈：前面的條目是失敗時依次走到的備用模型，最後一項是 Default 模型。規範要求鏈尾必須是官方 V4 之一：deepseek-official/deepseek-v4-flash 或 deepseek-official/deepseek-v4-pro（二選一）。設置卡片與網關在保存時會校驗鏈尾；舊配置若鏈尾不符合規範，啓動時會告警但仍可作爲純備用鏈工作，無法原樣保存。

時段（Time slots）¶

可選 timeSlots 按牆鍾窗口輪換有效根鏈：每條時段行自帶一條鏈，當前時刻落入某行窗口時，下一次根請求使用該行的鏈替代全天 rootChain；無匹配時段時仍用全天鏈。時段切換隻影響路由種子，不消耗冷卻，失敗時的 fallback 行走邏輯不變。

內置四套 UTC+8 預設（窗口爲代碼常量，預設行鎖定 tz 爲 Asia/Shanghai）：

glm-peak / glm-valley 僅在配置了 zai-coding-cn 時出現在卡片選擇器中。也可自定義 start/end（可跨午夜）與 days。

角色與規則¶

roles 可爲子智能體聲明獨立鏈與規則：rules 僅匹配子智能體請求，不匹配根請求。角色可設置 fallback: inherit-root，先走角色鏈再走繼承的根鏈。

雙前端支持¶

同一插件包，通過 --profile 區分安裝目標：

• Web：Settings → Plugins → Fallbacks 卡片
• dsh-tui：/fallbacks 會話診斷、/fallbacks config 只讀回顯、/settings 中 fallbacks 段編輯（需 dsh-tui ≥ v0.8.5）

共享配置源爲 $DSH_HOME/settings.yaml 中的 fallbacks: 段。

安裝與啓用¶

在對應 profile 下安裝（registry 安裝拉取已構建的 dist/，目標機無需編譯）：

dsh plugin --profile web add dsh-llm-fallbacks      # Web：Settings → Fallbacks 卡片
dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui 終端

可用 @<version> 固定版本。卸載、--dump-config 校驗等見倉庫 docs/install.md。

0.2.2 之前版本升級注意：舊版會寫入持久化 fallbacks/switch 會話事件，較新 DSH 可能因此無法打開會話。需先停止 dsh，在克隆的倉庫目錄執行修復腳本（--dry-run 預覽，--apply --backup 應用）。自 0.2.2 起插件不再寫入該類事件。

插件默認關閉：fallbacks.enabled 爲 false 時插件爲 no-op，須顯式開啓並配置鏈後才生效。

典型用法¶

在 $DSH_HOME/settings.yaml 增加 fallbacks: 段。下面是最小可運行示例的結構說明。

1、開啓插件

fallbacks:
  enabled: true

2、配置全天根鏈

  rootChain:
    - anthropic/claude-3-5-sonnet          # 失敗時先嚐試
    - deepseek-official/deepseek-v4-flash  # 鏈尾 Default（Flash 或 Pro 二選一）

3、（可選）按時段換鏈

  timeSlots:
    - kind: preset
      preset: liang-peak
      chain:
        - anthropic/claude-3-5-sonnet
    - kind: custom
      name: evening
      start: '22:00'
      end: '02:00'
      days: [1, 5]
      chain:
        - openai/gpt-4o

4、（可選）爲子智能體定義角色

  roles:
    list:
      - id: reviewer
        persona: Code-review subagents
        chain:
          - openai/gpt-4o-mini
        fallback: inherit-root
    rules:
      - role: reviewer

Web 用戶可在設置卡片中圖形化編輯同一命名空間；終端用戶可用 /settings 編輯簡單字段，複雜結構使用 JSON 文本字段。

適用場景與注意¶

適合誰：長期在 DSH 上跑多模型、多 provider 的智能體；需要峯谷時段自動換主模型；希望子智能體（如 reviewer）使用與主會話不同的備用策略。

使用注意：

• 插件以當前 dsh 進程權限運行，安裝前請閱讀 源碼 與 MIT 許可證，確認行爲符合預期。
• 社區目錄 SkillHub 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；插件列表與 GitHub 倉庫（約 16 stars）供選型參考。
• 鏈尾 Default 模型必須符合官方 V4 規範，否則無法通過 Web/網關保存。
• /fallbacks 與 /fallbacks config 爲診斷只讀，不能替代設置卡片或 YAML 編輯。

結尾¶

經過上面的步驟，DSH 在模型層失敗時可以不中斷任務、按角色與時段自動切換備用模型。dsh-llm-fallbacks 把「重試耗盡後怎麼辦」收斂到可配置的 fallbacks: 命名空間，Web 與 dsh-tui 共用同一套配置。

• 目錄頁：https://www.skillhub.cn/plugins/omdsh-dev/dsh-llm-fallbacks
• GitHub：https://github.com/omdsh-dev/dsh-llm-fallbacks