🐋 dsh-im-gateway

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

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

English · 简体中文

⚡ 一键安装：把提示词发给你的 dsh 即可

任选一种方式，把下面整段提示词发给你的 dsh（Web GUI 聊天框 / dsh --profile headless "…" / 已接入的 IM 聊天），agent 会自动完成下载、构建、安装——不用手动敲命令。

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

请帮我安装 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。

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

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

装好后：打开 dsh Web GUI → 设置 ⚙️ → 🐋 IM 网关 → 点选渠道连接（微信/WhatsApp 扫码即连，其余填凭据即可）。

💬 IM 命令

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

✨ Highlights

• 🌐 23+ 渠道全覆盖 — 对齐 OpenClaw 的渠道面：微信、飞书、Telegram、Discord、Slack、QQ、WhatsApp、Signal、Teams、LINE、Matrix、Mattermost、IRC、Twitch、Nostr、Zalo、iMessage……
• 🔁 每聊天一个 agent 会话 — 群里聊天 = 驱动 agent，回复实时回推；/new 换新会话，/bind 绑定现有会话
• ✅ 远程审批桥 — agent 请求工具批准时推送到 IM，聊天里回一句「批准 / 拒绝」即可，超时自动转回本机批准体系
• ❓ 交互式提问桥 — ask_user_question 的问题和选项同步到所有绑定渠道；Web 或任一 IM 均可回答，第一答生效并恢复同一个 agent
• ⏰ 聊天级定时提醒（im_cron） — 定时任务绑定聊天而非会话，/new 轮换、会话重启都不影响；在聊天里直接说「每天 9 点提醒我喝水」即可创建，到点直推
• 📱 手机多段输入合并 — .. 表示还有后续，!! 立即提交，裸文本 5 秒合并窗口，崩溃后自动恢复
• ✂️ 长回复智能分片 — 按各渠道上限切分，优先在换行/句号断行，带 （i/n） 序号且收敛
• 🛡️ 白名单安全默认 — 默认拒绝一切未知用户；审批应答强制校验会话归属
• 🔑 扫码登录 + 免扫码恢复 — 微信 / WhatsApp 扫码登录链接自动落盘；登录态（bot_token + 轮询游标）持久化，重启自动恢复连接，无需重复扫码
• 🖼️ 媒体收发 — 微信渠道完整支持图片/语音（服务端转文字）/文件/视频（CDN AES-128-ECB 加密），agent 可用 im_send_file 工具把工作区文件发给聊天
• 📦 一条命令安装 + 可视化连接 — 标准 dsh.bundle 插件；Web GUI 设置面板点选渠道、扫码/填凭据即连，无需重启
• 🎯 小白友好 — 微信/WhatsApp 点一下直接弹二维码；其余渠道表单引导，状态实时显示

❓ 如何回答交互式提问

当 agent 调用 ask_user_question 时，Web GUI 的结构化问题会同步发送到该会话绑定的全部 IM 聊天。Web 和 IM 同时可答，第一份有效答案生效；其余渠道会收到已回答通知，agent 随后从同一个等待点继续执行。

IM 回答窗口由 questionTimeoutSecs 控制（默认 600 秒）。窗口超时只会停止 IM 等待，Web GUI 中的问题仍可继续回答。等待按 session 隔离；多个渠道同时回答时，只有最先到达的一份会恢复 agent。

⏰ 聊天级定时提醒（im_cron）

定时任务绑定聊天（chatId）而非会话（sessionId）——你在微信里创建提醒后，无论 /new 轮换多少次、会话是否存活，到点都会直接推送到该聊天。这是 dsh 自带 schedule（session-local）在 IM 场景的替代方案。

创建：直接在聊天里对 agent 说「每天 9 点提醒我喝水」/「每周一 9 点生成今日待办」，agent 会调用 im_cron_add 工具创建。也可以手动指定参数：

管理：/cron list、/cron rm <id>；Web 设置面板提供 /dsh-im-gateway/api/cron（list / delete / enable）。

行为细节：

• 提醒按本地时区 + 星期计算下次触发时刻（支持 DST 间隙跳过、重叠取早）；
• 状态落盘 $DSH_HOME/dsh-im-gateway/cron.json，重启自动恢复；
• 发送失败自动重试（不推进下次触发）；
• 错过策略：cronCatchUp 默认 false（网关停机期间错过的提醒不补发，直接跳下次）；设为 true 则恢复后补发最近一次；
• 工具按当前聊天隔离：im_cron_list / im_cron_rm 只能读写本聊天创建的任务，防止越权。

📸 效果预览

🏗 架构

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

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

📡 支持的渠道

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

🚀 快速开始

1. 安装（一次）

# 方式一：npm 安装（推荐）
dsh plugin --profile web add dsh-im-gateway

# 方式二：本地源码（开发/调试用）
cd dsh-im-gateway
npm install && npm run build
dsh plugin --profile web add /path/to/dsh-im-gateway

dsh web    # 重启 dsh（安装插件后需要重启一次）

2. 连接渠道（之后所有操作都在网页里，无需再碰配置）

打开 dsh Web GUI（默认 http://localhost:3080）→ 设置 ⚙️ → 「🐋 IM 网关」：

• 微信 / WhatsApp：点「连接（扫码）」→ 页面直接弹出二维码，手机扫码确认即连 ✅
• 飞书 / Telegram / QQ 机器人 / Discord / Slack …：点「填写凭据」→ 按提示粘贴 token → 「保存并连接」✅

连接后无需重启，状态实时显示（等待扫码 / 已连接 / 异常）。重启 dsh 后所有已配置渠道自动重连（微信登录态已持久化，无需重复扫码）。

🔧 断开 vs 删除配置：已连接渠道卡片上有两个按钮——「断开」只是临时停用（重启自动恢复）；「删除配置」会移除凭据（重启不再连接，需重新配置）。

💡 手动配置方式（可选）：在 ~/.dsh/profiles/web/cordis.patch.yml 写配置，凭据也可用环境变量，见下文「配置」。

3. 开始使用

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

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

🔔 首次使用需要授权（安全默认）：第一次发消息会收到"未授权"提示，同时 dsh 设置 → IM 网关 面板顶部出现 「有用户请求访问」 横幅——点「允许」后即可正常使用，无需手动找用户 ID。

agent 回复实时回推；需要批准时在聊天里回「批准 / 拒绝」；agent 还可以用 im_send_file 把文件（截图/报告）直接发到聊天。

⚙️ 配置

所有配置写在 profile 的 cordis.patch.yml 的 im-gateway 行；凭据也可用环境变量（见下表）。

通用配置

- id: im-gateway
  config:
    sessionMode: per-chat          # per-chat（默认）| bound
    cwd: /path/to/workspace        # agent 工作目录
    provider: deepseek-official    # LLM provider（默认跟随 dsh）
    model: deepseek-v4-flash       # 模型（默认跟随 dsh）
    allowAllUsers: true            # 默认放行所有用户（开箱即用）；管控时改 false
    allowedUserIds:                # 白名单：按渠道（allowAllUsers=false 时生效）
      telegram: ['123456789']
      '*': ['u-common']            # 跨渠道通用
    mergeTimeoutSecs: 5            # 手机多段输入合并窗口
    approvalTimeoutSecs: 120       # 审批超时，超时转回本机批准
    questionTimeoutSecs: 600       # IM 交互提问回答窗口；超时后仍可在 Web 回答
    summaryOnTurnEnd: true         # 每轮结束推送 [✅ 完成] 摘要
    stateDir: ''                   # 状态目录（默认 $DSH_HOME/dsh-im-gateway）

渠道凭据速查

🧪 开发

npm install
npm run build          # tsc 构建到 lib/
npm test               # node --test（70 个用例：分片/合并/审批/交互提问/网关/渠道协议）

新增一个渠道只需 4 步：

1. 在 src/channels/ 新建 yourchannel.ts，实现 ChannelAdapter（6 个方法）
2. 在 src/channels/index.ts 注册
3. 在 src/index.ts 的 Config 里补配置字段
4. 在 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 保证 60 个用例全绿
• 给仓库加 dsh-plugin 和 deepseek-harness topic 可以进 awesome 插件列表

📄 许可证

MIT © zhuiyueya

Made with 🐋 for the DeepSeek Harness ecosystem