模型与账号接入

dsh-llm-fallbacks

btspoony/dsh-llm-fallbacks · ★ 26

btspoony精选

基于角色的模型重试与备用策略。

许可证
MIT
收录
2026-08-13
维护状态
active
安装方式
github
查看 manifest 检查详情
manifest 状态
已声明
manifest 路径
package.json#dsh
manifest 检查
2026-08-19
生命周期脚本
未发现

manifest 静态检查只记录声明与安装脚本,不代表兼容性或安全审查。

安装

dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks

GitHub 源码安装:首次需按提示配置 allowBuilds 构建授权后重试

安装与环境配置指引、插件开发教程见 DSH 中文社区文档 ↗

项目说明

原始 README · 正文语言:中文 · 阅读英文 README

目录
  1. dsh-llm-fallbacks
  2. 三项核心能力
  3. 自动模型降级
  4. 峰谷无忧(分时切换)
  5. 角色化 subagent
  6. 快速开始
  7. 安装
  8. 配置
  9. 验证
  10. 能力一览
  11. 纯挂载
  12. 文档
  13. 许可

preview

dsh-llm-fallbacks

English | 中文

npm license node pnpm dsh tui dsh dshfind

dsh(DeepSeek Harness)的自动模型降级插件:插件注册 N 条命名虚拟链,每条在模型选择器中都是一行 FallbacksChain / <链 id>——选择某条链的会话沿该链行走,llm 请求在列出的失败码上持续失败(权限错误、配额超限、限流 429 等)时,请求会在下一个可用 provider/model 上重试,任务不会因模型问题中断。选择真实 provider/model 的会话没有插件降级,只由 llm-retry 处理。在 Fallbacks 设置卡中创建链,然后选择它的 FallbacksChain / <id> 行即可。

两个 dsh 前端均可用:web profile(设置 → 插件配置 → Fallbacks 卡片)与 dsh-tui 终端 profile(/fallbacks 会话诊断、/fallbacks config 回读、/settings 的 fallbacks 分区用于编辑)。

三项核心能力

自动模型降级

会话模型选择走 FallbacksChain / <链 id> 时——root agent 选中该行,或子代理的角色以「指定降级链」指向该链——沿该链行走:请求在输出任何内容之前命中触发码,就在同一个请求内改到下一个可用 provider/model,step 继续运行。选择真实 provider/model 的会话不获得任何插件降级。无需手动切换模型;在配置链之前(chains 为空是唯一初始状态)插件不做任何事。

  • 谁能拿到链:只有模型选择走 FallbacksChain / <链 id> 的会话。包括选中该行的 root agent,以及角色「指定降级链」指向该链、分发时被盖章到该行的 subagent(本地 backend、请求上没有显式路由)。真实 provider/model 选择——无论 root 还是 subagent——完全交给 llm-retry。
  • 触发:triggerCodes(默认 AUTH / QUOTA / RATE_LIMIT)——任何 dsh 失败码都可用,包括 CONTEXT_WINDOW_EXCEEDED(会降级到上下文窗口更大的候选)。可重试失败(5xx、TRANSPORT、TIMEOUT 等)先交给 llm-retry;它的每次重试都会重新进入 walk,并从刚进入冷却的链头之后开始。
  • 已输出即提交:第一个输出 chunk 即提交该尝试——block start 算输出,usage 元数据块不算——提交之后的失败不会在该请求内切换,已产出的输出无法撤回。失败上抛给 loop;恢复路径是 llm-retry 重入(新的一次 walk)或终止失败。
  • 恢复:失败或被切走的模型在 cooldownMs 内不再被选中,revertPolicy: cooldown-expiry 在冷却到期后回到主模型;可选的 recovery: half-open 模式(YAML-only)把这次回归改为证据驱动,而非定时器驱动。
  • 保险丝:maxSwitchesPerStep 限制单次请求 walk 的切换次数(尝试数 ≤ 上限 + 1)——链式循环不会放大延迟。
  • 可见性:每次切换都写入 info 日志(from/to/role/reason/candidates),不存在静默切换。

→ 自动模型降级 · 上下文窗口降级

峰谷无忧(分时切换)

分时槽按链配置(chains[].timeSlots),按墙钟窗口轮换该链自己的生效条目:第一个窗口包含当前时刻的行作为优先段,在下一个请求里先于该链的 entries 走;默认降级链与默认模型(官方保底)始终接在其后。无行命中时,该链自己的条目作为最后兜底。轮换是路由种子而非失败决策:不消耗冷却,也不影响失败降级(fallback switch)。

Fallbacks 设置卡片:每条链一个 tab,各自带 分时槽设置 → 默认降级链 → 默认模型 区块与保存按钮

图为当前设置卡片的结构:每条链一个 tab(+ 新建、⋯ 改链名标签或删除链),选中 tab 内是 链名称 字段与逐链区块 分时槽设置 → 默认降级链 → 默认模型,由该链自己的 放弃修改/保存 按钮写入。子代理 区每个角色是一张可折叠的角色卡,另有自己的保存按钮。卡片在角色列表下方还有一个可折叠的 高级选项 区块(图中未画出)。

四个冻结的 UTC+8 预设(窗口是代码常量)。fallbacks.tz 是所有行窗口的判定时区;存在预设行时,卡片在自定义行里只读展示该时区(Asia/Shanghai (UTC+8)):

预设 窗口
liang-peak 周一至周五 09:00–12:00 与 14:00–18:00
liang-valley 其余所有 UTC+8 时间(梁高峰的补集)
glm-peak 周一至周五 14:00–18:00
glm-valley 其余所有时间(GLM 高峰的补集)

GLM Peak / GLM Valley 仅在配置了 zai-coding-cn 时才会出现在卡片选择器中。自定义行使用 start / end(HH:mm,可跨午夜)与可选 days 列表。

→ 分时槽

角色化 subagent

subagent 的角色由分发提示词声明——Assignment 头部字段 **Execute as**: <id>;它与 roles.list 中已声明的角色 id 匹配。只有这个已声明头部才解析出角色:persona 以 system-prompt 分区安装到子代理,子会话恰好写入一行 [role: <id>] 通知行,会话头部显示角色徽章。

角色身份只在分发时从一个来源解析——派发声明的 **Execute as**: <id> 头部——因此分发提示词声明了已声明角色 id 的子代理会拿到该角色的 persona、恰好一行 [role: <id>] 通知行与徽章。完全没有声明分发头部的子代理是未指定:没有 persona、通知行与徽章角色半边——插件也不干预。角色还可携带手动链指针(「指定降级链」):分发时 seam 把本地、无显式路由的子代理盖到 FallbacksChain / <role.chain> 上——带显式路由的请求属于已授权,插件永不改写;外部 backend 的子代理保持纯继承。没有规则匹配,也没有宿主策略咨询:映射就是你的静态配置。

这一套同时覆盖普通 subagent 分发与 Agent Team 队友:两者都是带着同一头部(由模型写入)经同一分发 seam 创建的子代理,不需要任何按机制区分的配置。

→ 角色化 subagent

快速开始

安装

Desktop / Web 插件页——在 DeepSeek Harness(Desktop 应用或 dsh web 会话)中打开侧边栏的插件(Plugins)页,点击添加插件,输入包名 dsh-llm-fallbacks,点击安装,然后按宿主的重启提示操作。该向导接受包名(即 npm 包名)、GitHub repo 或本地目录——registry 安装只需填包名。GUI 安装写入 web profile,与下方 --profile web 指向同一个 profile。

CLI——适用于脚本化环境或终端前端:

dsh plugin --profile web add dsh-llm-fallbacks      # web profile(设置 → Fallbacks 卡片)
dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui 终端 profile

dsh-tui 没有自己的插件页,只能走 CLI。可用 @<version> 固定版本。registry 安装拉取已构建包(dist/),目标机器不执行构建。registry / git / 本地目录三种安装方式、卸载与 --dump-config 校验 → docs/install.md。插件同时提供本地化元数据(Plugins 详情页的标题/描述,英文 + 简体中文)与图标——两者都在包内声明(locale/*.json + icon.svg),由宿主自动识别。

配置

插件的设置存放在共享的 fallbacks: 命名空间,可从三个界面编辑:

界面 说明 备注
Web 设置卡片 设置 → 插件配置 → Fallbacks fallbacks: 命名空间的完整 GUI 编辑器,写入共享设置文档
$DSH_HOME/settings.yaml dsh 设置文档中的 fallbacks: 分区 共享的事实来源——与 web 卡片写入同一文件;任何环境都可读写,脚本化配置亦可
TUI /settings dsh-tui 设置界面中的 fallbacks 分区 需要 dsh-tui ≥ v0.8.5;简单键使用原生字段,复杂结构使用 JSON 文本字段

(/fallbacks 与 /fallbacks config 是诊断命令——只读视图,不是编辑入口。)最小配置如下:

fallbacks:
  chains:                  # 命名虚拟链:每条 = picker 一行(FallbacksChain/<id>)
    - id: Auto             # picker 模型 id(大小写敏感、唯一)
      label: 默认链         # tab 标题 + picker 前缀(仅展示)
      entries:             # 默认降级链 …末尾是默认模型(恰好一个官方模型)
        - anthropic/claude-3-5-sonnet
        - deepseek-official/deepseek-v4-pro
      timeSlots: []        # 可选:该链自己的分时行
    - id: Coding
      label: 编码
      entries:
        - openai/gpt-4o-mini
        - deepseek-official/deepseek-flash
  roles:                   # 可选:角色身份 + 可选链指针
    list:
      - id: reviewer
        persona: Code-review subagents
        chain: Coding      # 指定降级链:该角色派发的子代理挂到 FallbacksChain/Coding

三条要点:

  • 没有功能开关:只要配置了链(chains 非空)插件才介入;空配置是完全的 no-op,Plugins 页的行开关是总开关。
  • 每条链的末项(默认模型)必须恰好是一个官方模型——四个 id 之一:deepseek-account/deepseek-flash、deepseek-account/deepseek-v4-pro、deepseek-official/deepseek-flash 或 deepseek-official/deepseek-v4-pro;前部「默认降级链」条目优先进走。该要求只针对非空 entries:空 entries 网关也会接受(行仍出现在选择器中,walk 以 EMPTY_EFFECTIVE_CHAIN 拒绝),而卡片要求选好链尾才允许保存。
  • 分时槽与角色都是可选的:第一个窗口命中的分时行是优先段,在该链的 entries(默认降级链 + 官方保底)之前走;角色是已声明的身份加一个可选的 chain 指针(「指定降级链」),root 请求完全不受角色影响。

完整参考(字段、条目语法、选择器规则、迁移)→ docs/configuration.md。

升级提示(破坏性变更):配置级 enabled 开关已移除——仍带 enabled: true/false 的存量分区可正常加载(该键被忽略并在下次保存时剔除),但开关不再有任何作用。若此前依赖 enabled: false 让插件保持静默,请改为清空该分区(或关闭 Plugins 页的插件行)。

验证

保存配置并重启会话,然后输入 /fallbacks——只读的会话诊断(来源、解析出的角色、链、最近的降级、冷却状态)。在 dsh-tui profile 下,/fallbacks config 会回读组合后的配置。

能力一览

  • 自动降级(仅虚拟路由)——FallbacksChain / <id> 会话(root 或角色盖章的 subagent)命中触发码时沿链切换,step 继续运行;真实模型会话没有插件降级。 → 详情
  • 上下文窗口感知降级——CONTEXT_WINDOW_EXCEEDED 会切到窗口更大的候选;该切换是请求级的(不消耗冷却)。 → 详情
  • 峰谷无忧(分时槽)——四个冻结的 UTC+8 预设或自定义窗口轮换该链自己的生效条目。 → 详情
  • 角色化 subagent——派发声明的角色为子代理带来 persona、通知行与徽章,其可选的 chain 指针把子代理挂到 FallbacksChain/<id>。 → 详情
  • 模型选择器中的 FallbacksChain——选择 FallbacksChain / <链 id> 即由配置链承载该会话;选择真实模型则只由 llm-retry 处理,没有插件降级。 → 详情
  • 五个内置预设角色——reviewer / scout / security-reviewer / sonic / task,随 apply 自动声明。 → 详情
  • dsh-tui 操作面——/fallbacks、/fallbacks config,以及与 web 卡片等价的 /settings 分区。 → 详情

纯挂载

插件以纯挂载方式安装:bundle 插入 + client 注入 + 自有 gateway 通道(/api/fallbacks/get|set|reset)——不修改 dsh 源码、没有 postinstall,dsh 升级也无需重新打补丁。旧版打过补丁的安装残留补丁无害。

文档

文档 内容
docs/install.md 桌面/Web 插件页 / profile 安装(web + dsh-tui)/ registry / git / 本地目录 / 卸载 / --dump-config 校验
docs/configuration.md fallbacks 命名空间完整参考、选择器语法、示例 YAML、插件配置卡片用法、TUI 回读、行为说明、预设角色
docs/features.md 能力参考:降级、上下文窗口降级、分时槽、角色化 subagent、选择器、预设角色、agent 预设、dsh-tui
docs/repair.md 会话日志修复:拒载类别、--apply 发布、参数、退出码、有损 --drop-legacy-events
docs/consumer-api.md 开发者消费契约:库 API + 具名 llm-fallbacks 服务 + 角色种子、导出清单、生命周期、类型
docs/release.md 发布流程:Trusted Publishing 配置、Release prep SOP、fragment 格式、回滚
docs/verification.md 验证记录(测试矩阵、bundle 层序、运行时契约、QA 门禁脚本)
CHANGELOG.md 已发布变更,由 .changes/ 的 fragment 汇总生成

许可

以 MIT 许可发布——见 LICENSE。版权与许可条款以 LICENSE 文件为准。