dsh-slack 0.3.4 → 0.3.5

package/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.3.5（2026-10-26）
+
+- Socket Mode 重连改为插件管理的有界退避；捕获启动与重连错误，凭据撤销等永久错误停止重试，卸载取消重连。自检区分凭据已配置、连接中、连接成功与认证失败。
+- Windows 回归 49 项通过、0 项跳过；宿主与未验收范围见[本次记录](docs/validation-0.3.5.md)。
+
 ## 0.3.4 (2026-10-05)
 
 - 标记已读只移除本次展示的消息，保留剩余未读与已读重投去重；发送不隐式重试，缺少消息回执时提示先检查频道。

package/README.en.md

@@ -8,6 +8,8 @@ Connect Slack for notifications, a Socket Mode inbox and thread replies.
 
 [![npm](https://img.shields.io/npm/v/dsh-slack)](https://www.npmjs.com/package/dsh-slack) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-slack-downloads.svg)](https://www.npmjs.com/package/dsh-slack)
 
+Feedback and contributions are welcome: report [issues](https://github.com/STARDUSTLC666/dsh-slack/issues) or submit [pull requests](https://github.com/STARDUSTLC666/dsh-slack/pulls).
+
 ## What it does
 
 - Send Markdown notifications to channels or threads.

package/README.md

@@ -8,6 +8,8 @@
 
 [![npm](https://img.shields.io/npm/v/dsh-slack)](https://www.npmjs.com/package/dsh-slack) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-slack-downloads.svg)](https://www.npmjs.com/package/dsh-slack)
 
+欢迎使用，遇到问题或有改进建议，请提交 [issues](https://github.com/STARDUSTLC666/dsh-slack/issues) 和 [PR](https://github.com/STARDUSTLC666/dsh-slack/pulls)。
+
 ## 功能
 
 - 向频道或线程发送 Markdown 通知。

package/docs/USAGE.en.md

@@ -2,6 +2,10 @@
 
 [Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
 
+## Connection diagnostics
+
+Configured credentials do not prove an active inbox connection. slack_health reports connection state. Transient failures back off; invalid credentials and permanent authorization errors stop retries. Reload after correcting credentials. Sends are not retried implicitly.
+
 ## Current improvements
 
 slack_inbox with limit=10 and markRead=true returns remaining; call again for unread messages. After a timeout or missing ts, inspect the channel before retrying to avoid duplicate notifications.

package/docs/USAGE.md

@@ -2,6 +2,10 @@
 
 [返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
 
+## 连接诊断
+
+凭据已填写不等于收件箱已连接。slack_health 显示真实连接状态；临时故障退避重连，凭据失效或权限错误停止重试。修正凭据后重新加载插件。发送操作不会隐式重试。
+
 ## 本次改进
 
 slack_inbox { limit: 10, markRead: true } 返回 remaining，继续调用可查看余下消息。遇到超时或缺少 ts 时先检查频道，确认未发送后再重试，避免重复通知。

package/docs/VALIDATION.md

@@ -1,5 +1,9 @@
 # dsh-slack 验证记录
 
+## 2026-10-26：0.3.5
+
+[本次修复、回归与未验收范围](validation-0.3.5.md)。
+
 本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
 
 ## 原中文记录

package/docs/validation-0.3.5.md

@@ -0,0 +1,19 @@
+# 0.3.5 验证记录
+
+日期：2026-10-26。官方 Windows 宿主：DSH 0.2.1-rc.3。
+
+## 行为变化
+
+Socket Mode 重连改为插件管理的有界退避；捕获启动与重连错误，凭据撤销等永久错误停止重试，卸载取消重连。自检区分凭据已配置、连接中、连接成功与认证失败。
+
+## 验证与限制
+
+- Windows 本地：49 项，49 通过、0 跳过；没有把跳过计为通过。
+- 真实 Slack SDK 的 token_revoked 重连故障在严格未处理异常模式下复现并回归；官方 RC.3 检查未配置状态。未配置真实 Slack 账号，线上收发未验收。
+- GitHub 的跨平台 CI 和 npm 发布完整性以该版本工作流及 registry 为准；本记录不把本地测试等同于已发布。
+
+## English
+
+Socket Mode uses caught, bounded reconnect backoff. Permanent authentication errors stop retries; disposal cancels reconnects. Health distinguishes configured credentials from an active connection.
+
+Runtime/account limits are listed above. Synthetic peers and model adapters do not establish live account delivery or model quality.

package/lib/index.d.ts

@@ -11,7 +11,7 @@ export { parseConfig, resolveToken, resolveDefaultChannel, requireToken, resolve
 export { createWebSlackClient, mapSlackError, assertChannel, assertText, assertThreadTs, type SlackClient, type PostMessageParams, type ChannelInfo, } from './slack-client.js';
 export { buildNotifyTool, buildChannelsTool, buildInboxTool, buildReplyTool, type ToolDeps } from './tools.js';
 export { parseMessageEvent, InboxQueue, createInboxQueue, INBOX_CAPACITY, type InboxMessage } from './inbox.js';
-export { startSocketModeClient, type SocketMessageHandler } from './socket.js';
+export { startSocketModeClient, type SocketMessageHandler, type SocketStatus, type SocketDisposer, type SocketLifecycleOptions } from './socket.js';
 export type { SlackContext, ToolDefinition, ToolOutputDefinition, ContentBlock } from './types.js';
 /**
  * 插件入口。配置缺失【不失败】（懒加载）：只 console.warn；

package/lib/index.js

@@ -71,10 +71,11 @@ export function apply(ctx, rawConfig) {
         return client;
     };
     const inboxProvider = () => inboxQueue;
-    const deps = { clientProvider, configProvider, inboxProvider };
+    let socket;
+    const deps = { clientProvider, configProvider, inboxProvider, socketStatusProvider: () => socket?.status() };
     const appToken = resolveAppToken(config);
     if (appToken !== '' && appToken.startsWith('xapp-')) {
-        const startSocket = () => startSocketModeClient(appToken, {
+        const startSocket = () => socket = startSocketModeClient(appToken, {
             onMessage(message) {
                 inboxQueue.push(message);
             },
@@ -83,7 +84,8 @@ export function apply(ctx, rawConfig) {
             ctx.effect(startSocket);
         }
         else {
-            startSocket();
+            const dispose = startSocket();
+            ctx.on?.('dispose', dispose);
         }
     }
     ctx.tools.register(buildNotifyTool(deps));

package/lib/socket.d.ts

@@ -1,16 +1,26 @@
-/**
- * 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 { type InboxMessage } from './inbox.js';
-/** Socket 消息回调。 */
 export interface SocketMessageHandler {
     onMessage(message: InboxMessage): void;
 }
 type Warn = (message: string, ...args: unknown[]) => void;
-/**
- * 启动 Socket Mode 客户端，返回 dispose 函数（断开连接）。
- * 网络错误 / 解析错误均 try/catch + warn，绝不抛出。
- */
-export declare function startSocketModeClient(appToken: string, handler: SocketMessageHandler, warn: Warn): () => void;
+export interface SocketStatus {
+    state: 'connecting' | 'connected' | 'reconnecting' | 'auth_failed' | 'stopped';
+    attempts: number;
+    error?: string;
+}
+export interface SocketClientLike {
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    start(): Promise<unknown>;
+    disconnect(): Promise<unknown>;
+}
+export interface SocketLifecycleOptions {
+    retryBaseMs?: number;
+    createClient?: (options: ConstructorParameters<typeof SocketModeClient>[0]) => SocketClientLike;
+}
+export type SocketDisposer = (() => void) & {
+    status(): SocketStatus;
+};
+export declare function startSocketModeClient(appToken: string, handler: SocketMessageHandler, warn: Warn, options?: SocketLifecycleOptions): SocketDisposer;
 export {};

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

@@ -63,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 },
@@ -84,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 } : {}) };
         },
     };
 }

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,6 +1,6 @@
 {
   "name": "dsh-slack",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "连接 Slack，发送通知并处理 Socket Mode 收件箱与线程回复。",
   "type": "module",
   "main": "./lib/index.js",