@kriskwok/dsh-feishu-gateway

Feishu Gateway

DeepSeek Harness 原生 Feishu (Lark) 网关：通过长连接从 Feishu 与 DSH 代理聊天，支持持久会话、/new、Markdown 回复、实时流式进度卡片、原生 Typing 反应、点击回答的审批 / 问答卡片，以及 pro

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add @kriskwok/dsh-feishu-gateway@0.2.15

兼容性与来源证明

Feishu Gateway 以 @kriskwok/dsh-feishu-gateway 发布，当前版本为 0.2.15。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: any
发布来源: npm
Registry 更新时间: 2026/9/21

版本

0.2.15stable

2026/8/26

0.2.14stable

2026/8/25

0.2.13stable

README

dsh-feishu-gateway

English | 中文

Chat with your DeepSeek Harness (DSH) agent from Feishu (Lark).

A DSH plugin bundle that mounts a Feishu long-connection listener; every Feishu message is routed to a stable DSH session (resumed via the agents service, so multi-turn chats stay in the same session), and the agent's answer is replied as a Markdown-rich post message. It also supports /new to start a fresh session, a native Typing reaction while the answer is being produced, live streaming progress cards for long tasks, click-to-answer cards for permission approvals and the model's ask_user_question tool, and proactive push.

Features

💬 Full conversation — Feishu private chat, or group @bot → DSH agent → reply. In groups, every topic/thread is its own independent DSH session, and all messages in that topic stay in the same session until /new.
🔁 Persistent sessions — each Feishu conversation (or group topic) maps to one DSH session (agents.resume / agents.create); /new (or "另起会话" / "新会话" / "重新开始" / "换个话题") starts a fresh one, including inside a group topic.
⌨️ Native Typing indicator — while the agent works, the bot adds a Typing reaction to your message (like hermes-agent's Feishu gateway); it stays until the answer is done, and is swapped for a CrossMark reaction on failure. No more "thinking…" hint text by default.
🎞 Streaming progress — long tasks report continuously: a live interactive card streams the agent's thinking, tool calls, and answer draft as they happen (reporting.mode: 'stream', default). Set reporting.mode: 'final' to only receive the final result.
🃏 Click-to-answer cards — permission approvals (approval/request, e.g. sandbox escalation) and the model's ask_user_question tool render as Feishu interactive cards: click ✅ 允许一次 / 🚫 拒绝 or an option button to answer. The click response instantly replaces the card with a decided state (buttons removed, result shown) plus a toast confirmation.
✍️ Markdown replies — plain rich-text (post) messages with the md tag: bold, inline code, lists and links render natively, no cards needed
🧩 Web-only interactive fences degrade gracefully — model-emitted dsh-ui interactive UI fences (e.g. from dsh-genui) only render in the Web UI; on Feishu they are auto-downgraded to a one-line readable hint (title extracted, "view in Web UI"), never a raw JSON code block
🤖 Full agent capability — the DSH agent runs with its own model and tools (bash, files, subagents…), fully autonomous
📨 Proactive push — optional admin HTTP API (/api/push) to push text / Markdown / cards to any user or group
🔌 No public network required — Feishu long connection, no webhook URL
🗂 Persistence — Feishu↔DSH session mapping survives restarts

Requirements

DeepSeek Harness installed and built (dsh CLI), with DEEPSEEK_API_KEY configured (the agent's model is used as-is)
A Feishu open-platform self-built app with the bot capability enabled (see below)

Feishu app setup

Feishu Open Platform → create a self-built app.
Enable the bot capability.
Grant permissions: im:message, im:message:send_as_bot (+ im:message:send_as_bot:readonly to read content). Publish a version.
Under Events & callbacks, choose long connection and subscribe to im.message.receive_v1 (no public URL needed). The same long connection also delivers card button clicks (card.action.trigger, used by the approval / Q&A cards) — no webhook URL required.
In Feishu, search the app name and add the bot as a contact.

The Typing reaction indicator and card buttons need the bot to be able to interact with messages in the chat (im:message). If the reaction API is denied, the gateway automatically falls back to the hintText message.

Installation (as a DSH plugin)

Prerequisite: this package is published on npm and dsh is on your PATH.

The recommended setup mounts the gateway into the web profile: it runs in the same process as the DSH Web UI, so starting the Web UI also starts the Feishu gateway, and both share the same DSH agent. A standalone profile is also supported (see "Alternative" at the end).

Option 1 (recommended): mount into the web profile

The web profile is DSH's default GUI profile (dsh --profile web).

Edit ~/.dsh/profiles/web/package.json to add the dependency and bundle:

{
  "name": "dsh-profile-web",
  "private": true,
  "dependencies": {
    "@kriskwok/dsh-feishu-gateway": "^0.2.0"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@kriskwok/dsh-feishu-gateway"
      ]
    }
  }
}

Install dependencies in the web profile directory:

cd ~/.dsh/profiles/web && pnpm install

Edit ~/.dsh/profiles/web/cordis.patch.yml and fill in your Feishu app credentials:

- id: feishu-gateway
  config:
    feishu:
      appId: cli_xxxxxxxxxxxxxxxx
      appSecret: xxxxxxxxxxxxxxxxxxxxxxxx
    http:
      port: 3100      # optional admin API
      token: your-token

Start (or restart) the web profile:

dsh --profile web

You can also use the one-shot script from this repository: ./scripts/create-profile.sh (mounts into the web profile by default; --standalone creates a standalone feishu profile instead).

Alternative: standalone feishu profile

To run the gateway without the Web UI, use a standalone profile:

mkdir -p ~/.dsh/profiles/feishu && cd ~/.dsh/profiles/feishu

cat > package.json <<'EOF'
{
  "name": "dsh-profile-feishu",
  "private": true,
  "dependencies": {
    "@kriskwok/dsh-feishu-gateway": "^0.2.0"
  },
  "dsh": {
    "profile": {
      "bundles": ["@deepseek-ai/dsh-base", "@kriskwok/dsh-feishu-gateway"]
    }
  }
}
EOF

cat > pnpm-workspace.yaml <<'EOF'
packages:
  - .
nodeLinker: hoisted
autoInstallPeers: false
EOF

pnpm install
# then create ~/.dsh/profiles/feishu/cordis.patch.yml with your app credentials
dsh --profile feishu

Configuration

All settings live in the feishu-gateway namespace (profile patch row or ~/.dsh/settings.yaml):

Field	Default	Description
`feishu.appId`	—	Feishu app id (required)
`feishu.appSecret`	—	Feishu app secret (required)
`feishu.domain`	`feishu`	`feishu` (CN) or `lark` (international)
`feishu.botOpenId`	``	Optional; @-detection works without it
`feishu.replyMode`	`at`	Group policy: `at` (reply only when @-mentioned) or `all` (reply to every message). Each group topic/thread is its own DSH session.
`workspace`	`/root/Documents/DSH-Workspace`	Agent working directory (the session is also auto-attached to the matching DSH Workspace, so it groups under that Workspace in the Web UI instead of "Ungrouped"). Both private and group-topic sessions are anchored here.
`hintText`	`爸爸，我正在努力处理中……`	Fallback "processing" text (only when the Typing reaction is disabled/unavailable)
`reporting.mode`	`stream`	`stream` = live streaming progress card; `final` = only the final answer
`reporting.typingReaction`	`true`	Show the native Feishu `Typing` reaction while working
`reporting.showReasoning`	`true`	Stream the model's reasoning in the card
`reporting.showToolCalls`	`true`	Stream tool-call activity in the card
`reporting.patchIntervalMs`	`1100`	Min interval between card patches; Feishu limits single-message updates to ~1/s (error 230020), and the stream backs off adaptively on failure
`reporting.maxBodyChars`	`900`	Max rendered card body length
`reporting.failureReaction`	`CrossMark`

Q&A cards in the web profile: ask_user_question answers go through the single ctx.userQuestions provider slot. The gateway never claims that slot (stealing it makes the Web UI's apiProxy host fail to start with DUPLICATE_PROVIDER); it wraps service.ask at the service boundary instead: sessions owned by a Feishu conversation are answered with Feishu cards, while every other session continues through the registered UI provider. Permission-approval cards work from Feishu in every setup. In a standalone feishu profile, both ask_user_question and approvals are answered from Feishu cards.

Session coexistence & self-healing

Preset composition (tools!) — in preset-roster deployments (e.g. the web profile), Feishu agents are composed from the deployment's agent preset (meta.agentPreset + preset mount), so the model gets its tools instead of treating tool calls as plain text.
Web UI coexistence — sessions have a single live owner. When the Web UI opens a session, the Feishu side takes over the running agent via agents.get() and drives the same session instead of failing with "while it is live" / "already exists"; both surfaces share one conversation.
Wedged-session self-heal — if a crashed process leaves a session permanently conflicted ("already exists"), the gateway mints a fresh session id, re-points the Feishu conversation at it, and continues chatting.

Admin HTTP API (optional)

Enable by setting http.port. Endpoints:

GET /health — status
POST /api/push — proactive push { "receive_id": "ou_xxx", "receive_id_type": "open_id", "msg_type": "text", "content": "{\"text\":\"hi\"}" }
GET /api/sessions — Feishu↔DSH session mapping overview

Development

pnpm install
pnpm build     # tsc → lib/
pnpm test      # offline self-tests

Note: @deepseek-ai/* packages are provided by the DSH host at runtime; for local type-checking they are symlinked from your deepseek-harness checkout (see the publish checklist).

License

MIT