Introduction¶

If you already have a working agent running in DSH, the next step is often not to keep tweaking the prompt, but to have it receive and reply to messages from popular chat applications. WeChat (ClawBot/iLink), QQ, and Lark (Feishu) each have their own login methods, event subscriptions, and sending interfaces. Implementing them yourself often wastes the bulk of your energy on channel adaptation.

The following introduces baisama-cloud/dsh-omni-bridge. It is a multi-channel bridge plugin that connects messages from WeChat (ClawBot/iLink), QQ, and Lark to the DSH agent, and sends the DSH agent’s replies back to the original sender.

What is it¶

dsh-omni-bridge is maintained by baisama-cloud and is licensed under MIT.

Its positioning is not to replace a specific IM bot platform, but to provide a multi-channel bridge layer on the DSH side:

• Receive chat messages from WeChat (ClawBot/iLink), QQ, and Lark (Feishu);
• Route messages to the DSH agent;
• Send the DSH agent’s replies back to the original sender;
• Provided as a DSH persistent bundle; the host/client is packaged into the profile and takes effect after restarting DSH.

After installation and restart, a “Remote Bridge” card will appear on the settings page, containing three configuration cards for WeChat, QQ, and Lark. The settings page completes configuration by calling the host route via fetch.

Core Features¶

Channel Capabilities¶

Lark’s long connection relies on the official SDK @larksuiteoapi/node-sdk.

Reply Strategy¶

The default reply rules for different channels are not exactly the same:

• WeChat and QQ do not have a default openid; they reply to whoever sent the message;
• When mentioned with @bot in a group, reply within the group;
• In Lark groups, replying requires a default @bot mention;
• In Lark private chats, they always reply.

Each channel uses a separate DSH session named omni-bridge-<channel>. Reply deduplication uses the sessionPersistence.readFrom watermark to avoid the issue of only receiving the first reply.

Installation and Enablement¶

Install from npm¶

Execute the following in the target DSH profile directory:

pnpm add dsh-omni-bridge

Then, in the profile’s package.json, append dsh-omni-bridge to dsh.profile.bundles. For example:

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

Finally, restart DSH. The bundle layer is composed at startup, so a restart is required for it to take effect.

Local tgz Installation¶

If you are using a local package file, follow the steps below:

1. Package:

npm pack

2. In the profile’s package.json:

• Append "dsh-omni-bridge" to dsh.profile.bundles;
• Append "dsh-omni-bridge": "file:<tgz path>" to dependencies.

Example:

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

3. Execute the following in the profile directory:

pnpm install

4. Restart DSH.

Configuration and Whitelisting¶

The configuration file is located at:

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

Documentation states the permission is 0600 when writing, and the directory is 0700.

Sender Whitelist¶

Each channel rejects all incoming messages by default. That is, when allowAll: false and allowedUsers is empty, no one can send messages to trigger the agent.

You need to explicitly allow one of two options:

• allowedUsers: Allow specific sender IDs;
• allowAll: true: Allow everyone. Documentation notes that this is not recommended for production environments.

The settings page also provides configuration entries for “Allowed User IDs” and “Allow All” for each channel card.

WeChat¶

1. Click “Get QR Code” on the settings page.

2. Scan the code with a mobile phone to log in.

3. After successful login, botToken is automatically filled in.

botToken will be written to ~/.dsh/omni-bridge-config.json. On the WeChat side, the iLink scan code login flow is used; receiving messages is in iLink pull mode, and sending messages goes through /ilink/bot/sendmessage.

QQ¶

1. Create a bot on the QQ Open Platform and obtain appId and secret.

2. Subscribe to “Single Chat Message” and “Group Chat @ Message” events.

3. Enable passive message permissions.

Upon completion, the QQ channel receives messages via the official gateway WebSocket and sends replies via POST /v2/users|groups/{openid}/messages.

Lark (Feishu)¶

1. Create a Lark (Feishu) self-built application and obtain appId and appSecret.

2. Add the im:message permission; the relevant permissions listed in the documentation include:

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

3. Choose “Long Connection” for subscription method and add the event:

im.message.receive_v1

4. Create a version and publish.

5. Invite the bot to a conversation or group.

The Lark channel receives messages via the official SDK long connection and sends messages via im/v1/messages.

Applicable Scenarios and Notes¶

This plugin is suitable for scenarios where you want to connect an existing DSH agent to WeChat, QQ, and Lark chat entry points. It connects the message receiving, sending, and agent sessions of the three channels together, eliminating the need to repeatedly implement a set of IM callback and reply logic within the application.

Note a few points before use:

• The plugin runs with the current DSH process permissions; you should check the source code and license before installing;
• All three channels reject incoming messages by default, so you must configure allowedUsers or allowAll;
• allowAll: true will allow everyone to trigger it, which is not recommended for production;
• Lark’s passive replies have a time limit and must be replied to within a limited time after receiving the message;
• You need to restart DSH after installing or modifying a bundle.

Conclusion¶

The value of dsh-omni-bridge is quite direct: it connects messages from WeChat (ClawBot/iLink), QQ, and Lark to the DSH agent and sends replies back to the sender. It provides independent DSH sessions, reply deduplication, sender whitelisting, and configuration entry points on the settings page, making it suitable as an external chat channel access layer for DSH agents.

Project Address:

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