@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.
package/lib/policy.js ADDED
@@ -0,0 +1,549 @@
1
+ /**
2
+ * dsh-llm-resilience 的纯策略核心。
3
+ *
4
+ * 这里不碰 dsh runtime:退避曲线、错误分类、链校验和熔断状态机都是纯函数/纯类,
5
+ * 可以在 `node --test` 里直接钉契约。适配器(Phase 1)只负责把这里的决策接到
6
+ * `ctx.llm.stream()` 和底层 provider 上。
7
+ *
8
+ * @module dsh-llm-resilience/policy
9
+ */
10
+
11
+ export const ACTIONS = Object.freeze({
12
+ RETRY: 'retry',
13
+ FALLBACK: 'fallback',
14
+ FAIL: 'fail',
15
+ });
16
+
17
+ const ACTION_VALUES = new Set(Object.values(ACTIONS));
18
+
19
+ export const BREAKER_STATES = Object.freeze({
20
+ CLOSED: 'closed',
21
+ OPEN: 'open',
22
+ HALF_OPEN: 'half-open',
23
+ PROBING: 'probing',
24
+ });
25
+
26
+ /** 单 target 的默认重试参数;与 dsh 内置 retryPolicy 的默认口径一致。 */
27
+ export const DEFAULT_TARGET = Object.freeze({
28
+ maxRetries: 5,
29
+ initialDelayMs: 1500,
30
+ multiplier: 2,
31
+ maxDelayMs: 20000,
32
+ jitterRatio: 0.3,
33
+ });
34
+
35
+ const CANCELLED_CODES = new Set(['ABORTED', 'CANCELLED', 'CANCELED', 'ABORT_ERR']);
36
+
37
+ /** 这些错误重试有意义:请求可能下次成功。 */
38
+ const RETRYABLE_CODES = new Set([
39
+ 'EMPTY_RESPONSE',
40
+ 'RATE_LIMIT',
41
+ 'SERVER',
42
+ 'TIMEOUT',
43
+ 'TRANSPORT',
44
+ 'STREAM_CLOSED',
45
+ 'MALFORMED_RESPONSE',
46
+ ]);
47
+
48
+ /** 这些错误换一个 provider/model 更有意义,重试同一个 target 通常没用。 */
49
+ const FALLBACK_CODES = new Set([
50
+ 'AUTH',
51
+ 'INVALID_CREDENTIAL',
52
+ 'MISSING_CREDENTIAL',
53
+ 'QUOTA',
54
+ 'ACCOUNT_QUOTA',
55
+ 'NO_ADAPTER',
56
+ 'UNKNOWN_MODEL',
57
+ 'MODEL_NOT_FOUND',
58
+ ]);
59
+
60
+ /**
61
+ * dsh 的请求级恢复协议。宿主在 `agent/request-error` 上据此卸载图片 / 压缩上下文后重试;
62
+ * 链路层必须原样抛出这两个 code(`IMAGE_OFFLOAD_REQUIRED` 还带 `offloadImages`),
63
+ * 任何覆盖都会让恢复路径失效。
64
+ */
65
+ const HOST_RECOVERY_CODES = new Set(['IMAGE_OFFLOAD_REQUIRED', 'CONTEXT_WINDOW_EXCEEDED']);
66
+
67
+ /** 这些错误是请求本身的问题,fallback 到别的 target 也不该假装能修。 */
68
+ const FAIL_CODES = new Set([
69
+ 'UNSUPPORTED_OPTION',
70
+ 'UNSUPPORTED_CONTENT',
71
+ 'INVALID_REQUEST',
72
+ 'INVALID_MODEL_INFO',
73
+ ...HOST_RECOVERY_CODES,
74
+ ]);
75
+
76
+ /**
77
+ * OpenDesign 这类网关把「会员权益/额度评估失败」放在 SERVER 500 里返回。
78
+ * 它是确定性状态,不是瞬时抖动;必须直接 fallback,不能按普通 500 重试。
79
+ */
80
+ const ENTITLEMENT_MESSAGE_RE = /membership|entitlement|quota|billing|balance|credit|plan\b/i;
81
+
82
+ function codeOf(failure) {
83
+ return typeof failure?.code === 'string' && failure.code.trim() ? failure.code.trim() : 'UNKNOWN';
84
+ }
85
+
86
+ /**
87
+ * 把一次模型请求失败分类成 retry / fallback / fail。
88
+ *
89
+ * @param failure - `{ code, message }` 形状的 LlmFailure。
90
+ * @param overrides - 按 code 覆盖分类,值必须是 retry/fallback/fail。
91
+ * @returns `{ action, code, reason }`。
92
+ */
93
+ export function classifyFailure(failure, overrides = {}) {
94
+ const code = codeOf(failure);
95
+ const message = typeof failure?.message === 'string' ? failure.message : '';
96
+ // 先于 codeActions:这两个 code 是宿主的恢复协议,不允许被覆盖。
97
+ if (HOST_RECOVERY_CODES.has(code)) return { action: ACTIONS.FAIL, code, reason: 'host-recovery' };
98
+ const override = overrides?.[code];
99
+ if (ACTION_VALUES.has(override)) return { action: override, code, reason: 'override' };
100
+
101
+ if (code === 'SERVER' && ENTITLEMENT_MESSAGE_RE.test(message)) {
102
+ return { action: ACTIONS.FALLBACK, code, reason: 'entitlement' };
103
+ }
104
+ if (CANCELLED_CODES.has(code)) return { action: ACTIONS.FAIL, code, reason: 'cancelled' };
105
+ if (FAIL_CODES.has(code)) return { action: ACTIONS.FAIL, code, reason: 'request-invalid' };
106
+ if (FALLBACK_CODES.has(code)) return { action: ACTIONS.FALLBACK, code, reason: 'provider-state' };
107
+ if (RETRYABLE_CODES.has(code)) return { action: ACTIONS.RETRY, code, reason: 'transient' };
108
+
109
+ // 未知 code 默认走 fallback:最后一个 target 仍会把原始错误抛出来,不是静默吞掉。
110
+ return { action: ACTIONS.FALLBACK, code, reason: 'unknown-code' };
111
+ }
112
+
113
+ /** 校验按 code 的覆盖表;拼错的值在 apply 时就要报出来,不能静默忽略。 */
114
+ export function validateCodeActions(codeActions = {}) {
115
+ const errors = [];
116
+ for (const [code, action] of Object.entries(codeActions ?? {})) {
117
+ if (HOST_RECOVERY_CODES.has(code)) {
118
+ errors.push(`codeActions.${code} cannot be overridden: the host owns this request-level recovery code`);
119
+ continue;
120
+ }
121
+ if (!ACTION_VALUES.has(action)) {
122
+ errors.push(`codeActions.${code} must be one of retry/fallback/fail (got ${JSON.stringify(action)})`);
123
+ }
124
+ }
125
+ return errors;
126
+ }
127
+
128
+ /** 把 target 的缺省值补齐,并夹到合法范围;只用于纯计算,不做配置校验。 */
129
+ function normalizedTarget(target) {
130
+ const initialDelayMs = positive(target?.initialDelayMs, DEFAULT_TARGET.initialDelayMs);
131
+ const maxDelayMs = Math.max(positive(target?.maxDelayMs, DEFAULT_TARGET.maxDelayMs), initialDelayMs);
132
+ return {
133
+ maxRetries: Math.max(0, Math.floor(target?.maxRetries ?? DEFAULT_TARGET.maxRetries)),
134
+ initialDelayMs,
135
+ multiplier: Math.max(1.01, target?.multiplier ?? DEFAULT_TARGET.multiplier),
136
+ maxDelayMs,
137
+ jitterRatio: Math.min(1, Math.max(0, target?.jitterRatio ?? DEFAULT_TARGET.jitterRatio)),
138
+ };
139
+ }
140
+
141
+ function positive(value, fallback) {
142
+ return Number.isFinite(value) && value > 0 ? value : fallback;
143
+ }
144
+
145
+ /**
146
+ * 第 `attempt` 次重试的名义等待时间(1-based,不含首次请求)。
147
+ *
148
+ * `attempt=1` 用 initialDelayMs;之后每次乘 multiplier;不超过 maxDelayMs。
149
+ */
150
+ export function nominalDelayMs(target, attempt) {
151
+ const t = normalizedTarget(target);
152
+ const exponent = Math.max(0, Math.floor(attempt) - 1);
153
+ return Math.min(Math.round(t.initialDelayMs * t.multiplier ** exponent), t.maxDelayMs);
154
+ }
155
+
156
+ /**
157
+ * 给名义等待加对称抖动,并再次夹到 maxDelayMs。
158
+ *
159
+ * @param nominalDelayMs - 名义等待。
160
+ * @param jitterRatio - 0..1;0 表示不抖动。
161
+ * @param random - 返回 [0,1) 的随机源;测试可注入。
162
+ * @param maxDelayMs - 上限。
163
+ */
164
+ export function jitteredDelayMs(nominalDelayMs, jitterRatio, random = Math.random, maxDelayMs = Infinity) {
165
+ const jitter = Math.min(1, Math.max(0, jitterRatio));
166
+ const factor = 1 - jitter + 2 * jitter * random();
167
+ return Math.min(Math.round(nominalDelayMs * factor), maxDelayMs);
168
+ }
169
+
170
+ /**
171
+ * 生成一个 target 的完整重试计划。
172
+ *
173
+ * 每次重试的等待独立计算;不会把上一个 target 的退避带进来。
174
+ *
175
+ * @param target - 链上的 target 配置。
176
+ * @param options.random - 随机源,测试可注入。
177
+ * @returns `[{ attempt, nominalDelayMs, delayMs }]`。
178
+ */
179
+ export function buildRetrySchedule(target, { random = Math.random } = {}) {
180
+ const t = normalizedTarget(target);
181
+ return Array.from({ length: t.maxRetries }, (_, index) => {
182
+ const attempt = index + 1;
183
+ const nominal = nominalDelayMs(t, attempt);
184
+ return {
185
+ attempt,
186
+ nominalDelayMs: nominal,
187
+ delayMs: jitteredDelayMs(nominal, t.jitterRatio, random, t.maxDelayMs),
188
+ };
189
+ });
190
+ }
191
+
192
+ /**
193
+ * 不带抖动的名义计划,供设置页逐行显示。
194
+ *
195
+ * @param target - 链上的 target 配置。
196
+ * @returns `[{ attempt, nominalDelayMs }]`。
197
+ */
198
+ export function nominalSchedule(target) {
199
+ const t = normalizedTarget(target);
200
+ return Array.from({ length: t.maxRetries }, (_, index) => ({
201
+ attempt: index + 1,
202
+ nominalDelayMs: nominalDelayMs(t, index + 1),
203
+ }));
204
+ }
205
+
206
+ /** 链上 target 的稳定身份;同一 provider 下的不同 model 是两个独立 target。 */
207
+ export function targetKey(target) {
208
+ return `${target?.provider ?? ''}\u0000${target?.model ?? ''}`;
209
+ }
210
+
211
+ /**
212
+ * 参与本次链的 target:`enabled: false` 的条目保留配置但不参与校验、路由和计数。
213
+ *
214
+ * @param targets - 配置里的完整链。
215
+ * @returns 顺序不变的可参与条目。
216
+ */
217
+ export function enabledTargets(targets) {
218
+ return (Array.isArray(targets) ? targets : []).filter((target) => target?.enabled !== false);
219
+ }
220
+
221
+ /** 设置页/日志里的显示名。 */
222
+ export function targetLabel(target) {
223
+ const label = typeof target?.label === 'string' ? target.label.trim() : '';
224
+ return label || `${target?.provider ?? '?'}/${target?.model ?? '?'}`;
225
+ }
226
+
227
+ /**
228
+ * 校验 fallback 链。
229
+ *
230
+ * 空 targets 是合法的 dormant 状态;非空时每个 target 必须完整、唯一、不能指向
231
+ * wrapper 自己(否则会递归)。
232
+ *
233
+ * @param route - 合成 provider 的 route 名。
234
+ * @param targets - 链上的 target 配置。
235
+ * @returns 错误字符串数组;空数组表示通过。
236
+ */
237
+ export function validateChain(route, targets) {
238
+ const errors = [];
239
+ if (typeof route !== 'string' || route.trim() === '') errors.push('route must be a non-empty string');
240
+ const list = Array.isArray(targets) ? targets : [];
241
+ const seen = new Set();
242
+ for (const [index, target] of list.entries()) {
243
+ // 保留原始下标:禁用条目被跳过,但报错里的 targets[i] 仍能对上配置文件。
244
+ if (target?.enabled === false) continue;
245
+ const at = `targets[${index}]`;
246
+ if (target === null || typeof target !== 'object') {
247
+ errors.push(`${at} must be an object`);
248
+ continue;
249
+ }
250
+ if (typeof target.provider !== 'string' || target.provider.trim() === '') {
251
+ errors.push(`${at}.provider must be a non-empty string`);
252
+ }
253
+ if (typeof target.model !== 'string' || target.model.trim() === '') {
254
+ errors.push(`${at}.model must be a non-empty string`);
255
+ }
256
+ if (typeof route === 'string' && target.provider === route) {
257
+ errors.push(`${at}.provider must not equal the wrapper route "${route}"`);
258
+ }
259
+ const key = targetKey(target);
260
+ if (seen.has(key)) errors.push(`${at} duplicates ${targetLabel(target)}`);
261
+ seen.add(key);
262
+
263
+ const maxRetries = target.maxRetries ?? DEFAULT_TARGET.maxRetries;
264
+ const initialDelayMs = target.initialDelayMs ?? DEFAULT_TARGET.initialDelayMs;
265
+ const multiplier = target.multiplier ?? DEFAULT_TARGET.multiplier;
266
+ const maxDelayMs = target.maxDelayMs ?? DEFAULT_TARGET.maxDelayMs;
267
+ const jitterRatio = target.jitterRatio ?? DEFAULT_TARGET.jitterRatio;
268
+ if (!Number.isSafeInteger(maxRetries) || maxRetries < 0) errors.push(`${at}.maxRetries must be a non-negative integer`);
269
+ if (!Number.isFinite(initialDelayMs) || initialDelayMs <= 0) errors.push(`${at}.initialDelayMs must be > 0`);
270
+ if (!Number.isFinite(multiplier) || multiplier <= 1) errors.push(`${at}.multiplier must be > 1`);
271
+ if (!Number.isFinite(maxDelayMs) || maxDelayMs < initialDelayMs) errors.push(`${at}.maxDelayMs must be >= initialDelayMs`);
272
+ if (!Number.isFinite(jitterRatio) || jitterRatio < 0 || jitterRatio > 1) errors.push(`${at}.jitterRatio must be between 0 and 1`);
273
+ }
274
+ return errors;
275
+ }
276
+
277
+ /**
278
+ * 每个 target 的熔断状态。
279
+ *
280
+ * - `closed`:正常使用。
281
+ * - `open`:连败达到阈值,锁到 `lockedUntil`;期间跳过。
282
+ * - `half-open`:锁已到期,允许一次探活。
283
+ * - `probing`:探活进行中;期间其他请求跳过,避免打爆刚恢复的 provider。
284
+ */
285
+ export class CircuitBreaker {
286
+ constructor({ failureThreshold = 5, lockMs = 3600000, now = Date.now } = {}) {
287
+ this.failureThreshold = Math.max(1, Math.floor(failureThreshold));
288
+ this.lockMs = Math.max(1, Math.floor(lockMs));
289
+ this.now = now;
290
+ this.entries = new Map();
291
+ /** 成功清除锁的时间,供多进程合并时删除别人磁盘上的旧锁。 */
292
+ this.tombstones = new Map();
293
+ }
294
+
295
+ #entry(key) {
296
+ let entry = this.entries.get(key);
297
+ if (entry === undefined) {
298
+ entry = { failures: 0, openedAt: null, lockedUntil: null, probing: false, locks: 0, updatedAt: null };
299
+ this.entries.set(key, entry);
300
+ }
301
+ return entry;
302
+ }
303
+
304
+ /** 当前状态;`open` 的 entry 在锁到期后自动变成 `half-open`。 */
305
+ state(key, now = this.now()) {
306
+ const entry = this.entries.get(key);
307
+ if (entry === undefined || entry.lockedUntil === null) return BREAKER_STATES.CLOSED;
308
+ if (entry.probing) return BREAKER_STATES.PROBING;
309
+ if (now < entry.lockedUntil) return BREAKER_STATES.OPEN;
310
+ return BREAKER_STATES.HALF_OPEN;
311
+ }
312
+
313
+ /** 记录一次失败;达到阈值就开锁。锁住期间再失败会延长当前锁。 */
314
+ recordFailure(key, now = this.now()) {
315
+ const entry = this.#entry(key);
316
+ this.tombstones.delete(key);
317
+ entry.failures += 1;
318
+ // 每次失败都推进 updatedAt:未达阈值的连败也要能在多进程合并时胜出,
319
+ // 否则成功之后重新累计的连败永远写不进状态文件(见 mergeBreakerSnapshots)。
320
+ entry.updatedAt = now;
321
+ if (entry.lockedUntil !== null) {
322
+ entry.probing = false;
323
+ entry.lockedUntil = now + this.lockMs;
324
+ return;
325
+ }
326
+ if (entry.failures >= this.failureThreshold) {
327
+ entry.openedAt = now;
328
+ entry.lockedUntil = now + this.lockMs;
329
+ entry.locks += 1;
330
+ }
331
+ }
332
+
333
+ /** 一次成功彻底清零该 target 的连败与锁。 */
334
+ recordSuccess(key) {
335
+ this.entries.delete(key);
336
+ this.tombstones.set(key, this.now());
337
+ }
338
+
339
+ /** `half-open` 时抢占唯一一次探活资格;其他状态返回 false。 */
340
+ beginProbe(key, now = this.now()) {
341
+ const entry = this.entries.get(key);
342
+ if (entry === undefined || entry.lockedUntil === null || entry.probing || now < entry.lockedUntil) return false;
343
+ entry.probing = true;
344
+ return true;
345
+ }
346
+
347
+ probeSucceeded(key) {
348
+ this.entries.delete(key);
349
+ this.tombstones.set(key, this.now());
350
+ }
351
+
352
+ /**
353
+ * 放弃本次探活资格但不改变锁:请求在探活后被取消,或错误属于「请求本身
354
+ * 有问题」而不该记到 provider 头上时使用。锁保持原样,下个请求可以重新探。
355
+ */
356
+ releaseProbe(key) {
357
+ const entry = this.entries.get(key);
358
+ if (entry?.probing === true) entry.probing = false;
359
+ }
360
+
361
+ /** 探活失败:重新锁一轮,并把连败记满。 */
362
+ probeFailed(key, now = this.now()) {
363
+ const entry = this.#entry(key);
364
+ this.tombstones.delete(key);
365
+ entry.probing = false;
366
+ entry.failures = Math.max(entry.failures, this.failureThreshold);
367
+ entry.lockedUntil = now + this.lockMs;
368
+ entry.locks += 1;
369
+ entry.updatedAt = now;
370
+ }
371
+
372
+ /** 可序列化快照,供持久化到 stateFile。 */
373
+ snapshot() {
374
+ const cutoff = this.now() - 24 * 3600 * 1000;
375
+ for (const [key, at] of this.tombstones) {
376
+ if (at < cutoff) this.tombstones.delete(key);
377
+ }
378
+ return {
379
+ version: 1,
380
+ entries: Object.fromEntries(this.entries),
381
+ cleared: Object.fromEntries(this.tombstones),
382
+ };
383
+ }
384
+
385
+ /** 从快照恢复;版本不认识就返回一个空 breaker,不让旧格式破坏启动。 */
386
+ static fromSnapshot(snapshot, options = {}) {
387
+ const breaker = new CircuitBreaker(options);
388
+ if (snapshot?.version !== 1 || typeof snapshot.entries !== 'object' || snapshot.entries === null) return breaker;
389
+ for (const [key, entry] of Object.entries(snapshot.entries)) {
390
+ if (entry === null || typeof entry !== 'object') continue;
391
+ breaker.entries.set(key, {
392
+ failures: Number.isSafeInteger(entry.failures) && entry.failures >= 0 ? entry.failures : 0,
393
+ openedAt: Number.isFinite(entry.openedAt) ? entry.openedAt : null,
394
+ lockedUntil: Number.isFinite(entry.lockedUntil) ? entry.lockedUntil : null,
395
+ probing: false,
396
+ locks: Number.isSafeInteger(entry.locks) && entry.locks >= 0 ? entry.locks : 0,
397
+ // 旧格式没有 updatedAt:退回 openedAt(开锁时间)作兼容,缺失时按 0。
398
+ updatedAt: Number.isFinite(entry.updatedAt)
399
+ ? entry.updatedAt
400
+ : Number.isFinite(entry.openedAt)
401
+ ? entry.openedAt
402
+ : null,
403
+ });
404
+ }
405
+ if (snapshot.cleared !== null && typeof snapshot.cleared === 'object') {
406
+ for (const [key, at] of Object.entries(snapshot.cleared)) {
407
+ if (Number.isFinite(at)) breaker.tombstones.set(key, at);
408
+ }
409
+ }
410
+ return breaker;
411
+ }
412
+ }
413
+
414
+ /**
415
+ * 按链顺序给出每个 target 的当前状态。适配器只对 `closed` 直接用、对 `half-open`
416
+ * 先 `beginProbe()`、对 `open`/`probing` 跳过。
417
+ */
418
+ export function planAttempts(targets, breaker, now = Date.now()) {
419
+ return (targets ?? []).map((target, index) => {
420
+ const key = targetKey(target);
421
+ return {
422
+ target,
423
+ index,
424
+ key,
425
+ label: targetLabel(target),
426
+ state: breaker.state(key, now),
427
+ };
428
+ });
429
+ }
430
+
431
+ /** 过滤掉当前不可用的 target,保留顺序。 */
432
+ export function usableAttempts(attempts) {
433
+ return attempts.filter(({ state }) => state !== BREAKER_STATES.OPEN && state !== BREAKER_STATES.PROBING);
434
+ }
435
+
436
+ /**
437
+ * 一次用户请求的全局预算:跨 target、跨重试累计。
438
+ *
439
+ * 只记录“已经真正发出去”的次数;等待时间也算进 deadline。0 表示该维度不限制。
440
+ */
441
+ export class AttemptBudget {
442
+ constructor({ maxTotalMs = 0, maxAttempts = 0 } = {}, now = Date.now) {
443
+ this.now = now;
444
+ this.maxTotalMs = Math.max(0, Number(maxTotalMs) || 0);
445
+ this.maxAttempts = Math.max(0, Math.floor(Number(maxAttempts) || 0));
446
+ this.startedAt = now();
447
+ this.deadlineAt = this.maxTotalMs > 0 ? this.startedAt + this.maxTotalMs : Infinity;
448
+ this.attempts = 0;
449
+ }
450
+
451
+ remainingMs(now = this.now()) {
452
+ if (this.deadlineAt === Infinity) return Infinity;
453
+ return Math.max(0, this.deadlineAt - now);
454
+ }
455
+
456
+ /** @returns 'deadline' | 'attempts' | undefined */
457
+ stopReason(now = this.now()) {
458
+ if (this.deadlineAt !== Infinity && now >= this.deadlineAt) return 'deadline';
459
+ if (this.maxAttempts > 0 && this.attempts >= this.maxAttempts) return 'attempts';
460
+ return undefined;
461
+ }
462
+
463
+ /** 记一次真正发出的上游请求。 */
464
+ take() {
465
+ this.attempts += 1;
466
+ }
467
+ }
468
+
469
+ /**
470
+ * 当前熔断状态的序列化视图,供设置页显示。
471
+ *
472
+ * `lockedUntil` 用 0 表示没有锁,避免在 JSON 里出现 null 与 number 的联合。
473
+ */
474
+ export function runtimeSnapshot(targets, breaker, now = Date.now()) {
475
+ const entries = breaker?.snapshot?.().entries ?? {};
476
+ return {
477
+ version: 1,
478
+ updatedAt: now,
479
+ targets: (targets ?? []).map((target) => {
480
+ const key = targetKey(target);
481
+ const entry = entries[key];
482
+ return {
483
+ key,
484
+ label: targetLabel(target),
485
+ state: breaker?.state?.(key, now) ?? BREAKER_STATES.CLOSED,
486
+ failures: Number.isSafeInteger(entry?.failures) ? entry.failures : 0,
487
+ lockedUntil: Number.isFinite(entry?.lockedUntil) ? entry.lockedUntil : 0,
488
+ locks: Number.isSafeInteger(entry?.locks) ? entry.locks : 0,
489
+ };
490
+ }),
491
+ };
492
+ }
493
+
494
+ /**
495
+ * 条目的「最后变化时间」:优先 `updatedAt`(每次失败都推进),旧格式退回 `openedAt`。
496
+ * 用于和 tombstone 比先后;缺失一律按 0,让「没时间戳的旧条目」输给任何成功清除。
497
+ */
498
+ function entryTime(entry) {
499
+ if (Number.isFinite(entry?.updatedAt)) return entry.updatedAt;
500
+ if (Number.isFinite(entry?.openedAt)) return entry.openedAt;
501
+ return 0;
502
+ }
503
+
504
+ function snapshotRank(entry) {
505
+ const lockedUntil = Number(entry?.lockedUntil) || 0;
506
+ const failures = Number(entry?.failures) || 0;
507
+ const locks = Number(entry?.locks) || 0;
508
+ return [lockedUntil, failures, locks];
509
+ }
510
+
511
+ function rankGreater(left, right) {
512
+ for (let index = 0; index < left.length; index += 1) {
513
+ if (left[index] !== right[index]) return left[index] > right[index];
514
+ }
515
+ return false;
516
+ }
517
+
518
+ /**
519
+ * 合并两份熔断快照,供多个 dsh 进程共享 stateFile。
520
+ *
521
+ * - 同一 key 取锁更晚、连败更多、锁次数更多的那份;
522
+ * - `cleared`(成功清除锁的时间)会删除磁盘上更早的**任何**条目;
523
+ * - 另一个进程在清除之后新建的条目保留,不会被旧成功误删;
524
+ * - 本进程没有条目的 key 不会删除磁盘条目——宁可多探一次也不误放行。
525
+ *
526
+ * `updatedAt` 是这个比较的时间轴:**每次失败都推进**(连败未达阈值时 `openedAt` 是
527
+ * null)。旧实现只拿 `openedAt` 比 tombstone,`null` 被当成 0,于是「成功之后重新累计
528
+ * 的连败」永远输给 tombstone、写不进状态文件——重启后连败归零,阈值形同虚设。
529
+ */
530
+ export function mergeBreakerSnapshots(base, incoming) {
531
+ const entries = { ...(base?.entries ?? {}) };
532
+ const cleared = { ...(base?.cleared ?? {}) };
533
+
534
+ for (const [key, at] of Object.entries(incoming?.cleared ?? {})) {
535
+ if (!Number.isFinite(at)) continue;
536
+ const entry = entries[key];
537
+ if (entry !== undefined && entryTime(entry) <= at) delete entries[key];
538
+ cleared[key] = Math.max(cleared[key] ?? 0, at);
539
+ }
540
+
541
+ for (const [key, entry] of Object.entries(incoming?.entries ?? {})) {
542
+ if (cleared[key] !== undefined && entryTime(entry) <= cleared[key]) continue;
543
+ const current = entries[key];
544
+ if (current === undefined || rankGreater(snapshotRank(entry), snapshotRank(current))) {
545
+ entries[key] = entry;
546
+ }
547
+ }
548
+ return { version: 1, entries, cleared };
549
+ }
@@ -0,0 +1,42 @@
1
+ /**
2
+ * 会话日志里的 fallback 事件。
3
+ *
4
+ * 这些记录是 `plugin:` 命名空间下的 **ignorable** 事件:认识的插件可以读,
5
+ * 不认识的前端会保留并跳过,不进入模型可见的 surface,也不影响 fork/resume。
6
+ * 记录失败绝不能影响正在进行的 LLM 请求,所以这里吞掉所有异常并只警告一次。
7
+ *
8
+ * @module dsh-llm-resilience/session-log
9
+ */
10
+
11
+ import { appendPluginRecord } from '@deepseek-ai/dsh-session';
12
+
13
+ export const RECORD_TYPE = 'plugin:llm-fallback';
14
+
15
+ /**
16
+ * @param sessions - 宿主 `ctx.sessions`;没有它时返回空记录器。
17
+ * @param logger - cordis logger。
18
+ * @param append - 测试注入,默认 `appendPluginRecord`。
19
+ * @returns `(sessionId, event) => void`
20
+ */
21
+ export function createSessionRecorder(sessions, logger, append = appendPluginRecord) {
22
+ let warned = false;
23
+ return (sessionId, event) => {
24
+ if (sessionId === undefined || sessions?.get === undefined) return;
25
+ let session;
26
+ try {
27
+ session = sessions.get(sessionId);
28
+ } catch {
29
+ return;
30
+ }
31
+ if (session === undefined) return;
32
+ try {
33
+ append(session, RECORD_TYPE, { at: Date.now(), ...event });
34
+ } catch (error) {
35
+ if (warned) return;
36
+ warned = true;
37
+ logger?.warn?.(
38
+ `llm-resilience: cannot append session record: ${error instanceof Error ? error.message : String(error)}`,
39
+ );
40
+ }
41
+ };
42
+ }
@@ -0,0 +1,105 @@
1
+ /**
2
+ * 熔断状态的跨进程持久化。
3
+ *
4
+ * 多个 dsh 进程可能共享同一个 `stateFile`。裸的「临时文件 + rename」只能保证
5
+ * 单进程不写坏文件,最后一个写入者仍会覆盖别人刚写下的锁。这里用 `stateFile.lock`
6
+ * 做互斥,并在持锁期间 **读-合并-写**:同一个 key 取锁更晚/连败更多的条目胜出。
7
+ *
8
+ * 拿不到锁时跳过本次落盘并让调用方稍后重试;锁文件超过 `staleLockMs` 视为
9
+ * 崩溃残留,直接清掉。写失败向上抛,由调用方记录。
10
+ *
11
+ * @module dsh-llm-resilience/state-file
12
+ */
13
+
14
+ import { mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
15
+ import { readFileSync } from 'node:fs';
16
+ import { dirname } from 'node:path';
17
+
18
+ import { mergeBreakerSnapshots } from './policy.js';
19
+
20
+ export function readStateFileSync(path, logger) {
21
+ if (path === undefined) return undefined;
22
+ try {
23
+ return JSON.parse(readFileSync(path, 'utf8'));
24
+ } catch (error) {
25
+ if (error?.code !== 'ENOENT') {
26
+ logger?.warn?.(
27
+ `llm-resilience: cannot read breaker state ${path}: ${
28
+ error instanceof Error ? error.message : String(error)
29
+ }`,
30
+ );
31
+ }
32
+ return undefined;
33
+ }
34
+ }
35
+
36
+ async function readStateFile(path, logger) {
37
+ try {
38
+ return JSON.parse(await readFile(path, 'utf8'));
39
+ } catch (error) {
40
+ if (error?.code !== 'ENOENT') {
41
+ logger?.warn?.(
42
+ `llm-resilience: cannot read breaker state ${path}: ${
43
+ error instanceof Error ? error.message : String(error)
44
+ }`,
45
+ );
46
+ }
47
+ return undefined;
48
+ }
49
+ }
50
+
51
+ /**
52
+ * 尝试创建锁文件。返回 `undefined` 表示在超时前没拿到;调用方应跳过本次写。
53
+ */
54
+ async function acquireLock(lockPath, { timeoutMs, staleMs }, now) {
55
+ const deadline = now() + timeoutMs;
56
+ for (;;) {
57
+ try {
58
+ const handle = await open(lockPath, 'wx');
59
+ await handle.writeFile(`${process.pid}\n${now()}\n`, 'utf8');
60
+ return handle;
61
+ } catch (error) {
62
+ if (error?.code !== 'EEXIST') throw error;
63
+ const info = await stat(lockPath).catch(() => undefined);
64
+ if (info !== undefined && now() - info.mtimeMs > staleMs) {
65
+ await unlink(lockPath).catch(() => {});
66
+ continue;
67
+ }
68
+ if (now() >= deadline) return undefined;
69
+ await new Promise((resolve) => setTimeout(resolve, 20 + Math.random() * 30));
70
+ }
71
+ }
72
+ }
73
+
74
+ /**
75
+ * 持锁合并后落盘。
76
+ *
77
+ * @param path - 状态文件路径。
78
+ * @param snapshot - 本进程当前的熔断快照。
79
+ * @param options.logger - cordis logger。
80
+ * @param options.now - 时钟,测试可注入。
81
+ * @param options.lockTimeoutMs - 等锁上限;拿不到就跳过本次写。
82
+ * @param options.staleLockMs - 锁文件多久没动视为崩溃残留。
83
+ * @returns 合并后的快照;跳过时 `undefined`。
84
+ */
85
+ export async function writeStateFileMerged(
86
+ path,
87
+ snapshot,
88
+ { logger, now = Date.now, lockTimeoutMs = 1000, staleLockMs = 5000 } = {},
89
+ ) {
90
+ await mkdir(dirname(path), { recursive: true });
91
+ const lockPath = `${path}.lock`;
92
+ const handle = await acquireLock(lockPath, { timeoutMs: lockTimeoutMs, staleMs: staleLockMs }, now);
93
+ if (handle === undefined) return undefined;
94
+ try {
95
+ const base = await readStateFile(path, logger);
96
+ const merged = mergeBreakerSnapshots(base, snapshot);
97
+ const temporary = `${path}.tmp-${process.pid}-${now()}`;
98
+ await writeFile(temporary, `${JSON.stringify(merged, null, 2)}\n`, 'utf8');
99
+ await rename(temporary, path);
100
+ return merged;
101
+ } finally {
102
+ await handle.close().catch(() => {});
103
+ await unlink(lockPath).catch(() => {});
104
+ }
105
+ }