dsh-slack 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# 更新记录
+
+[返回简介](README.md) · [使用说明](docs/USAGE.md) · [验证记录](docs/VALIDATION.md)
+
+[历史英文记录](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)
+
+- 标记已读只移除本次展示的消息，保留剩余未读与已读重投去重；发送不隐式重试，缺少消息回执时提示先检查频道。
+
+## 0.3.3 (2026-10-01)
+
+- 更新并对齐 Socket Mode 的传输依赖，修复依赖解析问题。
+
+## 0.3.0 (2026-08-26)
+
+- 新增 `slack_health` 自检（令牌/Socket Mode 配置一键体检）；修复只配置部分字段（如只有 token 没有 appToken）时可选链导致的启动崩溃。
+
+## 0.2.3 (2026-08-15)
+
+- `slack_channels` 自动分页：频道很多时不再只返回第一页。
+  - `slack_inbox` 去重 + `drain` 原子消费：Slack 重投的事件不会重复入队，`markRead` 期间新到的消息也不会被误清。
+  - WebClient 复用：同一 `token + slackApiUrl` 只创建一个客户端，减少重复初始化。
+  - 分页增加页数上限，防止异常 `next_cursor` 导致死循环。
+  - 错误映射补充 `not_authed` / `is_archived` / `msg_too_long` / `ratelimited`。
+
+## 更早的改动
+
+完整历史可查阅 [GitHub 提交记录](https://github.com/STARDUSTLC666/dsh-slack/commits/main)。

package/README.en.md

@@ -1,210 +1,48 @@
-[中文](README.md)
-
-![npm](https://img.shields.io/npm/v/dsh-slack) ![downloads](https://img.shields.io/npm/dm/dsh-slack) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-slack) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-slack?style=social)
-
 # 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,
-> enabling "Slack message → agent": `slack_inbox` receives messages, `slack_reply` replies in threads.
-> RTM and interactive components (buttons/modals/slash command replies) are out of scope for v0.2 — see
-> [Known limitations and roadmap](#known-limitations-and-roadmap) below.
-
-## 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`).
-
-## Changelog
-
-- **0.3.0**: new `slack_health` self-check (one-call token / Socket Mode config health); fixed a startup crash from optional chaining when only some config fields are set (e.g. token without appToken).
-- **0.2.3**:
-  - `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`.
-
+[中文](README.md)
 
-## Compatibility
+![dsh-slack whale girl plugin cover](https://raw.githubusercontent.com/STARDUSTLC666/dsh-slack/main/assets/cover-whale-girl.png)
 
-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.
+Connect Slack for notifications, a Socket Mode inbox and thread replies.
 
-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.
+[![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)
 
-## Installation
+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).
 
-The plugin runs inside the host process, is installed into the profile via `dsh plugin`, and takes effect after a restart:
+## What it does
 
-```sh
-dsh plugin --profile web add dsh-slack
-```
+- Send Markdown notifications to channels or threads.
+- List visible channels and read the Socket Mode inbox.
+- Reply in threads and check connection or token configuration.
 
-After installing, restart your dsh Web service; the four tools `slack_notify` / `slack_channels` / `slack_inbox` / `slack_reply` become visible to the model.
+## Install
 
-## Uninstall
+In DSH Desktop, install `dsh-slack` from the Plugins panel. If the bundled dsh command is available:
 
 ```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'
+dsh plugin --profile desktop add dsh-slack
 ```
 
-> Priority: `config.token` > env var `DSH_SLACK_TOKEN`; `config.appToken` > env var
-> `DSH_SLACK_APP_TOKEN`.
-
-### Create a Slack App and get a token
+For the web version, replace `desktop` with `web`. Restart DSH after installation.
 
-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
-```
+## Start using it
 
-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.
+Configure your Slack App and tokens, then ask to review the inbox and identify messages that need a reply.
 
-## Known limitations and roadmap
+## Requirements and configuration
 
-- **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.
+Requires a bot token. Socket Mode also needs an app token and permissions; the inbox is stored in memory.
 
-Roadmap: v0.3 plans to introduce interactive components (buttons/modals) and a persisted inbox.
+Detailed configuration, tool arguments and troubleshooting are in the [usage guide](docs/USAGE.en.md). For standalone development, follow the Node requirement in [package.json](package.json).
 
-## Dependencies
+## Documentation
 
-- 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`
+- [Usage and troubleshooting](docs/USAGE.en.md)
+- [Changelog](CHANGELOG.md)
+- [Validation scope and history](docs/VALIDATION.md)
+- [Report a problem or suggest a feature](https://github.com/STARDUSTLC666/dsh-slack/issues)
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/README.md

@@ -1,214 +1,48 @@
-[English](README.en.md)
-
 # dsh-slack
 
-> **让 agent 进你的 Slack**：发消息、看频道、收消息、回线程，双向通信。
-
-![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 双向通信。
+[English](README.en.md)
 
-## 兼容性
+![dsh-slack 鲸鱼娘插件封面](https://raw.githubusercontent.com/STARDUSTLC666/dsh-slack/main/assets/cover-whale-girl.png)
 
-验证宿主：官方发布标签源码构建的 Harness `0.2.0-rc.2`（commit `639ed01539`）+ Windows / Node `24.16.0`。43 项插件测试通过；同一个宿主里 18 个插件共同加载，本插件的 5 个工具全部注册，工具 schema 与健康检查契约通过。真实 Slack 登录、Socket Mode 收件和发送尚未验收。
+连接 Slack，发送通知并处理 Socket Mode 收件箱与线程回复。
 
-0.3.3 使用支持 Undici 7/8 的官方 Socket Mode SDK 3.1 或更新版本，并显式声明匹配的传输依赖，修复组合安装中旧 SDK 与宿主 Undici 8 的依赖不匹配；npm 包同时包含中英文说明。
+[![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)
 
-> **v0.2 范围（双向）**：v0.1 只做「agent → Slack」单向通知；v0.2 新增 Socket Mode，
-> 支持「Slack 消息 → agent」：`slack_inbox` 收取消息、`slack_reply` 线程回复。
-> RTM、交互组件（按钮/弹窗/slash command 回复）不在 v0.2，见下方
-> [已知限制与路线图](#已知限制与路线图)。
+欢迎使用，遇到问题或有改进建议，请提交 [issues](https://github.com/STARDUSTLC666/dsh-slack/issues) 和 [PR](https://github.com/STARDUSTLC666/dsh-slack/pulls)。
 
 ## 功能
 
-- `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`）。
-
-## 版本记录
-
-- **0.3.0**：新增 `slack_health` 自检（令牌/Socket Mode 配置一键体检）；修复只配置部分字段（如只有 token 没有 appToken）时可选链导致的启动崩溃。
-- **0.2.3**：
-  - `slack_channels` 自动分页：频道很多时不再只返回第一页。
-  - `slack_inbox` 去重 + `drain` 原子消费：Slack 重投的事件不会重复入队，`markRead` 期间新到的消息也不会被误清。
-  - WebClient 复用：同一 `token + slackApiUrl` 只创建一个客户端，减少重复初始化。
-  - 分页增加页数上限，防止异常 `next_cursor` 导致死循环。
-  - 错误映射补充 `not_authed` / `is_archived` / `msg_too_long` / `ratelimited`。
+- 向频道或线程发送 Markdown 通知。
+- 读取机器人可见频道和 Socket Mode 收件箱。
+- 回复线程，按配置检查连接与令牌。
 
 ## 安装
 
-插件运行在宿主进程内，通过 `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 自动重连，插件只记录告警、不抛崩。
-
-## 卸载
+桌面版可在「插件」面板按包名 `dsh-slack` 安装。已配置 dsh 命令时也可使用：
 
 ```bash
-dsh plugin --profile web remove dsh-slack
+dsh plugin --profile desktop add 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`
+网页版把命令中的 `desktop` 改为 `web`。安装后重启 DSH。
 
-读取通过 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 缺失不崩。
+配置 Slack App 和令牌后，可说：“查看 Slack 收件箱，整理需要回复的消息。”
 
-## 已知限制与路线图
+## 依赖与配置
 
-- **v0.1 是单向通知（agent→Slack）**；**v0.2 通过 Socket Mode 实现双向**（`slack_inbox` / `slack_reply`）。
-- **不支持** RTM、交互组件（按钮/弹窗/slash command 回复）。
-- `slack_inbox` 为进程内存队列：重启即清空，且不持久化；最多保留 200 条，满则丢最旧。
-- `channel` 为必填参数，`defaultChannel` 目前只作为说明提示写入 `channel` 参数描述，不替代
-  必填的 `channel`。
-- 令牌缺失时插件仍会加载（懒加载），错误在工具被调用时才抛出；appToken 缺失则仅告警。
+需要 Bot Token。Socket Mode 收消息还需要 App Token 与相应权限；收件箱在内存中保存。
 
-路线图：v0.3 计划引入交互组件（按钮/弹窗）与持久化收件箱。
+详细配置、工具参数与排错见[使用说明](docs/USAGE.md)。从源码独立开发时，Node 要求以 [package.json](package.json) 为准。
 
-## 依赖
+## 文档
 
-- 运行时：`@slack/web-api`（官方 WebClient）、`@slack/socket-mode`（Socket Mode 客户端）
-- peer（由宿主提供，插件运行时不直接 import）：`@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`
+- [使用与排错](docs/USAGE.md)
+- [更新记录](CHANGELOG.md)
+- [验证范围与历史记录](docs/VALIDATION.md)
+- [问题反馈与功能建议](https://github.com/STARDUSTLC666/dsh-slack/issues)
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/docs/CHANGELOG.en.md

@@ -0,0 +1,21 @@
+# Historical release notes
+
+[Current changelog](../CHANGELOG.md) · [Overview](../README.en.md)
+
+These English notes preserve the earlier translations. The main changelog contains the consolidated version history.
+
+## 0.3.4 (2026-10-05)
+
+- Mark only displayed inbox messages as read, preserving unread entries and retry deduplication. Disable implicit send retries; missing receipts prompt channel inspection.
+
+## 0.3.0 (2026-08-26)
+
+- new `slack_health` self-check (one-call token / Socket Mode config health); fixed a startup crash from optional chaining when only some config fields are set (e.g. token without appToken).
+
+## 0.2.3 (2026-08-15)
+
+- `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`.