@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/config.js ADDED
@@ -0,0 +1,135 @@
1
+ /**
2
+ * dsh-llm-resilience 的配置 schema 与默认值。
3
+ *
4
+ * 0.2.0 的设置平面按 profile entry id 索引,且只把**根字段带 `.volatile()`** 的
5
+ * entry 供出给设置页。这里的每个根字段都标了 volatile;读配置前必须先用
6
+ * `plainConfig()` 解开活单元格,否则会按对象合并。
7
+ *
8
+ * @module dsh-llm-resilience/config
9
+ */
10
+
11
+ import { isVolatile } from '@deepseek-ai/cosmokit';
12
+ import z from '@deepseek-ai/schemastery';
13
+
14
+ export const DEFAULT_ROUTE = 'fallback';
15
+ export const DEFAULT_STATE_FILE = '$DSH_HOME/storages/llm-resilience/state.json';
16
+
17
+ /**
18
+ * 链上一个上游 target 的配置。
19
+ *
20
+ * `maxRetries` 是**首次请求之后**的重试次数;每个 target 有独立的预算和退避,
21
+ * fallback 到下一个 target 时从头开始,不继承上一个 target 已经翻倍过的延迟。
22
+ */
23
+ const targetSchema = z.object({
24
+ enabled: z.boolean().default(true).description('关掉后这一条仍然保留配置,但不参与链'),
25
+ provider: z.string().description('上游 provider route,例如 opendesign'),
26
+ model: z.string().description('上游模型 id,例如 deepseek-v4.1-flash-eco'),
27
+ label: z.string().default('').description('设置页显示名;留空则用 provider/model'),
28
+ maxRetries: z.number().step(1).min(0).default(5).description('首次请求之后最多重试几次'),
29
+ initialDelayMs: z.number().min(1).default(1500).description('第一次重试前的等待毫秒数'),
30
+ multiplier: z.number().min(1.01).default(2).description('每次重试等待时间的倍率'),
31
+ maxDelayMs: z.number().min(1).default(20000).description('单次等待的上限毫秒数'),
32
+ jitterRatio: z.number().min(0).max(1).default(0.3).description('等待时间的对称抖动比例'),
33
+ });
34
+
35
+ const probeSchema = z
36
+ .object({
37
+ enabled: z.boolean().default(true),
38
+ background: z
39
+ .boolean()
40
+ .default(false)
41
+ .description('锁到期后在后台探活:当前请求跳过该 target,下次请求使用探活结果'),
42
+ timeoutMs: z.number().min(1).default(10000),
43
+ maxTokens: z.number().step(1).min(1).default(1),
44
+ prompt: z.string().default('ping'),
45
+ })
46
+ .default({ enabled: true, background: false, timeoutMs: 10000, maxTokens: 1, prompt: 'ping' });
47
+
48
+ const breakerSchema = z
49
+ .object({
50
+ failureThreshold: z.number().step(1).min(1).default(5),
51
+ lockMs: z.number().min(1).default(3600000),
52
+ probe: probeSchema,
53
+ stateFile: z.string().default(DEFAULT_STATE_FILE),
54
+ })
55
+ .default({
56
+ failureThreshold: 5,
57
+ lockMs: 3600000,
58
+ probe: { enabled: true, background: false, timeoutMs: 10000, maxTokens: 1, prompt: 'ping' },
59
+ stateFile: DEFAULT_STATE_FILE,
60
+ });
61
+
62
+ /**
63
+ * 一次用户请求的全局预算,跨所有 target 和重试累计。
64
+ *
65
+ * `maxTotalMs: 0` / `maxAttempts: 0` 表示不限制该项;默认 10 分钟、50 次尝试,
66
+ * 防止 3 个 target × 10 次重试把一步拖成十几分钟。
67
+ */
68
+ const limitsSchema = z
69
+ .object({
70
+ maxTotalMs: z.number().min(0).default(600000).description('整条链的总等待上限;0 表示不限制'),
71
+ maxAttempts: z.number().step(1).min(0).default(50).description('整条链最多发起几次上游请求;0 表示不限制'),
72
+ })
73
+ .default({ maxTotalMs: 600000, maxAttempts: 50 });
74
+
75
+ /**
76
+ * 宿主写入的运行状态,供设置页轮询显示。
77
+ *
78
+ * 这个字段不在插件自己的请求路径上读取;适配器通过共享的 volatile 写协议更新它,
79
+ * settings/describe 读取活单元格时就能看到最新值。写回配置时不要包含它。
80
+ */
81
+ const runtimeSchema = z
82
+ .object({
83
+ version: z.number().default(0),
84
+ updatedAt: z.number().default(0),
85
+ targets: z
86
+ .array(
87
+ z.object({
88
+ key: z.string(),
89
+ label: z.string(),
90
+ state: z.string(),
91
+ failures: z.number(),
92
+ lockedUntil: z.number(),
93
+ locks: z.number(),
94
+ }),
95
+ )
96
+ .default([]),
97
+ })
98
+ .default({ version: 0, updatedAt: 0, targets: [] });
99
+
100
+ const toolCallsSchema = z
101
+ .object({
102
+ retryMalformed: z.boolean().default(true),
103
+ })
104
+ .default({ retryMalformed: true });
105
+
106
+ export const Config = z.object({
107
+ enabled: z.boolean().default(true).volatile(),
108
+ route: z.string().default(DEFAULT_ROUTE).volatile(),
109
+ targets: z.array(targetSchema).default([]).volatile(),
110
+ breaker: breakerSchema.volatile(),
111
+ limits: limitsSchema.volatile(),
112
+ toolCalls: toolCallsSchema.volatile(),
113
+ codeActions: z.dict(z.string()).default({}).volatile(),
114
+ runtime: runtimeSchema.description('宿主写入的运行状态;设置页只读').volatile(),
115
+ });
116
+
117
+ /** 解开 volatile 字段解析出来的活单元格(递归)。 */
118
+ export function plainConfig(value) {
119
+ if (isVolatile(value)) return plainConfig(value.get());
120
+ if (Array.isArray(value)) return value.map(plainConfig);
121
+ if (value !== null && typeof value === 'object') {
122
+ return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, plainConfig(child)]));
123
+ }
124
+ return value;
125
+ }
126
+
127
+ /**
128
+ * 把组合层的原始 config 套上完整默认值。
129
+ *
130
+ * @param raw - 组合层传入的 config(可能含 volatile 活单元格)。
131
+ * @returns 解析后的普通对象。
132
+ */
133
+ export function resolvePluginConfig(raw) {
134
+ return plainConfig(Config(plainConfig(raw) ?? {}));
135
+ }
package/lib/index.js ADDED
@@ -0,0 +1,87 @@
1
+ /**
2
+ * dsh-llm-resilience — 宿主平面入口。
3
+ *
4
+ * 注册一条合成 provider route(默认 `fallback`)。该 route 对内按 `targets`
5
+ * 顺序逐条尝试真实 provider:每个 target 独立重试预算、独立熔断锁、锁到期先
6
+ * 探活。`targets: []` 时保持 dormant:route 存在但不提供模型,也不接收请求。
7
+ *
8
+ * 非法配置(重复 target、自指 route、非法数值/覆盖值)在加载期直接失败;运行时
9
+ * 错误(全部 target 失败、全部被锁)抛给宿主,不静默吞掉。
10
+ *
11
+ * @module dsh-llm-resilience
12
+ */
13
+
14
+ import { FallbackAdapter } from './adapter.js';
15
+ import { Config, resolvePluginConfig } from './config.js';
16
+ import { validateChain, validateCodeActions, enabledTargets } from './policy.js';
17
+ import { createSessionRecorder } from './session-log.js';
18
+
19
+ export { Config };
20
+ export { FallbackAdapter } from './adapter.js';
21
+ export { plainConfig, resolvePluginConfig } from './config.js';
22
+ export {
23
+ ACTIONS,
24
+ AttemptBudget,
25
+ BREAKER_STATES,
26
+ CircuitBreaker,
27
+ classifyFailure,
28
+ buildRetrySchedule,
29
+ enabledTargets,
30
+ mergeBreakerSnapshots,
31
+ nominalDelayMs,
32
+ nominalSchedule,
33
+ planAttempts,
34
+ runtimeSnapshot,
35
+ targetKey,
36
+ targetLabel,
37
+ usableAttempts,
38
+ validateChain,
39
+ validateCodeActions,
40
+ } from './policy.js';
41
+
42
+ /** 设置页用这个 loader entry id 取配置;与 cordis.patch.yml 的 `- id` 一致。 */
43
+ export const SETTINGS_ENTRY = 'llm-fallback';
44
+
45
+ /** 宿主 llm 服务是注册 adapter 的前提。 */
46
+ export const inject = ['llm'];
47
+
48
+ /**
49
+ * 注册合成 route。配置非法时在加载期直接失败;链为空时保持 dormant。
50
+ *
51
+ * @param ctx - cordis 插件上下文。
52
+ * @param config - 组合层配置(可能含 volatile 活单元格,适配器每次请求重新解析)。
53
+ */
54
+ export function apply(ctx, config = {}) {
55
+ const resolved = resolvePluginConfig(config);
56
+ const errors = [...validateChain(resolved.route, resolved.targets), ...validateCodeActions(resolved.codeActions)];
57
+ if (errors.length > 0) {
58
+ throw new Error(`llm-resilience: invalid configuration: ${errors.join('; ')}`);
59
+ }
60
+
61
+ // `sessions` 不是本插件的 inject 依赖:直接读 ctx.sessions 会抛错并拆掉 fiber。
62
+ // 用 ctx.get 拿可选服务,没有它时 session 记录器自动退化为空操作。
63
+ const sessions = typeof ctx.get === 'function' ? ctx.get('sessions') : undefined;
64
+ const adapter = new FallbackAdapter({
65
+ route: resolved.route,
66
+ config,
67
+ llm: ctx.llm,
68
+ logger: ctx.logger,
69
+ runtimeRef: config?.runtime,
70
+ recordSession: createSessionRecorder(sessions, ctx.logger),
71
+ });
72
+ ctx.llm.registerAdapter([resolved.route], adapter);
73
+ ctx.effect?.(() => () => adapter.dispose(), 'llm-resilience: flush breaker state');
74
+
75
+ if (!resolved.enabled) {
76
+ ctx.logger?.info?.(`llm-resilience: route "${resolved.route}" registered but plugin is disabled`);
77
+ return;
78
+ }
79
+ const targets = enabledTargets(resolved.targets);
80
+ if (targets.length === 0) {
81
+ ctx.logger?.info?.(`llm-resilience: route "${resolved.route}" dormant (no enabled targets configured)`);
82
+ return;
83
+ }
84
+ ctx.logger?.info?.(
85
+ `llm-resilience: route "${resolved.route}" registered with ${targets.length} enabled target(s)`,
86
+ );
87
+ }