force-push/dsh-llm-fallback

@deepseek-ai/dsh-llm-fallback

自愈式跨提供方模型回退。当一次模型请求以可治愈的失败码告终、且原地重试已经耗尽时，插件会选中链上的下一个回退目标，并通过运行时模型选择器所用的同一条 agent/request waterfall 把重试重新绑定到该目标——会话将在健康的模型上继续，而不是直接失败。

工作方式

插件监听两个 agent 作用域的 waterfall：

- agent/request-error——恢复决策点。插件挂载在 @deepseek-ai/dsh-llm-retry 之后，只会看到策略委派下来的失败：已耗尽的重试预算、落在 healOn 内的不可重试失败码，或超出上限的提供方延迟。它会选出第一个存活且尚未尝试过的回退目标，追加一条持久化的非表面 llm/fallback 事件，并返回 { kind: 'retry' }。
- agent/request——重绑定点。治愈生效期间，请求配置会被改写为回退路由；配置的 reasoningEffort 随请求发送，缺省时清除任何继承的 effort（与运行时模型选择器语义一致）。

always 模式的主路由通过委派获得尊重：它绝不会在本插件上 settle，因此链应当监视 normal 模式策略的路由。显式的运行时模型选择优先于治愈——第一次选择即令治愈自解除。

每个决策都是持久的：llm/fallback 事件记录失败的提供方、失败事实与选中的回退，远端渲染器无需加载本运行时即可展示治愈过程。

配置

组合条目提供 base；用户设置文档中的 llm-fallback 分节会在下一次失败时整体替换它（无需重启）：

llm-fallback:
chains:
- primary: { provider: z-ai-glm-53-flash }
fallbacks:
- { provider: openrouter, model: nvidia/nemotron-3-ultra-550b-a55b:free }
- { provider: openrouter, model: minimax/minimax-m3:free }
healOn: [SERVER, TIMEOUT, TRANSPORT, RATE_LIMIT, EMPTY_RESPONSE, INVALID_REQUEST]
sticky: true

| 字段 | 含义 |
| --- | --- |
| chains | 有序的治愈链；空列表使插件保持休眠。 |
| chains[].primary | 被监视的路由。model 缺省时监视该提供方路由上的所有模型。 |
| chains[].fallbacks | 有序目标；每项需要 provider 与 model，可选 reasoningEffort（off/low/high/max）。 |
| healOn | 触发治愈的失败码；其余失败码委派给下游。 |
| sticky | true 在 agent 余下生命周期内保持治愈；false 在治愈所在回合关闭时重新绑定 agent 自身的路由。 |

格式错误的分节会在写入处被拒绝——设置写入失败时会指明出错的链与字段。

安装

在 DeepSeek Harness 包发布到 npm 之前，将本仓库以 vendored 方式放入 DSH checkout：

git clone https://github.com/force-push/dsh-llm-fallback.git packages/llm/llm-fallback
pnpm install && pnpm run build:lib:host

harness 包发布后，npm install dsh-llm-fallback 即可替代 vendored 方式。

挂载

在宿主组合（或 profile patch）中把插件放在 llm-retry 之后：

- id: llm-fallback
name: '@deepseek-ai/dsh-llm-fallback'

回退路由必须是已注册的适配器路由——@deepseek-ai/dsh-llm-pi-ai 的已配置提供方路由或任何其他适配器家族。治愈时刻会跳过指向未注册路由的条目。

语义与限制

- 原地重试优先。 只有被监视路由自身的重试策略在该步骤耗尽后，才会查询链。
- 部分失败立即治愈。 原地重试无法修复的失败码（INVALID_REQUEST 一类的拒绝）在第一次出现时即治愈。
- 不检查上下文容量。 小于会话的回退模型将在上下文上失败；请有意地与 compaction 组合。
- Agent 回合是治愈边界——直接消费 ctx.llm.stream() 的调用方只有一次尝试，与 dsh-llm-retry 一致。
- 治愈会掩盖配置错误。 错误的 effort 表或端点会表现为被治愈掉的失败；持久化事件就是审计线索。
- 治愈需要已有路由。 链监视的是模型请求；未配置 provider/model 的 agent 会更早失败——在系统提示词组装或分发阶段——那时还没有任何可供治愈的请求。此类 agent 应从部署的 agent-default-model 取默认路由，或在挂载组合中显式固定路由。