前言¶

如果你已经在 DSH 中跑了一个可用的 agent，下一步经常不是继续调 prompt，而是希望它能从常用聊天软件里收消息、回消息。微信 ClawBot / iLink、QQ、飞书各自有登录方式、事件订阅和发送接口，自己接一遍容易把主要精力耗在通道适配上。

下面介绍 baisama-cloud/dsh-omni-bridge。它是一个多通道桥接插件：把微信 ClawBot、QQ、飞书的消息接入 DSH agent，并把 DSH agent 的回复回传给发消息的人。

这是什么¶

dsh-omni-bridge 由 baisama-cloud 维护，许可证为 MIT。

它的定位不是替代某个 IM 机器人平台，而是在 DSH 侧提供一个多通道桥接层：

• 接收微信 ClawBot / iLink、QQ、飞书（Lark）的聊天消息；
• 将消息路由给 DSH agent；
• 将 DSH agent 的回复回传给原发送者；
• 以 DSH 持久化 bundle 形式提供，host/client 打包进 profile，重启 DSH 后生效。

安装并重启后，设置页会出现「远程桥接」卡片，里面包含微信、QQ、飞书三张配置卡。设置页通过 fetch 调用 host 路由完成配置。

核心功能¶

通道能力¶

飞书长连接依赖官方 SDK @larksuiteoapi/node-sdk。

回复策略¶

不同通道的默认回复规则不完全一样：

• 微信、QQ 没有默认 openid，谁发消息就回谁；
• 群内 @机器人 时，回复到群里；
• 飞书群内默认需要 @机器人 才回复；
• 飞书私聊始终回复。

每个通道使用独立 DSH 会话，会话名为 omni-bridge-<channel>。回复去重使用 sessionPersistence.readFrom 水位，避免只拿到第一条回复的问题。

安装与启用¶

从 npm 安装¶

在目标 DSH profile 目录执行：

pnpm add dsh-omni-bridge

然后在 profile 的 package.json 中，将 dsh-omni-bridge 追加到 dsh.profile.bundles。例如：

{
  "dsh": {
    "profile": {
      "bundles": [
        "dsh-omni-bridge"
      ]
    }
  }
}

最后重启 DSH。bundle 层在启动时组合，因此需要重启生效。

本地 tgz 安装¶

如果你使用本地打包文件，按下面步骤操作：

1、打包：

npm pack

2、在 profile 的 package.json 中：

• 在 dsh.profile.bundles 追加 "dsh-omni-bridge"；
• 在 dependencies 追加 "dsh-omni-bridge": "file:<tgz 路径>"。

示例：

{
  "dsh": {
    "profile": {
      "bundles": [
        "dsh-omni-bridge"
      ]
    }
  },
  "dependencies": {
    "dsh-omni-bridge": "file:<tgz 路径>"
  }
}

3、在 profile 目录执行：

pnpm install

4、重启 DSH。

配置与放行¶

配置文件位于：

~/.dsh/omni-bridge-config.json

资料说明，写入时权限为 0600，目录为 0700。

发送者白名单¶

每个通道默认拒绝所有入站消息。也就是说，当 allowAll: false 且 allowedUsers 为空时，没有人可以发消息触发 agent。

你需要二选一显式放行：

• allowedUsers：允许特定发送者 ID；
• allowAll: true：允许所有人。资料标注不建议在生产环境使用。

设置页每个通道卡片也提供「允许的用户 ID」与「允许所有人」配置入口。

微信¶

1、在设置页点击「获取二维码」。

2、用手机扫码登录。

3、登录成功后自动回填 botToken。

botToken 会写入 ~/.dsh/omni-bridge-config.json。微信侧使用 iLink 扫码登录流程，收消息为 iLink 拉模式，发消息走 /ilink/bot/sendmessage。

QQ¶

1、在 QQ 开放平台创建机器人，获取 appId 和 secret。

2、订阅「单聊消息」「群聊@消息」事件。

3、开启被动消息权限。

完成后，QQ 通道通过官方网关 WebSocket 收消息，并通过 POST /v2/users|groups/{openid}/messages 回发消息。

飞书¶

1、创建飞书自建应用，获取 appId 和 appSecret。

2、添加 im:message 权限，资料中列出的相关权限包括：

im:message
im:message.group_at_msg
im:message.p2p_msg
im:message:send_as_bot

3、订阅方式选择长连接，并添加事件：

im.message.receive_v1

4、创建版本并发布。

5、让机器人加入会话或群。

飞书通道通过官方 SDK 长连接收消息，并通过 im/v1/messages 发消息。

适用场景与注意¶

这个插件适合想把已有 DSH agent 接到微信、QQ、飞书聊天入口的场景。它把三个通道的收消息、发消息和 agent 会话串起来，不需要在应用里重复实现一套 IM 回调和回传逻辑。

使用前注意几点：

• 插件以当前 DSH 进程权限运行，安装前应检查源码与许可证；
• 三个通道默认都拒绝入站消息，必须配置 allowedUsers 或 allowAll；
• allowAll: true 会允许所有人触发，不建议用于生产；
• 飞书被动回复有时效，需要在收到消息后的有限时间内回复；
• 安装或修改 bundle 后需要重启 DSH。

结尾¶

dsh-omni-bridge 的价值比较直接：把微信 ClawBot / iLink、QQ、飞书消息接入 DSH agent，并把回复回传给发送者。它提供独立 DSH 会话、回复去重、发送者白名单，以及设置页配置入口，适合作为 DSH agent 的外部聊天通道接入层。

项目地址：

https://github.com/baisama-cloud/dsh-omni-bridge