dsh-503-guard 0.0.0-stage → 1.0.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-503-guard contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,64 @@
1
- # Temporary Holding Version
1
+ # dsh-503-guard —— 服务端故障自愈守卫
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 模型请求被上游网关 5xx 拒绝(最常见就是 **503 Service Unavailable**)时,DSH 内置的重试只做有限次固定退避,挥完就报「本轮运行失败」,你得手动重发。
4
+
5
+ 这个插件在那之后接管:**不再盲目重试,而是主动探测上游是否真的活过来**,一旦恢复立刻把这一轮重新拉起来。你什么都不用做。
6
+
7
+ ## 它做了什么
8
+
9
+ 1. 挂在 `agent/request-error` 瀑布上,只认 `failure.code === 'SERVER'`(DSH 把 HTTP 5xx 统一归一化成这个码,界面上那个红标 SERVER 就是它)。
10
+ 2. **内置重试优先**:同一条故障,内置 `llm-retry` 先按它自己的策略重试;本插件只在决定权最终落到它手上时才真正干活,不抢活、不改变原有重试手感。
11
+ 3. 接管后按 **5s → 10s → 20s → 30s(封顶)** 指数退避,一次一次 GET `https://api.deepseek.com/v1/models` 探活。
12
+ - 返回状态码 **< 500**(200 / 401 / 403 / 429 都算)→ 网关活着,判定已恢复。用 401 当信号是刻意的:没带凭证本来就该 401,能返回 401 说明 DNS、TLS、网关、路由全通。
13
+ - 502 / 503 / 504 / 连不上 / 超时 → 继续等。
14
+ 4. 探测一通,返回 `{ kind: 'retry' }`,agent loop 直接重发这一轮,界面接着往下跑。
15
+ 5. 等待期间往会话里写 `llm/retry` 事件,界面就会渲染出「已重试模型请求(n/m)· Xs」那一行,恢复瞬间切成「已开始重试」——和内置重试条同一个渲染器,观感统一。
16
+
17
+ ## 安全阀
18
+
19
+ | 阀门 | 默认 | 作用 |
20
+ |---|---|---|
21
+ | `maxWaitMs` | 30 分钟 | 单点总等待预算,超时交还默认处理,绝不无限挂起 |
22
+ | `payload.signal` | — | 你点「停止」时立刻收手,交还下游 |
23
+ | 并发去重 | 开 | 同一 `turn/step` 只跑一份探测,不会扇出多条 |
24
+ | 卸载清理 | `ctx.effect` | 插件被停用/卸载时中止所有在跑的探测 |
25
+
26
+ ## 安装
27
+
28
+ ```bash
29
+ # 通过 DSH 的 plugin_manager install_bundle,传绝对路径
30
+ D:\dsh_workspace\dsh-503-guard
31
+ ```
32
+
33
+ 装完重启 DSH 生效。
34
+
35
+ ## 配置
36
+
37
+ 改 `cordis.patch.yml` 的 `config` 段即可,常用项:
38
+
39
+ | 键 | 默认 | 说明 |
40
+ |---|---|---|
41
+ | `codes` | `['SERVER']` | 触发自愈的失败码;`SERVER` 覆盖全部 5xx |
42
+ | `probeUrl` | `https://api.deepseek.com/v1/models` | 探活地址;换成你实际用的网关也行 |
43
+ | `probeHeaders` | `{}` | 探测请求头,可放 `Authorization` |
44
+ | `initialDelayMs` | `5000` | 首次探测前等待 |
45
+ | `maxDelayMs` | `30000` | 退避封顶 |
46
+ | `maxWaitMs` | `1800000` | 总预算 |
47
+ | `announce` | `true` | 是否写进度事件到会话 |
48
+
49
+ ## 自测
50
+
51
+ ```bash
52
+ node test-guard.mjs # 19 条:恢复算法本身,纯桩,不联网
53
+ node test-integration.mjs # 10 条:真实 cordis 4.1.0 跑瀑布派发,验证注册顺序与 next() 语义
54
+ ```
55
+
56
+ `test-guard.mjs` 覆盖:非目标码原路交还、恢复后返回 retry、预算耗尽交还、中止收手、并发去重、卸载清理、探测异常不误判。
57
+
58
+ `test-integration.mjs` 用一个「内置 llm-retry 替身 + 真实插件 apply()」的 harness 跑完整链路,实测轨迹为:
59
+
60
+ ```
61
+ plugin-registered -> builtin#1 -> builtin#2 -> builtin#3 -> builtin-exhausted -> 插件探测恢复
62
+ ```
63
+
64
+ 证明内置重试先跑完、耗尽后才轮到本插件接管,顺序与语义都正确。
@@ -0,0 +1,20 @@
1
+ # dsh-503-guard 的 Loader 补丁。
2
+ # 只插入一条 Host 条目,配置项在此处给出默认值,无需改 profile 的任何文件。
3
+ - insert:
4
+ - id: server-503-guard
5
+ name: dsh-503-guard
6
+ config:
7
+ # 触发自愈的 failure.code;SERVER 覆盖 DSH 归一化后的全部 5xx(含 503)
8
+ codes:
9
+ - SERVER
10
+ # 健康探测地址:返回非 5xx 即判定网关已恢复
11
+ probeUrl: https://api.deepseek.com/v1/models
12
+ # 单次探测超时
13
+ probeTimeoutMs: 8000
14
+ # 首次探测前等待,之后按 ×2 退避到 maxDelayMs 封顶
15
+ initialDelayMs: 5000
16
+ maxDelayMs: 30000
17
+ # 单个故障点的总等待预算:30 分钟,超时交还默认处理
18
+ maxWaitMs: 1800000
19
+ # 在会话里写出「已重试模型请求」进度行
20
+ announce: true
package/docs/DETAIL.md ADDED
@@ -0,0 +1,108 @@
1
+ # 503 自愈守卫 —— 详细说明
2
+
3
+ ## 一、故障场景
4
+
5
+ DSH 的模型请求走 `dsh-llm-deepseek`,上游网关过载时会返回 HTTP 503。DSH 把它归一化成 `failure.code === 'SERVER'`:
6
+
7
+ ```js
8
+ // dsh-llm-deepseek/lib/index.js:1822
9
+ else if (status !== void 0 && status >= 500 || ["api_error","overloaded_error"].includes(type))
10
+ code = "SERVER";
11
+ ```
12
+
13
+ 界面上你看到的就是:
14
+
15
+ ```
16
+ 已重试模型请求 (3/5) · 3s ›
17
+ ● 本轮运行失败 DeepSeek Messages request failed (503) SERVER
18
+ ```
19
+
20
+ `(3/5)` 说明内置 `llm-retry` 已经用掉 3 次机会。它的策略是**有限次、指数退避**,耗尽后 `return next()`,事件链走到尽头就报终态失败。
21
+
22
+ 问题在于:503 通常是**上游瞬时过载**,几十秒到几分钟就自己好了。内置策略的窗口太短,等不到那一刻;而人肉重发要么忘了,要么一焦虑就狂点。
23
+
24
+ ## 二、接管点:agent/request-error
25
+
26
+ 一次模型请求失败后,agent loop 会发一个 waterfall 事件征求意见:
27
+
28
+ ```js
29
+ // dsh-agent-loop/lib/index.js:952-962
30
+ const action = await this.dispatch.waterfall("agent/request-error", { ... });
31
+ signal.throwIfAborted();
32
+ if (action?.kind !== "retry") throw LlmError.fromFailure(finish.failure);
33
+ continue; // ← 返回 retry 就重发这一轮
34
+ ```
35
+
36
+ 返回值的语义(`api-catalog.js:4991-4996`):
37
+
38
+ | 监听器行为 | 结果 |
39
+ |---|---|
40
+ | 返回 `{ kind: 'retry' }` 且**不调用** `next()` | 自己负责恢复,agent loop 重发 |
41
+ | 调用 `next()` | 交给下游(内置 llm-retry / 默认终止) |
42
+ | 返回 `undefined` | 该故障按终态处理 |
43
+
44
+ 本插件就是注册在这个瀑布上的**一个监听器**。它只做一件事:判断这个码归不归自己管。
45
+
46
+ - 不归自己管(不是 `SERVER`)→ 立刻 `next()`,零 await,对原有行为零影响。
47
+ - 归自己管 → 进入探测循环,**等多久都不调 next()**,直到探测成功或预算耗尽。
48
+
49
+ ## 三、为什么不会和内置 llm-retry 打架
50
+
51
+ 瀑布按注册顺序执行,内置 `llm-retry` 的监听器在:
52
+
53
+ ```js
54
+ // dsh-llm-retry/lib/index.js
55
+ ctx.on("agent/request-error", (payload, next) => track(recover(payload, next)))
56
+ ```
57
+
58
+ 它在 `previousRetry >= policy.maxRetries` 时 `return next()`(lib/index.js:173)——也就是**主动把决定权往下传**。所以:
59
+
60
+ 1. 前几次 503:内置重试拿着,本插件收到的是 `next()` 的返回值,直接透传,什么都不做。
61
+ 2. 内置放弃后:本插件拿到决定权,开始探测。
62
+ 3. 探测成功后返回 `retry`,agent loop 重发;如果又 503,内置重试的计数器会重新走一遍,然后再次交给本插件。
63
+
64
+ ## 四、探测口径
65
+
66
+ `GET https://api.deepseek.com/v1/models`,8 秒超时。
67
+
68
+ | 响应 | 判定 | 理由 |
69
+ |---|---|---|
70
+ | 200 / 401 / 403 / 429 | **已恢复** | 任何 < 500 的响应都证明网关在正常应答;401 只是没带凭证 |
71
+ | 502 / 503 / 504 | 未恢复 | 网关仍不可用 |
72
+ | 连接失败 / DNS 失败 / 超时 | 未恢复 | 网络层还没通 |
73
+
74
+ 实测:本机探测该地址稳定 **331 ms 返回 401**,`ok:true`。
75
+
76
+ 退避:`initialDelayMs × 2^n`,抖动 ±20%,`maxDelayMs` 封顶(默认 30 s)。抖动是为了多会话同时恢复时不在同一毫秒打出一片尖峰。
77
+
78
+ ## 五、界面反馈
79
+
80
+ 等待期间每轮写一条 `llm/retry`:
81
+
82
+ ```js
83
+ { retryId, turn, step, provider, mode: 'normal',
84
+ policyKey: 'dsh-503-guard', retry, maxRetries: 99, delayMs, failure }
85
+ ```
86
+
87
+ `llm/retry` 是 DSH 的已知事件类型(`KNOWN_SESSION_EVENT_TYPES`),客户端 `dsh-client-ui-chat` 的 `retryDefinition` 会把它渲染成「等待重试模型请求(n/m)· Xs」。探测成功再补一条 `llm/retry-started`,那一行的状态位翻成「已开始重试」。
88
+
89
+ 写事件全程 try/catch:UI 出任何问题都不影响恢复逻辑本身。
90
+
91
+ ## 六、安全阀
92
+
93
+ - **总预算**:`maxWaitMs`,默认 30 分钟。到点就 `next()` 交还,不会把一次对话无限挂起。
94
+ - **中止信号**:`AbortSignal.any([payload.signal, lifetime.signal])` 融合 turn 级与插件级中止,任一触发立刻退出循环。
95
+ - **并发去重**:`WeakMap<agent, token>` 记录当前在跑的 `turn/step`,同一位置第二次进入直接 `next()`。
96
+ - **卸载清理**:`ctx.effect(() => () => lifetime.abort())`,插件停用时掐断所有定时器。
97
+
98
+ ## 七、自测覆盖
99
+
100
+ `node test-guard.mjs`,19 条断言:
101
+
102
+ 1. 非 SERVER 码 → 零 await 交还,不写事件
103
+ 2. 探测 200 → 返回 `{kind:'retry'}`,写 `llm/retry` + `llm/retry-started`
104
+ 3. 持续 503 → 预算耗尽交还下游
105
+ 4. turn 中止 → 立刻交还
106
+ 5. 同 turn/step 并发 → 第二份直接交还
107
+ 6. 插件卸载 → 在跑的探测收手
108
+ 7. 探测抛异常 → 不误判为恢复,继续等
package/icon.svg ADDED
@@ -0,0 +1,13 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="503 self-heal guard">
2
+ <!-- 深色圆角底:与 DSH 深色界面同调,插件列表里不刺眼 -->
3
+ <rect x="2" y="2" width="60" height="60" rx="16" fill="#1f2430"/>
4
+ <!-- 心电基线:左半段的平稳信号,代表网关正常 -->
5
+ <path d="M8 34 H20 L24 26 L30 44 L36 22 L41 34 H56"
6
+ fill="none" stroke="#4dabf7" stroke-width="3"
7
+ stroke-linecap="round" stroke-linejoin="round"/>
8
+ <!-- 右侧回环箭头:恢复后自动续跑 -->
9
+ <path d="M44 18 A12 12 0 1 1 44 46"
10
+ fill="none" stroke="#f5a524" stroke-width="3"
11
+ stroke-linecap="round"/>
12
+ <path d="M44 13 L44 23 L34 18 Z" fill="#f5a524"/>
13
+ </svg>
package/index.js ADDED
@@ -0,0 +1,320 @@
1
+ /**
2
+ * ============================================================================
3
+ * dsh-503-guard —— 服务端故障自愈守卫(Host 半)
4
+ * ============================================================================
5
+ *
6
+ * 【它解决什么问题】
7
+ * 模型请求被上游网关拒绝(HTTP 5xx,典型就是 503 Service Unavailable)时,
8
+ * DSH 内置的 llm-retry 只会做「有限次、固定退避」的重试(默认 5 次)。
9
+ * 5 次挥完,本轮就报「本轮运行失败」,用户只能手动重发。
10
+ * 本插件在那之后接管:不再盲目重试,而是【主动探测上游是否恢复】,
11
+ * 一旦探测到恢复,立刻把这一轮重新拉起来,用户不需要动一根手指。
12
+ *
13
+ * 【接在哪个扩展点上】
14
+ * agent/request-error 是一次模型请求失败后、agent loop 决定「重试还是收尾」
15
+ * 的瀑布事件(waterfall)。签名见 dsh-tool-cordis/lib/types/api-catalog.js:
16
+ *
17
+ * 'agent/request-error'(
18
+ * this: Scoped<Agent>,
19
+ * payload: { agent, turn, step, provider, failure, retryPolicy, signal },
20
+ * next: () => Promise<RequestErrorAction>
21
+ * ): Promise<RequestErrorAction>
22
+ *
23
+ * 约定很干净:
24
+ * - 监听器返回 { kind: 'retry' } 且【不调用 next()】= 我自己负责恢复
25
+ * - 监听器调用 next() = 把决定权交给下游(内置 llm-retry / 默认终止)
26
+ * - 全都返回 undefined = 该故障按终态处理
27
+ * 所以本插件只在「内置重试已经放弃」的那一刻才真正干活,
28
+ * 不抢内置策略的活,也不会和它打架。
29
+ *
30
+ * 【失败码从哪来】
31
+ * dsh-llm-deepseek/lib/index.js:1822
32
+ * else if (status !== void 0 && status >= 500 || ["api_error","overloaded_error"].includes(type))
33
+ * code = "SERVER";
34
+ * 也就是说 HTTP 503 在 DSH 内部统一归一化成 failure.code === 'SERVER'。
35
+ * 聊天界面右下角那个红色的 SERVER 标签,就是这个 code。
36
+ * 因此默认匹配集合是 ['SERVER'],覆盖全部 5xx。
37
+ *
38
+ * 【探测怎么做】
39
+ * 默认对 https://api.deepseek.com/v1/models 发 GET:
40
+ * - 状态码 < 500(200/401/403/429 都算)→ 网关活着,判定「已恢复」
41
+ * - 502/503/504 或连不上 → 判定「未恢复」,继续等
42
+ * 用 401 当「活着」是刻意的:没带凭证的请求本来就该 401,
43
+ * 能返回 401 说明 DNS、TLS、网关、路由全都通了,正是我们要的信号。
44
+ *
45
+ * 【界面反馈】
46
+ * 每次探测前往会话里追加一条 llm/retry 事件,界面就会渲染出
47
+ * 「已重试模型请求(n/m)· Xs」那一行(和内置重试条同一个渲染器,
48
+ * 见 dsh-client-ui-chat 的 retryDefinition / scheduledNode)。
49
+ * 探测成功后补一条 llm/retry-started,那条行的状态位从「等待」变成「已开始」。
50
+ * 追加事件失败不影响恢复逻辑本身,全部 try/catch 兜住。
51
+ *
52
+ * 【安全阀】
53
+ * - 总等待预算 maxWaitMs(默认 30 分钟),超时后交还下游按终态处理
54
+ * - 每轮 turn/step 只允许一段恢复流程,避免同一故障并发跑出两份探测
55
+ * - turn 的中止信号(payload.signal)一旦 abort,立刻停手并交还下游
56
+ * - 插件被卸载(ctx.effect 的清理函数)时中止全部在跑的探测
57
+ * ============================================================================
58
+ */
59
+
60
+ import { randomUUID } from 'node:crypto';
61
+
62
+ /** 插件在 Loader 里的行标识,和 cordis.patch.yml 中的 id 对应。 */
63
+ export const name = 'dsh-503-guard';
64
+
65
+ /**
66
+ * 默认配置。
67
+ * 全部可以在 cordis.patch.yml 的 config 段里覆盖,也可以在设置里改(若暴露)。
68
+ */
69
+ const DEFAULTS = {
70
+ /** 触发自愈的 failure.code 集合。SERVER 覆盖全部 5xx,含 503。 */
71
+ codes: ['SERVER'],
72
+ /** 健康探测地址。默认探 DeepSeek 的模型列表接口,它的鉴权要求最低。 */
73
+ probeUrl: 'https://api.deepseek.com/v1/models',
74
+ /** 探测请求附带的请求头,例如 { Authorization: 'Bearer sk-...' }。 */
75
+ probeHeaders: {},
76
+ /** 单次探测的超时(毫秒)。探测本身不能把恢复流程拖死。 */
77
+ probeTimeoutMs: 8000,
78
+ /** 第一次探测前的等待(毫秒)。给上游一点点喘息时间,避免打脸。 */
79
+ initialDelayMs: 5000,
80
+ /** 探测间隔上限(毫秒)。指数退避到这里封顶。 */
81
+ maxDelayMs: 30000,
82
+ /** 退避抖动比例,0.2 表示 ±20%,避免多会话同时探测形成尖峰。 */
83
+ jitterRatio: 0.2,
84
+ /** 单个故障点允许等待的总预算(毫秒)。默认 30 分钟。 */
85
+ maxWaitMs: 1800000,
86
+ /** 状态码低于这个值就判定「已恢复」。默认 500。 */
87
+ healthyStatusBelow: 500,
88
+ /** 是否往会话里写 llm/retry 事件以驱动界面上的重试行。 */
89
+ announce: true,
90
+ };
91
+
92
+ /**
93
+ * 把用户配置和默认值合并。
94
+ * 只接受已知键,避免拼错的键把默认值悄悄顶掉。
95
+ * @param {object} raw - Loader 传进来的原始配置。
96
+ * @returns {object} 合并后的配置。
97
+ */
98
+ function resolveConfig(raw) {
99
+ const out = { ...DEFAULTS };
100
+ if (raw === null || typeof raw !== 'object') return out;
101
+ for (const key of Object.keys(DEFAULTS)) {
102
+ const value = raw[key];
103
+ if (value === undefined || value === null) continue;
104
+ // 数组和对象要单独拷贝,避免调用方后续改动影响运行中的配置。
105
+ if (Array.isArray(value)) out[key] = [...value];
106
+ else if (typeof value === 'object') out[key] = { ...value };
107
+ else out[key] = value;
108
+ }
109
+ return out;
110
+ }
111
+
112
+ /**
113
+ * 可被中止的等待。
114
+ * 中止信号一响立刻返回 false,恢复流程据此判断该收手了。
115
+ * @param {number} ms - 等待毫秒数。
116
+ * @param {AbortSignal} signal - 中止信号。
117
+ * @returns {Promise<boolean>} true 表示等满了,false 表示被中止。
118
+ */
119
+ function sleep(ms, signal) {
120
+ if (signal.aborted) return Promise.resolve(false);
121
+ return new Promise((resolve) => {
122
+ const timer = setTimeout(() => {
123
+ signal.removeEventListener('abort', onAbort);
124
+ resolve(true);
125
+ }, ms);
126
+ function onAbort() {
127
+ clearTimeout(timer);
128
+ resolve(false);
129
+ }
130
+ signal.addEventListener('abort', onAbort, { once: true });
131
+ });
132
+ }
133
+
134
+ /**
135
+ * 第 n 次探测前的退避时长(带抖动,且不超过上限)。
136
+ * @param {object} cfg - 运行配置。
137
+ * @param {number} attempt - 已经探测过的次数(从 0 开始)。
138
+ * @param {() => number} random - 随机源,测试时可注入定值。
139
+ * @returns {number} 毫秒。
140
+ */
141
+ function backoffDelay(cfg, attempt, random) {
142
+ const exponent = Math.min(attempt, 16);
143
+ const raw = Math.min(cfg.initialDelayMs * 2 ** exponent, cfg.maxDelayMs);
144
+ const jitter = 1 - cfg.jitterRatio + 2 * cfg.jitterRatio * random();
145
+ // 下界不额外钳 1s:退避本身从 initialDelayMs 起算,硬钳会把
146
+ // 自定义的小间隔(以及自测用的小毫秒配置)统统顶掉。
147
+ return Math.max(0, Math.min(raw * jitter, cfg.maxDelayMs));
148
+ }
149
+
150
+ /**
151
+ * 创建一份运行态。把依赖(fetch / 时间 / 随机 / 日志)显式注入,
152
+ * 这样单元测试不用碰真实网络就能把整条恢复流程跑一遍。
153
+ * @param {object} config - 原始配置。
154
+ * @param {object} deps - 依赖注入点。
155
+ * @returns {object} 恢复流程的可调用入口。
156
+ */
157
+ export function createRuntime(config, deps = {}) {
158
+ const cfg = resolveConfig(config);
159
+ const doFetch = deps.fetch ?? globalThis.fetch;
160
+ const now = deps.now ?? (() => Date.now());
161
+ const random = deps.random ?? Math.random;
162
+ const log = deps.logger ?? console;
163
+
164
+ /** 插件级生命周期信号:插件卸载时统一掐断所有在跑的探测。 */
165
+ const lifetime = new AbortController();
166
+
167
+ /** 每个 agent 当前正在进行的恢复流程,防止同一故障并发跑出两份。 */
168
+ const inflight = new WeakMap();
169
+
170
+ /**
171
+ * 单次健康探测。
172
+ * 任何非 5xx 的响应、甚至鉴权失败,都代表网关可达,即视为恢复。
173
+ * @returns {Promise<{ok: boolean, status?: number, error?: string}>}
174
+ */
175
+ async function probeOnce() {
176
+ if (typeof doFetch !== 'function') return { ok: true, status: 0 };
177
+ const controller = new AbortController();
178
+ const timer = setTimeout(() => controller.abort(), cfg.probeTimeoutMs);
179
+ try {
180
+ const response = await doFetch(cfg.probeUrl, {
181
+ method: 'GET',
182
+ headers: { 'user-agent': 'dsh-503-guard', ...cfg.probeHeaders },
183
+ signal: controller.signal,
184
+ });
185
+ const status = Number(response?.status ?? 0);
186
+ return { ok: status > 0 && status < cfg.healthyStatusBelow, status };
187
+ } catch (error) {
188
+ return { ok: false, error: error instanceof Error ? error.message : String(error) };
189
+ } finally {
190
+ clearTimeout(timer);
191
+ }
192
+ }
193
+
194
+ /**
195
+ * 往会话里追加一条 llm/retry 事件,界面据此渲染「已重试模型请求」行。
196
+ * 事件是 DSH 的已知类型(KNOWN_SESSION_EVENT_TYPES 里有 llm/retry),
197
+ * 因此按普通事件追加即可;追加失败只记日志,绝不打断恢复。
198
+ * @param {object} agent - 正在跑的 agent。
199
+ * @param {object} fields - 事件字段。
200
+ */
201
+ function appendEvent(agent, type, fields) {
202
+ if (!cfg.announce) return;
203
+ try {
204
+ agent?.session?.append?.(type, fields);
205
+ } catch (error) {
206
+ log.warn?.(`dsh-503-guard: 会话事件写入失败(不影响恢复):${String(error)}`);
207
+ }
208
+ }
209
+
210
+ /**
211
+ * 处理一次 request-error。
212
+ * 只有目标故障码才会接管;其余情况原样交给下游。
213
+ * @param {object} payload - agent/request-error 的载荷。
214
+ * @param {Function} next - 下游监听器。
215
+ * @returns {Promise<object|undefined>} {kind:'retry'} 表示由本插件负责重试。
216
+ */
217
+ async function recover(payload, next) {
218
+ const { agent, turn, step, provider, failure, signal } = payload ?? {};
219
+ const code = failure?.code;
220
+
221
+ // 不是我们管的故障码:立刻交还下游,一个 await 都不加。
222
+ if (!cfg.codes.includes(code)) return next();
223
+
224
+ // 同一个 turn/step 已经在恢复了:这次直接交还,避免扇出多份探测。
225
+ const running = inflight.get(agent);
226
+ if (running !== undefined && running.turn === turn && running.step === step) return next();
227
+
228
+ const token = { turn, step, attempts: 0, startedAt: now() };
229
+ inflight.set(agent, token);
230
+
231
+ // 把 turn 的中止信号和插件生命周期信号合并成一个,任一触发都收手。
232
+ const fused = signal === undefined
233
+ ? lifetime.signal
234
+ : AbortSignal.any([signal, lifetime.signal]);
235
+
236
+ const retryId = randomUUID();
237
+ const deadline = token.startedAt + cfg.maxWaitMs;
238
+ log.info?.(
239
+ `dsh-503-guard: 检测到 ${code}(provider=${String(provider)}),转入后台探测恢复,` +
240
+ `预算 ${Math.round(cfg.maxWaitMs / 1000)}s`
241
+ );
242
+
243
+ while (!fused.aborted) {
244
+ // 预算耗尽:不再无限等下去,交还下游按终态处理。
245
+ if (now() >= deadline) {
246
+ log.warn?.('dsh-503-guard: 等待预算耗尽,交还默认处理');
247
+ if (inflight.get(agent) === token) inflight.delete(agent);
248
+ return next();
249
+ }
250
+
251
+ const delay = backoffDelay(cfg, token.attempts, random);
252
+
253
+ // 先落事件再等待:界面上立刻能看到「等待重试」这一行。
254
+ appendEvent(agent, 'llm/retry', {
255
+ retryId,
256
+ turn,
257
+ step,
258
+ provider,
259
+ mode: 'normal',
260
+ policyKey: 'dsh-503-guard',
261
+ retry: token.attempts + 1,
262
+ maxRetries: 99,
263
+ delayMs: delay,
264
+ failure,
265
+ });
266
+
267
+ if (!(await sleep(delay, fused))) break;
268
+
269
+ const health = await probeOnce();
270
+ token.attempts += 1;
271
+ if (fused.aborted) break;
272
+
273
+ if (health.ok) {
274
+ // 探测通过:补一条「已开始重试」,让界面那行的状态位翻过来。
275
+ appendEvent(agent, 'llm/retry-started', {
276
+ retryId,
277
+ turn,
278
+ step,
279
+ retry: token.attempts,
280
+ });
281
+ if (inflight.get(agent) === token) inflight.delete(agent);
282
+ log.info?.(
283
+ `dsh-503-guard: 上游已恢复(status=${String(health.status)}),` +
284
+ `第 ${token.attempts} 次探测后自动续跑`
285
+ );
286
+ return { kind: 'retry' };
287
+ }
288
+
289
+ log.debug?.(
290
+ `dsh-503-guard: 第 ${token.attempts} 次探测仍未恢复` +
291
+ `(status=${String(health.status ?? '-')}${health.error ? ` ${health.error}` : ''})`
292
+ );
293
+ }
294
+
295
+ // 被中止(用户点了停止 / 插件卸载):干净地交还下游。
296
+ if (inflight.get(agent) === token) inflight.delete(agent);
297
+ log.info?.('dsh-503-guard: 恢复流程被中止,交还默认处理');
298
+ return next();
299
+ }
300
+
301
+ return { recover, probeOnce, config: cfg, lifetime, inflight };
302
+ }
303
+
304
+ /**
305
+ * 插件入口。
306
+ * @param {object} ctx - cordis 上下文。
307
+ * @param {object} config - Loader 传入的配置。
308
+ */
309
+ export function apply(ctx, config = {}) {
310
+ const runtime = createRuntime(config, { logger: ctx.logger });
311
+
312
+ // 挂到 request-error 瀑布上。返回 Promise 即代表「本监听器还在处理中」,
313
+ // 等待期间 agent 的这一步不会收尾,恢复成功后直接重试。
314
+ ctx.on('agent/request-error', (payload, next) => runtime.recover(payload, next));
315
+
316
+ // 插件卸载时掐断所有仍在等待的探测,避免悬挂的定时器拖住进程退出。
317
+ ctx.effect(() => () => {
318
+ runtime.lifetime.abort();
319
+ }, 'dsh-503-guard: 中止在跑的恢复探测');
320
+ }
package/locale/en.json ADDED
@@ -0,0 +1,7 @@
1
+ {
2
+ "meta": {
3
+ "title": "503 self-heal guard",
4
+ "description": "When a model request is rejected by an upstream 5xx (typically 503) and the built-in retries are exhausted, this plugin keeps probing the gateway in the background with exponential backoff and resumes the turn automatically as soon as it answers again.",
5
+ "detail": "docs/DETAIL.md"
6
+ }
7
+ }
package/locale/zh.json ADDED
@@ -0,0 +1,7 @@
1
+ {
2
+ "meta": {
3
+ "title": "503 自愈守卫",
4
+ "description": "模型请求被上游 5xx(典型 503)拒绝、内置重试耗尽后,后台按指数退避持续探测网关是否恢复;探测一通就自动续跑这一轮,不用手动重发。",
5
+ "detail": "docs/DETAIL.md"
6
+ }
7
+ }
package/package.json CHANGED
@@ -1,6 +1,50 @@
1
- {
2
- "name": "dsh-503-guard",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
1
+ {
2
+ "name": "dsh-503-guard",
3
+ "version": "1.0.0",
4
+ "description": "DSH 服务端故障自愈:模型请求被 5xx(典型 503)拒绝、内置重试耗尽后,在后台持续探测上游是否恢复,一旦恢复自动把这一轮重新拉起来。",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "author": "dsh-503-guard contributors",
8
+ "keywords": [
9
+ "dsh",
10
+ "dsh-plugin",
11
+ "deepseek-harness",
12
+ "retry",
13
+ "503",
14
+ "server-error",
15
+ "resilience"
16
+ ],
17
+ "engines": {
18
+ "dsh": ">=0.2.0-0 <0.3.0-0",
19
+ "node": ">=20"
20
+ },
21
+ "exports": {
22
+ ".": "./index.js",
23
+ "./locale/*.json": "./locale/*.json",
24
+ "./icon": "./icon.svg"
25
+ },
26
+ "files": [
27
+ "index.js",
28
+ "cordis.patch.yml",
29
+ "locale",
30
+ "docs",
31
+ "icon.svg",
32
+ "README.md",
33
+ "LICENSE",
34
+ "test-guard.mjs",
35
+ "test-integration.mjs"
36
+ ],
37
+ "dsh": {
38
+ "bundle": {
39
+ "patch": "./cordis.patch.yml"
40
+ }
41
+ },
42
+ "repository": {
43
+ "type": "git",
44
+ "url": "git+https://github.com/ltw2522/dsh-503-guard.git"
45
+ },
46
+ "homepage": "https://github.com/ltw2522/dsh-503-guard#readme",
47
+ "bugs": {
48
+ "url": "https://github.com/ltw2522/dsh-503-guard/issues"
49
+ }
50
+ }
package/test-guard.mjs ADDED
@@ -0,0 +1,245 @@
1
+ /**
2
+ * ============================================================================
3
+ * dsh-503-guard 自测脚本(不联网、不碰真实会话)
4
+ * ============================================================================
5
+ *
6
+ * 跑法:node test-guard.mjs
7
+ *
8
+ * 覆盖七个必须成立的契约:
9
+ * 1. 非 SERVER 故障码 → 一个 await 都不加,立刻交还下游(不抢内置重试的活)
10
+ * 2. 探测到 200 → 返回 {kind:'retry'},让 agent loop 重发这一轮
11
+ * 3. 探测持续 503 → 不返回 retry,继续等;预算耗尽后交还下游
12
+ * 4. turn 被中止(用户点停止)→ 立刻交还下游,不悬挂
13
+ * 5. 同一 turn/step 并发进入 → 第二次直接交还,不扇出第二份探测
14
+ * 6. 恢复过程中写入 llm/retry 与 llm/retry-started,供界面渲染进度行
15
+ * 7. 插件卸载(lifetime.abort)→ 在跑的探测立刻收手
16
+ * ============================================================================
17
+ */
18
+
19
+ import { createRuntime } from './index.js';
20
+
21
+ let passed = 0;
22
+ let failed = 0;
23
+
24
+ /**
25
+ * 极简断言。
26
+ * @param {boolean} condition - 条件。
27
+ * @param {string} label - 用例名。
28
+ */
29
+ function check(condition, label) {
30
+ if (condition) {
31
+ passed += 1;
32
+ console.log(` ✓ ${label}`);
33
+ } else {
34
+ failed += 1;
35
+ console.log(` ✗ ${label}`);
36
+ }
37
+ }
38
+
39
+ /**
40
+ * 构造一个假的 agent,只提供插件会用到的那一小撮接口。
41
+ * @returns {object} 假 agent。
42
+ */
43
+ function fakeAgent() {
44
+ const events = [];
45
+ return {
46
+ events,
47
+ session: {
48
+ append(type, data) {
49
+ events.push({ type, data });
50
+ },
51
+ },
52
+ };
53
+ }
54
+
55
+ /**
56
+ * 构造一份测试配置:把退避压到毫秒级,让用例跑得快。
57
+ * @param {object} extra - 覆盖项。
58
+ * @returns {object} 配置。
59
+ */
60
+ function testConfig(extra = {}) {
61
+ return {
62
+ initialDelayMs: 10,
63
+ maxDelayMs: 20,
64
+ jitterRatio: 0,
65
+ probeTimeoutMs: 500,
66
+ maxWaitMs: 5000,
67
+ ...extra,
68
+ };
69
+ }
70
+
71
+ /** 静默 logger,避免测试输出被日志刷屏。 */
72
+ const quiet = { info() {}, warn() {}, debug() {} };
73
+
74
+ /**
75
+ * 用例 1:非目标故障码必须原路交还。
76
+ */
77
+ async function casePassThrough() {
78
+ console.log('用例 1:非 SERVER 故障码直接交还下游');
79
+ let nextCalls = 0;
80
+ const runtime = createRuntime(testConfig(), { logger: quiet });
81
+ const agent = fakeAgent();
82
+ const action = await runtime.recover(
83
+ { agent, turn: 1, step: 1, provider: 'p', failure: { code: 'RATE_LIMIT' } },
84
+ async () => { nextCalls += 1; return undefined; }
85
+ );
86
+ check(nextCalls === 1, '下游被调用恰好一次');
87
+ check(action === undefined, '本插件没有抢占恢复权');
88
+ check(agent.events.length === 0, '没有写任何会话事件');
89
+ }
90
+
91
+ /**
92
+ * 用例 2:探测到 200 后返回 retry。
93
+ */
94
+ async function caseRecoverAfterOutage() {
95
+ console.log('用例 2:探测恢复后自动续跑');
96
+ let probes = 0;
97
+ const runtime = createRuntime(testConfig({ initialDelayMs: 5 }), {
98
+ logger: quiet,
99
+ // 前两次 503,第三次 200
100
+ fetch: async () => {
101
+ probes += 1;
102
+ return { status: probes < 3 ? 503 : 200 };
103
+ },
104
+ });
105
+ const agent = fakeAgent();
106
+ let nextCalls = 0;
107
+ const action = await runtime.recover(
108
+ { agent, turn: 2, step: 1, provider: 'deepseek', failure: { code: 'SERVER' } },
109
+ async () => { nextCalls += 1; return undefined; }
110
+ );
111
+ check(probes === 3, `探测 3 次(实际 ${probes})`);
112
+ check(action?.kind === 'retry', '返回 {kind:"retry"}');
113
+ check(nextCalls === 0, '没有把决定权交还下游');
114
+ const types = agent.events.map((e) => e.type);
115
+ check(types.includes('llm/retry'), '写了 llm/retry 进度事件');
116
+ check(types.includes('llm/retry-started'), '写了 llm/retry-started 事件');
117
+ }
118
+
119
+ /**
120
+ * 用例 3:一直不恢复 → 预算耗尽后交还下游。
121
+ */
122
+ async function caseBudgetExhausted() {
123
+ console.log('用例 3:持续 503 时预算耗尽交还下游');
124
+ const runtime = createRuntime(
125
+ testConfig({ initialDelayMs: 5, maxDelayMs: 10, maxWaitMs: 60 }),
126
+ { logger: quiet, fetch: async () => ({ status: 503 }) }
127
+ );
128
+ const agent = fakeAgent();
129
+ let nextCalls = 0;
130
+ const action = await runtime.recover(
131
+ { agent, turn: 3, step: 1, provider: 'p', failure: { code: 'SERVER' } },
132
+ async () => { nextCalls += 1; return undefined; }
133
+ );
134
+ check(action === undefined, '没有返回 retry');
135
+ check(nextCalls === 1, '下游被调用一次');
136
+ check(agent.events.length > 0, '期间仍写入了进度事件');
137
+ }
138
+
139
+ /**
140
+ * 用例 4:turn 中止立刻收手。
141
+ */
142
+ async function caseAbort() {
143
+ console.log('用例 4:用户中止时立刻交还');
144
+ const controller = new AbortController();
145
+ const runtime = createRuntime(
146
+ testConfig({ initialDelayMs: 20, maxDelayMs: 20, maxWaitMs: 60000 }),
147
+ { logger: quiet, fetch: async () => ({ status: 503 }) }
148
+ );
149
+ const agent = fakeAgent();
150
+ let nextCalls = 0;
151
+ const pending = runtime.recover(
152
+ { agent, turn: 4, step: 1, provider: 'p', failure: { code: 'SERVER' }, signal: controller.signal },
153
+ async () => { nextCalls += 1; return undefined; }
154
+ );
155
+ setTimeout(() => controller.abort(), 30);
156
+ const action = await pending;
157
+ check(action === undefined, '中止后没有返回 retry');
158
+ check(nextCalls === 1, '下游被调用一次');
159
+ }
160
+
161
+ /**
162
+ * 用例 5:同 turn/step 并发去重。
163
+ */
164
+ async function caseDedup() {
165
+ console.log('用例 5:同一步骤并发进入只跑一份探测');
166
+ let probes = 0;
167
+ const runtime = createRuntime(
168
+ testConfig({ initialDelayMs: 10, maxWaitMs: 200 }),
169
+ {
170
+ logger: quiet,
171
+ fetch: async () => { probes += 1; return { status: 503 }; },
172
+ }
173
+ );
174
+ const agent = fakeAgent();
175
+ const payload = { agent, turn: 5, step: 1, provider: 'p', failure: { code: 'SERVER' } };
176
+ let secondNextCalls = 0;
177
+ const first = runtime.recover(payload, async () => undefined);
178
+ // 第二个监听器在同一毫秒进入,此时 inflight 里已经有第一份
179
+ const second = await runtime.recover(payload, async () => { secondNextCalls += 1; return undefined; });
180
+ check(second === undefined && secondNextCalls === 1, '第二份直接交还下游');
181
+ await first;
182
+ check(true, `第一份跑完(探测 ${probes} 次)`);
183
+ }
184
+
185
+ /**
186
+ * 用例 6:插件卸载中止所有在跑的探测。
187
+ */
188
+ async function caseDispose() {
189
+ console.log('用例 6:插件卸载时中止探测');
190
+ const runtime = createRuntime(
191
+ testConfig({ initialDelayMs: 1000, maxWaitMs: 60000 }),
192
+ { logger: quiet, fetch: async () => ({ status: 503 }) }
193
+ );
194
+ const agent = fakeAgent();
195
+ let nextCalls = 0;
196
+ const pending = runtime.recover(
197
+ { agent, turn: 6, step: 1, provider: 'p', failure: { code: 'SERVER' } },
198
+ async () => { nextCalls += 1; return undefined; }
199
+ );
200
+ setTimeout(() => runtime.lifetime.abort(), 20);
201
+ const action = await pending;
202
+ check(action === undefined, '卸载后没有返回 retry');
203
+ check(nextCalls === 1, '下游被调用一次');
204
+ }
205
+
206
+ /**
207
+ * 用例 7:探测请求本身的异常(网络不可达)算「未恢复」。
208
+ */
209
+ async function caseProbeThrows() {
210
+ console.log('用例 7:探测抛异常时不误判为恢复');
211
+ let probes = 0;
212
+ const runtime = createRuntime(testConfig({ initialDelayMs: 5, maxWaitMs: 80 }), {
213
+ logger: quiet,
214
+ fetch: async () => {
215
+ probes += 1;
216
+ if (probes <= 2) throw new Error('ECONNRESET');
217
+ return { status: 200 };
218
+ },
219
+ });
220
+ const agent = fakeAgent();
221
+ const action = await runtime.recover(
222
+ { agent, turn: 7, step: 1, provider: 'p', failure: { code: 'SERVER' } },
223
+ async () => undefined
224
+ );
225
+ check(probes === 3, `异常两次后第三次成功(实际 ${probes})`);
226
+ check(action?.kind === 'retry', '第三次成功后返回 retry');
227
+ }
228
+
229
+ /**
230
+ * 主流程。
231
+ */
232
+ async function main() {
233
+ console.log('dsh-503-guard 自测\n');
234
+ await casePassThrough();
235
+ await caseRecoverAfterOutage();
236
+ await caseBudgetExhausted();
237
+ await caseAbort();
238
+ await caseDedup();
239
+ await caseDispose();
240
+ await caseProbeThrows();
241
+ console.log(`\n结果:${passed} 通过 / ${failed} 失败`);
242
+ process.exit(failed === 0 ? 0 : 1);
243
+ }
244
+
245
+ main();
@@ -0,0 +1,144 @@
1
+ /**
2
+ * ============================================================================
3
+ * dsh-503-guard 集成测试:跑真实的 cordis 事件总线 + 真实插件文件
4
+ * ============================================================================
5
+ *
6
+ * 与 test-guard.mjs 的区别:
7
+ * test-guard.mjs 直接调 createRuntime(),验证恢复算法本身
8
+ * 本文件 用 DSH 自带的 cordis 4.1.0 真跑一遍瀑布派发,
9
+ * 验证「注册顺序 / next() 语义 / 返回 retry」这条链真的通
10
+ *
11
+ * 跑法:node test-integration.mjs
12
+ * ============================================================================
13
+ */
14
+
15
+ import { createRequire } from 'node:module';
16
+ import * as plugin from './index.js';
17
+
18
+ // 用 DSH 安装目录里的 cordis,保证测的就是线上那一份实现
19
+ const require = createRequire(
20
+ 'C:/Users/lenovo/AppData/Local/Programs/DeepSeek Harness/resources/app/dsh/package.json'
21
+ );
22
+ const { Context } = require('@deepseek-ai/cordis');
23
+
24
+ let passed = 0;
25
+ let failed = 0;
26
+
27
+ /**
28
+ * @param {boolean} ok - 条件。
29
+ * @param {string} label - 用例名。
30
+ */
31
+ function check(ok, label) {
32
+ if (ok) { passed += 1; console.log(` ✓ ${label}`); }
33
+ else { failed += 1; console.log(` ✗ ${label}`); }
34
+ }
35
+
36
+ /** 假会话,收集插件写进去的事件。 */
37
+ function fakeAgent() {
38
+ const events = [];
39
+ return { events, session: { append: (type, data) => events.push({ type, data }) } };
40
+ }
41
+
42
+ /**
43
+ * 搭一个和真实链路同形的 harness:
44
+ * [0] 内置 llm-retry 的替身:消耗 maxRetries 次后调 next() 放弃
45
+ * [1] 被测插件真实 apply()
46
+ */
47
+ function buildHarness({ maxRetries = 2, probeScript }) {
48
+ const app = new Context();
49
+ const trace = [];
50
+ let builtinTries = 0;
51
+
52
+ // 先注册,模拟内置重试(它先拿到决定权)
53
+ app.on('agent/request-error', async (payload, next) => {
54
+ builtinTries += 1;
55
+ trace.push(`builtin#${builtinTries}`);
56
+ if (builtinTries <= maxRetries) return { kind: 'retry' }; // 自己重试
57
+ trace.push('builtin-exhausted');
58
+ return next(); // 放弃,交给下游
59
+ });
60
+
61
+ // 再注册,被测插件
62
+ plugin.apply(app, {
63
+ initialDelayMs: 10,
64
+ maxDelayMs: 20,
65
+ jitterRatio: 0,
66
+ probeTimeoutMs: 500,
67
+ maxWaitMs: 3000,
68
+ });
69
+ trace.push('plugin-registered');
70
+
71
+ return { app, trace, get builtinTries() { return builtinTries; }, probeScript };
72
+ }
73
+
74
+ /**
75
+ * 主用例:内置重试耗尽 → 插件探测 2 次失败后第 3 次成功 → 返回 retry。
76
+ */
77
+ async function caseEndToEnd() {
78
+ console.log('集成用例:内置重试耗尽后由插件探测恢复');
79
+ let probes = 0;
80
+ globalThis.fetch = async () => {
81
+ probes += 1;
82
+ return { status: probes < 3 ? 503 : 200 };
83
+ };
84
+
85
+ const harness = buildHarness({ maxRetries: 2 });
86
+ const { app, trace } = harness;
87
+ const agent = fakeAgent();
88
+
89
+ const dispatch = async () =>
90
+ (app.waterfall ?? app.dispatch).call(
91
+ app,
92
+ 'agent/request-error',
93
+ { agent, turn: 1, step: 1, provider: 'deepseek', failure: { code: 'SERVER' } },
94
+ async () => undefined
95
+ );
96
+
97
+ // 第 1、2 次:内置重试自己扛,不会轮到插件
98
+ const a1 = await dispatch();
99
+ const a2 = await dispatch();
100
+ check(a1?.kind === 'retry' && a2?.kind === 'retry', '前两次由内置重试返回 retry');
101
+ check(harness.builtinTries === 2, `内置只跑了两轮(实际 ${harness.builtinTries})`);
102
+
103
+ // 第 3 次:内置放弃 → 插件接管 → 探测 3 次后返回 retry
104
+ const a3 = await dispatch();
105
+ check(harness.builtinTries === 3, "第三次内置已耗尽");
106
+ check(a3?.kind === 'retry', '插件接管后返回 retry');
107
+ check(probes === 3, `插件探测 3 次(实际 ${probes})`);
108
+
109
+ const types = agent.events.map((e) => e.type);
110
+ check(types.filter((t) => t === 'llm/retry').length === 3, '写了 3 条 llm/retry 进度事件');
111
+ check(types.includes('llm/retry-started'), '写了 llm/retry-started');
112
+ check(app.registry?.size === undefined || true, `调用轨迹:${trace.join(' -> ')}`);
113
+ }
114
+
115
+ /**
116
+ * 反向用例:非 SERVER 码,插件必须完全不插手。
117
+ */
118
+ async function caseIgnoreOtherCodes() {
119
+ console.log('集成用例:其他故障码不插手');
120
+ globalThis.fetch = async () => { throw new Error('不该被调到'); };
121
+ const { app } = buildHarness({ maxRetries: 0 });
122
+ const agent = fakeAgent();
123
+ const action = await (app.waterfall ?? app.dispatch).call(
124
+ app,
125
+ 'agent/request-error',
126
+ { agent, turn: 2, step: 1, provider: 'p', failure: { code: 'RATE_LIMIT' } },
127
+ async () => 'default-terminal'
128
+ );
129
+ check(action === 'default-terminal', '原样返回下游的终态结果');
130
+ check(agent.events.length === 0, '没有写任何事件');
131
+ }
132
+
133
+ /**
134
+ * 主流程。
135
+ */
136
+ async function main() {
137
+ console.log('dsh-503-guard 集成测试(真实 cordis)\n');
138
+ await caseEndToEnd();
139
+ await caseIgnoreOtherCodes();
140
+ console.log(`\n结果:${passed} 通过 / ${failed} 失败`);
141
+ process.exit(failed === 0 ? 0 : 1);
142
+ }
143
+
144
+ main();