Preface¶

A common challenge when connecting DeepSeek Harness Agent sessions to Feishu chats is handling message sending and receiving for the bot, presenting the Agent execution process, displaying tool call results, and maintaining connectivity without a public address.

The dsh-feishucard plugin introduced below is a Feishu bridge plugin designed for DSH. It uses the official SDK’s WebSocket long connection to send and receive Feishu messages, requiring no public IP, domain, or tunnel; it streams the reply process within Feishu cards and maintains an independent session for each chat.

What Is This¶

dsh-feishucard is a self-developed bridge plugin between DeepSeek Harness and Feishu (Lark), maintained by cmfok, and licensed under MIT.

It addresses a focused set of issues:

Receiving and sending messages via the official Feishu SDK long connection
Streaming Agent replies within Feishu cards
Maintaining independent Agent sessions for each Feishu chat
Providing basic chat commands, processing emoji receipts, proactive message tools, and approval cards
Supporting multi-bot configuration and keep-alive operation

The package includes three components: a Host plugin, a long-connection helper subprocess, and an auto-registering bundle patch.

Core Features¶

Long Connection for Sending and Receiving¶

The plugin receives Feishu messages via the official SDK’s WebSocket long connection, injects them into the Agent session, and replies to the same chat with interactive cards.

This channel requires no public IP, domain, or tunnel, making it suitable for local or intranet environments.

Streaming Reply Cards¶

Feishu replies use cards, supporting:

Real-time PATCH updates
Inline display of process utterances
Collapsible panels for tool calls
Rate limiting, backoff, circuit breaking, and plain text fallback

When the card channel is unavailable, replies can degrade to plain text.

Independent Sessions Per Chat¶

Each Feishu chat corresponds to a dedicated, exclusive Agent session. Session state is persisted and restored after restarts.

The following commands are supported within chats:

/new [name]
/switch <index>
/list
/help

Processing Emoji Receipt¶

Upon message arrival, the plugin can add a processing emoji receipt. The default is OnIt, and it can be set to none to disable.

Model Tool¶

The plugin provides a feishu_send model tool, enabling the Agent to send messages proactively.

Approval Cards¶

When a session requires approval, an interactive card is presented on the Feishu side, featuring “Allow Once” and “Reject” buttons.

Approval cards have the following behaviors:

Auto-rejects after a 5-minute timeout
Auto-cancels approvals when the session is cancelled

Multi-Bot Support¶

A single instance can be configured with multiple Feishu bots, each bot can be bound to its own workspace.

Keep-Alive Mechanism¶

The plugin includes the following keep-alive capabilities:

The helper automatically restarts after a crash, with a 5s cooldown
Automatically reconnects upon credential changes
Utilizes the SDK’s built-in reconnection capability

Installation and Activation¶

Install the plugin with the following command and restart dsh web:

dsh plugin --profile web add dsh-feishucard
dsh web

On first installation, if pnpm intercepts the protobufjs build script and logs ERR_PNPM_IGNORED_BUILDS, you need to allow that build script.

Set allowBuilds.protobufjs to true in the pnpm-workspace.yaml for the corresponding profile:

allowBuilds:
  protobufjs: true

Then rerun the installation command:

dsh plugin --profile web add dsh-feishucard

For local development, you can also install using the package directory:

dsh plugin --profile web add <package-directory>

Or use the file: protocol:

dsh plugin --profile web add file:<package-directory>

Feishu Open Platform Configuration¶

On the Feishu Open Platform side, a one-time configuration is required:

Create an enterprise self-built application and enable bot capabilities.
Add the required permissions.
Subscribe to the long connection event im.message.receive_v1 under Events & Callbacks.
Create a version and publish.

The permissions that need to be configured include:

im:message.p2p_msg:readonly
im:message.group_at_msg:readonly
im:message:send_as_bot
im:message.reaction

im:message.reaction is an optional permission.

Configuration Example¶

The plugin configuration is stored separately in:

~/.dsh-feishucard/feishu.config.json

The configuration file is decoupled from the repository. Example:

{
  "bots": [
    {
      "name": "My Bot",
      "workspace": "C:\\path\\to\\workspace",
      "appId": "cli_xxxxxxxxxxxxxxxx",
      "appSecret": "your_app_secret",
      "reactionEmoji": "OnIt"
    }
  ]
}

The configuration supports hot reload with a polling interval of 10 seconds; no restart is needed after changes.

Session state is persisted in:

~/.dsh-feishucard/state-<appId>.json

If the legacy ecosystem path is detected:

~/.cc-connect/

and a configuration exists there, the plugin will automatically migrate it once on first startup.

Typical Usage¶

After installing and configuring the bot, you can directly use the following in Feishu chats:

/new

to create a new session.

/new order investigation

to create a new session with a name.

/list

to view the session list.

switch 2

or:

/switch 2

to switch to the second session.

/help

to view help.

For proactive messages, the Agent can call the feishu_send tool. When approval is needed, use the buttons on the Feishu card to “Allow Once” or “Reject”.

Development and Troubleshooting¶

For local development, first install dependencies:

npm i

Syntax check:

npm run check

Smoke test:

npm run smoke

The plugin’s dependency requirements include:

"@deepseek-ai/dsh-tools": "^0.1.0-rc.5"

and:

"@larksuiteoapi/node-sdk": "^1.73.0"

When using a file: dependency installation on Windows, node_modules/dsh-feishucard in the profile may be a physical copy rather than a symlink. After modifying source files, you need to sync the copy or rerun the installation command before restarting.

Applicable Scenarios and Notes¶

This plugin is suitable for the following scenarios:

Want to use DSH Agent sessions directly within Feishu
Wish to see the Agent’s process utterances and tool call panels
Don’t want to rely on public IP, domain names, or tunnels
Need independent sessions per chat with recovery after restarts
Need approval cards and proactive message tools

Before use, please note:

Do not install other DSH Feishu plugins simultaneously. WS long connections for the same Feishu app will kick each other off.
The plugin runs with the permissions of the current dsh process. Review the source code and license before installation.
Feishu Open Platform requires correct configuration of permissions, event subscriptions, and version publishing.
First installation may encounter ERR_PNPM_IGNORED_BUILDS; you need to allow the protobufjs build script.
When using a file: installation for local development, pay attention to the copy synchronization issue on Windows.

Links¶

GitHub address:

https://github.com/cmfok/dsh-feishucard

dsh-feishucard: Bridging Feishu Streaming Cards for DeepSeek Harness