IM 对话桥 eighteentang/dsh-plugin-im-bridge

dsh-plugin-im-bridge

把 IM 机器人接成 DSH 的对话入口：手机上给机器人发消息，电脑上的智能体干活。

DSH 是一个编码智能体，能读写文件、执行命令、跑长任务。
这个插件让它在手机上有个「嘴」和「耳朵」—— 出门在外也能给它派活。

你的手机 你的电脑 ┌──────────────┐ ┌───────────────────────────────┐ │ 给机器人 │ 平台服务器 │ DSH 客户端 │ │ 发一条消息 │ ──────────▶ │ └─ 本插件 │ │ │ │ └─ 专用会话（有全套工具） │ │ 收到回答 │ ◀────────── │ 改文件 / 跑命令 /… │ └──────────────┘ └───────────────────────────────┘

零、现在支持哪些平台

| 平台 | 状态 | 怎么连 |
| QQ | ✅ 完整可用 | 收发 + 智能体。要自己申请一个 QQ 机器人（见下） |
| 微信 | ✅ 完整可用 | 收发 + 智能体。走官方 iLink / ClawBot 通道，扫码即可，不用申请凭据 |
| 企业微信 | ⚠️ 只能收 | 官方长连接已接；回复帧格式官方未公开，发不回去 |
| 飞书 | ⚠️ 只能收 | 入站已接；出站未实现，且要另装约 30 MB 的官方 SDK |
| 钉钉 | ⚠️ 只能收 | 入站已接；出站未实现（Stream 通道本身不能回复） |

设置页里每个平台都如实标注完成度 —— 没做完的不会假装能用。

内核与平台无关，只有传输层是各平台专属的

共用内核：队列 / 专用会话 / 会话面板 / 权限预设 / 回复分派 ↑ 这些一份代码，所有平台都用传输层 ：QQ（WebSocket 长连接）/ 微信（HTTP 长轮询）/ …各自一份

所以新接一个平台＝只写它的传输层，内核不用动（企微/飞书/钉钉的入站就是这么接上的）。

一、能做什么

| 场景 | 说明 |
| 远程派活 | 在手机上让电脑上的智能体干活，回到电脑看结果 |
| 随手查 | 让它读某个文件、列目录、搜代码，结果直接回到手机上 |
| 长任务 | 发起一件事然后走开，回来在 DSH 里看完整过程 |
| 双向对话 | 不只是「发指令」—— 它会回话、会追问、会报告进度 |
| 发图 / 语音 / 文件 | 手机上发一张截图或文件 ✱，它会存在电脑桌面上并把路径交给智能体 —— 智能体能直接读那张图 |

✱ 当前平台覆盖：QQ 支持图文 / 语音 / 文件的收发；微信支持收（图片解密、语音取自带转写），出站待做。
附件落在 <你的桌面>/im-bridge-media/<平台>/<日期>/，文件名会做清洗。

每个平台各有一条独立的专用会话（QQ 和微信互不干扰），也和你电脑上正在进行的会话互不干扰。

二、开始之前：准备凭据

两条路，选一条就行：

路线 A：微信（最省事，不用申请任何东西）

只要手机微信是 8.0.70 或更高，并且「我 → 设置 → 插件」里能看到 「微信 ClawBot」。连的时候会出现一个二维码，扫码即可。

这条路的凭据（bot_token）存在本机，重启客户端不用重扫。

路线 B：QQ（要自己申请，约 15 分钟）

这一步只能你自己做（要实名、要用你自己的 QQ 号）。

1. 注册并创建机器人

去 https://q.qq.com → 登录 → 创建机器人应用。

⚠ 需要实名认证。个人开发者可以创建，但要走审核。

2. 拿到 AppID 和 AppSecret

创建完成后，进机器人后台 → 「开发设置」 页面，里面有：

AppID —— 一串数字，例如 1903121969 AppSecret —— 一串字母数字，不要外传

AppSecret 等于你机器人的密码。 泄露了别人就能用你的机器人。
本插件把凭据存在本机（~/.dsh/.credentials.yaml），不会上传到任何地方。

3. 把你自己加进沙箱白名单（⚠️ 最容易漏、漏了会静默失败）

在机器人后台 → 「沙箱配置」 → 找到 「消息列表单聊」 → 把你的 QQ 号加进去。

不加会怎样：机器人收不到任何消息，而且不报错 ——你会以为插件坏了，其实消息根本没到。这是最常见的「装好了但没反应」。

4. 想上正式环境？多半不行（要知道为什么）

插件默认走沙箱环境，原因很实际：

| | 沙箱 | 正式 |
| 网关 | sandbox.api.sgroup.qq.com | api.bot.qq.com |
| 限制 | 只有白名单里的 QQ 号能用 | 要配置 IP 白名单 |
| 家用宽带 | ✅ 能用 | ❌ 没有固定公网 IP，过不去 |

所以家用宽带就用沙箱 —— 你自己用完全够。要上线给很多人用，得有固定公网 IP 的服务器。

三、安装插件

前提

已经装好 DSH 并能正常对话（能登录、能发消息）。

方式一：在 DSH 界面里装（推荐，不用命令行）

1. 打开 DSH 侧边栏的 插件 页
2. 点 「添加插件」
3. 在「包名或地址」里填这个插件的 GitHub 地址：

github:eighteentang/dsh-plugin-im-bridge#v1.2.7

4. 确认安装，然后重启 DSH 客户端

⚠ 必须填完整地址，不能只填 dsh-plugin-im-bridge。
那个输入框的引导会提示「填插件包名」—— 但这个插件没有发布到 npm，只发在 GitHub 上。只填包名会被拒（找不到该包）。

界面原文是「输入插件的包名、GitHub 仓库地址或本地目录路径」——我们属于第二种。
⚠ GitHub 地址不经过 npm 安装源（这是 DSH 界面自己的提示）：「GitHub 地址和 .tgz 直链不经过安装源，需要本机能直接访问它或配置代理」。
所以如果卡住/超时，先确认这台机器能访问 github.com（或已配代理）。

如果你所在网络访问 GitHub 困难，就只能先用下面的命令行方式配好代理再装。

方式二：命令行安装（等价，适合脚本/远程）

DSH 自带插件管理命令：

dsh plugin --profile <你的profile名> add github:eighteentang/dsh-plugin-im-bridge#v1.2.7

--profile 的名字：填你自己的 profile 名 —— 看 ~/.dsh/profiles/ 下的目录名就是它。

⚠ web 是 DSH 随附的模板名，不必然是你的 profile 名。
用 dsh --profile <名字> --from-default-profile <模板> 新建过的 profile 会是别的名字（例如 desktop）。写错名字 = 装到另一个 profile，当前客户端看不到。

验证装上了

重启后（两种方式都要重启）DSH 客户端里应该出现：

· 设置 → 连接 IM ← 配置凭据的地方
· 侧边栏一个企鹅图标 ← 点开是 QQ 会话面板

看不到？ 检查三件事：

1. 插件装到了正确的 profile（命令行：dsh plugin --profile <名字> list）
2. 客户端真的重启了 —— 只禁用再启用不够，Node 的模块缓存会让它继续用旧代码
3. 界面装的：那一步是否真的提示成功（失败时界面会显示原因）

关于版本

上面两种方式都推荐带 #v1.2.7 —— 不写标签装的是 main 的最新提交，上游随时可能变。

装某个具体版本（把 v1.2.4 换成你要的） github:eighteentang/dsh-plugin-im-bridge#v1.2.7

看有哪些版本可选 https://github.com/eighteentang/dsh-plugin-im-bridge/tags

⚠ DSH 界面里装的插件暂不支持自动更新（界面原文）：「插件安装后，暂不支持自动更新。若需升级，请先卸载再安装新版」。
所以升级要手动重来一次 —— 换成新的 #vX.Y.Z 重装。

⚠️ 版本注意（微信用户）

请用 v1.2.2 或更新。
v1.2.1 及更早的版本发微信回复时缺一个 client_id 字段 ——表现是：日志显示发送成功（HTTP 200），但微信里只有第一条消息出现，之后每条都收不到。v1.2.2 修的就是这个。

每个版本改了什么：见 CHANGELOG.md。

升级

dsh plugin --profile <你的profile名> add github:eighteentang/dsh-plugin-im-bridge#v1.2.7 # 换成的版本号

然后重启客户端。

升级不会丢凭据。 插件在启动时会自动把旧键名的凭据迁移到新键名（credential-migrated 那条日志就是它干的）。

但升级可能会丢会话历史 —— 如果新版本换了内部会话 id 前缀。
那种情况 CHANGELOG.md 里会写明。会话历史丢了不影响功能，只是 QQ 那条线的上下文从头开始。

我装的是哪个版本？

看 profile 里那份 package.json 的 dsh-plugin-im-bridge 字段：

装了标签版 → 显示 github:eighteentang/dsh-plugin-im-bridge#v1.2.7 装了浮动版 → 显示 github:eighteentang/dsh-plugin-im-bridge
cat ~/.dsh/profiles/<profile名>/package.json

四、填凭据并连接

打开 设置 → 连接 IM，每个平台一行：开关、完成度、连接状态、凭据都在那一行里。
点「配置/测试」展开，填凭据，再点「保存并测试连接」。

凭据保存在哪：本机 ~/.dsh/.credentials.yaml，记录名 im-bridge/bot。

设置页不会回显 AppSecret —— 这是有意的，它是密钥不是普通配置。
配好之后那页会显示「凭据已保存 · AppID 尾号 XXXX」，点「重新设置」才能改。

连接状态怎么看

设置页顶部和侧边栏面板都会显示状态。也可以直接查本机的状态接口：

curl http://127.0.0.1:8799/im-bridge/status

返回 "connected": true 和 "bot": "你的机器人名" 就对了。

接口只监听回环地址（127.0.0.1） —— 外面的机器访问不到。

五、试第一条消息

QQ：用你在第二章加进白名单的那个 QQ 号，给机器人发一条。
微信：直接在微信里给「微信 ClawBot」发一条。

帮我看看 D 盘有哪些文件

正常的话：它会真的去列目录，然后把结果回到你手机上。

没反应？ 按这个顺序查：

| 症状 | 最可能的原因 |
| 完全没回复（QQ） | ① 你的 QQ 号没加进沙箱白名单（第二章路线 B 第 3 点）；② 设置页显示未连接 → 凭据错 |
| 完全没回复（微信） | 设置页那行是否显示「已连接」；且插件版本必须 ≥ v1.2.2 —— 更早的版本发微信回复缺一个字段，只有第一条能显示 |
| 回复"我没有工具" | 会话的工具没挂上 —— 看下面的「已知问题」 |
| 回复"没有 API key" | 模型路由没配对 —— 看下面的「模型配置」 |
| 回了一句就卡住 | 上一轮还在处理；等一会儿或再发一条 |

五·二、发图片 / 语音 / 文件

直接在聊天里发就行，不用打任何命令。

附件会落在你的桌面：

<桌面>/im-bridge-media/<平台>/<日期>/<文件名> 例如 C:\Users\你\Desktop\im-bridge-media\weixin\2026-10-13\照片.jpg

插件把本地路径拼进给智能体的消息里，所以你可以直接说：

看看我刚发的那张图，告诉我上面写的什么

智能体会自己去读那个文件（它有 read_image 等工具）。

| 平台 | 收（你发给机器人） | 发（机器人回给你） |
| QQ | ✅ 图文 / 语音 / 文件 | ✅ 图文 / 语音 / 文件（单文件 ≤ 5 MB）|
| 微信 | ✅ 图片（自动解密）/ 语音（取自带转写）| ⏳ 出站待做 |

几个已知边界（如实说）：

- QQ 单文件上限 5 MB —— 超过会明确报错，不会硬传一个被截断的文件。
分片上传还没做。
- 微信语音不下载音频，只取微信自带的转写文字（本机没有 ffmpeg，silk 转不了码）。
- 文件名会被清洗（剥掉路径分隔符与 Windows 非法字符）——附件名是对方给的，不能直接信。
- 图片解密失败不静默：会在旁边留一份密文原件并记事件，方便事后查。

想换落地目录？目前写死在桌面。改的话在 media.js 的 mediaDirFor。
（为什么不做成配置项：还没有"要换"的真实需求，多一个口子就多一处要维护。）

六、模型配置（可能需要你改）

插件让各平台的专用会话用你 DSH 里设置的默认模型。但有个坑：

DSH 内置的默认是 deepseek-official（需要 DEEPSEEK_API_KEY）。
如果你是用账号登录（没有 API key），插件会回退到 deepseek-account，这通常是对的。

如果机器人回"no API key for provider route"，就在插件的配置里显式指定：

profile 的 cordis.patch.yml 里，im-bridge 那一行
- id: im-bridge
name: dsh-plugin-im-bridge
config:
agentProvider: deepseek-account
agentModel: deepseek-flash

| 配置项 | 说明 |
| agentProvider | 模型服务商。账号登录用 deepseek-account |
| agentModel | 模型 id，例如 deepseek-flash |
| agentReasoningEffort | 思考强度，例如 high / max |
| workspace | 各平台专用会话的工作目录（默认 DSH 的工作目录） |
| sandbox | 是否连 QQ 沙箱环境（默认 true；只管 QQ） |
| permissionPreset | 专用会话的权限预设（默认 danger-full-access） |
| agentSessionId | 覆盖 QQ 的专用会话 id（默认留空 = 用内置值）|

什么时候要改 agentSessionId

模型会把历史里关于自身能力的错误结论继承下去 —— 那种情况下改代码没用， 得换一个全新会话（换上下文）让修好的能力真正生效。

⚠ 但绝不要改内置默认值那个思路：默认值是所有用户共享的，改掉它等于让每个装这个插件的人一起换会话、丢历史。正确做法是在自己的 profile patch 里设：

- id: im-bridge
config:
agentSessionId: "im-bridge-dedicated-v2"

换 id 是非破坏性的：旧会话数据仍完整留在 ~/.dsh/sessions/.../im-bridge-dedicated-v1/，只是不再被 resume。想回去，把那一行删掉即可。代价是新会话读不到旧对话历史。

⚠ 必须重启客户端才生效（插件代码不热加载）。

七、安全：这个插件权限很大，务必读完

⚠️ 它把电脑的操作能力交给了"能给机器人发消息的人"

装好之后，能私聊你这个机器人的人，就能在你的电脑上执行命令。

默认配置是 permissionPreset: danger-full-access（无需审批）——因为专用会话是无人值守的：审批框弹在电脑桌面上，你在手机上根本看不到，如果要用"每次审批"，机器人会直接卡死。

所以你必须做一件事：去 QQ 开放平台确认谁能私聊这个机器人。
如果是公开可加的，任何找到它的人都能操作你的电脑。

收紧权限的办法

- id: im-bridge
name: dsh-plugin-im-bridge
config:
只能读，不能改 permissionPreset: read-only

可能的取值：read-only / workspace-write / danger-full-access。

注意：workspace-write 在部分机器上沙箱初始化会失败（SetNamedSecurityInfoW failed (Win32 5)），导致所有命令都跑不起来。
如果遇到，用 danger-full-access 或 read-only。

凭据安全

- AppSecret 不要贴到任何聊天里（包括给 AI 看的对话）
- 泄露了就去对应平台的开发者后台重置（QQ 是 AppSecret；微信是重新扫码换 token）
- 凭据只存在本机 ~/.dsh/.credentials.yaml

八、它是怎么工作的

理解这个能帮你排查问题。

QQ 开放平台 │ WebSocket 长连接（插件主动连出去，不需要公网 IP） ▼ im-bridge（Host 插件，跑在 DSH 进程里） │ ① 收到消息 → 排队（避免两条消息合并成一个回合） │ ② 交给一个专用会话处理 ▼ 专用会话（智能体，带全套工具：读写文件 / 执行命令 / 搜索 /…）
│ ③ 干完活 ▼ im-bridge → 回手机（各平台各自的回复通道）

几个设计点（都是踩坑踩出来的）：

| 设计 | 为什么 |
| 消息排队 | 智能体会把收件箱里的消息合并处理 —— 两条消息只回一个。排队保证「一条消息一个回答」 |
| 每个平台一条专用会话 | 各平台的线互相独立，也独立于你在 GUI 里用的会话。以 origin: subagent 创建，不出现在会话列表里 |
| 看门狗 | 上一轮如果卡住（超过 45 秒），自动解封并把排队消息放出去 —— 否则会永久卡死 |
| 被动→主动回复回退 | QQ 的被动回复有 msg_id 限制，失效时自动改用主动推送（微信则是每条消息带 context_token 回复） |
| 凭据自动迁移 | 插件改过包名/凭据键名；升级时会自动把旧凭据搬过来，你不用重填 |

状态日志：~/.dsh/im-bridge-status.log（JSON 行格式，排查问题的第一手材料）

九、卸载

dsh plugin --profile <你的profile名> remove dsh-plugin-im-bridge

已知问题：卸载后 ~/.dsh/profiles/<名字>/node_modules/ 下可能残留一个名叫 dsh-plugin-im-bridge 的死链接（junction）。
不影响使用（插件的加载清单已经清干净了），但可以手动删掉。

十、已知问题

| 问题 | 状态 |
| 用 select 绑 preset 会让 resume 后的会话丢掉几乎全部工具（能回话但干不了活） | 已修（改用 mount） |
| workspace-write 沙箱在部分机器上初始化失败，所有命令报 grantWrite Win32 5 | 规避：用 danger-full-access 或 read-only |
| 卸载后 junction 残留 | 已知，不影响使用 |
| 需要人工审批的权限预设会让专用会话卡死（审批框在电脑上，手机看不到） | 默认已避开（用 danger-full-access） |
| 会话历史被「模型自己的错误结论」污染后，改代码也没用，得换会话 id | 已修（换代会话 id） |

十一、许可与版本

MIT —— 见 LICENSE。

当前版本：见 CHANGELOG.md 最上面那条。
钉版本 / 升级：见上面的「钉住版本（推荐）」一节。

这个插件不是 DeepSeek 官方项目，是第三方插件。
各平台的接口用法来自腾讯 / 飞书 / 钉钉的公开文档。