Skip to content

dsh-im-bridge

Verified

dsh-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 文件,所有依赖都已打包在内,安装时不需要联网下载。

  1. 把 dsh-im-bridge-<版本>.tgz 复制到运行 DSH 的电脑上,记下绝对路径。
  2. DSH Web →「插件」→「添加插件」,输入这个绝对路径(以 .tgz 结尾),安装并启用。 命令行:dsh plugin --profile <profile> add /绝对路径/dsh-im-bridge-<版本>.tgz
  3. 打开「设置」→「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 ✅ 以 QQ 语音消息发送(SILK 格式,插件自动转换)
微信 ❌ 不支持:微信官方通道(iLink)没有开放机器人发送语音消息,腾讯官方插件也只支持发送文字、图片、视频和文件;实测请求被接受但用户收不到
Discord ❌ 暂不支持

使用方法(设置 → IM 桥接 →「任务完成提示语音」)

  1. 点「上传音频」,选一个或多个音频文件(可一次多选),上传后立即保存,可在页面上试听、删除。
  2. 勾选要开启的渠道(目前只有 QQ)。
  3. 「使用哪段」:只有一段时总是用它;有多段时,不指定就每次随机挑一段,也可以在下拉框里固定用某一段。
  4. 「本轮用时至少」:0 表示每次回复后都发;填 60 表示只在耗时超过 1 分钟的任务完成后发,避免简单问答也跟一条语音。
  5. 点「保存」。

音频要求

项目 限制
格式 浏览器能播放的常见格式: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

  1. https://discord.com/developers/applications → New Application → Bot → Reset Token;打开 MESSAGE CONTENT INTENT。
  2. 「安装」页把安装链接设为「无」,再关闭「公共机器人」。
  3. 用 https://discord.com/oauth2/authorize?client_id=<AppID>&scope=bot+applications.commands&permissions=326417615936 把 bot 拉进私人服务器(查看频道、发消息、表情、上传文件、读历史、管理/创建/在子区发消息)。
  4. 用户 ID:设置 → 高级 → 开发者模式,右键头像复制。
  5. 国内网络需要设置 proxy。

QQ 官方机器人

  1. 在 QQ 开放平台创建机器人,拿到 AppID、AppSecret;AppSecret 写入凭据库 QQ_BOT_SECRET。
  2. 机器人在单聊 60 分钟内可被动回复 4 条、群聊 5 分钟内 5 条;超出后改为主动发送(有额度,用户可关闭)。长任务的结果可能受此限制。
  3. 审批、提问、排队回执、选择器用 QQ 原生按钮(回调按钮);QQ 拒绝按钮时自动改为文字(回复序号、「批准」),连续被拒 3 次后本次运行不再尝试。
  4. 私聊回复边生成边显示(QQ 流式消息);群聊写完再发。语音消息使用 QQ 自带的识别文字;文件、视频会交给 agent。
  5. agent 可以用 im_send_file 工具把图片、文件发回 QQ / Discord。

个人微信(微信 ClawBot / iLink)

  1. 腾讯官方的「微信 ClawBot」插件通道(ilinkai.weixin.qq.com)。用自己的微信扫码即可,不需要小号;微信「我 → 设置 → 插件」里要能看到 ClawBot(需较新版本的微信)。
  2. npm run build 后运行 npm run weixin:login,用微信扫码登录;凭据保存在 stateDir/weixin-<accountId>/。无头服务器可把打印出的链接生成二维码再扫,或发到微信「文件传输助手」里点开。
  3. 只能私聊;回复需要带上用户最近一条消息的对话凭证,长时间没给机器人发消息时,主动消息可能发不出去,发一条消息即可恢复。
  4. 没有按钮和流式消息(接口不支持):选择用回复序号,回复写完再发;支持"正在输入"、收发图片和文件(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 私信联系仓库作者;修复发布后再公开细节。