前言¶
在 DeepSeek Harness（DSH）中为不同平台分别配置 IM 通道，意味着要复制多次会话 plumbing，维护成本高。dsh-telegram 是较早的单一平台实现，但第三方维护，语言硬编码，且无法在一个会话 plumbing 上复用。dsh-im-global 把这套 plumbing 抽取出来，用一个插件统一接入多个平台，会话持久化且重启不中断。
这是什么¶
dsh-im-global 是一个 DSH 插件，提供全局 IM 通道：Telegram、Discord、Slack、Mattermost、Zulip 和 Matrix。它共享与钉钉 / QQ / 微信 / 飞书 / 企业微信网关相同的架构：一个插件、channels: [...] 列表、每个平台一个适配器。会话按对话绑定，重启后仍然有效。
核心功能¶
- 多平台接入：Telegram、Discord、Slack、Mattermost、Zulip、Matrix。
- 会话持久化：每个对话绑定一个会话，重启后继续。
- 配置与凭证分离：凭证通过环境变量或凭证存储管理，配置文件只引用名称。
- 允许名单（allowlist）：默认拒绝所有消息，需配置允许的用户 ID 才能接收与回答。
- Settings 页面：可在 DSH 界面中添加 / 测试 / 保存通道，无需重启进程。
- 原生 Markdown：各平台使用各自正确的 Markdown 语法。
安装与启用¶
通过插件市场添加索引源：
https://raw.githubusercontent.com/monkey-sking/dsh-im-global/main/index.json
然后在 DSH 中通过插件管理界面安装 dsh-im-global。
配置方式¶
有两种配置途径：
-
Settings 页面（无需 YAML 与重启）
- 在 Plugins 中启用该 bundle。
- 打开 Settings → Chat channels，添加通道：选择类型、命名凭证、设置服务器 URL、测试凭证并保存。
- 保存后受影响通道原地重启，不重启整个进程。
- 凭证名称存储在页面，实际密钥在凭证存储中。 -
cordis.patch.yml
- 在 profile 的cordis.patch.yml中添加im-global行：
- id: im-global
config:
channels:
- id: telegram-main
type: telegram
tokenRef: TELEGRAM_BOT_TOKEN
- id: discord-main
type: discord
tokenRef: DISCORD_BOT_TOKEN
凭证命名与内容：
| 平台 | 默认凭证名 | 内容 |
|—|—|—|
| Telegram | TELEGRAM_BOT_TOKEN | BotFather → /newbot 返回的 token |
| Discord | DISCORD_BOT_TOKEN | 开发者门户 → Bot → Token |
| Slack | SLACK_BOT_TOKEN | OAuth & Permissions → Bot User OAuth Token (xoxb-…) |
| Slack | SLACK_APP_TOKEN | Basic Information → App-Level Tokens (xapp-…, scope connections:write) |
| Matrix | MATRIX_ACCESS_TOKEN | 任意账号的访问令牌 |
| Mattermost | MATTERMOST_TOKEN | 个人访问令牌 |
| Zulip | ZULIP_BOT_TOKEN | <bot email>:<api key>（Settings → Bots） |
允许名单（allowlist）安全策略¶
插件默认为“拒绝所有消息”（fail-closed）。未配置允许名单时，任何平台消息都会被拒绝，并显示为“locked”。
配置允许的用户 ID：
- Settings 页面：在通道卡片填写 允许的用户 id（逗号分隔）。
- cordis.patch.yml：
- id: im-global
config:
allowedUsers: [123456789] # 全局默认
channels:
- id: telegram-main
type: telegram
tokenRef: TELEGRAM_BOT_TOKEN
allowedUsers: [987654321] # 通道级覆盖
- 优先级：通道级 > 全局级 > 未配置（保持锁定）。
获取用户 ID 的方式：
- Telegram：机器人日志中的数字 id
- Discord：Snowflake
- Slack：member id
- Matrix：@user:server
- Mattermost / Zulip：数字用户 id
按钮回答同样受允许名单约束，防止群组中任意成员误答。
平台特性¶
- Telegram：Bot API 长轮询；同一 token 只能被一个进程长轮询；若已有其他 Telegram 通道使用同一 token，需在配置中禁用旧通道（
disabled: true）。 - Discord：Gateway WebSocket + REST。
- Slack：Socket Mode WebSocket + Web API。
- Mattermost：WebSocket + REST。
- Zulip：event-queue 长轮询。
- Matrix：client-server
/sync长轮询。
迁移与兼容¶
从其他 Telegram 插件迁移会话时，可运行迁移脚本：
node scripts/migrate-telegram-bindings.mjs telegram-main
该脚本复制旧的 chat -> session 映射，使同一聊天继续使用原 Harness 会话，而不是新建会话。
适用场景与注意¶
- 适合需要统一接入多个 IM 平台的 DSH 用户，特别是多团队协作或跨平台场景。
- 插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证（MIT）。
- 确保 Node.js 版本 ≥ 20。
结尾¶
dsh-im-global 将多个 IM 平台统一到一套插件架构中，用允许名单做安全网关，兼顾配置灵活性与会话持久化。如需更多信息，可访问项目目录页或 GitHub 仓库。
