dsh-im-gateway

一句话定位

dsh-im-gateway 把 DeepSeek Harness 接入你常用的聊天软件：微信、飞书、钉钉、企业微信、QQ、Telegram、Discord、Slack 等 25 个渠道都变成 dsh agent 的前端通道，在聊天里发消息就能驱动 agent 处理代码与办公任务，agent 的回复也会实时推回聊天。

核心能力

• 25 个聊天渠道接入：覆盖国内（微信/飞书/钉钉/企业微信/QQ）、海外（WhatsApp/Telegram/Discord/Slack/Signal/LINE/Matrix/Mattermost/IRC/Twitch/Nostr/Nextcloud/Synology/Zalo/Teams/Google Chat）和 Apple 生态（iMessage）共 25 个渠道
• 统一会话路由：每个聊天窗口对应独立 agent 会话，支持 per-chat/bound 两种模式、/new /sessions /continue /bind /unbind 等命令，重启后自动恢复上次绑定
• 远程审批与交互提问：工具批准请求推到聊天，回「批准/拒绝」即可；agent 调用 ask_user_question 时问题同步到所有绑定渠道，第一份有效答案生效
• 聊天级定时提醒：定时任务绑在 chatId 上而非会话，支持一次性/每天/按星期与 IANA 时区，状态落盘重启自动恢复
• 微信扫码登录与官方扫码接入：微信/WhatsApp 走手机关联设备；飞书/QQ/钉钉/企业微信支持官方 SDK 扫码一键创建机器人，自动落盘凭据
• 访问控制与白名单：默认放行所有用户；可改为按渠道白名单，未授权用户首次发消息在设置面板一键批准

技术实现

• 语言: TypeScript（ESM，tsc 编译到 lib/，main 指向 lib/index.js）
• 关键依赖: @deepseek-ai/cordis（宿主插件框架）、@deepseek-ai/schemastery（配置 Schema）、qrcode（本机生成二维码 data URL）；可选依赖按渠道动态引入，如 @larksuiteoapi/node-sdk / @tencent-connect/qqbot-connector / @wecom/aibot-node-sdk / @whiskeysockets/baileys / dingtalk-stream
• 架构模式: Cordis bundle 插件（cordis.patch.yml 通过 insert 把 im-gateway 注入 profile 组合层），inject = ['agents','jobs','tools','attachments','webServer','sessionQuery','agentPresets','userQuestions','workspaceRegistry']；通过 ctx.effect 注册定时器和 Web GUI HTTP API（/dsh-im-gateway/api/*），所有凭据与状态落到 $DSH_HOME/dsh-im-gateway/（默认 ~/.dsh/dsh-im-gateway/）
• 入口文件: src/index.ts（Cordis 插件入口 + Schemastery Config 声明）；每个渠道独立 src/channels/<name>.ts 实现 ChannelAdapter 契约（src/core/types.ts:46-74）

适用场景

适合想在常用 IM 里跟 DeepSeek Harness 交互、让 agent 帮忙读代码、跑命令、写文件的用户：日常不用打开 web 控制台，直接在聊天框发消息即可。团队或小工作室可在群聊里把 agent 当助理，每个人的对话上下文彼此隔离；管理员也能用远程审批、提问桥、定时提醒等把 agent 嵌进已有的协作流。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:zhuiyueya/dsh-im-gateway

配置项

插件通过 Schemastery Schema（src/index.ts:48）声明字段。下表「说明」列写人话：默认值已能跑通普通场景，普通用户无需调整，需要管控或多账号时再改。

各渠道独立的字段（如 channels.telegram.token、channels.feishu.appId 等）见 src/core/types.ts:86-114；连接方式上 微信 / WhatsApp 是扫码绑定，飞书 / 钉钉 / 企业微信 / QQ 支持官方扫码一键创建或手动填凭据，Telegram / Discord / Slack / LINE / Matrix / Mattermost / IRC / Twitch / Signal / Nostr / Nextcloud / Synology / Zalo / Teams / Google Chat 走凭据表单，iMessage 在 macOS 上开关即用。

常见问题

Q: 安装后从哪里开始？

A: 重启 dsh web，打开「设置 ⚙️ → 🐋 IM 网关」面板；点击任意渠道卡片即可扫码或填凭据接入，无需再次重启。微信/WhatsApp 用手机扫码关联设备，飞书/QQ/钉钉/企业微信支持官方扫码一键创建机器人，其它渠道按需填 token 即可。

Q: 不同聊天之间上下文会互相串吗？

A: 默认「per-chat」模式下每个聊天窗口对应独立 agent 会话；可发 /new 开新会话、/sessions 列出当前工作区会话、/continue 跨会话续接，或切到 bound 模式用 /bind 绑定一个本机现有 live 会话。

Q: 怎么让某个用户能驱动 agent？

A: 默认 allowAllUsers=true 全部放行。需要管控时在设置面板或 cordis.patch.yml 里把 allowAllUsers 改为 false，并通过「设置 → IM 网关 → 待授权请求」一键批准新用户，或在 allowedUserIds 配置按渠道白名单。

Q: 工具需要批准时怎么应答？

A: agent 触发工具批准时会把请求推送到对应聊天，直接回复「批准/拒绝/yes/no/同意」即可；超过 approvalTimeoutSecs（默认 120 秒）会自动回退到本机批准体系。

Q: 手机端怎么把长消息分多次发？

A: 在 IM 里逐段发送，结尾加「..」表示还没说完，5 秒合并窗口内（可调 mergeTimeoutSecs）会拼成一段发往 agent；想立即提交就以「!!」结尾，崩溃或断网后未发送的缓冲区也能恢复。

Q: 微信聊天登录态会丢吗？

A: 微信 iLink 登录态（bot_token）会持久化到 $DSH_HOME/dsh-im-gateway/wechat-state.json，重启后自动跳过扫码直接轮询；只有连续 3 次 token 失效才会清除登录态要求重新扫码，建议使用专用小号。

Q: 定时提醒是绑在聊天还是会话上？

A: 绑在聊天（chatId）上，与会话轮换无关。在聊天里说「每天 9 点提醒我喝水」，agent 会创建 im_cron 任务；即使 /new 切换会话，定时也会按时推回同一个聊天，支持一次性/每天/按星期与 IANA 时区。

Q: 可以中途撤回某个渠道的连接吗？

A: 「断开」只是停止运行态并保留配置，重启 dsh 后会自动恢复；「删除配置」才会清空凭据与白名单，之后需要重新接入。

上手难度

入门 — 扫码或填 token 即可接入主流渠道；进阶用户可调整会话模式、白名单、合并/审批/定时阈值，深度定制则按 ChannelAdapter 契约（src/core/types.ts:46）新增渠道。

已知问题与限制

• 部分渠道仅提供骨架（src/channels/stubs.ts）：Tlon（Urbit）、腾讯元宝、Twilio 语音电话三个渠道目前仅有占位实现，v0.1 未实现收发，启动后状态停留在「骨架（未实现）」
• 实验性渠道需专用基础设施：Microsoft Teams 需 Azure Bot Framework 注册；Google Chat 接收需公网 webhook；Nextcloud Talk 与 Zalo 标注「实验性」，文档与凭据流程可能变化
• iMessage 仅支持 macOS（src/channels/imessage.ts:37 用 osascript 发送，接收依赖本机 imsg 子进程，未配置时只能发不能收）
• 微信 iLink 协议仅支持私聊且需专用小号（src/channels/wechat.ts:8）；一个账号一个 poller，群聊不响应
• 微信登录态仅在连续 3 次 token 失效（errcode -14）后才清除，长时间断网重连可能需要手动重新扫码
• 配置覆盖优先级：$DSH_HOME/dsh-im-gateway/channels.json（UI 写入）> cordis.patch.yml 中 channels 字段；手改配置后建议重启 dsh 让 initAll 重新加载
• 二维码只在本机 Host 内生成 data URL，不经过第三方二维码服务（README.md 引用 docs/qr-login-matrix.md），但要求 Node ≥ 18 的 fetch/AbortSignal.timeout 支持

把 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。

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

🚀 快速开始

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。

📡 支持的渠道

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

✨ 核心功能

💬 IM 命令

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

✅ 远程审批

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

❓ 交互式提问

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

回答窗口由 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 步：

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 保证 106 个用例全绿
• 给仓库加 dsh-plugin 和 deepseek-harness topic 可以进 awesome 插件列表

📄 许可证

MIT © zhuiyueya

Made with 🐋 for the DeepSeek Harness ecosystem