dsh-im-bridge
Verifieddsh-im-bridge · v0.4.0 · MIT · Web UI
IM bridge for DeepSeek Harness: chat with and drive DSH sessions from Discord, QQ and WeChat, with a settings page in DSH Web
Install
dsh plugin add dsh-im-bridge Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-im-bridge
在 IM 里像用 DSH Web 界面一样和 DSH 会话对话、指挥它干活。支持 Discord、QQ 官方机器人、个人微信(腾讯 iLink)。核心层与渠道无关:每个渠道声明自己的能力(能否编辑消息、有没有按钮、回复是否需要令牌……),核心按能力选择渲染方式,做不到的都有纯文本兜底。设计见 docs/design.md。
插件运行在 DSH Host 进程内,调用与 Web 界面相同的 Host API:从 IM 新建的会话就是普通会话,Web 侧边栏实时可见,两边可以同时操作。插件只发起出站连接,不另开端口;设置页用到的接口挂在 DSH 自己的 Web 服务下(/im-bridge/api/*),沿用 DSH 的登录校验。
功能
| 会话 | 私信 = 一个会话;Discord 服务器频道里 @机器人 自动开线程作为新会话,线程内不用 @;会话标题生成后线程自动改名;/sessions /attach 接入 Web 上已有的会话,接入时回放最近几轮 |
| 回复 | 能编辑的渠道(Discord)边生成边编辑,带 ▉ 光标,满长度自动续写下一条,代码块不会被切断;不能编辑的渠道写完再发,QQ 私聊用流式消息边生成边显示 |
| 进度 | 一条进度消息原地更新:运行状态、已用时、最近的工具调用(⏳/✅/❌);不能编辑的渠道在回复末尾附工具摘要 |
| 排队 | 任务运行中发的消息先排队(和 Web 一样),回执上有「立即插话」「撤回」按钮(无按钮渠道回复序号) |
| 审批 | 工具审批卡片「允许一次 / 拒绝」,与 Web 同时出现,谁先答算谁的,另一边自动收起;无按钮渠道回复「批准 / 拒绝」 |
| 提问 | 模型提问(ask_user_question)逐题出卡片:单选按钮、多选下拉、「其他…」弹出输入框、跳过;也可以直接打字回答;计划审阅的批准按钮为绿色;限时提问超时后仍可补答 |
| 模型 | /model 两级选择(提供商 → 模型 → 思考档位),/reasoning 切思考档位;与 Web 共用模型目录,切换会同时设为 DSH 默认模型 |
| 会话工具 | /history /title /compact /preset(Agent 预设,第一轮前) /permission(权限预设) /status |
| 附件 | 图片直接交给模型;其他文件经 DSH 文件上传交给 agent;只从各渠道自己的 CDN 下载,禁止重定向,按实际字节数限制大小 |
| Web 镜像 | 在 Web 里给已绑定会话发的消息会同步一条到 IM |
| 后台会话 | 切到别的会话后,原会话回复完成或等待审批 / 提问时发「📬」提示,带「切回去」按钮;当前会话正在回复时先攒着,回复结束后合并发送(最多等 3 分钟,审批 / 提问 1 分钟);切回后补发审批 / 提问卡片 |
| 可靠性 | 最终回复先记账再发送,失败按 30 秒 / 2 分钟退避重试,重启后补发(可能重复的会标注);桥接重启时仍在跑的任务继续显示,期间结束的任务补发结果;断线重连后补收漏掉的消息;编辑连续被限流时自动改为写完再发 |
| 设置页 | DSH Web「设置 → IM 桥接」:三个渠道的状态、凭据、白名单、微信扫码、配对审批、通用选项,保存即生效 |
| 权限 | 默认拒绝:只有 allowUsers 里的用户能用;Discord 可限制服务器、频道;管理员与普通用户命令分级;只有发起人(或管理员)能回答审批和提问;可选配对码授权 |
| 完成提示语音 | 娱乐功能,默认关闭:任务正常完成后再补发一条你上传的语音(如「领导,您交代的任务已经完成了」);目前仅 QQ,见下文 |
命令
所有渠道都支持文本命令(!new …,前缀可配置);Discord 另有斜杠菜单和自动补全,回复仅自己可见。
| 命令 | 作用 |
|---|---|
/new [prompt] [workspace] |
新建会话 |
/sessions [workspace]、/attach <会话>、/detach |
列出、接入、解绑会话 |
/ws、/use <工作区> |
列出、选择新会话使用的工作区 |
/model [模型] [档位]、/reasoning [档位] |
切换模型、思考档位 |
/stop、/steer <内容> |
停止当前任务(排队的保留)、运行中插话 |
/history [轮数]、/title [标题]、/compact |
最近几轮、标题、压缩上下文 |
/preset [预设]、/permission [预设] |
Agent 预设、权限预设 |
/status、/whoami、/help |
状态、身份、帮助 |
/pair approve <码> / list / revoke <用户> |
配对管理(管理员,需开启 pairing) |
安装
在线安装(npm)
DSH Web →「插件」→「添加插件」,输入 dsh-im-bridge,安装并启用;然后打开「设置」→「IM 桥接」完成配置(见下)。
命令行:dsh plugin --profile <profile> add dsh-im-bridge
离线安装包
插件打包成一个 .tgz 文件,所有依赖都已打包在内,安装时不需要联网下载。
- 把
dsh-im-bridge-<版本>.tgz复制到运行 DSH 的电脑上,记下绝对路径。 - DSH Web →「插件」→「添加插件」,输入这个绝对路径(以
.tgz结尾),安装并启用。 命令行:dsh plugin --profile <profile> add /绝对路径/dsh-im-bridge-<版本>.tgz - 打开「设置」→「IM 桥接」完成配置(见下)。
制作安装包:在插件目录运行 npm install && npm run package,生成 dist/dsh-im-bridge-<版本>.tgz 和 dist/安装说明.md。
设置页(DSH Web →「设置」→「IM 桥接」)
- 状态:每个账号显示在线、连接中、需要登录、白名单为空等状态;「重新连接」重连所有账号。
- Discord:填 Bot Token、允许的用户 ID、管理员。
- QQ:填 AppID、AppSecret、沙箱 / Markdown 开关。
- 微信:「扫码登录」直接在页面上显示二维码,扫码成功后你的微信 ID 自动加入白名单;可退出登录。
- 配对:开启后,陌生人的配对申请出现在对应账号下,点「批准 / 拒绝 / 移除」即可。
- 通用:代理、默认工作区、命令前缀、用量行 / 工具进度 / 思考过程 / Web 输入同步开关。
- 任务完成提示语音:选择开启的渠道、上传 / 试听 / 删除音频、指定使用哪段或每次随机(见下节)。
- 点「保存」:Token、Secret 存进 DSH 凭据库(页面不再显示),其余设置通过 DSH 的配置编辑服务写入 profile 的
cordis.patch.yml,插件随即热重载(IM 连接断开几秒)。 - 设置页的接口(
/im-bridge/api/*)与 DSH Web 使用同一套登录验证,未登录的请求一律拒绝;写操作另有同源和请求头检查。
已经用旧版本安装、升级到带设置页的版本时,DSH 只在启动时扫描插件的网页部分:升级后需要重启一次 DSH,设置页才会出现。全新安装不受影响。
任务完成提示语音(娱乐功能)
这是一个娱乐性质的附加功能,默认关闭,不影响正常的文字回复。
每次任务正常完成、文字回复发完之后,再补发一条语音消息,比如「领导,您交代的任务已经完成了」。任务出错、被中断或停止时不发。
支持的渠道
| 渠道 | 支持 | 说明 |
|---|---|---|
| ✅ | 以 QQ 语音消息发送(SILK 格式,插件自动转换) | |
| 微信 | ❌ | 不支持:微信官方通道(iLink)没有开放机器人发送语音消息,腾讯官方插件也只支持发送文字、图片、视频和文件;实测请求被接受但用户收不到 |
| Discord | ❌ | 暂不支持 |
使用方法(设置 → IM 桥接 →「任务完成提示语音」)
- 点「上传音频」,选一个或多个音频文件(可一次多选),上传后立即保存,可在页面上试听、删除。
- 勾选要开启的渠道(目前只有 QQ)。
- 「使用哪段」:只有一段时总是用它;有多段时,不指定就每次随机挑一段,也可以在下拉框里固定用某一段。
- 「本轮用时至少」:0 表示每次回复后都发;填 60 表示只在耗时超过 1 分钟的任务完成后发,避免简单问答也跟一条语音。
- 点「保存」。
音频要求
| 项目 | 限制 |
|---|---|
| 格式 | 浏览器能播放的常见格式:mp3、m4a、wav、aac 等(由浏览器解码;ogg / flac 视浏览器而定) |
| 文件大小 | 单个文件不超过 10 MB |
| 时长 | 自动去掉首尾静音后 0.5–20 秒;建议 2–5 秒 |
| 数量 | 最多保存 10 段 |
| 处理方式 | 转为单声道 24 kHz,编码为 SILK 保存在插件状态目录 voice-clips/ 下,只保存在本机 |
注意
- 插件不内置任何音频,需要你自己上传。请只使用你自己录制、或有权使用的音频;不要上传他人声音的录音或仿冒他人声音的合成音频(除非取得本人同意),也不要上传受版权保护的音乐、影视片段。
- QQ 的每条语音都算一条消息:被动回复额度(每条用户消息可回复的条数、有效期)用完后会改为主动消息,主动消息有月度配额;回复较多时建议设置「本轮用时至少」。
- 语音发送失败只记录日志,不会影响文字回复。
- 语音编码使用打包在插件里的 SILK 编解码器(
lib/silk.wasm,来自 silk-wasm,含 Skype 的 SILK SDK 代码)。它的许可证只授予版权许可,明确不授予任何专利许可;SILK 是 QQ / 微信语音的通用格式,个人使用一般不涉及问题,但如果你要把本插件用于商业产品,请自行评估相关专利风险。许可证全文见包内lib/THIRD_PARTY_LICENSES.txt。
开发者:本机链接安装与热更新
npm install && npm run build
dsh plugin --profile web add "link:$PWD"
npm run deploy # 构建、原子替换 lib/、触发热重载并核对(不重启 DSH)
配置(YAML,可选)
通常用设置页即可;下面是 cordis.patch.yml 里 im-bridge 行的完整字段,供手工编辑参考。
凭据(bot token、AppSecret)不写进配置文件,存进 DSH 凭据库 ~/.dsh/.credentials.yaml 的 refs 下(DSH 实时读取;~/.dsh/.env 只在 DSH 启动时读一次)。
- id: im-bridge
name: dsh-im-bridge
config:
stateDir: !!js dshHomePath('im-bridge')
proxy: http://127.0.0.1:7890 # 可选:仅 IM 连接走的 HTTP 代理(Discord 在国内需要)
defaultWorkspace: dsh-plugins # 可选
discord:
- accountId: main
tokenRef: DISCORD_BOT_TOKEN
allowUsers: ['<Discord 用户 ID>']
qq:
- accountId: main
appId: '<AppID>'
secretRef: QQ_BOT_SECRET
allowUsers: ['<user_openid>'] # 先开 pairing 或看 bridge.log 拿到 openid
weixin:
- accountId: main
allowUsers: ['<微信用户 id>']
通用配置
| 字段 | 默认 | 说明 |
|---|---|---|
stateDir |
必填 | 状态目录:绑定、投递记录、配对、日志 bridge.log、status.json(文件 0600) |
defaultWorkspace |
— | 没选工作区时新会话使用的工作区 |
timeZone |
本机时区 | 随 prompt 发送的 IANA 时区 |
proxy |
— | 仅 IM 连接的 HTTP 代理;DSH 其他请求不受影响 |
mirrorWebInput |
true |
Web 输入同步到 IM |
showReasoning |
false |
回复里以引用块附上思考过程 |
usageFooter |
true |
每条回复末尾显示本会话累计 token 和缓存命中(与 Web 输入框右下角一致) |
toolProgress |
true |
显示工具调用进度 |
commandPrefix |
! |
文本命令前缀 |
sessionListLimit |
10 |
/sessions 列出的数量 |
attachHistoryTurns |
3 |
/attach 时回放的轮数(0 关闭) |
maxImageBytes / maxFileBytes |
8 MiB / 25 MiB | 转发的图片 / 文件上限(按实际下载字节) |
approvalArgumentChars |
900 |
审批卡片显示的参数字符数 |
requestTimeoutMs |
60000 |
调用 DSH 的超时 |
sendTimeoutMs |
30000 |
单次 IM 平台调用(发消息、编辑、正在输入)的超时;超时按「可能没送到」处理,回复由投递记录稍后重试(设置页「超时」可改) |
sendFileTimeoutMs |
120000 |
im_send_file 整体超时,含排在前面消息之后的等待;超时或用户暂停时工具立即报错,会话不会卡住(设置页可改) |
laneStallTimeoutMs |
300000 |
同一对话按顺序发送;前一条卡住超过这个时间,后面的消息不再等它(设置页可改) |
progressMaxLines / progressEditIntervalMs / streamEditIntervalMs / typingIntervalMs |
10 / 1500 / 1200 / 8000 | 渲染节流 |
doneVoice |
{ channels: [], clip: '', minSeconds: 0 } |
任务完成提示语音:开启的渠道(目前只能填 qq)、固定使用的音频 id(空 = 随机)、本轮最短用时(秒);音频在设置页上传 |
每个账号(discord[] / qq[] / weixin[])
| 字段 | 默认 | 说明 |
|---|---|---|
accountId |
main |
账号名 |
allowUsers |
[] |
允许的用户 ID;为空且未开配对时不上线 |
admins |
[] |
管理员;为空则 allowUsers 里的人都是管理员(配对用户不算) |
userCommands |
status sessions new stop steer history |
普通用户可用的命令 |
render |
Discord edit,QQ/微信 final-only |
渲染方式(不能编辑的渠道总是写完再发) |
approvals / questions |
race |
race 与 Web 同时提供;web-only 只在 Web |
pairing |
false |
陌生人私信可申请 8 位配对码(1 小时有效、存加盐哈希、每账号最多 3 个待批、每人 10 分钟一次、错 5 次锁 1 小时),管理员 /pair approve |
Discord:tokenRef |
DISCORD_BOT_TOKEN |
bot token 凭据名 |
Discord:allowGuilds / allowChannels / freeResponseChannels / registerCommands |
服务器 / 频道白名单、免 @ 频道、注册斜杠命令 | |
QQ:appId / secretRef / sandbox / markdown |
— / QQ_BOT_SECRET / false / false |
AppID、AppSecret 凭据名、沙箱、以 Markdown 发送 |
微信:baseUrl |
iLink 默认地址 |
各渠道接入
Discord
- https://discord.com/developers/applications → New Application → Bot → Reset Token;打开 MESSAGE CONTENT INTENT。
- 「安装」页把安装链接设为「无」,再关闭「公共机器人」。
- 用
https://discord.com/oauth2/authorize?client_id=<AppID>&scope=bot+applications.commands&permissions=326417615936把 bot 拉进私人服务器(查看频道、发消息、表情、上传文件、读历史、管理/创建/在子区发消息)。 - 用户 ID:设置 → 高级 → 开发者模式,右键头像复制。
- 国内网络需要设置
proxy。
QQ 官方机器人
- 在 QQ 开放平台创建机器人,拿到 AppID、AppSecret;AppSecret 写入凭据库
QQ_BOT_SECRET。 - 机器人在单聊 60 分钟内可被动回复 4 条、群聊 5 分钟内 5 条;超出后改为主动发送(有额度,用户可关闭)。长任务的结果可能受此限制。
- 审批、提问、排队回执、选择器用 QQ 原生按钮(回调按钮);QQ 拒绝按钮时自动改为文字(回复序号、「批准」),连续被拒 3 次后本次运行不再尝试。
- 私聊回复边生成边显示(QQ 流式消息);群聊写完再发。语音消息使用 QQ 自带的识别文字;文件、视频会交给 agent。
- agent 可以用
im_send_file工具把图片、文件发回 QQ / Discord。
个人微信(微信 ClawBot / iLink)
- 腾讯官方的「微信 ClawBot」插件通道(
ilinkai.weixin.qq.com)。用自己的微信扫码即可,不需要小号;微信「我 → 设置 → 插件」里要能看到 ClawBot(需较新版本的微信)。 npm run build后运行npm run weixin:login,用微信扫码登录;凭据保存在stateDir/weixin-<accountId>/。无头服务器可把打印出的链接生成二维码再扫,或发到微信「文件传输助手」里点开。- 只能私聊;回复需要带上用户最近一条消息的对话凭证,长时间没给机器人发消息时,主动消息可能发不出去,发一条消息即可恢复。
- 没有按钮和流式消息(接口不支持):选择用回复序号,回复写完再发;支持"正在输入"、收发图片和文件(
im_send_file)。
安全须知
- 能使用 bot 的人等于拥有本机 agent 的全部权限;在
danger-full-access预设下没有审批拦截。务必配置allowUsers,只在私人服务器 / 私聊使用。 - 斜杠命令的回复只有自己可见;但频道里 agent 的回复对能看到该频道的人可见。
- 日志不记录消息正文和密钥。
开发
npm run typecheck # 类型检查(源码 + 测试)
npm test # vitest
npm run typecheck:compat # 用 deepseek-harness 源码(DSH_SOURCE 指定路径)校验 src/host/ 的结构类型
npm run build # esbuild 打包到 lib/(宿主端、网页端、微信登录脚本)
npm run package # 生成离线安装包 dist/*.tgz
npm run deploy # 构建并热更新到运行中的 DSH
| 目录 | 职责 |
|---|---|
src/host/ |
唯一调用 DSH 的地方:结构类型与 HostApi |
src/core/ |
渠道无关:路由、会话绑定、渲染、排队回执、审批与提问、命令、模型、权限与配对、投递记录、状态存储、诊断 |
src/channels/discord/ |
Discord(discord.js 14;可走代理) |
src/channels/qq/ |
QQ 官方 Bot API v2 |
src/channels/weixin/ |
腾讯 iLink(个人微信) |
src/channels/fake/ |
测试用内存渠道(Discord 形状 / QQ 形状) |
src/settings/ |
设置页宿主端:接口路由、微信扫码登录、请求协议 |
src/client/ |
设置页网页端(React,DSH 客户端模块格式) |
scripts/third-party/ |
打包进二进制(silk.wasm)的第三方代码的许可证原文,构建时并入 THIRD_PARTY_LICENSES.txt |
更新记录
- 0.4.0:新增「任务完成提示语音」(娱乐功能,QQ):设置页上传 / 试听 / 删除音频、按渠道开启、指定或随机、最短用时;完善第三方许可证与署名说明(含间接来源与 SILK 编解码器)。
- 0.3.x:设置页、离线安装包、npm 发布、第三方许可证清单;修复发送队列在网络中断后可能卡死的问题,新增发送超时设置。
许可与致谢
本项目以 MIT 许可证发布,全文与所有版权声明见 LICENSE。
改编或参考的项目(均为 MIT,版权声明已保留在 LICENSE 中)
| 项目 | 版权方 | 本项目如何使用 |
|---|---|---|
| dsh-plugin-discord | tjiisztiuv | 部分代码改编:DSH 接入、Discord 渲染与交互、兼容性类型检查脚本 |
| @xmanrui/dsh-im | xmanrui | 部分代码改编:QQ 与微信适配器的协议细节、微信扫码登录流程 |
| openclaw-weixin | Tencent | 间接来源:上一项中的微信 iLink 请求格式、扫码状态与消息字段源自此项目 |
| @tencent-connect/dsh-qqbot | Tencent Connect | 仅参照 QQ 按钮的数据格式,未复制代码 |
| @tencent-connect/qqbot-nodejs | Tencent | 仅参照 QQ 流式消息、媒体与语音上传的接口格式,未复制代码 |
| OpenClaw | OpenClaw 贡献者 | 仅参考设计思路,未复制代码 |
| Hermes Agent | Nous Research | 仅参考设计思路与文档,未复制代码 |
| DeepSeek Harness | DeepSeek | src/host/ 的结构类型对照 DSH 插件接口编写,未包含 DSH 源码 |
打包进发布包的第三方代码:npm 包与离线安装包的 lib/ 打包了运行所需的依赖,各自保留原许可证,完整清单与许可证原文见包内 lib/THIRD_PARTY_LICENSES.txt(构建时自动生成)。其中:
- discord.js 及 @discordjs/* 为 Apache-2.0,其余 JavaScript 依赖为 MIT / 0BSD;
lib/silk.wasm(QQ 语音编码)来自 silk-wasm(MIT),其中编译了 libSilkCodec(MIT)和 SILK 编解码源码(BSD 风格许可证,版权方为 Skype Limited 与 Russell)。SILK 许可证明确不授予专利许可,商业使用请自行评估。
不包含:插件不内置任何音频、图标或各平台的商标图形。
贡献:提交 Issue / Pull Request 即表示你同意你贡献的内容以 MIT 许可证发布;请勿提交来源不明或许可证不兼容的代码。如果你认为本项目遗漏了某项署名,请提 Issue,会尽快补上。
免责声明
- 非官方项目:本项目是个人开发的第三方插件,与 Discord Inc.、腾讯(QQ、微信)、DeepSeek 及 DeepSeek Harness、OpenClaw、Nous Research 均无隶属、合作或背书关系。Discord、QQ、微信、WeChat、DeepSeek、Skype、SILK 等名称和商标归各自所有者所有,本项目仅为说明兼容性和来源而提及。
- 遵守平台规则与法律法规:使用者需自行遵守所在地的法律法规,以及各平台的服务条款和开发者规范(如 Discord 开发者条款、QQ 开放平台机器人规范、微信 ClawBot / iLink 的使用规则),不得用于发送垃圾信息、骚扰、批量营销或任何违法违规用途。因违反平台规则导致的封号、限流等后果由使用者自行承担。
- 远程操作风险:通过本插件可以远程指挥 DSH 在你的电脑上执行命令、读写文件。请务必配置
allowUsers,妥善保管机器人令牌,不要在不可信的群聊中使用;因配置不当或 Agent 执行结果造成的数据丢失、费用或其他损失,作者不承担责任。 - 数据与隐私:消息内容会经过对应平台(Discord、腾讯)的服务器传输,受这些平台各自的隐私政策约束。插件本身不向作者或任何第三方上传数据;令牌和登录凭证只保存在本机 DSH 的凭据存储与插件状态目录中。若在群聊中使用,请注意群内其他成员能看到 Agent 的回复,勿处理他人的个人信息。
- 按原样提供:本软件按"原样"提供,不附带任何明示或暗示的担保,详见 LICENSE。
- 娱乐功能:「任务完成提示语音」仅供娱乐;上传音频的版权、肖像(声音)权由上传者负责,插件作者不对用户上传的内容承担责任。
安全问题反馈
发现安全漏洞时,请不要公开发 Issue,通过 Gitee 私信联系仓库作者;修复发布后再公开细节。