dsh-im-union 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 本项目版本号遵循语义化版本；发布面与宿主兼容矩阵见 `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 里的报告与双连接对照实验，定位、根因与修正值全部准确。
+
+### Fixed
+
+- **Gateway intents 位值写错导致服务器频道消息永远收不到**（#1）：`GUILD_MESSAGES` 实写为 `1 << 15`（应为 `1 << 9`）、`MESSAGE_CONTENT` 实写为 `1 << 24`（应为 `1 << 15`，且 `1 << 24` 不是任何已定义 intent）。于是 IDENTIFY 实际请求的是 `MESSAGE_CONTENT | DIRECT_MESSAGES | 未定义位`，**从未订阅 GUILD_MESSAGES**——Discord 因此不推送服务器频道的 `MESSAGE_CREATE`；而握手/READY/心跳全部正常，连接看着是健康的，故极难发现。有有效值 `16814080 → 37377`。**不引入新的门户勾选要求**：`MESSAGE_CONTENT`（特权位）此前已被 `1 << 15` 误命名请求着，行为不变。
+- **IDENTIFY 补齐 `GUILDS`（`1 << 0`）**：此前 `INTENTS.GUILDS` 定了却从未使用，招不到 `GUILD_CREATE`，部分场景（刚加入的服务器、缓存缺失的频道）拿不到上下文。
+- **`createDiscordAdapter` 透传 `logger`**：`ChannelFactory` 契约早已有 `logger` 字段（宿主接线到 `plugin.log`），本工厂始终丢弃它，导致 Discord 适配器的全量生命周期日志（含“Gateway 断开”）不落盘——#1 里“`plugin.log` 没有任何入站记录”的次因。
+- **测试不得拿实现值自证**：`tests/discord.test.mjs` 原本把错误位值 `(1<<15)|(1<<12)|(1<<24)` 钉进了断言，这是本缺陷能存活的原因。现改为按官方文档值逐位断言，并加“`1<<24` 必须为 0”的回归守卫；新增 logger 透传用例。全量 771/771 绿。
+
+### Known（本版本未动，另单跟踪）
+
+- Gateway `close` 后无自动重连（仅记日志），op 7 RECONNECT 后靠重建；`AccountManager.ensureConnected` 只在操作时触发——Discord 定期下发 RECONNECT 时会静默失联直到手动重启。属代码内已标注的 **T2.5 挂账**（需退避策略 + RESUME/session 生命周期设计），与本次位值修正无关。
+
 ## 0.5.0（QQ 渠道能力补齐：出站图片 / Markdown / 入站图片文件 / 审批按钮 / 群管理）
 
 对照 `_ref-im/dsh-qqbot`（同一套 QQ 官方 api-v2）逐面解锁 `src/channels/qq.ts`，遵守净室 / 零运行时依赖 / D7 纪律。

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-im-union",
   "name": "dsh-im-union",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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）。"

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;
@@ -131,6 +174,8 @@ export declare function createDiscordAdapter(options: {
     accountId: string;
     config: Record<string, string>;
     secrets: Record<string, string | undefined>;
+    /** 生命周期日志出口（`ChannelFactory` 契约字段）；不接则 Gateway 断开等日志静默。 */
+    logger?: (msg: string) => void;
 }): DiscordAdapter;
 interface DiscordMessageLike {
     channel_id?: string;

package/lib/channels/discord.js

@@ -1,10 +1,23 @@
 import { FILE_BUDGET } from '../engine/files.js';
 import { mergeQuote } from '../engine/quote.js';
+/**
+ * Gateway intents：位值逐条对齐官方 list-of-intents。
+ *
+ * 写错不会报错也不会断连——只是对应事件永远不推，连接看着完全健康，所以很难发现
+ * （历史上 `GUILD_MESSAGES` 被写成 `1 << 15`、`MESSAGE_CONTENT` 写成 `1 << 24`，
+ * 于是服务器频道消息永远收不到）。故每个常量带官方位号注释，并由
+ * `tests/discord.test.mjs` 按位钉值校验（断言写在测试里的必须是官方文档值，
+ * 不得拿实现值自证）。
+ */
 const INTENTS = {
+    /** `1 << 0` GUILDS：`GUILD_CREATE` 等（非特权）。 */
     GUILDS: 1 << 0,
+    /** `1 << 9` GUILD_MESSAGES：服务器频道 `MESSAGE_CREATE`（非特权）。 */
+    GUILD_MESSAGES: 1 << 9,
+    /** `1 << 12` DIRECT_MESSAGES：私聊 `MESSAGE_CREATE`（非特权）。 */
     DIRECT_MESSAGES: 1 << 12,
-    GUILD_MESSAGES: 1 << 15,
-    MESSAGE_CONTENT: 1 << 24,
+    /** `1 << 15` MESSAGE_CONTENT：读消息正文（**特权** intent，需在开发者门户勾选）。 */
+    MESSAGE_CONTENT: 1 << 15,
 };
 const OP = {
     DISPATCH: 0,
@@ -49,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 缺失（凭据库解析失败或未配置账号）');
@@ -62,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 ??
@@ -105,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) {
@@ -151,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') {
@@ -204,12 +321,79 @@ export class DiscordAdapter {
             op: OP.IDENTIFY,
             d: {
                 token: this.token,
-                intents: INTENTS.GUILD_MESSAGES | INTENTS.DIRECT_MESSAGES | INTENTS.MESSAGE_CONTENT,
+                // 含 GUILDS：否则无 GUILD_CREATE，部分场景（刚加入的服务器、缓存缺失的频道）拿不到上下文。
+                intents: INTENTS.GUILDS | INTENTS.GUILD_MESSAGES | INTENTS.DIRECT_MESSAGES | INTENTS.MESSAGE_CONTENT,
                 properties: { os: 'dsh-plugin', browser: 'dsh-im-union', device: 'dsh-im-union' },
             },
         });
     }
+    /** 可续传：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() {
@@ -549,5 +733,9 @@ export function createDiscordAdapter(options) {
         throw new Error(`discord 账号 ${options.accountId}: botToken 未入库（检查凭据配置）`);
     }
     const apiBase = options.config.apiBaseUrl;
-    return new DiscordAdapter({ token, ...(apiBase !== undefined && apiBase !== '' ? { apiBase } : {}) });
+    return new DiscordAdapter({
+        token,
+        ...(apiBase !== undefined && apiBase !== '' ? { apiBase } : {}),
+        ...(options.logger !== undefined ? { logger: options.logger } : {}),
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-im-union",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "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",

package/src/channels/discord.ts

@@ -39,11 +39,24 @@ import type {
   SemanticMessage,
 } from './types.js'
 
+/**
+ * Gateway intents：位值逐条对齐官方 list-of-intents。
+ *
+ * 写错不会报错也不会断连——只是对应事件永远不推，连接看着完全健康，所以很难发现
+ * （历史上 `GUILD_MESSAGES` 被写成 `1 << 15`、`MESSAGE_CONTENT` 写成 `1 << 24`，
+ * 于是服务器频道消息永远收不到）。故每个常量带官方位号注释，并由
+ * `tests/discord.test.mjs` 按位钉值校验（断言写在测试里的必须是官方文档值，
+ * 不得拿实现值自证）。
+ */
 const INTENTS = {
+  /** `1 << 0` GUILDS：`GUILD_CREATE` 等（非特权）。 */
   GUILDS: 1 << 0,
+  /** `1 << 9` GUILD_MESSAGES：服务器频道 `MESSAGE_CREATE`（非特权）。 */
+  GUILD_MESSAGES: 1 << 9,
+  /** `1 << 12` DIRECT_MESSAGES：私聊 `MESSAGE_CREATE`（非特权）。 */
   DIRECT_MESSAGES: 1 << 12,
-  GUILD_MESSAGES: 1 << 15,
-  MESSAGE_CONTENT: 1 << 24,
+  /** `1 << 15` MESSAGE_CONTENT：读消息正文（**特权** intent，需在开发者门户勾选）。 */
+  MESSAGE_CONTENT: 1 << 15,
 } as const
 
 const OP = {
@@ -86,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 {
@@ -121,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 === '') {
@@ -135,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 ??
@@ -179,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
   }
 
@@ -223,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') {
@@ -277,13 +393,81 @@ export class DiscordAdapter implements ChannelAdapter {
       op: OP.IDENTIFY,
       d: {
         token: this.token,
-        intents: INTENTS.GUILD_MESSAGES | INTENTS.DIRECT_MESSAGES | INTENTS.MESSAGE_CONTENT,
+        // 含 GUILDS：否则无 GUILD_CREATE，部分场景（刚加入的服务器、缓存缺失的频道）拿不到上下文。
+        intents: INTENTS.GUILDS | INTENTS.GUILD_MESSAGES | INTENTS.DIRECT_MESSAGES | INTENTS.MESSAGE_CONTENT,
         properties: { os: 'dsh-plugin', browser: 'dsh-im-union', device: 'dsh-im-union' },
       },
     })
   }
 
+  /** 可续传：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 })
   }
 
@@ -647,13 +831,19 @@ export function createDiscordAdapter(options: {
   accountId: string
   config: Record<string, string>
   secrets: Record<string, string | undefined>
+  /** 生命周期日志出口（`ChannelFactory` 契约字段）；不接则 Gateway 断开等日志静默。 */
+  logger?: (msg: string) => void
 }): DiscordAdapter {
   const token = options.secrets.botToken
   if (typeof token !== 'string' || token === '') {
     throw new Error(`discord 账号 ${options.accountId}: botToken 未入库（检查凭据配置）`)
   }
   const apiBase = options.config.apiBaseUrl
-  return new DiscordAdapter({ token, ...(apiBase !== undefined && apiBase !== '' ? { apiBase } : {}) })
+  return new DiscordAdapter({
+    token,
+    ...(apiBase !== undefined && apiBase !== '' ? { apiBase } : {}),
+    ...(options.logger !== undefined ? { logger: options.logger } : {}),
+  })
 }
 
 interface DiscordMessageLike {