dsh-im-union 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 本项目版本号遵循语义化版本；发布面与宿主兼容矩阵见 `scripts/hosts.mjs`（README 管理块同源）。
 
+## 0.5.3（Discord Gateway 自动重连与 RESUME 续传：#2 收口）
+
+原挂账 T2.5 落地：连接一断就只记日志、不重建，而 Discord 会**定期**主动下发 `op 7 RECONNECT`，所以这条路径必然被走到——账号静默失联直到手动重启。
+
+### Added
+
+- **退避自动重连**：`close` / `op 7` / 僵尸判定统一走 `scheduleAttempt()`——指数退避 `base·2^(n-1)`（默认 1s 起）+ 正向抖动≤30%（免全量客户端同刻共击），封顶 60s；**不主动放弃**（IM 账号静默失联比慢重连更糟）。单一 `reconnectTimer` 位即并发守卫：close 与 op7 同时触发只保留一个排程。
+- **RESUME 续传**：捕获 READY 的 `session_id` 与 `resume_gateway_url`，断线重连优先打 resume 域并发 `op 6`（带最后 `seq`），不丢断口期间的事件也不重拉全量；拿不到 resume 信息时回退完整 IDENTIFY。`RESUMED` 帧才置 `connected`，并重连成功留痕（含第几次尝试）。
+- **僵尸连接判定**：发出 `HEARTBEAT` 后下一拍仍未收 ACK → 主动断开并进重连（官方推荐做法）；收到 ACK 即清位，不误判。
+- **`op 9` 两档分流**：`d=false` 会**清 session**（不清则后续 HELLO 误走 RESUME 反复碰壁）；两档均经退避排程而非零等待，消除「op9 d=true → 同连接立即 RESUME → 再被拒」的热循环。
+
+### Fixed
+
+- **重连与上层 `connect()` 叠出双 Gateway 连接**：`AccountManager.ensureConnected` 在任何操作前都会调 `connect()`，而它在 `connected=false` 时不撤内部排程就另建一条——Discord 视为两个 session，入站可能只投其中一条。现在 `connect()` 语义改为**接管**：先 `cancelScheduled()` + 主动拆旧 socket + 归零 `attempts`，全仓始终只有一条在途连接。
+- **被替换的旧 socket 迟到事件污染当前状态**：message/close/error 三个处理器均先比 `this.ws !== ws`，旧连接的迟到帧与 close 一律丢弃（不改 `connected`、不触发新排程、不向上层投递消息）。
+
+### 面板可见性
+
+无需新增 API：重连等待期内 `connected` 保持 false，而 `account-manager` 已按 `live?.adapter?.connected === true` 透出账号状态，故降级对用户可见（不再是“看着已连接但其实哑了”）。
+
+### 备注
+
+- `reconnectBaseMs` / `reconnectMaxMs` / `random` 仅作为适配器构造选项（供测试确定性断言），**不进用户设置面**：默认值已适用于生产，多一个开关就多一类误配。
+- 新增 9 例契约测试（共 40 例 discord / **780 例全量**）：退避递增封顶、op7 不叠加排程、RESUME 域名与 seq、IDENTIFY 回退、僵尸判定与 ACK 不误判、disconnect 不重连、connect 接管不叠连、旧 socket 事件丢弃。
+
 ## 0.5.2（Discord 服务器频道消息失联：Gateway intents 位值修正）
 
 感谢 @lide4144 在 #1 里的报告与双连接对照实验，定位、根因与修正值全部准确。

package/README.en.md

@@ -3,7 +3,7 @@
 A union IM bridge for DeepSeek Harness — a clean-room reimplementation merging the capability sets of xmanrui/dsh-im and MichengAI/dsh-im-connect, with no source copied from either.
 
 <!-- host-compat:begin — generated by scripts/sync-hosts.mjs from scripts/hosts.mjs; DO NOT EDIT -->
-- **Supported DSH hosts:** `0.1.2-rc.1` `0.1.5-rc.1` `0.1.5-rc.2` `0.1.5-rc.3` `0.1.7-rc.1` `0.1.7-rc.2` `0.2.0-rc.1` `0.2.0-rc.2` `0.2.1-alpha.2` `0.2.1-alpha.3` `0.2.1-rc.1` `0.2.1-rc.2` `0.2.1-rc.3` `0.2.1-rc.4` (14 rc/alpha releases across lines 0.1.2 / 0.1.5 / 0.1.7 / 0.2.0 / 0.2.1)
+- **Supported DSH hosts:** `0.1.2-rc.1` `0.1.5-rc.1` `0.1.5-rc.2` `0.1.5-rc.3` `0.1.7-rc.1` `0.1.7-rc.2` `0.2.0-rc.1` `0.2.0-rc.2` `0.2.1-alpha.2` `0.2.1-alpha.3` `0.2.1-rc.1` `0.2.1-rc.2` `0.2.1-rc.3` `0.2.1-rc.4` `0.2.1-rc.5` `0.2.2-rc.1` (16 rc/alpha releases across lines 0.1.2 / 0.1.5 / 0.1.7 / 0.2.0 / 0.2.1)
 <!-- host-compat:end -->
 
 ## Status

package/README.md

@@ -3,7 +3,7 @@
 DeepSeek Harness 的 IM 联合桥——净室重写，能力合集来自社区两仓（xmanrui/dsh-im 与 MichengAI/dsh-im-connect），不复制其源码。
 
 <!-- host-compat:begin — generated by scripts/sync-hosts.mjs from scripts/hosts.mjs; DO NOT EDIT -->
-- **支持的 DSH 宿主：** `0.1.2-rc.1` `0.1.5-rc.1` `0.1.5-rc.2` `0.1.5-rc.3` `0.1.7-rc.1` `0.1.7-rc.2` `0.2.0-rc.1` `0.2.0-rc.2` `0.2.1-alpha.2` `0.2.1-alpha.3` `0.2.1-rc.1` `0.2.1-rc.2` `0.2.1-rc.3` `0.2.1-rc.4`（覆盖 0.1.2 / 0.1.5 / 0.1.7 / 0.2.0 / 0.2.1 共 14 个 rc/alpha）
+- **支持的 DSH 宿主：** `0.1.2-rc.1` `0.1.5-rc.1` `0.1.5-rc.2` `0.1.5-rc.3` `0.1.7-rc.1` `0.1.7-rc.2` `0.2.0-rc.1` `0.2.0-rc.2` `0.2.1-alpha.2` `0.2.1-alpha.3` `0.2.1-rc.1` `0.2.1-rc.2` `0.2.1-rc.3` `0.2.1-rc.4` `0.2.1-rc.5` `0.2.2-rc.1`（覆盖 0.1.2 / 0.1.5 / 0.1.7 / 0.2.0 / 0.2.1 共 16 个 rc/alpha）
 <!-- host-compat:end -->
 
 ## 状态

package/dsh.plugin.json

@@ -1,14 +1,14 @@
 {
   "id": "dsh-im-union",
   "name": "dsh-im-union",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": {
     "en": "Union IM bridge for DeepSeek Harness: multi-account bots across messaging platforms, each chat bound to its own session, with cross-host-version compatibility (0.1.2-rc.1 .. 0.2.1-rc.3).",
     "zh": "DeepSeek Harness 的 IM 联合桥：多平台多账号机器人、每个聊天绑定独立会话，跨宿主版本兼容（0.1.2-rc.1 至 0.2.1-rc.3）。"
   },
   "license": "MIT",
   "engines": {
-    "dsh": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4"
+    "dsh": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1"
   },
   "main": "./lib/index.js",
   "client": {

package/lib/channels/discord.d.ts

@@ -53,6 +53,12 @@ export interface DiscordAdapterOptions {
     fetchImpl?: FetchLike;
     WebSocketImpl?: WSFactory;
     logger?: (msg: string) => void;
+    /** 重连退避基准（默认 1000ms），按 2^n 递增到 `reconnectMaxMs`；测试可压小。 */
+    reconnectBaseMs?: number;
+    /** 重连退避上限（默认 60000ms）：不放弃重试，只封顶等待。 */
+    reconnectMaxMs?: number;
+    /** 抖动源（默认 `Math.random`）：测试注定值以确定性断言等待时长。 */
+    random?: () => number;
 }
 export declare class DiscordApiError extends Error {
     readonly status: number;
@@ -70,19 +76,56 @@ export declare class DiscordAdapter implements ChannelAdapter {
     private readonly fetchImpl;
     private readonly wsFactory;
     private readonly log;
+    private readonly reconnectBaseMs;
+    private readonly reconnectMaxMs;
+    private readonly random;
     private listeners;
     private ws;
     private botUserId;
     private lastSeq;
     private heartbeat;
     private readonly closeController;
+    /** 首次 IDENTIFY 用的 Gateway 地址（`connect()` 取定）；重连优先走 `resumeUrl`。 */
+    private gatewayUrl;
+    /** READY 下发的 session_id：有值且 `resumeUrl` 在位才能 RESUME（不丢事件）。 */
+    private sessionId;
+    /** READY 下发的 resume_gateway_url（与初次 `/gateway` 不同域，必须用它续传）。 */
+    private resumeUrl;
+    /** 连续重连次数；READY/RESUMED 归零，驱动指数退避。 */
+    private attempts;
+    /** 已发 HEARTBEAT 等 ACK：下一拍仍未清即判定僵尸连接。 */
+    private awaitingAck;
+    /** 待执行的重连排程（单一排程位即并发守卫：重复 close/RECONNECT 不叠加）。 */
+    private reconnectTimer;
+    /** 主动拆线位：`disconnect()` 后不得再自动重连。 */
+    private shuttingDown;
     constructor(options: DiscordAdapterOptions);
     onMessage(listener: MessageListener): () => void;
     private rest;
     connect(signal?: AbortSignal): Promise<void>;
+    /**
+     * 建一条 Gateway 连接。重连不重跑 `connect()` 的 REST 面：
+     * 能续传时用 READY 给的 `resume_gateway_url`，否则回退初次取定的 `gatewayUrl`。
+     */
+    private openGateway;
+    /** 取消待执行的重连排程（单一收口，避免各处 clearTimeout 写法走样）。 */
+    private cancelScheduled;
     disconnect(): Promise<void>;
     private handleGatewayFrame;
     private sendIdentify;
+    /** 可续传：READY 同时给了 session_id 与 resume_gateway_url 才成立（缺一必须重 IDENTIFY）。 */
+    private canResume;
+    private sendResume;
+    /** 指数退避 + 正向抖动（最多 +30%，避免全量客户端同刻共击）：base·2^(n-1) 封顶 maxMs。 */
+    private backoffMs;
+    /**
+     * 唯一的退避排程原语。单一 `reconnectTimer` 位就是并发守卫：close、op7、op9 多源
+     * 同时触发时只保留第一个排程（不叠加、不互相覆盖、不泄漏旧定时器）。
+     * 不主动放弃：只把等待封顶在 `reconnectMaxMs`，IM 账号静默失联比慢重连更糟。
+     */
+    private scheduleAttempt;
+    /** 重连一条新连接：不重跑 `connect()` 的 REST 面，地址用已取定的 resume/gateway 位。 */
+    private scheduleReconnect;
     private sendHeartbeat;
     private stopHeartbeat;
     private sendFrame;

package/lib/channels/discord.js

@@ -62,12 +62,29 @@ export class DiscordAdapter {
     fetchImpl;
     wsFactory;
     log;
+    reconnectBaseMs;
+    reconnectMaxMs;
+    random;
     listeners = [];
     ws;
     botUserId = '';
     lastSeq;
     heartbeat;
     closeController = new AbortController();
+    /** 首次 IDENTIFY 用的 Gateway 地址（`connect()` 取定）；重连优先走 `resumeUrl`。 */
+    gatewayUrl = '';
+    /** READY 下发的 session_id：有值且 `resumeUrl` 在位才能 RESUME（不丢事件）。 */
+    sessionId = '';
+    /** READY 下发的 resume_gateway_url（与初次 `/gateway` 不同域，必须用它续传）。 */
+    resumeUrl = '';
+    /** 连续重连次数；READY/RESUMED 归零，驱动指数退避。 */
+    attempts = 0;
+    /** 已发 HEARTBEAT 等 ACK：下一拍仍未清即判定僵尸连接。 */
+    awaitingAck = false;
+    /** 待执行的重连排程（单一排程位即并发守卫：重复 close/RECONNECT 不叠加）。 */
+    reconnectTimer;
+    /** 主动拆线位：`disconnect()` 后不得再自动重连。 */
+    shuttingDown = false;
     constructor(options) {
         if (typeof options.token !== 'string' || options.token === '') {
             throw new Error('discord: botToken 缺失（凭据库解析失败或未配置账号）');
@@ -75,6 +92,9 @@ export class DiscordAdapter {
         this.token = options.token;
         this.apiBase = options.apiBase ?? 'https://discord.com/api/v10';
         this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.reconnectBaseMs = options.reconnectBaseMs ?? 1000;
+        this.reconnectMaxMs = options.reconnectMaxMs ?? 60_000;
+        this.random = options.random ?? Math.random;
         const globalWS = globalThis.WebSocket;
         this.wsFactory =
             options.WebSocketImpl ??
@@ -118,34 +138,87 @@ export class DiscordAdapter {
     }
     // —— Gateway ——————————————————————————————————————————
     async connect(signal) {
+        this.shuttingDown = false;
+        // 上层显式 connect（`AccountManager.ensureConnected` 在任何操作前都会调）：
+        // 由它接管重连。若不先撤内部排程并拆旧 socket，会同时存在两条 Gateway 连接
+        // （Discord 视为两个 session，入站可能只投其中一条）。
+        this.cancelScheduled();
+        this.attempts = 0;
+        const prev = this.ws;
+        if (prev !== undefined) {
+            this.ws = undefined; // 先摘引用：旧 socket 迟到的 close/message 不再参与状态判定
+            this.stopHeartbeat();
+            try {
+                prev.close();
+            }
+            catch {
+                // ignore：旧连接关不上也不能阻塞新连接建立。
+            }
+        }
         const me = (await this.rest('GET', '/users/@me', undefined, signal));
         this.botUserId = String(me.id ?? '');
         const gateway = (await this.rest('GET', '/gateway', undefined, signal));
         const url = String(gateway.url ?? 'wss://gateway.discord.gg/?v=10&encoding=json');
-        const wsUrl = url.includes('?') ? `${url}&encoding=json` : `${url}/?v=10&encoding=json`;
+        this.gatewayUrl = url.includes('?') ? `${url}&encoding=json` : `${url}/?v=10&encoding=json`;
+        this.openGateway();
+    }
+    /**
+     * 建一条 Gateway 连接。重连不重跑 `connect()` 的 REST 面：
+     * 能续传时用 READY 给的 `resume_gateway_url`，否则回退初次取定的 `gatewayUrl`。
+     */
+    openGateway() {
+        if (this.shuttingDown)
+            return;
+        const wsUrl = this.resumeUrl !== '' ? this.resumeUrl : this.gatewayUrl;
         const ws = this.wsFactory(wsUrl);
         this.ws = ws;
-        ws.addEventListener('message', (event) => this.handleGatewayFrame(String(event.data)));
+        this.awaitingAck = false;
+        // 两个处理器都先比 `this.ws !== ws`：被 connect()/重连替换过的旧 socket，
+        // 其迟到帧与 close 一律不得再改当前状态（否则会误判断开、叠排重连）。
+        ws.addEventListener('message', (event) => {
+            if (this.ws !== ws)
+                return;
+            this.handleGatewayFrame(String(event.data));
+        });
         ws.addEventListener('close', () => {
+            if (this.ws !== ws)
+                return;
             this.connected = false;
             this.stopHeartbeat();
-            if (!this.closeController.signal.aborted)
-                this.log('discord Gateway 断开（上层重连策略归 T2.5）');
+            // 主动拆线（disconnect / 宿主 abort / connect 接管）不重连；其余一律进退避排程。
+            if (this.shuttingDown || this.closeController.signal.aborted)
+                return;
+            this.scheduleReconnect('断开');
         });
         ws.addEventListener('error', () => {
+            if (this.ws !== ws)
+                return;
             this.connected = false;
         });
     }
+    /** 取消待执行的重连排程（单一收口，避免各处 clearTimeout 写法走样）。 */
+    cancelScheduled() {
+        if (this.reconnectTimer !== undefined) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+    }
     async disconnect() {
+        this.shuttingDown = true;
         this.stopHeartbeat();
+        this.cancelScheduled();
+        this.sessionId = '';
+        this.resumeUrl = '';
+        this.attempts = 0;
         this.closeController.abort();
+        const ws = this.ws;
+        this.ws = undefined;
         try {
-            this.ws?.close();
+            ws?.close();
         }
         catch {
             // 已断开即目标达成。
         }
-        this.ws = undefined;
         this.connected = false;
     }
     handleGatewayFrame(raw) {
@@ -164,32 +237,63 @@ export class DiscordAdapter {
                 const intervalMs = Number(frame.d?.heartbeat_interval ?? 41250);
                 this.stopHeartbeat();
                 this.heartbeat = setInterval(() => this.sendHeartbeat(), intervalMs);
-                this.sendIdentify();
+                // 有 session 就续传（不丢断口期间的事件、不重拉全量）；否则完整 IDENTIFY。
+                if (this.canResume())
+                    this.sendResume();
+                else
+                    this.sendIdentify();
                 return;
             }
             case OP.HEARTBEAT_ACK:
+                this.awaitingAck = false;
                 return;
             case OP.RECONNECT:
-                this.log('discord Gateway 要求重连（当前实现退IDENTIFY重建）');
+                // 服务端定期要求重连：先落排程，再关连接（close 处理器看到已有排程就不叠加）。
+                this.scheduleReconnect('收到 op7 RECONNECT');
                 try {
                     this.ws?.close();
                 }
                 catch {
-                    // ignore
+                    // ignore：排程已落，关失败也不影响下一轮。
                 }
                 return;
             case OP.INVALID_SESSION: {
                 this.connected = false;
                 this.stopHeartbeat();
-                if (frame.d === true) {
-                    this.log('discord 会话可续（RESUME 归后续迭代），当前直接重 IDENTIFY');
-                }
-                this.sendIdentify();
+                // d=false 意味会话已确定没了：不清 session 的话，下一条 HELLO 会误走 RESUME 反复碰壁。
+                if (frame.d !== true)
+                    this.sessionId = '';
+                // 官方要求收到 op9 后等 1–5s 再动作；走同一退避位，不另并一套定时器，
+                // 也避免「op9 d=true → 同连接立即 RESUME → 再被拒」的热循环。
+                const useResume = this.canResume();
+                this.scheduleAttempt(`会话失效（op9 d=${String(frame.d)}）`, () => {
+                    if (useResume)
+                        this.sendResume();
+                    else
+                        this.sendIdentify();
+                });
                 return;
             }
             case OP.DISPATCH: {
                 if (frame.t === 'READY') {
                     this.connected = true;
+                    this.attempts = 0;
+                    this.awaitingAck = false;
+                    this.sessionId = String(frame.d?.session_id ?? '');
+                    const resume = frame.d?.resume_gateway_url;
+                    if (typeof resume === 'string' && resume !== '')
+                        this.resumeUrl = resume;
+                    this.log(this.sessionId !== '' && this.resumeUrl !== ''
+                        ? 'discord Gateway 就绪（session 已建立，后续断开可 RESUME 续传）'
+                        : 'discord Gateway 就绪（未拿到 resume 信息，后续断开将重 IDENTIFY）');
+                    return;
+                }
+                if (frame.t === 'RESUMED') {
+                    const recovered = this.attempts;
+                    this.connected = true;
+                    this.attempts = 0;
+                    this.awaitingAck = false;
+                    this.log(`discord Gateway RESUME 成功（断口期间事件已续传${recovered > 1 ? `，第 ${recovered} 次尝试` : ''}）`);
                     return;
                 }
                 if (frame.t === 'MESSAGE_CREATE') {
@@ -223,7 +327,73 @@ export class DiscordAdapter {
             },
         });
     }
+    /** 可续传：READY 同时给了 session_id 与 resume_gateway_url 才成立（缺一必须重 IDENTIFY）。 */
+    canResume() {
+        return this.sessionId !== '' && this.resumeUrl !== '';
+    }
+    sendResume() {
+        this.sendFrame({
+            op: OP.RESUME,
+            d: { token: this.token, session_id: this.sessionId, seq: this.lastSeq ?? 0 },
+        });
+    }
+    /** 指数退避 + 正向抖动（最多 +30%，避免全量客户端同刻共击）：base·2^(n-1) 封顶 maxMs。 */
+    backoffMs(attempt) {
+        const base = Math.min(this.reconnectBaseMs * 2 ** Math.max(0, attempt - 1), this.reconnectMaxMs);
+        return Math.round(base * (1 + this.random() * 0.3));
+    }
+    /**
+     * 唯一的退避排程原语。单一 `reconnectTimer` 位就是并发守卫：close、op7、op9 多源
+     * 同时触发时只保留第一个排程（不叠加、不互相覆盖、不泄漏旧定时器）。
+     * 不主动放弃：只把等待封顶在 `reconnectMaxMs`，IM 账号静默失联比慢重连更糟。
+     */
+    scheduleAttempt(reason, action) {
+        if (this.shuttingDown)
+            return;
+        if (this.reconnectTimer !== undefined) {
+            this.log(`discord ${reason}：已有重连排程在队，不叠加`);
+            return;
+        }
+        const attempt = ++this.attempts;
+        const wait = this.backoffMs(attempt);
+        this.log(`discord ${reason}，${wait}ms 后第 ${attempt} 次尝试`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            if (this.shuttingDown)
+                return;
+            try {
+                action();
+            }
+            catch (error) {
+                // 建连/发帧本身抛（如宿主缺 WebSocket）：转下一轮退避，不把异常冒到事件循环外。
+                this.log(`discord 重连尝试失败: ${error.message}`);
+                this.scheduleAttempt('重连尝试失败', action);
+            }
+        }, wait);
+    }
+    /** 重连一条新连接：不重跑 `connect()` 的 REST 面，地址用已取定的 resume/gateway 位。 */
+    scheduleReconnect(reason) {
+        this.scheduleAttempt(`Gateway ${reason}`, () => {
+            this.openGateway();
+        });
+    }
     sendHeartbeat() {
+        // 上一拍还没 ACK 就到了下一拍 = 僵尸连接（TCP 活着但服务端已不响应），
+        // 官方推荐做法是主动断开重建；close 处理器会接手排重连。
+        if (this.awaitingAck) {
+            this.awaitingAck = false;
+            this.stopHeartbeat();
+            this.log('discord 心跳无 ACK，判定僵尸连接并主动断开重连');
+            try {
+                this.ws?.close();
+            }
+            catch {
+                // close 处理器不可依赖时，手动补一排程。
+                this.scheduleReconnect('僵尸连接断开失败');
+            }
+            return;
+        }
+        this.awaitingAck = true;
         this.sendFrame({ op: OP.HEARTBEAT, d: this.lastSeq ?? null });
     }
     stopHeartbeat() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-im-union",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Union IM bridge for DeepSeek Harness 鈥?clean-room merge of dsh-im and dsh-im-connect capabilities, compatible across 0.1.2-rc.1 .. 0.2.1-rc.2 hosts.",
   "type": "module",
   "license": "MIT",
@@ -41,16 +41,16 @@
   },
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4"
+    "dsh": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-locale": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-settings": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4",
-    "@deepseek-ai/dsh-host-webserver": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4",
+    "@deepseek-ai/dsh-agent": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2",
     "react": "^18.2.0"
   },

package/src/channels/discord.ts

@@ -99,6 +99,12 @@ export interface DiscordAdapterOptions {
   fetchImpl?: FetchLike
   WebSocketImpl?: WSFactory
   logger?: (msg: string) => void
+  /** 重连退避基准（默认 1000ms），按 2^n 递增到 `reconnectMaxMs`；测试可压小。 */
+  reconnectBaseMs?: number
+  /** 重连退避上限（默认 60000ms）：不放弃重试，只封顶等待。 */
+  reconnectMaxMs?: number
+  /** 抖动源（默认 `Math.random`）：测试注定值以确定性断言等待时长。 */
+  random?: () => number
 }
 
 export class DiscordApiError extends Error {
@@ -134,12 +140,29 @@ export class DiscordAdapter implements ChannelAdapter {
   private readonly fetchImpl: FetchLike
   private readonly wsFactory: WSFactory
   private readonly log: (msg: string) => void
+  private readonly reconnectBaseMs: number
+  private readonly reconnectMaxMs: number
+  private readonly random: () => number
   private listeners: MessageListener[] = []
   private ws: WSLike | undefined
   private botUserId = ''
   private lastSeq: number | undefined
   private heartbeat: ReturnType<typeof setInterval> | undefined
   private readonly closeController = new AbortController()
+  /** 首次 IDENTIFY 用的 Gateway 地址（`connect()` 取定）；重连优先走 `resumeUrl`。 */
+  private gatewayUrl = ''
+  /** READY 下发的 session_id：有值且 `resumeUrl` 在位才能 RESUME（不丢事件）。 */
+  private sessionId = ''
+  /** READY 下发的 resume_gateway_url（与初次 `/gateway` 不同域，必须用它续传）。 */
+  private resumeUrl = ''
+  /** 连续重连次数；READY/RESUMED 归零，驱动指数退避。 */
+  private attempts = 0
+  /** 已发 HEARTBEAT 等 ACK：下一拍仍未清即判定僵尸连接。 */
+  private awaitingAck = false
+  /** 待执行的重连排程（单一排程位即并发守卫：重复 close/RECONNECT 不叠加）。 */
+  private reconnectTimer: ReturnType<typeof setTimeout> | undefined
+  /** 主动拆线位：`disconnect()` 后不得再自动重连。 */
+  private shuttingDown = false
 
   constructor(options: DiscordAdapterOptions) {
     if (typeof options.token !== 'string' || options.token === '') {
@@ -148,6 +171,9 @@ export class DiscordAdapter implements ChannelAdapter {
     this.token = options.token
     this.apiBase = options.apiBase ?? 'https://discord.com/api/v10'
     this.fetchImpl = options.fetchImpl ?? ((globalThis as { fetch?: FetchLike }).fetch as FetchLike)
+    this.reconnectBaseMs = options.reconnectBaseMs ?? 1000
+    this.reconnectMaxMs = options.reconnectMaxMs ?? 60_000
+    this.random = options.random ?? Math.random
     const globalWS = (globalThis as { WebSocket?: { new (url: string): WSLike } }).WebSocket
     this.wsFactory =
       options.WebSocketImpl ??
@@ -192,33 +218,83 @@ export class DiscordAdapter implements ChannelAdapter {
   // —— Gateway ——————————————————————————————————————————
 
   async connect(signal?: AbortSignal): Promise<void> {
+    this.shuttingDown = false
+    // 上层显式 connect（`AccountManager.ensureConnected` 在任何操作前都会调）：
+    // 由它接管重连。若不先撤内部排程并拆旧 socket，会同时存在两条 Gateway 连接
+    // （Discord 视为两个 session，入站可能只投其中一条）。
+    this.cancelScheduled()
+    this.attempts = 0
+    const prev = this.ws
+    if (prev !== undefined) {
+      this.ws = undefined // 先摘引用：旧 socket 迟到的 close/message 不再参与状态判定
+      this.stopHeartbeat()
+      try {
+        prev.close()
+      } catch {
+        // ignore：旧连接关不上也不能阻塞新连接建立。
+      }
+    }
     const me = (await this.rest('GET', '/users/@me', undefined, signal)) as { id?: string }
     this.botUserId = String(me.id ?? '')
     const gateway = (await this.rest('GET', '/gateway', undefined, signal)) as { url?: string }
     const url = String(gateway.url ?? 'wss://gateway.discord.gg/?v=10&encoding=json')
-    const wsUrl = url.includes('?') ? `${url}&encoding=json` : `${url}/?v=10&encoding=json`
+    this.gatewayUrl = url.includes('?') ? `${url}&encoding=json` : `${url}/?v=10&encoding=json`
+    this.openGateway()
+  }
+
+  /**
+   * 建一条 Gateway 连接。重连不重跑 `connect()` 的 REST 面：
+   * 能续传时用 READY 给的 `resume_gateway_url`，否则回退初次取定的 `gatewayUrl`。
+   */
+  private openGateway(): void {
+    if (this.shuttingDown) return
+    const wsUrl = this.resumeUrl !== '' ? this.resumeUrl : this.gatewayUrl
     const ws = this.wsFactory(wsUrl)
     this.ws = ws
-    ws.addEventListener('message', (event: { data: string }) => this.handleGatewayFrame(String(event.data)))
+    this.awaitingAck = false
+    // 两个处理器都先比 `this.ws !== ws`：被 connect()/重连替换过的旧 socket，
+    // 其迟到帧与 close 一律不得再改当前状态（否则会误判断开、叠排重连）。
+    ws.addEventListener('message', (event: { data: string }) => {
+      if (this.ws !== ws) return
+      this.handleGatewayFrame(String(event.data))
+    })
     ws.addEventListener('close', () => {
+      if (this.ws !== ws) return
       this.connected = false
       this.stopHeartbeat()
-      if (!this.closeController.signal.aborted) this.log('discord Gateway 断开（上层重连策略归 T2.5）')
+      // 主动拆线（disconnect / 宿主 abort / connect 接管）不重连；其余一律进退避排程。
+      if (this.shuttingDown || this.closeController.signal.aborted) return
+      this.scheduleReconnect('断开')
     })
     ws.addEventListener('error', () => {
+      if (this.ws !== ws) return
       this.connected = false
     })
   }
 
+  /** 取消待执行的重连排程（单一收口，避免各处 clearTimeout 写法走样）。 */
+  private cancelScheduled(): void {
+    if (this.reconnectTimer !== undefined) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = undefined
+    }
+  }
+
   async disconnect(): Promise<void> {
+    this.shuttingDown = true
     this.stopHeartbeat()
+    this.cancelScheduled()
+    this.sessionId = ''
+    this.resumeUrl = ''
+    this.attempts = 0
     this.closeController.abort()
+    const ws = this.ws
+    this.ws = undefined
     try {
-      this.ws?.close()
+      ws?.close()
     } catch {
       // 已断开即目标达成。
     }
-    this.ws = undefined
     this.connected = false
   }
 
@@ -236,31 +312,58 @@ export class DiscordAdapter implements ChannelAdapter {
         const intervalMs = Number(frame.d?.heartbeat_interval ?? 41250)
         this.stopHeartbeat()
         this.heartbeat = setInterval(() => this.sendHeartbeat(), intervalMs)
-        this.sendIdentify()
+        // 有 session 就续传（不丢断口期间的事件、不重拉全量）；否则完整 IDENTIFY。
+        if (this.canResume()) this.sendResume()
+        else this.sendIdentify()
         return
       }
       case OP.HEARTBEAT_ACK:
+        this.awaitingAck = false
         return
       case OP.RECONNECT:
-        this.log('discord Gateway 要求重连（当前实现退IDENTIFY重建）')
+        // 服务端定期要求重连：先落排程，再关连接（close 处理器看到已有排程就不叠加）。
+        this.scheduleReconnect('收到 op7 RECONNECT')
         try {
           this.ws?.close()
         } catch {
-          // ignore
+          // ignore：排程已落，关失败也不影响下一轮。
         }
         return
       case OP.INVALID_SESSION: {
         this.connected = false
         this.stopHeartbeat()
-        if (frame.d === true) {
-          this.log('discord 会话可续（RESUME 归后续迭代），当前直接重 IDENTIFY')
-        }
-        this.sendIdentify()
+        // d=false 意味会话已确定没了：不清 session 的话，下一条 HELLO 会误走 RESUME 反复碰壁。
+        if (frame.d !== true) this.sessionId = ''
+        // 官方要求收到 op9 后等 1–5s 再动作；走同一退避位，不另并一套定时器，
+        // 也避免「op9 d=true → 同连接立即 RESUME → 再被拒」的热循环。
+        const useResume = this.canResume()
+        this.scheduleAttempt(`会话失效（op9 d=${String(frame.d)}）`, () => {
+          if (useResume) this.sendResume()
+          else this.sendIdentify()
+        })
         return
       }
       case OP.DISPATCH: {
         if (frame.t === 'READY') {
           this.connected = true
+          this.attempts = 0
+          this.awaitingAck = false
+          this.sessionId = String(frame.d?.session_id ?? '')
+          const resume = frame.d?.resume_gateway_url
+          if (typeof resume === 'string' && resume !== '') this.resumeUrl = resume
+          this.log(
+            this.sessionId !== '' && this.resumeUrl !== ''
+              ? 'discord Gateway 就绪（session 已建立，后续断开可 RESUME 续传）'
+              : 'discord Gateway 就绪（未拿到 resume 信息，后续断开将重 IDENTIFY）',
+          )
+          return
+        }
+        if (frame.t === 'RESUMED') {
+          const recovered = this.attempts
+          this.connected = true
+          this.attempts = 0
+          this.awaitingAck = false
+          this.log(`discord Gateway RESUME 成功（断口期间事件已续传${recovered > 1 ? `，第 ${recovered} 次尝试` : ''}）`)
           return
         }
         if (frame.t === 'MESSAGE_CREATE') {
@@ -297,7 +400,74 @@ export class DiscordAdapter implements ChannelAdapter {
     })
   }
 
+  /** 可续传：READY 同时给了 session_id 与 resume_gateway_url 才成立（缺一必须重 IDENTIFY）。 */
+  private canResume(): boolean {
+    return this.sessionId !== '' && this.resumeUrl !== ''
+  }
+
+  private sendResume(): void {
+    this.sendFrame({
+      op: OP.RESUME,
+      d: { token: this.token, session_id: this.sessionId, seq: this.lastSeq ?? 0 },
+    })
+  }
+
+  /** 指数退避 + 正向抖动（最多 +30%，避免全量客户端同刻共击）：base·2^(n-1) 封顶 maxMs。 */
+  private backoffMs(attempt: number): number {
+    const base = Math.min(this.reconnectBaseMs * 2 ** Math.max(0, attempt - 1), this.reconnectMaxMs)
+    return Math.round(base * (1 + this.random() * 0.3))
+  }
+
+  /**
+   * 唯一的退避排程原语。单一 `reconnectTimer` 位就是并发守卫：close、op7、op9 多源
+   * 同时触发时只保留第一个排程（不叠加、不互相覆盖、不泄漏旧定时器）。
+   * 不主动放弃：只把等待封顶在 `reconnectMaxMs`，IM 账号静默失联比慢重连更糟。
+   */
+  private scheduleAttempt(reason: string, action: () => void): void {
+    if (this.shuttingDown) return
+    if (this.reconnectTimer !== undefined) {
+      this.log(`discord ${reason}：已有重连排程在队，不叠加`)
+      return
+    }
+    const attempt = ++this.attempts
+    const wait = this.backoffMs(attempt)
+    this.log(`discord ${reason}，${wait}ms 后第 ${attempt} 次尝试`)
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined
+      if (this.shuttingDown) return
+      try {
+        action()
+      } catch (error) {
+        // 建连/发帧本身抛（如宿主缺 WebSocket）：转下一轮退避，不把异常冒到事件循环外。
+        this.log(`discord 重连尝试失败: ${(error as Error).message}`)
+        this.scheduleAttempt('重连尝试失败', action)
+      }
+    }, wait)
+  }
+
+  /** 重连一条新连接：不重跑 `connect()` 的 REST 面，地址用已取定的 resume/gateway 位。 */
+  private scheduleReconnect(reason: string): void {
+    this.scheduleAttempt(`Gateway ${reason}`, () => {
+      this.openGateway()
+    })
+  }
+
   private sendHeartbeat(): void {
+    // 上一拍还没 ACK 就到了下一拍 = 僵尸连接（TCP 活着但服务端已不响应），
+    // 官方推荐做法是主动断开重建；close 处理器会接手排重连。
+    if (this.awaitingAck) {
+      this.awaitingAck = false
+      this.stopHeartbeat()
+      this.log('discord 心跳无 ACK，判定僵尸连接并主动断开重连')
+      try {
+        this.ws?.close()
+      } catch {
+        // close 处理器不可依赖时，手动补一排程。
+        this.scheduleReconnect('僵尸连接断开失败')
+      }
+      return
+    }
+    this.awaitingAck = true
     this.sendFrame({ op: OP.HEARTBEAT, d: this.lastSeq ?? null })
   }