模型与账号接入
dsh-llm-fallbacks
btspoony/dsh-llm-fallbacks · ★ 26
基于角色的模型重试与备用策略。
查看 manifest 检查详情
安装
dsh plugin --profile web add github:btspoony/dsh-llm-fallbacksGitHub 源码安装:首次需按提示配置 allowBuilds 构建授权后重试
安装与环境配置指引、插件开发教程见 DSH 中文社区文档 ↗
项目说明

dsh-llm-fallbacks
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)。
图为当前设置卡片的结构:每条链一个 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 创建的子代理,不需要任何按机制区分的配置。
快速开始
安装
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 文件为准。