ax-feishu-bridge

A Feishu/Lark message-bridge extension for DeepSeek Harness and Pi — keep collaborating with your local DSH/Pi right inside your familiar chat interface.

DSH & Pi Feishu feedback group: https://applink.feishu.cn/client/chat/chatter/add_by_link?link_token=57dvecbb-95d3-4d01-b689-6ebc3d17c867

Join the group to report any issues with the extension.

My social platforms — follow me to catch the latest AI tools first

Account name across all platforms: AX阿煊

Bilibili: https://space.bilibili.com/4489397

Key Features

• Create a Feishu/Lark bot quickly by scanning a QR code — minimal manual setup
• Separate Pi sessions for DMs, group chats, and group topics
• Group chat policies:
  • open: reply directly in groups and topics without an @; you still need to manually enable the "receive all messages in group chats" permission for the bot in the Feishu developer console
  • mention: reply only when the bot is @-mentioned, a keyword matches, or someone replies to a bot message (the latter two are optional)
• Attachment inputs including images, code files, and text files; image understanding depends on whether the selected model supports images
• Parse Feishu interactive alert cards; when replying to a message or card, the original content can be passed to Pi together
• Group keyword triggers, and follow-up questions by replying to bot messages
• Switch the model, workspace, past sessions, and thinking level of the current conversation inside Feishu
• An immediate "Replying…" appears as soon as a message is received, and the answer streams into the same card; can be stopped, with a completed or failed status shown
• Render Markdown content
• Even when the Pi agent is closed, a resident background service keeps the conversation going — the Pi agent does not need to run in the foreground.

Quick Start

The quick start below begins with DeepSeek Harness (DSH); Pi users can jump straight to Pi Quick Start.

DeepSeek Harness (DSH)

This extension is also distributed as a DeepSeek Harness bundle. Bot setup and the chat experience are the same as Pi.

1. Install

Prerequisite: dsh is already installed on your machine

Install from npm

dsh plugin --profile web add ax-feishu-bridge --ignore-scripts

2. Launch and First-Time Setup

After installation, restart dsh. If no Feishu bot configuration is detected, a terminal setup wizard starts automatically: it is recommended to choose "scan QR code to auto-create the Feishu assistant" and scan the QR code in the terminal as prompted; if you already have an existing Feishu/Lark app, you can also enter the App ID and App Secret manually.

After setup, the bridge starts automatically and connects to Feishu/Lark, and it reconnects automatically every time you start dsh afterwards.

DSH uses its own config file ~/.dsh/feishu/config.harness.json, separate from Pi's config — the two can be installed side by side and coexist.

3. Interacting in Feishu

Exactly the same as Pi:

• DM: just send a message
• Group chats: whether you need to @ the bot depends on the group policy
• Topics: each topic maps to its own independent session

If the group policy is set to open and you want the bot to reply to any group message without being @-mentioned, you must also enable either the "receive all messages in group chats" or the "receive messages sent by users and bots in group chats" permission under Events and Callbacks of the bot in the Feishu developer console.

In-chat commands like /new, /resume, /model, /thinking, /stop, /workspace, /status, and /config are also available; see "Using It in Feishu" below for the full list.

Two differences to note:

• DSH offers a trimmed-down set of /feishu management commands: setup / status / autostart / debug / reset, but no start / stop / restart — the bridge starts and stops automatically with dsh, controlled by autoStart in the config.
• DSH environment variables use the HARNESS_ prefix (e.g. HARNESS_APP_ID) instead of Pi's FEISHU_; the card callback port also differs by default — Pi uses 3001, DSH uses 3002, so both can run side by side without conflicts

Pi

1. Install

pi install npm:ax-feishu-bridge

You can also install from Git:

pi install git:github.com/AX1202/ax-feishu-bridge

2. Initial Setup

Run inside Pi:

/feishu setup

It is recommended to choose "scan QR code to auto-create the Feishu assistant" and scan the QR code in the terminal as prompted.

If you already have an existing Feishu/Lark app, you can also enter the App ID and App Secret manually.

3. Start the Bridge

/feishu start

If auto-start is enabled, the bridge connects to Feishu/Lark automatically when a Pi session starts.

4. Start Chatting

Open the bot in Feishu/Lark and just send a message.

• DM: just send a message
• Group chats: whether you need to @ the bot depends on the group policy
• Topics: each topic maps to its own independent Pi session

If the group policy is set to open and you want the bot to reply to any group message without being @-mentioned, you must also enable either the "receive all messages in group chats" or the "receive messages sent by users and bots in group chats" permission under Events and Callbacks of the bot in the Feishu developer console.

Running the Pi Agent Feishu Plugin on Windows

Solution

1. Install Git for Windows first

After installation, this file usually exists:

C:\Program Files\Git\bin\bash.exe

This is the Bash environment used by Pi on Windows.

2. Configure Pi's settings.json

Open:

C:\Users\<your-username>\.pi\agent\settings.json

Add this line inside the braces:

"shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"

Note: if the file already contains other settings, don't remove them — just add this line.

This setting mainly tells the Pi main program which Bash to use.

3. Add Git Bash to the Windows PATH

Some plugins invoke directly:

bash

They don't necessarily read Pi's shellPath config, so you also need to add Git Bash to the system PATH.

Run in PowerShell:

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\Program Files\Git\bin",
  "User"
)

4. Restart PowerShell

After running the command above, close PowerShell and reopen it.

Then verify:

where.exe bash

If the output is:

C:\Program Files\Git\bin\bash.exe

the fix succeeded.

5. Run Pi again

pi

Summary

The most robust setup is to do both:

shellPath in settings.json
+
C:\Program Files\Git\bin in the Windows PATH

The former is for the Pi main program; the latter is for plugins or subprocesses that invoke bash directly.

Using It in Feishu

Common commands to send to the bot:

Managing It inside Pi

Managing It inside DSH

Type these in the DSH web composer or terminal (relies on the host DSH's command facility; silently skipped when the host doesn't provide it, without affecting the bridge itself):

Difference from Pi: DSH does not provide /feishu start | stop | restart — the bridge starts and stops automatically with dsh. After setup / reset, restart dsh for the new config to take effect.

Note (DSH platform limitation): command results render as collapsible command nodes in the conversation flow, but a brand-new blank session does not render command records — if a command seems to do nothing, send any ordinary message in that session first, then run the command. setup is unaffected (its prompts and QR code live in the terminal).

Configuration

Config is saved by default at:

~/.pi/agent/feishu/config.json

It can also be configured via environment variables:

config.json fields

In addition to the environment variables above, you can also set these in config.json (priority: env vars > config.json > defaults):

Note: long-running tasks (e.g. running tests, builds, batch processing) are not reported as "task failed" by default — once promptNotifySec is reached, Feishu only shows "the task is still processing", the reply card stays "replying", and the result is delivered normally when done. A hard timeout only applies when promptTimeoutSec is explicitly set. Run /feishu restart after changes for them to take effect.

Runtime settings

The following bridge settings can be changed instantly with /config in a direct message with the bot — no restart needed — and are saved to ~/.pi/agent/feishu/runtime-overrides.json:

/config
/config groupKeywords alert,alerts
/config groupAlsoOnReply true
/config streamingReply false
/config clear groupKeywords
/config clear all

The hot-updatable scope only includes groupPolicy, groupKeywords, groupAlsoOnReply, ignoreBotMessages, reactEmoji, language, and the streaming display parameters; app credentials, quoted-message expansion, and connection mode cannot be changed via chat.

Stored Files

Notes

• Whether images can be recognized depends on whether the selected model supports image input.
• Image and text/code file inputs are existing capabilities; interactive card parsing and reply-context expansion are capabilities added in newer versions.
• When you "reply" to a message or card, Pi sees the original content plus your new question; this does not re-send the original message to the group.
• /feishu reset only clears config and mappings; it never deletes session history.
• Tasks created from TUI, CLI, or other channels are not proactively pushed to Feishu.
• /workspace currently only supports absolute paths, or paths starting with ~/.
• /resume first shows the recent sessions of the current project by default; you can switch to "all sessions" in the card and page through them.
• Card buttons now prefer webhook response mode; if you want to temporarily keep the older WS update flow, set FEISHU_CARD_ACTION_MODE to ws.
• The card callback listens on 0.0.0.0:3001/webhook/card (Pi) / 0.0.0.0:3002/webhook/card (DSH) by default; you need to point the interactive card callback URL to an externally reachable URL in the Feishu developer console.

FAQ

Why isn't the bot replying?

Check three things:

• Whether the Feishu bot has been created and configured
• Whether /feishu start has been run
• Whether the group policy requires @-mentioning the bot

I sent a message in the group, why did the bot ignore me?

If you set the group policy to mention, the bot replies only after being @-mentioned.
In open mode: it can reply directly in groups and topics without an @, but you still need to manually enable the "receive all messages in group chats" permission for the bot in the Feishu developer console for it to take effect.

Boot auto-start of the background service is not implemented yet; currently you need to manually start the Pi agent once after the computer boots for it to work properly. Once started, the Pi agent does not need to run in the foreground — even after it is closed, you can still chat in Feishu/Lark.