dsh-slack 0.3.3 → 0.3.5

package/lib/socket.js

@@ -1,16 +1,94 @@
-/**
- * Socket Mode 启动/生命周期：用 @slack/socket-mode 建立 WebSocket，
- * 收到 message 事件写入收件箱；网络错误只 warn 不抛崩（SDK 自带自动重连）。
- */
+/** Socket Mode lifecycle: SDK auto-reconnect is disabled; every attempt is owned and caught here. */
 import { SocketModeClient } from '@slack/socket-mode';
 import { parseMessageEvent } from './inbox.js';
-/**
- * 启动 Socket Mode 客户端，返回 dispose 函数（断开连接）。
- * 网络错误 / 解析错误均 try/catch + warn，绝不抛出。
- */
-export function startSocketModeClient(appToken, handler, warn) {
-    const client = new SocketModeClient({ appToken });
+const AUTH_ERRORS = new Set(['invalid_auth', 'not_authed', 'account_inactive', 'user_removed_from_team', 'team_disabled', 'token_revoked', 'token_expired', 'missing_scope', 'not_allowed_token_type']);
+function errorCode(error) {
+    const value = error;
+    const code = value?.data?.error ?? value?.code;
+    if (typeof code === 'string' && (AUTH_ERRORS.has(code) || /^(?:E[A-Z0-9_]+|slack_webapi_[a-z_]+)$/.test(code)))
+        return code;
+    return 'connection_error';
+}
+export function startSocketModeClient(appToken, handler, warn, options = {}) {
+    const client = (options.createClient ?? (config => new SocketModeClient(config)))({
+        appToken, autoReconnectEnabled: false,
+        clientOptions: { timeout: 15000, retryConfig: { retries: 0 }, rejectRateLimitedCalls: true },
+    });
+    const retryBase = Number.isFinite(options.retryBaseMs) ? Math.max(1, Math.min(30000, options.retryBaseMs)) : 1000;
+    let status = { state: 'connecting', attempts: 0 };
+    let stopped = false, fatal = false, connecting = false, needsRetry = false, failures = 0;
+    let retry;
+    const log = (message, error) => {
+        try {
+            warn('[dsh-slack] ' + message + (error === undefined ? '' : '（' + errorCode(error) + '）'));
+        }
+        catch { /* Logging must not create an unhandled rejection. */ }
+    };
+    const disconnect = () => { void Promise.resolve().then(() => client.disconnect()).catch(error => log('Socket Mode 断开失败', error)); };
+    const schedule = () => {
+        if (stopped || fatal || connecting || retry !== undefined)
+            return;
+        status = { ...status, state: 'reconnecting' };
+        const delay = Math.min(30000, retryBase * 2 ** Math.min(failures, 5));
+        retry = setTimeout(() => { retry = undefined; connect(); }, delay);
+        retry.unref?.();
+    };
+    const failure = (error) => {
+        const code = errorCode(error);
+        fatal = AUTH_ERRORS.has(code);
+        status = { ...status, state: fatal ? 'auth_failed' : 'reconnecting', error: code };
+        failures++;
+        needsRetry = !fatal;
+        log(fatal ? 'Socket Mode 令牌或权限无效，已停止重连；更新 App-Level Token 后重启插件' : 'Socket Mode 连接失败，将退避重试', error);
+        if (fatal)
+            disconnect();
+    };
+    const connect = () => {
+        if (stopped || fatal || connecting)
+            return;
+        connecting = true;
+        needsRetry = false;
+        status = { ...status, state: status.attempts === 0 ? 'connecting' : 'reconnecting', attempts: status.attempts + 1 };
+        void Promise.resolve().then(() => {
+            if (!stopped)
+                return client.start();
+        }).then(() => {
+            if (stopped)
+                disconnect();
+        }).catch(error => { if (!stopped)
+            failure(error); }).finally(() => {
+            connecting = false;
+            if (needsRetry)
+                schedule();
+        });
+    };
+    client.on('connected', () => {
+        if (stopped || fatal) {
+            disconnect();
+            return;
+        }
+        failures = 0;
+        needsRetry = false;
+        status = { state: 'connected', attempts: status.attempts };
+    });
+    client.on('disconnected', () => {
+        if (stopped || fatal)
+            return;
+        needsRetry = true;
+        status = { ...status, state: 'reconnecting' };
+        schedule();
+    });
+    client.on('error', error => {
+        if (stopped || fatal)
+            return;
+        if (AUTH_ERRORS.has(errorCode(error)))
+            failure(error);
+        else
+            log('Socket Mode 连接错误', error);
+    });
     client.on('slack_event', (...args) => {
+        if (stopped || fatal)
+            return;
         const raw = args[0];
         try {
             const message = parseMessageEvent(raw);
@@ -18,34 +96,22 @@ export function startSocketModeClient(appToken, handler, warn) {
                 handler.onMessage(message);
         }
         catch (error) {
-            warn('[dsh-slack] 解析 Socket Mode 事件失败：', error);
+            log('解析 Socket Mode 事件失败', error);
         }
         finally {
-            // events_api 事件必须 ack，否则 Slack 会重投；重复投递由收件箱 seen 去重兜底。
-            if (typeof raw.ack === 'function') {
-                void raw.ack().catch(() => { });
-            }
+            if (typeof raw?.ack === 'function')
+                void Promise.resolve().then(() => raw.ack()).catch(() => { });
         }
     });
-    client.on('error', (...args) => {
-        warn('[dsh-slack] Socket Mode 连接错误（SDK 会自动重连）：', args[0]);
-    });
-    try {
-        client.start().catch((error) => {
-            warn('[dsh-slack] Socket Mode 启动失败：', error);
-        });
-    }
-    catch (error) {
-        warn('[dsh-slack] Socket Mode 启动异常：', error);
-    }
-    return () => {
-        try {
-            client.disconnect().catch((error) => {
-                warn('[dsh-slack] Socket Mode 断开失败：', error);
-            });
-        }
-        catch (error) {
-            warn('[dsh-slack] Socket Mode 断开异常：', error);
-        }
-    };
+    connect();
+    return Object.assign(() => {
+        if (stopped)
+            return;
+        stopped = true;
+        if (retry !== undefined)
+            clearTimeout(retry);
+        retry = undefined;
+        status = { ...status, state: 'stopped' };
+        disconnect();
+    }, { status: () => ({ ...status }) });
 }

package/lib/tools.d.ts

@@ -2,11 +2,13 @@ import type { SlackConfig } from './config.js';
 import type { ToolDefinition } from './types.js';
 import type { SlackClient } from './slack-client.js';
 import type { InboxQueue } from './inbox.js';
+import type { SocketStatus } from './socket.js';
 /** 工具构建的依赖注入点。 */
 export interface ToolDeps {
     clientProvider: () => SlackClient;
     configProvider: () => SlackConfig | undefined;
     inboxProvider: () => InboxQueue;
+    socketStatusProvider?: () => SocketStatus | undefined;
 }
 /** 自检工具：检查 token / appToken / 默认频道配置，不发起网络请求。 */
 export declare function buildHealthTool(deps: ToolDeps): ToolDefinition;

package/lib/tools.js

@@ -32,6 +32,7 @@ const CHANNELS_OUTPUT_SCHEMA = {
 const INBOX_OUTPUT_SCHEMA = {
     type: 'object',
     properties: {
+        remaining: { type: 'integer' },
         messages: {
             type: 'array',
             items: {
@@ -47,7 +48,7 @@ const INBOX_OUTPUT_SCHEMA = {
             },
         },
     },
-    required: ['messages'],
+    required: ['messages', 'remaining'],
     additionalProperties: true,
 };
 function textBlock(text) {
@@ -62,7 +63,7 @@ function clampLimit(value) {
 export function buildHealthTool(deps) {
     return {
         name: 'slack_health',
-        description: 'dsh-slack 自检：检查 botToken / appToken / 默认频道配置是否就绪（不发起网络请求）。遇到问题时先运行本工具定位。',
+        description: 'dsh-slack 自检：检查 botToken / appToken / 默认频道配置和当前 Socket Mode 连接状态（不额外发起网络请求）。遇到问题时先运行本工具定位。',
         parameters: compileParameters({}),
         output: {
             schema: { type: 'object', additionalProperties: true },
@@ -83,11 +84,15 @@ export function buildHealthTool(deps) {
             const token = resolveToken(config);
             checks.push({ name: 'botToken', ok: token !== '', detail: token !== '' ? '已配置' : '未配置：请填 token 或环境变量（发送/频道工具需要）' });
             const appToken = resolveAppToken(config);
-            checks.push({ name: 'appToken', ok: true, detail: appToken !== '' ? '已配置（Socket Mode 收件箱可用）' : '未配置（收件箱功能不可用，通知不受影响）' });
+            checks.push({ name: 'appToken', ok: appToken === '' || appToken.startsWith('xapp-'), detail: appToken !== '' ? '已配置（Socket Mode 连接状态见下项）' : '未配置（收件箱功能不可用，通知不受影响）' });
             const defaultChannel = resolveDefaultChannel(config);
             checks.push({ name: '默认频道', ok: true, detail: defaultChannel !== '' ? defaultChannel : '未配置（发送时必须显式给 channel）' });
-            const ok = token !== '';
-            return { ok, plugin: 'dsh-slack', checks };
+            const socket = deps.socketStatusProvider?.();
+            const states = { connecting: '正在连接', connected: '已连接', reconnecting: '已断开，退避重连中', auth_failed: '令牌或权限无效，已停止重连；更新 App-Level Token 后重启插件', stopped: '已停止' };
+            if (appToken !== '')
+                checks.push({ name: 'Socket Mode', ok: socket?.state === 'connected', detail: socket ? states[socket.state] + (socket.error ? '（' + socket.error + '）' : '') : '仅检查配置，尚未确认连接' });
+            const ok = token !== '' && checks.every(check => check.ok === true);
+            return { ok, plugin: 'dsh-slack', checks, ...(socket ? { socket } : {}) };
         },
     };
 }
@@ -170,7 +175,7 @@ export function buildChannelsTool(deps) {
 export function buildInboxTool(deps) {
     const parameters = compileParameters({
         limit: { type: 'integer', description: '最多返回的消息数（默认 10，范围 1-50）。' },
-        markRead: { type: 'boolean', description: '为 true 时，返回后清空收件箱队列（标记已读）。' },
+        markRead: { type: 'boolean', description: '为 true 时，只将本次返回的消息标记已读；未返回的消息继续保留。' },
     });
     const output = {
         schema: INBOX_OUTPUT_SCHEMA,
@@ -180,7 +185,7 @@ export function buildInboxTool(deps) {
                 return [textBlock('收件箱为空：尚未开启 Socket Mode（缺少 appToken），或暂未收到新的 Slack 消息。请确认已配置 appToken 并订阅 message.channels / message.im 事件。')];
             }
             const lines = v.messages.map((m) => '[' + m.channel + '] ' + m.user + '（ts: ' + m.ts + '）：' + m.text);
-            return [textBlock('收件箱（' + v.messages.length + ' 条，新的在前）：\n' + lines.join('\n'))];
+            return [textBlock('收件箱（' + v.messages.length + ' 条，新的在前；剩余未读 ' + (v.remaining ?? 0) + ' 条）：\n' + lines.join('\n'))];
         },
     };
     return {
@@ -194,7 +199,7 @@ export function buildInboxTool(deps) {
             const markRead = raw.markRead === true;
             const queue = deps.inboxProvider();
             const messages = markRead ? queue.drain(limit) : queue.list(limit);
-            return { messages: messages.map((m) => ({ ts: m.ts, channel: m.channel, user: m.user, text: m.text })) };
+            return { messages: messages.map((m) => ({ ts: m.ts, channel: m.channel, user: m.user, text: m.text })), remaining: queue.size };
         },
     };
 }

package/lib/types.d.ts

@@ -28,6 +28,7 @@ export interface SlackContext {
     };
     /** Cordis 生命周期：传入启动函数，其返回的清理函数在 dispose 时执行。 */
     effect?: (start: () => void | (() => void)) => void;
+    on?: (event: 'dispose', listener: () => void) => unknown;
     /** 可选日志器；缺省回退 console.warn。 */
     logger?: {
         warn(message: string, ...args: unknown[]): void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-slack",
-  "version": "0.3.3",
-  "description": "DSH Slack 插件：通知与桥接，Socket Mode 双向消息（收件箱 + 线程回复）。",
+  "version": "0.3.5",
+  "description": "连接 Slack，发送通知并处理 Socket Mode 收件箱与线程回复。",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -17,7 +17,9 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
-    "README.en.md"
+    "README.en.md",
+    "docs",
+    "CHANGELOG.md"
   ],
   "license": "MIT",
   "dsh": {