dsh-feishu-bridge-ailoushu

dsh-feishu-bridge

A bridge plugin that connects a Feishu (Lark) bot to DeepSeek Harness (DSH): Feishu / Lark ↔ DeepSeek Harness.

Message a bot in Feishu, and the message becomes one task for a DSH Agent; the Agent's final answer and progress hints (e.g. which tools it called) are sent back to Feishu — control DSH agents directly from Feishu.

• No public endpoint needed: WebSocket long connection, runs locally
• Session context preserved: one DSH Session per Feishu chat / thread
• Visible execution: tool-call progress forwarded to Feishu in real time
• Control from Feishu: /reset, /workspace, /mode, /model, /effort, /stop, and more

Quick install

# Install from GitHub (recommended)
npx @deepseek-ai/dsh plugin --profile web add git+https://github.com/ailoushu666/dsh-feishu-bridge.git

# Or install from a local checkout (development)
npx @deepseek-ai/dsh plugin --profile web add "<this project directory>"

For the full steps see Quick start (deploy into DSH); Feishu console setup: docs/feishu-setup.md.

中文：README.md

Features

• Uses Feishu's official @larksuiteoapi/node-sdk over a WebSocket long connection — no public IP / domain / port forwarding required.
• Reuses the same DSH Session per Feishu chat (or thread), so context is preserved; each thread is independent.
• Replies are linked to the triggering message; replies inside a thread stay in that thread.
• By default only handles direct messages and group messages that @mention the bot.
• Visible progress: tool calls show as 🔧 调用工具 <name>, and intermediate replies between tool calls are forwarded too (💬), all sent through a throttled queue so Feishu rate limits never drop them; the final answer is replied to the original message separately.
• Instant acknowledgement (“processing / queued”) for every message; turns exceeding turnTimeoutMs are auto-cancelled with a notice.
• Autonomous DSH turns are pushed back to Feishu: when DSH wakes the Agent on its own (goal rounds / scheduled tasks / background jobs) and produces a result, Feishu receives it — no longer limited to one reply per message.
• Interactive questions in Feishu: when the Agent needs your confirmation or choice (ask_user_question), the question and its options arrive as a ❓ list — reply with a number (e.g. 1), an option label, or free text to answer, and the Agent continues; invalid replies (several numbers for a single choice, out-of-range numbers) are re-prompted instead of polluting the Agent.
• A set of Feishu control commands: switch project folder, switch working mode, switch model & reasoning effort, stop a task, record feedback, manage a long-running goal, enter plan mode, and more.

Supported commands

Send them directly in Feishu (@mention the bot in groups, plain in DMs). Case-insensitive.

/workspace, /mode, /model, /effort without an argument show the current value or available options. For /mode, the short names read / write / full map to read-only / workspace-write / danger-full-access; full names are also accepted.

Requirements

• Node.js ^22.19.0 or >= 24 (same as Harness).
• A working DeepSeek Harness (dsh web).
• A Feishu self-built app with: bot capability enabled, the im.message.receive_v1 event subscribed over long connection, and the required permissions granted.

See docs/feishu-setup.md for the full Feishu console steps.

Quick start (deploy into DSH)

Step 1: Prepare Feishu

Follow docs/feishu-setup.md: create the self-built app → enable the bot capability → grant permissions → subscribe im.message.receive_v1 over long connection → publish and install the app. Note down the App ID and App Secret.

Step 2: Install the plugin into the web profile

npx @deepseek-ai/dsh plugin --profile web add "<this project directory>"

The plugin creates a disabled by default feishu-bridge instance in the bundle layer.

Step 3: Store the secret and enable

The App ID (not secret) and the App Secret (secret) are stored separately:

1. Put the App Secret into DSH's credential file ~/.dsh/.credentials.yaml (Windows: C:\Users\<you>\.dsh\.credentials.yaml), with a key matching appSecretEnv (default FEISHU_APP_SECRET):

   FEISHU_APP_SECRET: <your App Secret>
   

2. Edit the profile patch ~/.dsh/profiles/web/cordis.patch.yml (Windows: C:\Users\<you>\.dsh\profiles\web\cordis.patch.yml) and override the same id to enable it:

   - id: feishu-bridge
     disabled: false
     config:
       appId: cli_xxxxxxxxxxxxxxxx        # App ID (not secret)
       appSecretEnv: FEISHU_APP_SECRET    # reference name; value lives in ~/.dsh/.credentials.yaml
       domain: feishu                     # feishu (China) or lark (international)
       requireMention: true               # group messages must @mention the bot
       dmMode: open                       # DMs: open / allowlist / disabled
   

Do not insert a second instance with the same id — that raises duplicate loader entry id: feishu-bridge.

Step 4: Start

npx @deepseek-ai/dsh web

This line means the Feishu long connection is up:

feishu-bridge: WebSocket connected

Step 5: Verify

• DM the bot; it replies with the final answer, and keeps context on follow-ups.
• In a group: @bot your question.
• Send /help for the full command list.

Config & credential locations

Configuration options

Full example:

- id: feishu-bridge
  disabled: false
  config:
    appId: cli_xxxxxxxxxxxxxxxx
    appSecretEnv: FEISHU_APP_SECRET
    domain: feishu
    requireMention: true
    dmMode: open
    # optional:
    provider: deepseek-official
    model: deepseek-v4-flash
    reasoningEffort: high
    workspace: C:\Project\my-repo
    agentPreset: coding
    streamProgress: true
    maxProgressMessages: 10

Feishu permissions

The default setup (DM + group @mention + reply) needs these permissions; see docs/feishu-setup.md for details:

Event subscription: use the long connection receive mode and subscribe im.message.receive_v1.

Project structure

dsh-feishu-bridge/
├── package.json          # package metadata + dsh.bundle declaration
├── cordis.patch.yml      # bundle patch: disabled-by-default instance
├── lib/
│   ├── index.js          # plugin entry (name/inject/Config/apply + command dispatch)
│   ├── config.js         # config schema + validation
│   ├── feishu.js         # Feishu long connection + send/reply
│   └── bridge.js         # session mapping + agent driving + channel state + command execution
├── docs/
│   ├── technical.md      # technical documentation
│   └── feishu-setup.md   # Feishu developer console guide
└── .env.example          # explains credential location (no .env needed in practice)

Security

• The App Secret lives only in DSH's credential file ~/.dsh/.credentials.yaml; the plugin never records it or writes it into the project.
• Internal errors reply with a unified errorMessage only — stack traces and sensitive info never reach Feishu users.
• Session IDs are derived via SHA-256 and never embed the raw chat_id / thread_id.
• Do not run multiple long-connection consumers for the same Feishu app (e.g. both this bridge and OpenClaw's Feishu channel). Feishu distributes events randomly among the connections, so messages get "stolen" and the bot becomes flaky or silent.

Known limitations (MVP)

• Text messages only; images, rich text (post), files and cards are unsupported.
• Replies are sent all-at-once (not streamed); progress covers "tool call started + intermediate replies", not tool results.
• Progress messages, intermediate replies, autonomous-turn results and ❓ questions are all sent to the chat root — including for thread conversations (Feishu API limitation: only reply can stay inside a thread).
• No persistent chatId → sessionId mapping: after a DSH restart, existing Feishu chats get a new Session (the old one stays on disk but is no longer reused).
• Runtime switches of model / reasoning effort / project folder are in-memory and reset to config defaults after a DSH restart.
• /export (ZIP download) is a DSH web-only feature; the Feishu text channel cannot deliver files.
• Only one long-connection instance per Feishu app.

Troubleshooting

Uninstall

npx @deepseek-ai/dsh plugin --profile web remove dsh-feishu-bridge

Then remove the leftover feishu-bridge config from ~/.dsh/profiles/web/cordis.patch.yml.

Docs

• Feishu developer console guide
• Technical documentation

License

MIT