dsh-im-gateway

🐋 dsh-im-gateway

把 DeepSeek Harness 接入你常用的每一个聊天软件

Aggregated IM gateway for DeepSeek Harness (dsh) — drive your coding agents from WeChat, Feishu, Telegram, Discord, QQ and 25+ chat platforms, with unified sessions, remote approvals, interactive questions and one-command setup.

English · 简体中文

📸 效果预览

⚡ 一键安装

任选一种方式，把下面整段提示词发给你的 dsh（Web GUI 聊天框、dsh --profile headless "…" 或已接入的 IM 聊天），agent 会自动完成安装。安装插件后重启一次 dsh web。

方式 A · npm 安装（推荐）

请安装 dsh-im-gateway 插件：dsh plugin --profile web add dsh-im-gateway
装完提醒我重启 dsh web。

方式 B · GitHub 克隆安装

请帮我安装 dsh-im-gateway 插件（DeepSeek Harness 的聚合 IM 网关）：
1. 执行 git clone --depth 1 https://github.com/zhuiyueya/dsh-im-gateway.git /tmp/dsh-im-gateway
2. 执行 cd /tmp/dsh-im-gateway && npm install && npm run build
3. 执行 dsh plugin --profile web add /tmp/dsh-im-gateway
4. 汇报结果；如果提示需要重启，提醒我重启 dsh web。

方式 C · 远程仓库直装

请安装 dsh-im-gateway 插件：dsh plugin --profile web add https://github.com/zhuiyueya/dsh-im-gateway.git
装完提醒我重启 dsh web（首次安装依赖约 1-2 分钟）。

方式 D · 本机已有项目目录

请把本机项目 dsh-im-gateway 安装为 dsh 插件：
1. 进入项目目录执行 npm install && npm run build
2. 执行 dsh plugin --profile web add <项目绝对路径>
3. 提醒我重启 dsh web。

🚀 快速开始

1. 安装并打开设置

安装完成后重启 dsh web，打开：设置 ⚙️ → 🐋 IM 网关。

2. 连接渠道

• 微信 / WhatsApp：点击「连接（扫码）」，用手机关联设备。
• 飞书 / QQ / 钉钉 / 企业微信：点击「扫码接入机器人」，使用对应平台 App 扫码确认；也可以手动填写凭据。
• Telegram / Discord / Slack 等：按卡片中的官方文档和凭据表单完成接入。

连接后无需重启，状态统一显示为：已连接 / 未连接 / 连接中 / 异常。重启 dsh 后，已保存配置的渠道会自动恢复；微信登录态已持久化，无需重复扫码。

断开 vs 删除配置：暂时断开只停止运行并保留配置，重启后会自动恢复；删除配置会移除凭据，之后需要重新接入。

3. 开始使用

在连接好的聊天软件里给机器人发消息：

/help        ← 查看可用命令
你好，帮我看看当前工作区    ← 普通聊天 = 驱动 agent

如果设置了 allowAllUsers: false，未授权用户首次发消息会收到授权提示，Web 设置页顶部会出现访问请求；默认 allowAllUsers: true 时无需授权步骤。

agent 回复会实时回推；需要批准时在聊天里回复「批准 / 拒绝」；agent 也可以使用 im_send_file 将工作区文件发送到聊天。

各平台为什么支持或不支持扫码，见 docs/qr-login-matrix.md。

📡 支持的渠道

渠道	状态	接收方式	接入方式
Telegram	✅ 完整	Bot API 长轮询	@BotFather token
Discord	✅ 完整	Gateway WebSocket	Bot token
Slack	✅ 完整	Socket Mode	xoxb- + xapp- token
飞书 / Lark	✅ 完整	官方 SDK 长连接	官方扫码或 App ID + Secret
钉钉	✅ 完整	官方 Stream 长连接	官方扫码或 Client ID + Secret
企业微信	✅ 完整	官方智能机器人 WebSocket	官方扫码或 Bot ID + Secret
微信	✅ 完整*	腾讯官方 iLink 长轮询（设备扫码）	官方 iLink 账号（建议专用账号）
QQ 机器人	✅ 完整	官方 WebSocket	官方扫码或 AppID + Secret
LINE	✅ 完整	REST + webhook	Channel token
Matrix	✅ 完整	客户端同步	Homeserver + token
Mattermost	✅ 完整	WebSocket + REST	Server URL + token
IRC	✅ 完整	原生 socket	服务器地址
Twitch	✅ 完整	WebSocket IRC	OAuth token
Signal	✅ 完整	signal-cli 子进程	本机 signal-cli
Nextcloud Talk	✅ 完整	REST 轮询	实例账号
Synology Chat	✅ 完整	webhook	Incoming webhook
Zalo	✅ 完整	REST + webhook	OA token
iMessage	✅ 完整*	imsg / osascript	macOS
WhatsApp	🔄 动态依赖	Baileys 扫码	npm i @whiskeysockets/baileys
Nostr	🔄 动态依赖	NIP-04 私信	npm i @noble/curves
Teams	🧪 实验性	Bot Framework	Azure 注册
Google Chat	🧪 实验性	webhook	公网地址
Tlon / 元宝 / 语音	🧪 骨架	—	基础设施

✅ 完整 = 收发可用 ｜ 🔄 动态依赖 = 未装 SDK 时提示安装 ｜ 🧪 实验性 = 需公网或专用基础设施 ｜ *微信 = 腾讯官方 iLink 渠道（媒体收发 + 语音转文字 + typing）

✨ 核心功能

💬 IM 命令

在连接好的聊天软件里，发给机器人的消息以 / 开头即命令：

命令	说明
/help	本帮助
/status	查询当前会话（会话 id / 工作区 / 待批准）
/new · /clear	开启全新会话（per-chat 模式）
/workspaces	列出所有工作区
/workspace <路径>	切换工作区（后续 /new 生效）
/sessions [all|路径]	列出会话（默认当前工作区；all 全部）
/continue <会话id>	继续已有会话（跨渠道/跨工作区）
/bind <session-id>	绑定本机 live 会话（bound 模式）
/unbind	解绑（bound 模式）
/channels	各渠道连接状态
/cron list	查看本聊天定时任务
/cron rm <id>	删除本聊天的定时任务
批准 / 拒绝	应答待批准请求（也支持 yes / no / 同意）
普通文本	发给 agent；结尾 .. 表示还有后续，!! 立即提交

✅ 远程审批

agent 请求工具批准时会把请求推送到聊天；直接回复「批准 / 拒绝」即可。审批回复会校验聊天与会话归属，超时后转回本机批准体系。

❓ 交互式提问

当 agent 调用 ask_user_question 时，Web GUI 的问题和选项会同步发送到该会话绑定的全部 IM 聊天。Web 和 IM 均可回答，第一份有效答案生效，其余渠道会收到已回答通知。

问题类型	IM 回答方式	示例
单选	选项编号、完整标签或自定义文字	2、完整模式、以后再说
多选	用逗号、中文逗号、顿号或分号分隔	1,3、快速、测试
自由输入	直接回复完整文本	项目名叫 dsh-im-gateway
多个问题	每行使用 问题序号: 答案	1: 2 换行 2: 1,3

回答窗口由 questionTimeoutSecs 控制，默认 600 秒。窗口超时只会停止 IM 等待，Web GUI 中的问题仍可继续回答；等待按 session 隔离。

⏰ 聊天级定时提醒

定时任务绑定聊天（chatId）而非会话（sessionId）。在聊天里说「每天 9 点提醒我喝水」或「每周一 9 点生成今日待办」，agent 会创建提醒；无论 /new 轮换多少次或会话是否重启，到点都会直接推送到该聊天。

• /cron list：查看本聊天的定时任务
• /cron rm <id>：删除定时任务
• 支持一次性提醒、每天提醒和按星期提醒
• 支持 IANA 时区与 DST 间隙/重叠处理
• 状态落盘，重启自动恢复；发送失败自动重试

📱 消息与媒体

• 手机多段输入：.. 表示还有后续，!! 立即提交，裸文本在 5 秒窗口内合并，崩溃后自动恢复。
• 长回复按各渠道上限分片，优先在换行或句号处断行，带 （i/n） 序号。
• 微信支持图片、语音转文字、文件、视频；agent 可通过 im_send_file 发送工作区文件。

🛡️ 访问控制

默认 allowAllUsers: true 便于开箱使用；需要管控时设为 false 并配置渠道白名单。审批应答始终校验会话归属。

🏗 架构

   IM 渠道 (Telegram / 微信 / 飞书 / Discord / …)              DSH agent
        │  adapter 归一化入站                                    ▲
        ▼                                                       │
┌─────────────────────────┐      ┌────────────────────────┐    │
│  ChannelAdapter          │◄────►│  ImGateway (核心网关)    │────┘
│  · 每渠道一个适配器       │      │  · 会话路由 (per-chat)   │
│  · 收: 轮询/WebSocket/   │      │  · 白名单 & IM 命令      │
│     webhook → ImMessage  │      │  · 审批桥 / 提问桥       │
│  · 发: send(chatId,text) │      │  · 分片 / 多段合并       │
└─────────────────────────┘      └────────────────────────┘
        ▲
        │  session/event · assistant/message · turn/end
        └────────────────────────────────────────────────────

用户消息 → 渠道 adapter → 网关(白名单→合并→会话路由) → agent.followup()
agent 回复 ← 网关(按渠道分片) ← session/event(assistant/message) ← agent
工具批准 → approval/request → 推送到聊天 → 「批准」→ allowed-once

🧪 开发

npm install
npm run build          # tsc 构建到 lib/
npm test               # node --test（106 个用例）

新增一个渠道只需 4 步：

• 在 src/channels/ 新建 yourchannel.ts，实现 ChannelAdapter（6 个方法）
• 在 src/channels/index.ts 注册
• 在 src/index.ts 的 Config 里补配置字段
• 在 README 渠道表加一行 ✨

export function createYourChannel(config, log): ChannelAdapter | undefined {
  if (!config.token) return undefined          // 未配置凭据 → 不启动
  return {
    id: 'yourchannel', label: 'YourChannel', maxMessageLength: 2000,
    start() { /* 连接 / 轮询 / 扫码 */ },
    stop() { /* 释放 */ },
    async send(chatId, text) { /* 发消息 */ },
    setMessageHandler(h) { /* 入站回调 */ },
    status() { return 'running' },
  }
}

🤝 贡献

• 修 bug、补渠道、完善文档都欢迎！
• 请先 npm test 保证 106 个用例全绿
• 给仓库加 dsh-plugin 和 deepseek-harness topic 可以进 awesome 插件列表

📄 许可证

MIT © zhuiyueya

Made with 🐋 for the DeepSeek Harness ecosystem