前言¶

在 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