# dsh-im

> 把九种 IM 渠道和公网 AI Office 接入 DeepSeek Harness，支持多机器人独立工作区与凭据。

## Metadata

- Author: [@xmanrui](https://github.com/xmanrui)
- Repo: <https://github.com/xmanrui/dsh-im.git>
- GitHub: [xmanrui/dsh-im](https://github.com/xmanrui/dsh-im)
- Stars: 141
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `ai-agents`, `chatbot`, `cordis`, `deepseek`, `deepseek-harness`, `dingtalk-bot`, `discord-bot`, `dsh`, `dsh-plugin`, `feishu-bot`, `im-bot`, `slack-bot`, `telegram-bot`, `wechat-bot`, `whatsapp-bot`
- Forks: 25
- Open Issues: 6
- Last push: 2026-08-20T20:24:02.000Z
- Added: 2026-08-17T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:xmanrui/dsh-im
```

## Wiki

## 一句话定位
把九种 IM 聊天工具（微信、飞书、钉钉、企业微信、QQ、Slack、Telegram、Discord、WhatsApp）和公网 AI Office 一起接到 DeepSeek Harness，让用户在不离开 IM 的同时调用 Harness 完成对话、生成与自动操作，每个渠道都能接入多个机器人并独立管理。

## 核心能力
- 把九种主流 IM（微信、飞书、钉钉、企业微信、QQ、Slack、Telegram、Discord、WhatsApp）合并到一个「IM机器人」设置入口，各渠道使用各自的扫码或凭据流程接入
- 支持同一渠道接入多个机器人，每张机器人卡片独立保存工作区、凭据、连接状态和聊天-会话映射，互不影响地查看、测试、重连或移除
- 让本机 Harness 主动连接公网 AI Office 发起反向桥接，遵循 `office-harness.v1` 协议，不需要本机公网 IP、端口转发或 WebSocket
- 为每个机器人提供 `Harness` 命令面板：`/help`、`/new`、`/status`、`/models`、`/model`、`/stop`、`/steer`、`/compact`、`/workspace`、`/workspacelist`、`/sessionlist`、`/session`，以及交互式提问和远程审批
- 按各平台能力显示流式回复与进度：飞书流式卡片、Slack 官方流式消息、企业微信原生「正在思考」、QQ/Telegram/Discord 通过编辑消息逐步呈现
- 把 JPEG、PNG、WebP、以图片文件方式发送的 GIF 一起上传 Harness 做识别，单张 5 MB、单条总 20 MB、最多 20 张

## 技术实现
- **语言**: JavaScript / TypeScript（ESM，`"type": "module"`，React 18 编写 Web UI）
- **关键依赖**: `dingtalk-stream`（钉钉 Stream 长连接）、`@tencent-connect/qqbot-nodejs`（QQ 频道）、`@wecom/aibot-node-sdk`（企业微信）、`qrcode`（扫码绑定用；`react` / `@whiskeysockets/baileys` 等为辅助依赖）
- **架构模式**: 单一 cordis 插件 `@xmanrui/dsh-im`，通过 `cordis.patch.yml` 注入 DSHCordis 运行时；同时声明 `dsh.bundle.patch`（注入 plugin 注册）与 `dsh.client.inject`（注入 `@deepseek-ai/dsh-client-connection`、`-runtime`、`-ui-settings`、`-ui-slots`、`-locale` 五个客户端包）。Host 通过 RPC 暴露在九个渠道，Client 在设置页内向 Harness 注册一个 `IM机器人` Tab
- **入口文件**: `plugin-src/host/index.mjs`（Host 编排），`plugin-src/client/index.js`（Client 设置入口）；运行时打包到 `lib/index.js` 与 `lib/client.js`，原仓库命名规则下 `src/` 是 Host 共享渠道实现（实际脚手架为 `plugin-src/host/channels`）

## 适用场景
DSH 用户希望在被 IM / Web 办公工具打断时也能随时调用 Harness：销售或客服团队把 IM 渠道接到 DSH，让同事或外部用户在熟悉的聊天窗口里就触发代码生成、文档汇总、图片识别；多账号/多项目方需要为每个机器人指定不同的工作区与 Agent Preset，在群里互不串扰；需要让公网协作平台反向调用本机 DSH，而又不愿暴露端口。用户也可以让已配置好的机器人互相对话、做自动化串联。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | >=22.19 | 来自 `package.json:engines.node` |
| DSH（cordis/connection/credentials/webServer/typertGateway/slots/locale/workspaces） | 未在 package.json 中声明 | 插件依赖上述 Host 与 Client 服务，建议沿用同作者其他插件已验证的 DSH 0.1.0-rc.6+ 体系 |
| 平台 | macOS / Windows / Linux | 由 DSH Web profile 接管；不依赖操作系统特性 |
| 原生模块 | 无 | 仅使用 IM 厂商 SDK 与 `qrcode`，无 `node-pty`、`node:sqlite` 等原生绑定 |

## 安装方式
```bash
dsh plugin --profile web add github:xmanrui/dsh-im
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `rpcAuthority` | 字符串（`loopback` 或 `trusted-host`） | IM 管理 RPC（扫码、凭据提交、机器人增删）接受的浏览器来源。`loopback` 仅本机，`trusted-host` 放宽到 Connection 已信任的局域网 | `loopback` |
| 各渠道机器人凭据 | 在 dsh 设置页中按渠道分别配置 | 例如飞书 App ID/Secret、Slack Bot Token + App Token、Telegram Bot Token、钉钉 Client ID/Secret、企业微信 Bot ID/Secret、QQ AppID/AppSecret、WhatsApp 设备扫码；token 只写入本机凭据存储 | 首次安装后均为空 |
| AI Office Base URL（实验） | https URL（loopback 允许 http） | 反向连接到的公网 Office 地址；不能带用户名密码或 query，路径会被归一化为 `/` | 未配置时 AI Office Connector 不可用 |

## 常见问题

**Q: 这个插件和其它 DSH IM 插件是什么关系？**

A: dsh-im 是一个统一的合并包，把九种 IM 渠道放到同一个「IM机器人」设置入口。从 `bin/dsh-im.mjs` 走安装命令或 GitHub 源安装时，会读取 `~/.dsh/profiles/<profile>/package.json`，把旧的 `@xmanrui/dsh-feishu`、`@xmanrui/dsh-weixin`、`@xmanrui/dsh-dingtalk` 三个独立包自动删除；旧的扫码绑定和凭据会保留下来，可以在 dsh-im 卡片里继续看到。

**Q: 一个 IM 渠道能加几个机器人？**

A: 可以加任意多，每个机器人在设置页里是一张独立卡片，凭据、连接状态、工作区、聊天-会话映射、连接测试、重连、移除都按机器人粒度生效。新机器人默认使用 Host 当时的工作目录，Preset 继承 Harness 的 `agent-presets.default`。

**Q: /model、/steer、/stop 这些命令有什么区别？**

A: `/model` 查看或切换当前会话使用的模型，可在 `/models` 输出的序号和 `Provider/模型ID` 之间二选一；`/steer <补充指令>` 把文字指令追加到当前聊天正在运行的任务；`/stop` 立即停止当前聊天发起的运行任务、保留排队的消息。三者都只影响调用它们的聊天，即便多个聊天绑定到同一个 Harness 会话。

**Q: 图片支持什么格式、大小有上限吗？**

A: 九种渠道都识别 JPEG、PNG、WebP 以及以图片文件方式发送的 GIF；单张图片上限 5 MB，单条消息内图片总大小上限 20 MB，单条消息最多 20 张。超出限制会被 `src/channels/shared/image-prompt.mjs` 拦截并向用户给出中文错误提示，不会进入 Harness。

**Q: AI Office 是什么？现在能用吗？**

A: AI Office 是让本机 Harness 主动连接公网 Office 的反向通道，按 `office-harness.v1` 协议工作：先用 `POST /api/harness/connector/heartbeat` 握手，再用 `GET /api/harness/connector/stream` 接收 SSE 下行任务，租约 90 秒，每 30 秒续租。当前在设置页左侧 Tab 中标注为「实验功能」，需要先在公网 Office 拿到 Base URL 和 Device Token 才能启用。

**Q: 为什么从外网/局域网访问不到管理页面？**

A: 这是有意为之。`plugin-src/host/rpc-authority.mjs` 默认把 IM 管理 RPC 锁定到 `loopback`，避免扫码链接、凭据提交、机器人增删等敏感操作被外网调用。如果确实要把 dsh web 暴露到受信局域网内，可以在 profile 的 `cordis.patch.yml` 里写 `config: { rpcAuthority: trusted-host }`；该模式只是复用 Connection 已信任的 Host authority，并不是用户认证。

**Q: 如何完全卸载？**

A: 运行 `dsh plugin --profile web remove @xmanrui/dsh-im`，或在插件包安装目录下用 `npx -y github:xmanrui/dsh-im uninstall`。之后重启 `dsh web`，设置页里的「IM机器人」入口会被移除，已保存的 Secret 和 Device Token 仍由本机凭据存储保管。

**Q: 机器人的命令谁都可以执行吗？**

A: 是的。任何在对应平台可见范围里、能给机器人发消息的用户都能触发 `/session`、`/workspace` 等命令，从而把后续消息写到被绑定会话里、调用其可用工具。所以上线机器人前要确认可见用户是可信的；Telegram 安全模式可叠加白名单，群聊命令在该模式下会被无视。

## 上手难度
入门 — 安装一步完成，设置页有九个渠道的完整中文/英文引导，多数渠道支持扫码零配置；但每个渠道的凭据来源需要用户在对应 IM 平台开发者后台单独申请，所以首次接入时长取决于读者熟悉 IM 平台的程度。

## 已知问题与限制
- AI Office Connector 当前在设置页 Tab 上明确标注为「实验功能」（`plugin-src/client/index.js:61`），协议版本 `office-harness.v1` 仍可能演进
- `workspace-command.mjs`、`compact-command.mjs` 中保留了「当前机器人暂不支持列出工作区 / 切换工作区 / 上下文压缩」的回退分支，意味着某些渠道的 `/workspace`、`/workspacelist`、`/sessionlist`、`/compact` 命令会直接提示用户该功能暂不支持
- IM 管理 RPC 默认仅 `loopback`；如要在受信局域网打开管理页，必须在 profile 的 `cordis.patch.yml` 中显式设置 `rpcAuthority: trusted-host`（`plugin-src/host/rpc-authority.mjs:7-11`）；该模式只复用 Host/Origin 防护，不是用户认证
- WhatsApp 通过 WhatsApp Web 长连接保持登录，手机端掉线或服务端主动断开会让机器人进入「离线」状态，需要重新扫码关联设备
- 切换工作区只会清理本机器人旧聊天-会话映射，不会删除、清空或归档任何旧 Session；跨工作区绑定时则会一并清除该机器人所有聊天的旧映射，开放机器人前请评估可见用户是否可信
- Plugin ID 含在 plugin ID 中的关键字限制：`rpcAuthority` 仅接受 `loopback` 或 `trusted-host`，写入其它值会在 Host 启动时抛 `TypeError`
- DSH（DeepSeek Harness）版本要求未在 `package.json` 中声明，需结合宿主版本实际验证；插件使用了 `ctx.typertGateway`、`ctx.workspaces`、`ctx.slots` 等较新的注入点

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-im](https://deepseek-plugin.org/plugins/xmanrui/dsh-im)
Wiki generated by AI (model: `MiniMax-M3`)