dsh-slack 0.2.3 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stardustlc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -2,6 +2,8 @@
 
 # dsh-slack
 
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
 DSH (DeepSeek Harness) community plugin: lets the agent communicate with Slack bidirectionally.
 
 > **v0.2 scope (two-way)**: v0.1 only did one-way "agent → Slack" notifications; v0.2 adds Socket Mode,
@@ -12,11 +14,25 @@ DSH (DeepSeek Harness) community plugin: lets the agent communicate with Slack b
 ## Features
 
 - `slack_notify`: send a Markdown text message to a channel (or thread), returning the message `ts`.
-- `slack_channels`: list the channels currently visible to the bot (`conversations.list`).
-- `slack_inbox`: read messages received via Socket Mode (in-memory queue, keeps up to 200).
+- `slack_channels`: list the channels currently visible to the bot (`conversations.list`, paginating through `next_cursor` until complete).
+- `slack_inbox`: read messages received via Socket Mode (in-memory queue, keeps up to 200; deduplicates retries and consumes atomically with `markRead=true`).
 - `slack_reply`: reply to an inbox message as a thread (`chat.postMessage` with `thread_ts`).
+- WebClient instances are cached by `token + slackApiUrl` and rebuilt automatically when configuration changes.
 - Configuration via `cordis.patch.yml`; tokens support environment-variable fallback (`DSH_SLACK_TOKEN` / `DSH_SLACK_APP_TOKEN`).
 
+### v0.2.3 improvements
+
+- `slack_channels` paginates automatically so large workspaces no longer lose channels after the first page.
+- `slack_inbox` deduplicates Slack's at-least-once event deliveries and drains atomically on `markRead`.
+- WebClient reuse avoids rebuilding clients on every tool call.
+- Pagination has a page cap to prevent loops from a misbehaving `next_cursor`.
+- Error mapping adds `not_authed` / `is_archived` / `msg_too_long` / `ratelimited`.
+
+
+## Compatibility
+
+Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+
 ## Installation
 
 The plugin runs inside the host process, is installed into the profile via `dsh plugin`, and takes effect after a restart:
@@ -27,6 +43,15 @@ dsh plugin --profile web add dsh-slack
 
 After installing, restart your dsh Web service; the four tools `slack_notify` / `slack_channels` / `slack_inbox` / `slack_reply` become visible to the model.
 
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-slack
+```
+
+Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+
+
 ## Configuration
 
 Configuration lives in the profile's `cordis.patch.yml`; override this plugin's line by `id: slack` (overriding replaces that line's `config` wholesale — it does not merge). Available options:
@@ -142,7 +167,10 @@ All error messages are in Chinese, readable by both the model and the user:
 - `invalid_auth`: hints to check/regenerate the token.
 - `channel_not_found`: hints the channel name or ID is wrong.
 - `not_in_channel`: hints to invite the bot App into the channel first.
-- `token_revoked` / `account_inactive` / `missing_scope`: hints permission or token expiry, reinstall the App.
+- `token_revoked` / `account_inactive` / `missing_scope` / `not_authed`: hints permission or token expiry, reinstall the App.
+- `is_archived`: hints the channel is archived and cannot receive messages.
+- `msg_too_long`: hints the message exceeds Slack's 40,000-character limit.
+- `ratelimited`: hints to retry after a short wait.
 
 ## Development and testing
 
@@ -154,7 +182,7 @@ pnpm test      # 先 build，再用 node:test 跑 test/*.test.mjs
 
 Tests need no real token: parameter compilation, config parsing (incl. env fallback), tool registration (4 tools + Chinese error on missing config),
 injecting a fake client to assert `postMessage` arguments (incl. `thread_ts`), output schema pure-JSON validation,
-inbox queue capacity/clear, Socket Mode event parsing (fake event objects), and no-crash on missing appToken.
+inbox queue capacity/clear/deduplication/atomic drain, Socket Mode event parsing (fake event objects), and no-crash on missing appToken.
 
 ## Known limitations and roadmap
 
@@ -173,4 +201,4 @@ Roadmap: v0.3 plans to introduce interactive components (buttons/modals) and a p
 
 ## License
 
-MIT
+MIT

package/README.md

@@ -6,6 +6,8 @@
 
 ![npm version](https://img.shields.io/npm/v/dsh-slack?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-slack) ![license](https://img.shields.io/npm/l/dsh-slack) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-slack?style=social)
 
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
 
 DSH（DeepSeek Harness）社区插件：让 agent 与 Slack 双向通信。
 
@@ -17,11 +19,25 @@ DSH（DeepSeek Harness）社区插件：让 agent 与 Slack 双向通信。
 ## 功能
 
 - `slack_notify`：向指定频道（或线程）发送一条 Markdown 文本消息，返回消息 `ts`。
-- `slack_channels`：列出机器人当前可见的频道（`conversations.list`）。
-- `slack_inbox`：读取通过 Socket Mode 收到的消息（内存队列，最多保留 200 条）。
+- `slack_channels`：列出机器人当前可见的频道（`conversations.list`，自动沿 `next_cursor` 翻页拉全）。
+- `slack_inbox`：读取通过 Socket Mode 收到的消息（内存队列，最多保留 200 条；自动去重，`markRead=true` 原子消费）。
 - `slack_reply`：以线程回复形式回复某条收件箱消息（`chat.postMessage` 带 `thread_ts`）。
+- WebClient 按 `token + slackApiUrl` 缓存复用，配置变更时自动重建。
 - 配置走 `cordis.patch.yml`，令牌支持环境变量回退（`DSH_SLACK_TOKEN` / `DSH_SLACK_APP_TOKEN`）。
 
+### v0.2.3 优化
+
+- `slack_channels` 自动分页：频道很多时不再只返回第一页。
+- `slack_inbox` 去重 + `drain` 原子消费：Slack 重投的事件不会重复入队，`markRead` 期间新到的消息也不会被误清。
+- WebClient 复用：同一 `token + slackApiUrl` 只创建一个客户端，减少重复初始化。
+- 分页增加页数上限，防止异常 `next_cursor` 导致死循环。
+- 错误映射补充 `not_authed` / `is_archived` / `msg_too_long` / `ratelimited`。
+
+
+## 兼容性
+
+在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+
 ## 安装
 
 插件运行在宿主进程内，通过 `dsh plugin` 安装进 profile，重启后生效：
@@ -98,6 +114,15 @@ export DSH_SLACK_APP_TOKEN=xapp-你的App级令牌
 > 未配置 `appToken` 时插件**不会崩溃**：只打印告警，`slack_inbox` 返回空队列（中文提示）。
 > Socket Mode 网络错误由 SDK 自动重连，插件只记录告警、不抛崩。
 
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-slack
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中的对应插件行。
+
 ## 工具清单
 
 ### `slack_notify`
@@ -150,7 +175,10 @@ export DSH_SLACK_APP_TOKEN=xapp-你的App级令牌
 - `invalid_auth`：提示检查/重新生成 token。
 - `channel_not_found`：提示频道名或频道 ID 错误。
 - `not_in_channel`：提示先把机器人 App 邀请进频道。
-- `token_revoked` / `account_inactive` / `missing_scope`：提示权限或令牌失效，需重新安装 App。
+- `token_revoked` / `account_inactive` / `missing_scope` / `not_authed`：提示权限或令牌失效，需重新安装 App。
+- `is_archived`：提示频道已归档，不能发消息。
+- `msg_too_long`：提示 Slack 单条消息超过 40,000 字符。
+- `ratelimited`：提示请求太频繁，稍后重试。
 
 ## 开发与测试
 
@@ -162,7 +190,7 @@ pnpm test      # 先 build，再用 node:test 跑 test/*.test.mjs
 
 测试无需真实 token：参数编译、配置解析（含 env 回退）、工具注册（4 个工具 + 缺配置中文报错）、
 注入 fake client 断言 `postMessage` 参数（含 `thread_ts`）、输出 schema 纯 JSON 校验、
-收件箱队列容量/清空、Socket Mode 事件解析（fake event 对象）、appToken 缺失不崩。
+收件箱队列容量/清空/去重/原子 drain、Socket Mode 事件解析（fake event 对象）、appToken 缺失不崩。
 
 ## 已知限制与路线图
 
@@ -182,5 +210,4 @@ pnpm test      # 先 build，再用 node:test 跑 test/*.test.mjs
 
 ## License
 
-MIT
-
+MIT

package/lib/config.js

@@ -27,7 +27,7 @@ export function parseConfig(raw) {
  * 解析 token：config.token 优先，其次环境变量 DSH_SLACK_TOKEN。
  */
 export function resolveToken(config) {
-    const fromConfig = config?.token.trim() ?? '';
+    const fromConfig = config?.token?.trim() ?? '';
     if (fromConfig)
         return fromConfig;
     return process.env[ENV_TOKEN]?.trim() ?? '';

package/lib/index.js

@@ -5,7 +5,7 @@
  */
 import { parseConfig, requireToken, resolveAppToken, resolveToken } from './config.js';
 import { createWebSlackClient } from './slack-client.js';
-import { buildChannelsTool, buildInboxTool, buildNotifyTool, buildReplyTool } from './tools.js';
+import { buildChannelsTool, buildInboxTool, buildNotifyTool, buildHealthTool, buildReplyTool } from './tools.js';
 import { createInboxQueue } from './inbox.js';
 import { startSocketModeClient } from './socket.js';
 export const name = 'dsh-slack';
@@ -90,4 +90,5 @@ export function apply(ctx, rawConfig) {
     ctx.tools.register(buildChannelsTool(deps));
     ctx.tools.register(buildInboxTool(deps));
     ctx.tools.register(buildReplyTool(deps));
+    ctx.tools.register(buildHealthTool(deps));
 }

package/lib/socket.js

@@ -11,14 +11,21 @@ import { parseMessageEvent } from './inbox.js';
 export function startSocketModeClient(appToken, handler, warn) {
     const client = new SocketModeClient({ appToken });
     client.on('slack_event', (...args) => {
+        const raw = args[0];
         try {
-            const message = parseMessageEvent(args[0]);
+            const message = parseMessageEvent(raw);
             if (message !== null)
                 handler.onMessage(message);
         }
         catch (error) {
             warn('[dsh-slack] 解析 Socket Mode 事件失败：', error);
         }
+        finally {
+            // events_api 事件必须 ack，否则 Slack 会重投；重复投递由收件箱 seen 去重兜底。
+            if (typeof raw.ack === 'function') {
+                void raw.ack().catch(() => { });
+            }
+        }
     });
     client.on('error', (...args) => {
         warn('[dsh-slack] Socket Mode 连接错误（SDK 会自动重连）：', args[0]);

package/lib/tools.d.ts

@@ -8,6 +8,8 @@ export interface ToolDeps {
     configProvider: () => SlackConfig | undefined;
     inboxProvider: () => InboxQueue;
 }
+/** 自检工具：检查 token / appToken / 默认频道配置，不发起网络请求。 */
+export declare function buildHealthTool(deps: ToolDeps): ToolDefinition;
 export declare function buildNotifyTool(deps: ToolDeps): ToolDefinition;
 export declare function buildChannelsTool(deps: ToolDeps): ToolDefinition;
 export declare function buildInboxTool(deps: ToolDeps): ToolDefinition;

package/lib/tools.js

@@ -1,5 +1,5 @@
 import { compileParameters } from './compile.js';
-import { resolveDefaultChannel } from './config.js';
+import { resolveAppToken, resolveDefaultChannel, resolveToken } from './config.js';
 import { assertChannel, assertText, assertThreadTs, mapSlackError } from './slack-client.js';
 const NOTIFY_OUTPUT_SCHEMA = {
     type: 'object',
@@ -58,6 +58,39 @@ function clampLimit(value) {
         return 10;
     return Math.min(50, Math.max(1, Math.trunc(value)));
 }
+/** 自检工具：检查 token / appToken / 默认频道配置，不发起网络请求。 */
+export function buildHealthTool(deps) {
+    return {
+        name: 'slack_health',
+        description: 'dsh-slack 自检：检查 botToken / appToken / 默认频道配置是否就绪（不发起网络请求）。遇到问题时先运行本工具定位。',
+        parameters: compileParameters({}),
+        output: {
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => {
+                const rec = (value ?? {});
+                const rawChecks = Array.isArray(rec.checks) ? rec.checks : [];
+                const lines = ['dsh-slack 自检' + (rec.ok === true ? '：正常。' : '：发现问题。')];
+                for (const item of rawChecks) {
+                    const c = (item ?? {});
+                    lines.push('- ' + String(c.name) + '：' + (c.ok === true ? '✅ ' + String(c.detail ?? '') : '❌ ' + String(c.detail ?? '')));
+                }
+                return [textBlock(lines.join('\n'))];
+            },
+        },
+        async execute() {
+            const config = deps.configProvider();
+            const checks = [];
+            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 收件箱可用）' : '未配置（收件箱功能不可用，通知不受影响）' });
+            const defaultChannel = resolveDefaultChannel(config);
+            checks.push({ name: '默认频道', ok: true, detail: defaultChannel !== '' ? defaultChannel : '未配置（发送时必须显式给 channel）' });
+            const ok = token !== '';
+            return { ok, plugin: 'dsh-slack', checks };
+        },
+    };
+}
 export function buildNotifyTool(deps) {
     const defaultChannel = resolveDefaultChannel(deps.configProvider());
     const channelDescription = defaultChannel

package/package.json

@@ -1,54 +1,59 @@
-{
-  "name": "dsh-slack",
-  "version": "0.2.3",
-  "description": "DSH 社区插件：Slack 通知/桥接（v0.2 支持 Socket Mode 双向：收件箱 + 线程回复）",
-  "type": "module",
-  "main": "./lib/index.js",
-  "types": "./lib/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./package.json": "./package.json",
-    "./cordis.patch.yml": "./cordis.patch.yml"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md"
-  ],
-  "license": "MIT",
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "dependencies": {
-    "@slack/socket-mode": "^3.0.0",
-    "@slack/web-api": "^8.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.7.3"
-  },
-  "repository": {
-    "url": "https://github.com/STARDUSTLC666/dsh-slack",
-    "type": "git"
-  },
-  "bugs": {
-    "url": "https://github.com/STARDUSTLC666/dsh-slack/issues"
-  },
-  "homepage": "https://github.com/STARDUSTLC666/dsh-slack#readme",
-  "author": "stardustlc",
-  "keywords": [
-    "dsh-plugin",
-    "deepseek-harness",
-    "dsh"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
-    "test:protocol": "node test/protocol-acceptance.mjs"
-  }
-}
+{
+  "name": "dsh-slack",
+  "version": "0.3.0",
+  "description": "DSH 社区插件：Slack 通知/桥接（v0.2 支持 Socket Mode 双向：收件箱 + 线程回复）",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "pnpm run build",
+    "test:protocol": "node test/protocol-acceptance.mjs"
+  },
+  "dependencies": {
+    "@slack/socket-mode": "^3.0.0",
+    "@slack/web-api": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.3"
+  },
+  "repository": {
+    "url": "git+https://github.com/STARDUSTLC666/dsh-slack.git",
+    "type": "git"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-slack/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-slack#readme",
+  "author": "stardustlc",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh"
+  ],
+  "packageManager": "pnpm@11.7.0",
+  "engines": {
+    "node": ">=22"
+  }
+}