@magic6/dsh-llm-resilience 0.0.0-stage → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,279 @@
1
+ # dsh-llm-resilience
2
+
3
+ [English](https://github.com/T-splines/dsh-llm-resilience/blob/main/README.md) | **简体中文**
4
+
5
+ **让不稳定的 LLM 网关表现得像可靠的一样——DeepSeek Harness 的按 target 重试、流式安全回退链与持久化熔断。**
6
+
7
+ 这个插件来自作者部署中实际遇到的失败场景:**OpenDesign Go** 的工具调用流与 API 连接会
8
+ 间歇性不稳定。一条工具调用流损坏、一次传输中断,或者一次以普通 500 返回的会员/额度错误,
9
+ 就可能让整个 agent step 失败。DSH 内置的 `retryPolicy` 是 provider 级的:它能对同一条路由
10
+ 退避,但不能换 provider/model,也没有熔断。在日常使用中,这个插件把 OpenDesign Go 从
11
+ **基本不可用**提升到了**基本可靠可用**:安全的重试吸收瞬时故障;网关额度耗尽或坏掉时由
12
+ 备用 provider 接手;持久化熔断器阻止继续打一个已经死掉的上游。
13
+
14
+ > 本插件是独立项目,与 OpenDesign、DeepSeek 没有隶属或背书关系;
15
+ > OpenDesign Go 只是促成这套设计的实际部署场景。该失败模式并非它独有:任何会间歇性
16
+ > 损坏工具调用流、或把额度错误伪装成普通 500 的网关,都适用同一条链。
17
+
18
+ - [为什么需要它](#为什么需要它)
19
+ - [差异点](#差异点)
20
+ - [注册了什么](#注册了什么)
21
+ - [安装](#安装)
22
+ - [配置](#配置)
23
+ - [错误分类](#错误分类)
24
+ - [流式输出、工具调用与整步重放](#流式输出工具调用与整步重放)
25
+ - [熔断](#熔断)
26
+ - [设置页](#设置页)
27
+ - [边界与不做的事](#边界与不做的事)
28
+ - [测试](#测试)
29
+ - [兼容与迁移](#兼容与迁移)
30
+
31
+ ## 为什么需要它
32
+
33
+ DSH 的 `retryPolicy` 已经在 provider 级重试,但:
34
+
35
+ - 退避倍率固定为 2,不能配 1.5;
36
+ - `agent/request-error` 只能重试**同一条路由**,不能换 provider/model;
37
+ - 没有熔断:一个 provider 整体不可用时,每个 step 仍然先打它;
38
+ - `MALFORMED_RESPONSE`(工具调用流损坏)与工具**执行**失败需要分开处理。
39
+
40
+ 本插件注册一个合成 provider route(默认 `fallback`,模型 `auto`),内部按链调用真实
41
+ provider/model:
42
+
43
+ ```
44
+ fallback/auto
45
+ ├─ target 0: primary-gateway/your-model 独立重试预算 + 独立熔断
46
+ ├─ target 1: backup-provider/your-model 独立重试预算 + 独立熔断
47
+ └─ target 2: local/your-model 独立重试预算 + 独立熔断
48
+ ```
49
+
50
+ 每个 target 有自己的重试预算、退避曲线和熔断;切到下一个 target 时退避从头开始,
51
+ 不继承上一条已经翻倍过的延迟。
52
+
53
+ ## 差异点
54
+
55
+ - **每个 target 独立重试。** `maxRetries` / `initialDelayMs` / `multiplier`(支持 1.5)/
56
+ `maxDelayMs` / `jitterRatio` 都按 target 配置。
57
+ - **按错误类型决策。** 以 `SERVER` 500 返回的会员/额度错误直接 fallback;普通
58
+ 500/超时/传输错误重试;请求本身无效直接失败,不换 target。`codeActions` 可以覆盖默认表。
59
+ - **流式安全的工具调用。** 文本/推理增量立即透传;tool-call 的 block-start/delta 缓冲到
60
+ `block-end` 才交付。因此工具参数非法(没有 block-end)时可以丢弃缓冲并重试,
61
+ 宿主不会看到重复输出。
62
+ - **整步重放续点。** 内容已经交付后再失败,不能在同一请求内换 target;插件记住
63
+ `sessionId + 请求指纹`,宿主重放同一步时从下一个 target 开始,并且计划是**轮转**而不是
64
+ 截断,覆盖整条链。失败的是链尾时原地重试它——绝不把可重试失败改写成终态
65
+ `FALLBACK_EXHAUSTED`。
66
+ - **持久化熔断,按 provider + model 记账。** 连败 N 次锁一个时间窗;到期进入 half-open
67
+ 探活(前台或后台)。状态原子写进 `stateFile`,多进程用锁 + tombstone 合并,
68
+ 重启不会忘掉尚未达到阈值的连败计数。
69
+ - **全局预算。** `limits.maxTotalMs`(默认 10 分钟)与 `limits.maxAttempts`(默认 50)
70
+ 跨 target、跨重试累计;退避等待也计入 deadline。任何 target × 重试的组合都不能把一步
71
+ 拖到无上限。
72
+ - **请求级恢复码原样透传。** `IMAGE_OFFLOAD_REQUIRED`(含 `offloadImages`)与
73
+ `CONTEXT_WINDOW_EXCEEDED` 原样抛出,让宿主的图片卸载 / 上下文压缩先恢复。
74
+ - **设置页。** 编辑链、上下移动 target、查看每次重试计划、实时看熔断状态
75
+ (`closed / open / half-open / probing`)。
76
+ - **有测试。** 90 个 `node --test` 用例,另有隔离 DSH + 本地假 OpenAI server 的端到端冒烟
77
+ (见 [DESIGN.md](DESIGN.md))。
78
+
79
+ ## 注册了什么
80
+
81
+ | 项 | 值 |
82
+ |:--|:--|
83
+ | 合成 route | `fallback`(可配置) |
84
+ | 合成模型 | `auto` |
85
+ | profile entry id | `llm-fallback`(为设置兼容保持不变) |
86
+ | 包名 | `dsh-llm-resilience` |
87
+ | 默认状态文件 | `$DSH_HOME/storages/llm-resilience/state.json` |
88
+
89
+ `targets: []`(或所有 target `enabled: false`)时 route 仍然注册但保持 dormant:
90
+ 可以先在设置页建链,再启用。
91
+
92
+ ## 安装
93
+
94
+ 要求:DSH `0.2.2-rc.x`、Node.js 20+。
95
+
96
+ ### 从 npm 安装
97
+
98
+ ```bash
99
+ dsh plugin --profile web add @magic6/dsh-llm-resilience
100
+ ```
101
+
102
+ ### 从源码安装
103
+
104
+ ```bash
105
+ git clone https://github.com/T-splines/dsh-llm-resilience.git
106
+ cd dsh-llm-resilience
107
+ dsh plugin --profile web add "$PWD"
108
+ ```
109
+
110
+ 包本身是 bundle(`dsh.bundle.patch`),`llm-fallback` entry 已由 bundle 挂载。**覆盖这个
111
+ entry**,不要再 `insert` 一份。在 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 里整体
112
+ 替换 `config`:
113
+
114
+ ```yaml
115
+ - id: llm-fallback
116
+ name: 'dsh-llm-resilience'
117
+ config:
118
+ enabled: true
119
+ route: fallback
120
+ targets:
121
+ - enabled: true
122
+ provider: primary-gateway
123
+ model: your-model
124
+ maxRetries: 5
125
+ initialDelayMs: 1500
126
+ multiplier: 2
127
+ maxDelayMs: 20000
128
+ jitterRatio: 0.3
129
+ - enabled: true
130
+ provider: backup-provider
131
+ model: your-backup-model
132
+ maxRetries: 3
133
+ initialDelayMs: 1000
134
+ breaker:
135
+ failureThreshold: 5
136
+ lockMs: 3600000
137
+ probe:
138
+ enabled: true
139
+ background: false
140
+ timeoutMs: 10000
141
+ maxTokens: 1
142
+ prompt: 'ping'
143
+ stateFile: '$DSH_HOME/storages/llm-resilience/state.json'
144
+ limits:
145
+ maxTotalMs: 600000
146
+ maxAttempts: 50
147
+ toolCalls:
148
+ retryMalformed: true
149
+ ```
150
+
151
+ 把 `primary-gateway` / `backup-provider` 换成 DSH 模型目录里的真实 provider id(设置页的
152
+ 只读下拉框里能看到)。provider 不存在的 target 会报 `NO_ADAPTER`,链继续往后走,不会假装
153
+ 它服务成功。
154
+
155
+ 然后把 agent 的默认模型指到合成 route:
156
+
157
+ ```yaml
158
+ - id: agent-default-model
159
+ config:
160
+ provider: fallback
161
+ model: auto
162
+ ```
163
+
164
+ 不启动 agent 验证组合树(`web` 是常见 profile 名,换成你自己的):
165
+
166
+ ```bash
167
+ dsh --profile web --dump-config | grep -A8 'id: llm-fallback'
168
+ ```
169
+
170
+ > 用 `--patch` 覆盖已有的 `llm-fallback` 条目时,要把 `targets` 数组写全:DSH 的配置合并
171
+ > 会给省略的数组字段补空默认值,只写 `breaker` 会把链清空。
172
+
173
+ **不要给会员/额度类错误配 10 次重试。** 它们是确定性的 provider 状态,重试同一个 target
174
+ 只会浪费预算,应该在第一次失败后直接 fallback。
175
+
176
+ ## 配置
177
+
178
+ | 字段 | 含义 |
179
+ |:--|:--|
180
+ | `enabled` | 总开关;禁用时 route 仍存在但拒绝请求 |
181
+ | `route` | 合成 provider 名(默认 `fallback`);不能出现在 `targets` 里 |
182
+ | `targets[]` | 有序的 `{ provider, model, enabled, label, maxRetries, initialDelayMs, multiplier, maxDelayMs, jitterRatio }` |
183
+ | `breaker` | `failureThreshold`、`lockMs`、探活参数(`enabled` / `background` / `timeoutMs` / `maxTokens` / `prompt`)、`stateFile` |
184
+ | `limits` | `maxTotalMs`、`maxAttempts`;`0` 表示不限制该维度 |
185
+ | `toolCalls.retryMalformed` | 重试模型输出损坏的工具调用(默认 `true`);工具**执行**失败不支持重试 |
186
+ | `codeActions` | 按稳定错误码覆盖默认动作(`retry` / `fallback` / `fail`) |
187
+
188
+ ## 错误分类
189
+
190
+ | 错误 | 动作 | 理由 |
191
+ |:--|:--|:--|
192
+ | `SERVER` + membership/entitlement/quota/billing/credit/plan | fallback | 确定性账号状态,重试无用 |
193
+ | `SERVER` / `TIMEOUT` / `TRANSPORT` / `RATE_LIMIT` / `EMPTY_RESPONSE` / `STREAM_CLOSED` | retry | 瞬时故障 |
194
+ | `MALFORMED_RESPONSE` | retry | 模型输出损坏;重试整个 LLM 请求是安全的 |
195
+ | `AUTH` / `INVALID_CREDENTIAL` / `MISSING_CREDENTIAL` | fallback | 换一个 provider |
196
+ | `QUOTA` / `ACCOUNT_QUOTA` | fallback | 换 provider / 额度 |
197
+ | `NO_ADAPTER` / `UNKNOWN_MODEL` / `MODEL_NOT_FOUND` | fallback | 该 target 不可用 |
198
+ | `ABORTED` / `CANCELLED` | fail | 调用方取消 |
199
+ | `UNSUPPORTED_OPTION` / `INVALID_REQUEST` / `UNSUPPORTED_CONTENT` | fail | 请求本身的问题,换 target 也修不好 |
200
+ | `IMAGE_OFFLOAD_REQUIRED` | fail(原样抛出) | 宿主的图片卸载恢复必须看到它 |
201
+ | `CONTEXT_WINDOW_EXCEEDED` | fail(原样抛出) | 宿主的上下文压缩恢复必须看到它 |
202
+ | 未知 code | fallback | 最后一个 target 仍会抛原始错误,不静默吞掉 |
203
+
204
+ `IMAGE_OFFLOAD_REQUIRED` 与 `CONTEXT_WINDOW_EXCEEDED` 不可覆盖:它们是 DSH 的请求级恢复协议,
205
+ 宿主的监听器依赖原始 code 与元数据。
206
+
207
+ ## 流式输出、工具调用与整步重放
208
+
209
+ - 只有在**还没有向调用方交付可见内容**时,才能在同一请求内换 target。
210
+ - 文本/推理增量立即透传。
211
+ - tool-call 的 block-start/delta 缓冲到 `block-end`;参数非法的工具调用(没有 `block-end`)
212
+ 可以丢弃并安全重试。
213
+ - 已经交付可见内容后再失败,交给宿主 `dsh-llm-retry` 整步重放。插件记录请求指纹与已试到的
214
+ target,重放时从下一个 target 开始;计划**轮转**而不是截断,失败点之前的 target 不会消失。
215
+ 失败的是链尾时原地重试它。
216
+ - 合成 route 写下的 replay 信封在请求到达上游前会还原成真实 target 的 provider/model,
217
+ 保留签名与 id。旧包名 `dsh-llm-fallback` 写下的信封仍然可读。
218
+
219
+ ## 熔断
220
+
221
+ ```
222
+ closed --(连续 failureThreshold 次失败)--> open
223
+ open --(lock 到期)--> half-open
224
+ half-open --(探活成功)--> 下一次真实请求成功后 closed
225
+ half-open --(探活失败)--> 再锁一轮
226
+ ```
227
+
228
+ - 状态按 `provider + model` 记账,不按 provider 整体记账。
229
+ - `stateFile` 用锁 + 读-合并-写原子更新;并发进程取锁更晚/连败更多的条目;成功清除写
230
+ tombstone,旧锁不会被复活。
231
+ - 未达阈值的连败也会落盘(`updatedAt` 是合并时间轴),重启不会把计数清零。
232
+ - 全部 target 都 open/probing 时抛 `ALL_TARGETS_LOCKED`,附每个 target 的 `lockedUntil`,
233
+ 不会硬打最后一个被锁的 provider。
234
+
235
+ ## 设置页
236
+
237
+ Plugins → Installed → `dsh-llm-resilience` → **Model fallback chain**:
238
+
239
+ - 每个 target 一行:启用、provider、model(从会话模型目录读出的只读下拉)、显示名、
240
+ 重试参数、上下移动、删除、新增;
241
+ - 「重试计划」悬停:每次重试一行,`jitter > 0` 时显示区间;
242
+ - 熔断与全局预算字段;
243
+ - 「运行状态」每 4 秒从宿主读取:`closed / open / half-open / probing`、剩余锁定时间、
244
+ 连败与累计锁次数;
245
+ - 非环回浏览器拿到的是宿主内存态视图,卡片会明说,而不是把插件默认值当成部署策略。
246
+
247
+ ## 边界与不做的事
248
+
249
+ - **工具执行失败不重试。** cordis 4.1 的 `tools/execute` waterfall 的 `next()` 是单次调用,
250
+ 再次调用会抛 `next() called multiple times`;自动重放 tool body 需要 DSH 核心/executor
251
+ 提供钩子。本插件不提供「配置了但静默无效」的开关。模型输出损坏的工具调用重试不受影响。
252
+ - **不无限重试。** 全局 deadline 与尝试上限是必须的;`0` 只是关闭该维度,不建议生产使用。
253
+ - **不替代 `@deepseek-ai/dsh-llm-retry`。** 后者仍负责 step 级重试;本插件负责 provider 选择
254
+ 与请求级韧性。
255
+ - **不会为了回退而缓冲整个流。** 已经交付可见内容后再换 target 会重复输出,所以交给宿主
256
+ 整步重放。
257
+
258
+ ## 测试
259
+
260
+ ```bash
261
+ npm test
262
+ ```
263
+
264
+ 90 个用例覆盖退避/抖动、错误分类、链校验、适配器执行、流式安全、整步重放轮转、熔断持久化
265
+ 与多进程合并、全局预算、后台探活、设置页纯函数,以及 replay 信封(含旧包名兼容)。
266
+ 隔离 `DSH_HOME` + 假 OpenAI-compatible server 的端到端冒烟见 [DESIGN.md](DESIGN.md)。
267
+
268
+ ## 兼容与迁移
269
+
270
+ - DSH `0.2.2-rc.x`(`engines.dsh` 为 `>=0.2.2-0 <0.3.0-0`)、Node.js 20+。
271
+ - **0.5.0 从 `dsh-llm-fallback` 改名。** profile entry id 保持 `llm-fallback`,设置和已有
272
+ patch 继续可用;把 `name:` 字段改成 `dsh-llm-resilience` 即可。
273
+ - 默认熔断状态文件移到 `$DSH_HOME/storages/llm-resilience/state.json`;想继续用旧文件就显式
274
+ 设置 `stateFile`。
275
+ - 旧包名写下的 replay 信封仍然可读(`dsh-llm-fallback` 作为 legacy kind 接受)。
276
+
277
+ ## 许可
278
+
279
+ MIT,见 [LICENSE](LICENSE)。
@@ -0,0 +1,46 @@
1
+ # dsh-llm-resilience 的宿主平面挂载。
2
+ #
3
+ # 这个插件注册一个**合成的 provider route**(默认 `fallback`),对上层表现为普通
4
+ # provider;内部按 `targets` 顺序调用真实 provider,处理每 target 的重试、链式
5
+ # fallback、熔断锁和 half-open 探活。
6
+ #
7
+ # 设计见 DESIGN.md。Phase 1 已注册适配器,Phase 3 增加了设置页卡片,Phase 2 增加了全局
8
+ # 预算、可观测性、多进程 stateFile 锁和后台探活;`targets: []` 或全部 target
9
+ # `enabled: false` 时 route 存在但保持 dormant,不提供模型、不接收请求。
10
+ # 设置页按这个 entry id(`llm-fallback`)索引;所有根字段都带 `.volatile()`,
11
+ # 否则 dsh-settings 的 describe() 会跳过这个 entry。
12
+ - insert:
13
+ - id: llm-fallback
14
+ name: 'dsh-llm-resilience'
15
+ config:
16
+ enabled: true
17
+ route: fallback
18
+ # 链上每个 target 的重试预算是独立的;fallback 到下一个 target 时退避重置,
19
+ # 不接着上一个 target 已经翻倍过的延迟继续。每个 target 的 `enabled: false`
20
+ # 保留配置但不参与链(设置页可切换)。
21
+ targets: []
22
+ # 每个 target 连败 failureThreshold 次后锁 lockMs;锁到期后先做一次最小
23
+ # chat 探活(maxTokens: 1),成功才恢复使用,失败再锁一轮。
24
+ breaker:
25
+ failureThreshold: 5
26
+ lockMs: 3600000
27
+ probe:
28
+ enabled: true
29
+ # true:锁到期的 target 本次请求直接跳过,后台探活,下次请求使用结果。
30
+ background: false
31
+ timeoutMs: 10000
32
+ maxTokens: 1
33
+ prompt: 'ping'
34
+ stateFile: '$DSH_HOME/storages/llm-resilience/state.json'
35
+ # 单次请求的全局预算;跨 target、跨重试累计,0 表示不限制。
36
+ limits:
37
+ maxTotalMs: 600000
38
+ maxAttempts: 50
39
+ # 只重试「模型输出坏了」的工具调用(MALFORMED_RESPONSE 等)。
40
+ # 工具**执行**失败的重试在插件层做不到:cordis 的 tools/execute waterfall
41
+ # 的 next() 是单次调用,再次调用会抛 next() called multiple times;
42
+ # 需要 dsh 核心提供 retry 钩子,见 DESIGN.md §8。
43
+ toolCalls:
44
+ retryMalformed: true
45
+ # 按稳定错误码覆盖分类:retry / fallback / fail。默认分类见 lib/policy.js。
46
+ codeActions: {}