dsh-im

一句话定位

把九种 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，而又不愿暴露端口。用户也可以让已配置好的机器人互相对话、做自动化串联。

前置依赖与兼容性

安装方式

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

配置项

常见问题

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 等较新的注入点

  

---

---

简介

通过扫码、App Manifest 或已有机器人凭据把 IM 机器人接入 DeepSeek Harness，并让本机 Harness 主动连接公网 AI Office。一个插件、一个设置入口，统一管理九种 IM 渠道和 AI Office Connector。每个 IM 渠道都支持接入多个机器人，各机器人的连接状态、工作区和会话绑定彼此独立。

Connect IM bots to DeepSeek Harness by scanning a QR code, using an App Manifest, or entering existing bot credentials, and let the local Harness connect outward to a public AI Office. One plugin and one settings entry manage nine multi-bot IM channels and the AI Office Connector.

界面

当前内置渠道

其他 IM 平台可继续按同一渠道适配器结构接入。

九个内置渠道均支持把 JPEG、PNG、WebP 图片，以及以图片文件方式发送的 GIF，连同可选文字说明发送给 Harness；单张图片上限为 5 MB，单条消息中的图片总大小上限为 20 MB。

AI Office Connector

「AI Office」页让本机 Harness 主动连接公网 Office，本机无需公网 IP、端口转发或 WebSocket 服务。Device Token 只写入 Harness 凭据存储；普通配置文件仅保存设备 ID、Office Origin、工作区 alias 和 Instruction Preset alias。Office 只能选择 alias，不会收到本机绝对路径。

当前协议版本为 office-harness.v1。连接器使用 POST /api/harness/connector/heartbeat 完成鉴权和能力握手，再以 GET /api/harness/connector/stream 建立 SSE 下行；设置页会从 Office Base URL 自动展示全部固定 Hook，并在断线后按退避策略自动重连。

Office 的 job.available 会触发本机拉取任务、校验 Workspace/Preset alias、领取 90 秒租约并每 30 秒续租。连接器创建独立 Harness Session，把状态、工具名和增量文字安全回传 Office，终态只允许写入一次。Harness 发起的工具审批或补充问题会进入 Office 人工面板；批准、拒绝或文字答案再经 SSE 回到原 Session，断线时由租约与 Heartbeat 恢复。

Heartbeat 成功响应必须是 JSON：{"ok":true,"protocolVersion":"office-harness.v1"}。这使「连接测试通过」代表命中了兼容的 Office Connector，而不只是某个碰巧返回 200 的网址。

安装

推荐从 npm 安装已发布的稳定版本：

dsh plugin --profile web add -w @xmanrui/dsh-im

重启 dsh web，然后打开「设置 → 插件 → IM机器人」。

如需试用尚未发布到 npm 的最新代码，可以改用 GitHub 源安装器：

npx -y github:xmanrui/dsh-im install

GitHub 源安装会直接拉取并构建 Git 依赖；pnpm 10 及以上版本可能要求先在 profile 的 pnpm-workspace.yaml 中允许该依赖执行构建脚本。普通用户建议优先使用 npm 稳定版。

安装后，在对应渠道页面按照内置引导完成扫码或凭据配置。所有 Secret 和 Token 只提交给本机 Harness Host，并写入受保护的凭据存储；状态接口和机器人列表不会回传这些凭据。

每个 Telegram 机器人都可以在自己的卡片中切换访问模式。旧机器人和新接入机器人均默认使用兼容模式：私聊直接响应，群聊仅在提及机器人或回复机器人消息时响应。只有主动切换到**安全模式（私聊白名单）**后，机器人才会忽略全部群聊，并只接受该机器人白名单中的数字 User ID。白名单每行一个 ID、按机器人独立保存；切回兼容模式时会保留但不使用，再切回安全模式即可继续使用。安全模式的空白名单会拒绝该机器人的所有入站消息。

机器人命令

示例：先发送 /models，再发送 /model 2 切换到列表中的第 2 个模型。其他命令示例：/help、/new、/status、/model deepseek-official/deepseek-v4-pro、/steer 只检查配置文件、/stop、/compact、/workspace /Users/alice/projects/my-app、/sessionlist 2、/sessionlist /Users/alice/projects/my-app 或 /session session-id

命令说明

• /help 不需要参数，也不会创建会话；它会返回当前机器人支持的完整命令列表。
• /status 不需要参数，也不会向模型发送消息或改变会话绑定；它用于确认当前机器人能够连接 DeepSeek Harness。
• /new 只解除当前聊天在 dsh-im 中保存的会话绑定，不会删除、清空或归档旧 Session。下一条普通消息会在当前工作区创建并绑定一个新 Session。任务正在运行或等待问题、审批时，应先完成交互或使用 /stop，再使用 /new。
• /models 不需要参数，也不会创建会话。它为 Harness 当前配置的全部可用模型分配序号，同时显示可稳定复制的 Provider/模型ID；某个 Provider 查询失败时，其他 Provider 的结果仍会显示。
• /model 不带参数时只查看当前会话模型；带参数时接受 /models 列出的序号或完整模型 ID，例如 /model 2。完整 ID 必须精确匹配。聊天尚无会话时，有效的切换命令会创建并绑定一个空白会话，但不会触发模型回复。切换只影响当前会话；Harness 还会尝试把它保存为以后新会话的默认模型，已有其他会话不受影响。
• 正在运行任务或等待审批、问题回答时不能切换模型；请等待完成，或先使用 /stop。含图片的会话无法切换到不支持图片输入的模型。
• /stop 和 /steer 只控制当前聊天自己发起的运行任务，即使多个聊天绑定同一个 Session，也不会有意控制其他聊天的任务。/stop 不删除会话或历史，并保留尚未开始的排队消息；重复发送是安全的。
• /steer 只接受文字，可包含多行；它不会创建新会话或第二个任务。没有运行任务时请直接发送普通消息；等待审批或问题回答时请先处理交互，或使用 /stop。
• /compact 只作用于当前聊天已经绑定的 Harness 会话，不会把命令发送给模型。当前聊天尚未创建会话、会话正在生成回复或没有可压缩历史时，机器人会直接返回对应状态。
• 只接受已经存在的绝对目录；路径无效时机器人会返回具体提示和正确用法。
• /workspacelist 不需要参数。它合并 Harness 全局登记项与当前机器人的路径；当前路径仍存在且可安全显示时会排在首位并标记为“当前”。结果可直接复制到 /workspace 命令。
• /sessionlist 的数字参数按命令执行时与 /workspacelist 相同的最新顺序解析；也可使用绝对路径直接指定工作区。结果会回显最终选中的路径。
• /sessionlist 会列出该工作区登记的所有会话。已归档会话会标记为“已归档”；空白会话和子代理会话在它们归属该工作区时也会列出；没有标题的会话显示为“暂无标题”。结果中的 ID 可直接用于 /session Session ID。
• /session 只接受一个由 /sessionlist 获得的 Session ID。它不会新建会话或立即向模型发送消息；绑定成功后，当前聊天的后续消息会继续该会话。普通归档会话可以绑定但不会自动取消归档，子代理会话不能绑定。
• /session 会自动定位会话唯一所属的工作区。同工作区绑定只替换当前聊天的映射；跨工作区绑定会切换该机器人的工作区、清除该机器人所有聊天的旧会话映射，再绑定当前聊天，因此会影响该机器人的其他聊天。已经开始生成的回复仍可完成。
• 工作区切换和会话绑定只会清除或替换 dsh-im 的聊天映射，不会删除、清空或归档任何旧 Session 内容；旧 Session 仍可再次列出和绑定。
• 任何已在对应平台可见范围内、能够正常向机器人发消息的用户都可以执行这些命令，不区分管理员和普通用户。Telegram 兼容模式遵循原有私聊及群聊提及/回复规则；安全模式只允许当前机器人白名单中的私聊用户执行，群聊命令始终忽略。
• 工作区列表来自 Harness Host 的全局登记信息，可能包含其他机器人、其他渠道或非 IM 项目的本机绝对路径。请将机器人可见范围限制给可信用户。
• 会话列表同样来自该全局 Harness Host；会话 ID 和标题可能属于其他机器人、其他渠道或非 IM 项目，并可能包含敏感元数据。开放命令前请确保所有可见用户都可信。
• 任何能执行 /session 的用户都能接续所选会话，并通过后续消息写入会话或触发其可用工具。请只向可信用户开放机器人及其会话列表。
• 切换成功后只清除当前机器人的旧 Harness 会话映射，不影响其他机器人。
• 新工作区对后续消息生效；已经开始生成的回复会继续完成。

其它功能

• 图片识别：九个内置渠道都可以把 JPEG、PNG、WebP，以及以图片文件方式发送的 GIF 交给 Harness；图片可以附带文字说明。单张图片上限为 5 MB，单条消息中的图片总大小上限为 20 MB。
• 在机器人卡片切换工作区：设置页中的每张机器人卡片都会显示当前 Harness 工作区。可以直接填写已有目录的绝对路径，也可以打开目录选择器。切换只清除该机器人的旧聊天映射，不会删除、清空或归档旧 Session；已经开始的回复可以继续完成，后续消息使用新工作区。
• 检查连接并发送测试消息：机器人在线时，点击卡片上的「检查连接」会检查平台连接，并向该机器人最近记录的私聊发送一条“DeepSeek Harness 连接测试成功”消息；WhatsApp 会发送到账号自聊。测试消息不会创建 Harness Session，也不会调用模型。机器人必须至少收到过一条私聊才能记住测试目标，否则页面会提示尚无可用的测试会话。
• 重试连接和移除接入：机器人离线时，卡片上的操作会变为「重试连接」；不再使用时可以点击「移除接入」。这些操作都只作用于所选机器人，不影响其他机器人或渠道。
• 多机器人独立管理：同一渠道可以接入多个机器人。每个机器人分别保存凭据、连接状态、工作区和聊天会话映射，卡片上的工作区、连接检查、重试和移除操作互不影响。
• 流式回复和进度提示：插件会按各平台能力显示正在思考、工具执行和逐步生成的回答；不支持原生流式接口的平台会通过编辑消息、卡片更新或最终消息完成回复。

设计

• Harness 中只注册一个「IM机器人」设置页，其中包含九个 IM 渠道和一个 AI Office Connector；
• 九个渠道及 Office Connector 的 Host、客户端与运行时源码都在本仓库维护，不依赖外部独立插件；
• 设置页跟随 DeepSeek Harness 的语言选择，在中文和 English 之间即时切换；
• 左侧使用 Logo 切换微信、飞书、钉钉、企业微信、QQ、Slack、Telegram、Discord、WhatsApp 和 AI Office，不使用启用/停用开关；
• 九个 IM 渠道保持独立的 RPC、凭据、连接监督和会话映射；Office Connector 另行维护设备凭据、Job 租约、审批等待与并发上限；
• 浏览器只获得二维码、Manifest、脱敏状态，以及用户为当前 Telegram 机器人主动保存的访问模式和白名单 User ID；手动输入的 Secret 或 Token 仅单向提交给本机 Host，任何 RPC 响应都不会返回 App Secret、bot_token、钉钉 client_secret、企业微信 Secret、QQ app_secret、Slack Bot/App Token、Telegram/Discord Bot Token、WhatsApp 关联设备密钥、AI Office Device Token，或从平台消息中观察到的其他原始用户标识。

本地开发

npm install
npm run check
node bin/dsh-im.mjs install --source .

npm run check 运行单元测试、构建 Host/Client 产物，并验证发布包不包含凭据或独立渠道设置页注册。

IM 管理 RPC 默认仅接受回环浏览器。如果 Web profile 在受信任的局域网内对外提供服务，可在该 profile 的 cordis.patch.yml 中显式开放给 Connection 已信任的 Host authority：

- id: xmanrui-dsh-im
  config:
    rpcAuthority: trusted-host

trusted-host 只复用 Harness 的 Host／Origin 防护，不是用户认证。启用后，能访问该局域网地址的人也能查看机器人状态、扫码或提交应用凭据、重连和删除机器人；只应在可信网络中使用。

---

联系方式

欢迎通过邮箱、微信或小红书联系我。