前言¶

如果你已經在 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