dsh-im-union 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 本项目版本号遵循语义化版本；发布面与宿主兼容矩阵见 `scripts/hosts.mjs`（README 管理块同源）。
 
+## 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.2",
   "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

@@ -131,6 +131,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,
@@ -204,7 +217,8 @@ 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' },
             },
         });
@@ -549,5 +563,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.2",
   "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 = {
@@ -277,7 +290,8 @@ 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' },
       },
     })
@@ -647,13 +661,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 {