Slack

English # dsh-slack > 让 agent 进你的 Slack：发消息、看频道、收消息、回线程，双向通信。 DSH（DeepSeek Harness）社区插件：让 agent 与 Slack 双向通信。 > v0.2 范围（双向）：v0.1 只做「agent → Slack」单向通知；v0.2 新增 Socket Mode， > 支持「Slack 消息 → agent」：slack_inbox 收取消息、slack_reply 线程回复。 > RTM、交互组件（按钮/弹窗/slash command 回复）不在 v0.2，见下方 > 已知限制与路线图。 ## 功能 - 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）。 ### v0.2.3 优化 - slack_channels 自动分页：频道很多时不再只返回第一页。 - slack_inbox 去重 + drain 原子消费：Slack 重投的事件不会重复入队，markRead 期间新到的消息也不会被误清。 - WebClient 复用：同一 token + slackApiUrl 只创建一个客户端，减少重复初始化。 - 分页增加页数上限，防止异常 next_cursor 导致死循环。 - 错误映射补充 not_authed / is_archived / msg_too_long / ratelimited。 ## 安装 插件运行在宿主进程内，通过 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 自动重连，插件只记录告警、不抛崩。 ## 工具清单 ### 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