dsh-slack 0.3.3 → 0.3.5

package/docs/USAGE.en.md

@@ -0,0 +1,189 @@
+# dsh-slack usage guide
+
+[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.
+
+## 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`, 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`).
+
+## Installation
+
+The plugin runs inside the host process, is installed into the profile via `dsh plugin`, and takes effect after a restart:
+
+```sh
+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:
+
+| Key | Type | Required | Description |
+| --- | --- | --- | --- |
+| `token` | string | yes* | Slack token: bot token (`xoxb-`) or user token (`xoxp-`). When empty, falls back to the `DSH_SLACK_TOKEN` env var. |
+| `appToken` | string | no* | App-Level Token (starts with `xapp-`); used to receive messages after enabling Socket Mode. When empty, falls back to the `DSH_SLACK_APP_TOKEN` env var. |
+| `defaultChannel` | string | no | Default channel (e.g. `#general`). The default target when the model doesn't specify a channel; written into the `channel` parameter description. |
+
+`*` `token` may be left empty at the "config layer", in which case it falls back to the env var; when both are empty the plugin still loads, but calling the send/list/reply tools returns a Chinese error. An empty `appToken` only warns — no crash — and `slack_inbox` returns an empty queue (one-way mode).
+
+**Method 1: environment variables (recommended, no hard-coded tokens)**
+
+```sh
+# 在启动 dsh 的进程里设置
+export DSH_SLACK_TOKEN=xoxb-你的机器人令牌
+export DSH_SLACK_APP_TOKEN=xapp-你的App级令牌
+```
+
+**Method 2: override in the profile's cordis.patch.yml**
+
+In your profile directory (`$DSH_HOME/profiles/web/cordis.patch.yml`) append:
+
+```yaml
+# 覆盖 dsh-slack 的 slack 行配置（整体替换）
+- id: slack
+  config:
+    token: 'xoxb-你的机器人令牌'
+    appToken: 'xapp-你的App级令牌'
+    defaultChannel: '#general'
+```
+
+> Priority: `config.token` > env var `DSH_SLACK_TOKEN`; `config.appToken` > env var
+> `DSH_SLACK_APP_TOKEN`.
+
+### Create a Slack App and get a token
+
+1. Open <https://api.slack.com/apps>, click **Create New App** (choose `From scratch`, name the app, select the workspace).
+2. On the **OAuth & Permissions** page, under **Scopes → Bot Token Scopes** check:
+   - `chat:write` (required to send messages)
+   - `channels:read` (required to list channels)
+3. Back at the top, click **Install to Workspace** (authorize).
+4. Grab the **Bot User OAuth Token** (starts with `xoxb-`).
+5. Add the bot (App) to the channels it should post in: `/invite @your-bot` in the channel (required for private channels).
+
+### Enable Socket Mode (two-way message receiving)
+
+To receive Slack messages (`slack_inbox` / `slack_reply`), enable Socket Mode and generate an App-Level Token:
+
+1. Open <https://api.slack.com/apps> and open your App.
+2. Open the **Socket Mode** page → turn on the toggle (**Enable Socket Mode**).
+3. Click **Generate Token and Scopes** to create an App-Level Token: name the token, check the `connections:write` scope.
+   Copy the `xapp-` App-Level Token (shown only once — save it immediately).
+4. Open the **Event Subscriptions** page, enable events, and under **Subscribe to bot events → Add Bot User Event** add:
+   - `message.channels` (public channel messages)
+   - `message.im` (bot DMs)
+5. Put the App-Level Token into `appToken` (or the `DSH_SLACK_APP_TOKEN` env var).
+6. Restart the dsh Web service; the plugin connects automatically via Socket Mode and starts receiving messages.
+
+> Without `appToken` the plugin **won't crash**: it only prints a warning and `slack_inbox` returns an empty queue (with a Chinese hint).
+> Socket Mode network errors are auto-reconnected by the SDK; the plugin only logs a warning and never throws.
+
+## Tool reference
+
+### `slack_notify`
+
+Send Markdown text to a channel/thread (underlying `chat.postMessage`).
+
+| Param | Type | Required | Description |
+| --- | --- | --- | --- |
+| `channel` | string | yes | Channel name (e.g. `#general`) or channel ID. |
+| `text` | string | yes | The Markdown text to send. |
+| `thread_ts` | string | no | The `ts` of the thread to reply to. |
+
+Returns: `{ "ts": "...", "channel": "#general" }` (`ts` for later `thread_ts` reference).
+
+### `slack_channels`
+
+List channels visible to the bot (underlying `conversations.list`).
+
+No parameters. Returns: `{ "channels": [{ "id": "...", "name": "..." }, ...] }`.
+
+### `slack_inbox`
+
+Read messages received via Socket Mode (in-memory queue, keeps up to 200, newest first).
+
+| Param | Type | Required | Description |
+| --- | --- | --- | --- |
+| `limit` | integer | no | Maximum number of messages to return (default 10, range 1-50). |
+| `markRead` | boolean | no | When `true`, clears the inbox queue after returning (mark as read). |
+
+Returns: `{ "messages": [{ "ts": "...", "channel": "...", "user": "...", "text": "..." }, ...] }`.
+
+### `slack_reply`
+
+Reply to an inbox message as a thread (underlying `chat.postMessage` with `thread_ts`).
+
+| Param | Type | Required | Description |
+| --- | --- | --- | --- |
+| `channel` | string | yes | Channel name (e.g. `#general`) or channel ID. |
+| `text` | string | yes | Reply content (Markdown text). |
+| `thread_ts` | string | yes | The `ts` of the message to reply to (from `slack_inbox`). |
+
+Returns: `{ "ts": "...", "channel": "#general" }`.
+
+## Error handling
+
+All error messages are in Chinese, readable by both the model and the user:
+
+- Unconfigured token: `token 未配置：缺少 Slack 机器人令牌（xoxb-）…请在 profile 的 cordis.patch.yml 覆盖 slack 行的 config.token 并重启，或设置环境变量 DSH_SLACK_TOKEN。`
+- Unconfigured App-Level Token: only a warning; `slack_inbox` returns an empty queue (with a Chinese hint) and other tools are unaffected.
+- `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` / `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
+
+```sh
+pnpm install   # 安装依赖并触发 prepare（tsc 构建）
+pnpm build     # tsc 编译 src → lib
+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/deduplication/atomic drain, Socket Mode event parsing (fake event objects), and no-crash on missing appToken.
+
+## Known limitations and roadmap
+
+- **v0.1 is one-way notification (agent→Slack)**; **v0.2 is two-way via Socket Mode** (`slack_inbox` / `slack_reply`).
+- **No** RTM or interactive components (buttons/modals/slash command replies).
+- `slack_inbox` is an in-process memory queue: cleared on restart, not persisted; keeps up to 200, dropping the oldest when full.
+- `channel` is a required parameter; `defaultChannel` is currently only written into the `channel` parameter description as a hint — it does not replace the required `channel`.
+- With a missing token the plugin still loads (lazy loading); the error is only thrown when the tool is called; a missing appToken only warns.
+
+Roadmap: v0.3 plans to introduce interactive components (buttons/modals) and a persisted inbox.
+
+## Dependencies
+
+- Runtime: `@slack/web-api` (official WebClient), `@slack/socket-mode` (Socket Mode client)
+- peer (provided by the host; not imported directly by the plugin at runtime): `@deepseek-ai/cordis`, `@deepseek-ai/dsh-tools`
+
+## License
+
+MIT

package/docs/USAGE.md

@@ -0,0 +1,193 @@
+# dsh-slack 使用说明
+
+[返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
+
+## 连接诊断
+
+凭据已填写不等于收件箱已连接。slack_health 显示真实连接状态；临时故障退避重连，凭据失效或权限错误停止重试。修正凭据后重新加载插件。发送操作不会隐式重试。
+
+## 本次改进
+
+slack_inbox { limit: 10, markRead: true } 返回 remaining，继续调用可查看余下消息。遇到超时或缺少 ts 时先检查频道，确认未发送后再重试，避免重复通知。
+
+## 功能
+
+- `slack_notify`：向指定频道（或线程）发送一条 Markdown 文本消息，返回消息 `ts`。
+- `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`）。
+
+## 安装
+
+插件运行在宿主进程内，通过 `dsh plugin` 安装进 profile，重启后生效：
+
+```sh
+dsh plugin --profile web add dsh-slack
+```
+
+安装后重启你的 dsh Web 服务，`slack_notify` / `slack_channels` / `slack_inbox` / `slack_reply`
+四个工具即对模型可见。
+
+## 配置
+
+配置在 profile 的 `cordis.patch.yml` 里按 `id: slack` 覆盖本插件的行（覆盖会整体替换该行的
+`config`，不会合并）。可用配置项：
+
+| 键 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `token` | string | 是* | Slack 令牌：机器人令牌（`xoxb-`）或用户令牌（`xoxp-`）。留空时回退到环境变量 `DSH_SLACK_TOKEN`。 |
+| `appToken` | string | 否* | App-Level Token（`xapp-` 开头），开启 Socket Mode 后用于接收消息。留空时回退到环境变量 `DSH_SLACK_APP_TOKEN`。 |
+| `defaultChannel` | string | 否 | 默认频道（如 `#general`）。模型未特别指定频道时的默认目标，写进 `channel` 参数说明里。 |
+
+`*` `token` 在「配置层」可留空，此时回退环境变量；两者都为空时插件照常加载，但调用发消息/列频道/
+回复工具时会返回中文报错。`appToken` 留空则只告警、不崩溃，`slack_inbox` 返回空队列（单向模式）。
+
+**方式一：环境变量（推荐，不写死令牌）**
+
+```sh
+# 在启动 dsh 的进程里设置
+export DSH_SLACK_TOKEN=xoxb-你的机器人令牌
+export DSH_SLACK_APP_TOKEN=xapp-你的App级令牌
+```
+
+**方式二：profile 的 cordis.patch.yml 直接覆盖**
+
+在你的 profile 目录（`$DSH_HOME/profiles/web/cordis.patch.yml`）追加：
+
+```yaml
+# 覆盖 dsh-slack 的 slack 行配置（整体替换）
+- id: slack
+  config:
+    token: 'xoxb-你的机器人令牌'
+    appToken: 'xapp-你的App级令牌'
+    defaultChannel: '#general'
+```
+
+> 优先级：`config.token` > 环境变量 `DSH_SLACK_TOKEN`；`config.appToken` > 环境变量
+> `DSH_SLACK_APP_TOKEN`。
+
+### 创建 Slack App 并拿令牌
+
+1. 打开 <https://api.slack.com/apps>，点 **Create New App**（选 `From scratch`，给 App 起名、选工作区）。
+2. 进入 **OAuth & Permissions** 页，在 **Scopes → Bot Token Scopes** 下勾选：
+   - `chat:write`（发消息必需）
+   - `channels:read`（列频道必需）
+3. 回到顶部点 **Install to Workspace**（授权）。
+4. 拿到 **Bot User OAuth Token**（以 `xoxb-` 开头）。
+5. 把机器人（App）加进它要发消息的频道：在频道里 `/invite @你的机器人`（私有频道必需）。
+
+### 开启 Socket Mode（双向收消息）
+
+要接收 Slack 消息（`slack_inbox` / `slack_reply`），需要开启 Socket Mode 并生成 App-Level Token：
+
+1. 打开 <https://api.slack.com/apps>，进入你的 App。
+2. 左侧 **Socket Mode** 页 → 打开开关（**Enable Socket Mode**）。
+3. 点 **Generate Token and Scopes** 生成 App-Level Token：给 Token 起名，勾选 `connections:write` scope。
+   生成后拿到以 `xapp-` 开头的 App-Level Token（只显示一次，请立即保存）。
+4. 进入 **Event Subscriptions** 页，开启事件订阅，在 **Subscribe to bot events → Add Bot User Event** 添加：
+   - `message.channels`（公开频道消息）
+   - `message.im`（机器人私信）
+5. 把 App-Level Token 配进 `appToken`（或环境变量 `DSH_SLACK_APP_TOKEN`）。
+6. 重启 dsh Web 服务，插件自动通过 Socket Mode 建立连接并开始收消息。
+
+> 未配置 `appToken` 时插件**不会崩溃**：只打印告警，`slack_inbox` 返回空队列（中文提示）。
+> Socket Mode 网络错误由 SDK 自动重连，插件只记录告警、不抛崩。
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-slack
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中的对应插件行。
+
+## 工具清单
+
+### `slack_notify`
+
+向指定频道/线程发送 Markdown 文本（底层 `chat.postMessage`）。
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `channel` | string | 是 | 频道名（如 `#general`）或频道 ID。 |
+| `text` | string | 是 | 要发送的 Markdown 文本。 |
+| `thread_ts` | string | 否 | 回复某条消息所在线程的 `ts`。 |
+
+返回：`{ "ts": "...", "channel": "#general" }`（`ts` 供后续 `thread_ts` 引用）。
+
+### `slack_channels`
+
+列出机器人可见频道（底层 `conversations.list`）。
+
+无参数。返回：`{ "channels": [{ "id": "...", "name": "..." }, ...] }`。
+
+### `slack_inbox`
+
+读取通过 Socket Mode 收到的消息（内存队列，最多保留 200 条，新的在前）。
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `limit` | integer | 否 | 最多返回的消息数（默认 10，范围 1-50）。 |
+| `markRead` | boolean | 否 | 为 `true` 时，返回后清空收件箱队列（标记已读）。 |
+
+返回：`{ "messages": [{ "ts": "...", "channel": "...", "user": "...", "text": "..." }, ...] }`。
+
+### `slack_reply`
+
+以线程回复形式回复某条收件箱消息（底层 `chat.postMessage` 带 `thread_ts`）。
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `channel` | string | 是 | 频道名（如 `#general`）或频道 ID。 |
+| `text` | string | 是 | 回复内容（Markdown 文本）。 |
+| `thread_ts` | string | 是 | 要回复消息的 `ts`（来自 `slack_inbox` 返回的 `ts`）。 |
+
+返回：`{ "ts": "...", "channel": "#general" }`。
+
+## 错误处理
+
+所有错误信息均为中文，模型与用户都能直接读懂：
+
+- 未配置令牌：`token 未配置：缺少 Slack 机器人令牌（xoxb-）…请在 profile 的 cordis.patch.yml 覆盖 slack 行的 config.token 并重启，或设置环境变量 DSH_SLACK_TOKEN。`
+- 未配置 App-Level Token：只告警，`slack_inbox` 返回空队列（含中文提示），不影响其它工具。
+- `invalid_auth`：提示检查/重新生成 token。
+- `channel_not_found`：提示频道名或频道 ID 错误。
+- `not_in_channel`：提示先把机器人 App 邀请进频道。
+- `token_revoked` / `account_inactive` / `missing_scope` / `not_authed`：提示权限或令牌失效，需重新安装 App。
+- `is_archived`：提示频道已归档，不能发消息。
+- `msg_too_long`：提示 Slack 单条消息超过 40,000 字符。
+- `ratelimited`：提示请求太频繁，稍后重试。
+
+## 开发与测试
+
+```sh
+pnpm install   # 安装依赖并触发 prepare（tsc 构建）
+pnpm build     # tsc 编译 src → lib
+pnpm test      # 先 build，再用 node:test 跑 test/*.test.mjs
+```
+
+测试无需真实 token：参数编译、配置解析（含 env 回退）、工具注册（4 个工具 + 缺配置中文报错）、
+注入 fake client 断言 `postMessage` 参数（含 `thread_ts`）、输出 schema 纯 JSON 校验、
+收件箱队列容量/清空/去重/原子 drain、Socket Mode 事件解析（fake event 对象）、appToken 缺失不崩。
+
+## 已知限制与路线图
+
+- **v0.1 是单向通知（agent→Slack）**；**v0.2 通过 Socket Mode 实现双向**（`slack_inbox` / `slack_reply`）。
+- **不支持** RTM、交互组件（按钮/弹窗/slash command 回复）。
+- `slack_inbox` 为进程内存队列：重启即清空，且不持久化；最多保留 200 条，满则丢最旧。
+- `channel` 为必填参数，`defaultChannel` 目前只作为说明提示写入 `channel` 参数描述，不替代
+  必填的 `channel`。
+- 令牌缺失时插件仍会加载（懒加载），错误在工具被调用时才抛出；appToken 缺失则仅告警。
+
+路线图：v0.3 计划引入交互组件（按钮/弹窗）与持久化收件箱。
+
+## 依赖
+
+- 运行时：`@slack/web-api`（官方 WebClient）、`@slack/socket-mode`（Socket Mode 客户端）
+- peer（由宿主提供，插件运行时不直接 import）：`@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`
+
+## License
+
+MIT

package/docs/VALIDATION.md

@@ -0,0 +1,24 @@
+# dsh-slack 验证记录
+
+## 2026-10-26：0.3.5
+
+[本次修复、回归与未验收范围](validation-0.3.5.md)。
+
+本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
+
+## 原中文记录
+
+验证宿主：官方发布标签源码构建的 Harness `0.2.0-rc.2`（commit `639ed01539`）+ Windows / Node `24.16.0`。43 项插件测试通过；同一个宿主里 18 个插件共同加载，本插件的 5 个工具全部注册，工具 schema 与健康检查契约通过。真实 Slack 登录、Socket Mode 收件和发送尚未验收。
+
+0.3.3 使用支持 Undici 7/8 的官方 Socket Mode SDK 3.1 或更新版本，并显式声明匹配的传输依赖，修复组合安装中旧 SDK 与宿主 Undici 8 的依赖不匹配；npm 包同时包含中英文说明。
+
+> **v0.2 范围（双向）**：v0.1 只做「agent → Slack」单向通知；v0.2 新增 Socket Mode，
+> 支持「Slack 消息 → agent」：`slack_inbox` 收取消息、`slack_reply` 线程回复。
+> RTM、交互组件（按钮/弹窗/slash command 回复）不在 v0.2，见下方
+> [已知限制与路线图](USAGE.md#已知限制与路线图)。
+
+## Original English record
+
+Validation host: Harness `0.2.0-rc.2` built from its official release tag (commit `639ed01539`), Windows and Node `24.16.0`. All 43 plugin tests pass; all 18 plugins mount together and this plugin registers all five tools, with tool schemas and health-check contracts passing. Real Slack authorization, Socket Mode delivery and sending have not been verified.
+
+Version 0.3.3 requires the official Socket Mode SDK 3.1 or newer, which supports Undici 7/8, and explicitly declares its transport dependency. This fixes combined installations that paired an older SDK with the host's Undici 8. Both language versions of this README are included in the npm package.

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/inbox.d.ts

@@ -27,7 +27,7 @@ export declare class InboxQueue {
     /** 返回最近 limit 条消息（新的在前）。 */
     list(limit: number): InboxMessage[];
     /**
-     * 原子地取出最近 limit 条并清空整个队列。
+     * 原子地取出最近 limit 条，只将返回的消息标记为已读。
      * 避免“先 list 再 clear”之间新到的消息被误清掉。
      */
     drain(limit: number): InboxMessage[];

package/lib/inbox.js

@@ -27,11 +27,11 @@ export class InboxQueue {
         if (this.seen.has(key))
             return;
         this.seen.add(key);
+        while (this.seen.size > Math.max(200, this.capacity * 4))
+            this.seen.delete(this.seen.values().next().value);
         this.items.push(message);
         if (this.items.length > this.capacity) {
-            const removed = this.items.splice(0, this.items.length - this.capacity);
-            for (const item of removed)
-                this.seen.delete(this.key(item));
+            this.items.splice(0, this.items.length - this.capacity);
         }
     }
     /** 返回最近 limit 条消息（新的在前）。 */
@@ -42,24 +42,20 @@ export class InboxQueue {
         return this.items.slice(-n).reverse();
     }
     /**
-     * 原子地取出最近 limit 条并清空整个队列。
+     * 原子地取出最近 limit 条，只将返回的消息标记为已读。
      * 避免“先 list 再 clear”之间新到的消息被误清掉。
      */
     drain(limit) {
         const n = Math.max(0, Math.trunc(limit));
         if (n === 0) {
-            this.clear();
             return [];
         }
         const out = this.items.splice(-n).reverse();
-        this.items = [];
-        this.seen.clear();
         return out;
     }
     /** 清空队列。 */
     clear() {
         this.items = [];
-        this.seen.clear();
     }
     /** 当前队列长度。 */
     get size() {

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/slack-client.js

@@ -5,7 +5,10 @@
 import { WebClient } from '@slack/web-api';
 /** 用官方 WebClient 实现。 */
 export function createWebSlackClient(token, slackApiUrl) {
-    const client = new WebClient(token, { ...(slackApiUrl !== undefined && slackApiUrl !== '' ? { slackApiUrl } : {}) });
+    const client = new WebClient(token, {
+        timeout: 25000, retryConfig: { retries: 0 }, rejectRateLimitedCalls: true,
+        ...(slackApiUrl !== undefined && slackApiUrl !== '' ? { slackApiUrl } : {})
+    });
     return {
         async postMessage(params) {
             const result = await client.chat.postMessage({
@@ -14,6 +17,8 @@ export function createWebSlackClient(token, slackApiUrl) {
                 ...(params.thread_ts !== undefined ? { thread_ts: params.thread_ts } : {}),
             });
             const ts = typeof result.ts === 'string' ? result.ts : '';
+            if (!ts)
+                throw new Error('Slack 未返回消息回执，无法确认提交结果；请先检查频道，避免直接重发。');
             return { ts };
         },
         async listChannels() {
@@ -21,8 +26,7 @@ export function createWebSlackClient(token, slackApiUrl) {
             let pages = 0;
             const allChannels = [];
             const seen = new Set();
-            // conversations.list 默认分页（每页约 100-200 条）；企业工作区频道很多时
-            // 必须沿 next_cursor 翻完，否则模型会漏掉后面的频道。
+            // Follow the official pagination cursor, with the existing 20-page cap.
             do {
                 pages += 1;
                 if (pages > 20)
@@ -41,12 +45,6 @@ export function createWebSlackClient(token, slackApiUrl) {
                 cursor = typeof next === 'string' && next !== cursor ? next : '';
             } while (cursor !== '');
             return allChannels;
-            /*
-              // if (typeof ch.id === 'string' && typeof ch.name === 'string') {
-                // allChannels.push({ id: ch.id, name: ch.name })
-              */
-            // }
-            // removed duplicate return
         },
     };
 }

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 {};