dsh-lark-bridge

<p align="center"> <img src="https://img.shields.io/badge/dsh--lark--bridge-0.3.1-blueviolet" alt="version"> <img src="https://img.shields.io/badge/tests-272-green" alt="tests"> <img src="https://img.shields.io/badge/license-BSD--3--Clause-blue" alt="license"> <img src="https://img.shields.io/badge/transport-WebSocket%20long--connection-orange" alt="transport"> </p>

<h1 align="center">🕊️ dsh-lark-bridge</h1>

<p align="center"> <b>Run a full DeepSeek Harness coding agent inside Feishu / Lark</b><br/> <i>Native thinking process, approval cards, live goal/todo cards, subagent fan-out, bilingual slash panel — no public webhook URL needed.</i> </p>

<p align="center"> <a href="README.zh.md">中文</a> · <a href="#quick-start">Quick Start</a> · <a href="#features">Features</a> · <a href="#slash-commands">Slash Commands</a> · <a href="#configuration">Configuration</a> · <a href="#architecture">Architecture</a> · <a href="#development">Development</a> </p>

---

What is this?

dsh-lark-bridge is a Feishu/Lark IM channel for DeepSeek Harness — a plugin that makes your coding agent work right inside a chat. Each conversation (DM or group) drives its own dsh agent with:

• Native thinking process — model reasoning renders as Feishu's own "thinking" message,

tool calls with icons, results as code blocks. No black box.

• Interactive approval cards — operations needing confirmation become clickable

cards (Allow once / Deny), with the decider written back.

• Live lifecycle reactions — OK → THINKING → DONE / ERROR on every message.
• Live goal & todo cards — goal phase changes and todo snapshots update a card in the

chat, so a long-running task is never a silent gap.

• WebSocket long connection — no public callback URL, no reverse proxy.

Feishu is the carrier; the work is still done by DeepSeek Harness itself.

✨ Features

🚀 Quick Start

npx @deepseek-ai/dsh plugin --profile web add github:moyu-good/dsh-lark-bridge \
  && npx @deepseek-ai/dsh web

The console prints a QR code → scan with Feishu to create the app → fill in your DeepSeek API Key in Settings → Models → DM the bot or @ it in a group.

> Already using dsh? Drop the npx @deepseek-ai/ prefix.

The package ships prebuilt (lib/ is committed) — no build step on install. A prepare hook rebuilds automatically only when the compiled output is missing (e.g. a source clone without the committed output).

💬 Slash Commands

Panel descriptions are bilingual: English when the platform domain is open.larksuite.com (international Lark), Chinese for open.feishu.cn

(domestic Feishu). Set locale: zh|en to force one.

vs. other Feishu/Lark bridges

⚙️ Configuration

> ⚠️ File delivery is default-deny. Without outbound.allowedFileDirs, > send_file with a local path fails with > local file source requires outbound.allowedFileDirs to be configured — > the agent appears to send, nothing arrives. URLs and raw buffers always work.

Credentials resolve in three layers, later wins: bundle patch config → settings document plugin section → first-boot QR registration.

🔐 Required app permissions

A newly created Feishu app needs these scopes published before the panel and messaging work. The QR onboarding flow grants them automatically; a manually created app must add them in Developer Console → Permissions, then create and publish a version (scopes added after the last publish are not visible to the API until a new version ships):

Debug with the API directly — the console page shows granted, the API shows what the published version carries:

# 1. token
curl -s -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  -H 'Content-Type: application/json' \
  -d "{\"app_id\":\"$APP_ID\",\"app_secret\":\"$APP_SECRET\"}" | jq -r .tenant_access_token
# 2. slash commands (should list your commands after sync)
curl -s "https://open.feishu.cn/open-apis/application/v7/app_slash_commands?page_size=50" \
  -H "Authorization: Bearer $TOKEN"
# 3. published scopes (check application:app_slash_command is present)
curl -s "https://open.feishu.cn/open-apis/application/v6/applications/$APP_ID/app_versions?lang=zh_cn" \
  -H "Authorization: Bearer $TOKEN"

The slash panel sync runs on session create/resume — after granting the scope, send the bot one message to trigger it.

🧭 Architecture

Feishu / Lark ── WebSocket 长连接 ──►  dsh-lark-bridge (dsh 进程内的 feishu-channel 插件)
   (聊天/审批/图片)                        │
                                          ▼
                     host 服务契约: agents / sessions / tools / approval /
                     goal / workspace / settings / commands
                                          │
                                          ▼
                                     DeepSeek Harness 本体

The bridge runs inside the dsh process as the feishu-channel plugin — it is not a separate server. npx @deepseek-ai/dsh web (or --profile chat) boots dsh with this plugin composed; the plugin opens the WebSocket long connection and drives everything from there. Any launcher (shell script, systemd, supervisor) can host it; it has no dependency on any other agent framework.

🛠️ Development

pnpm install
pnpm run build    # clean + tsc + tsdown (emits into lib/, committed)
pnpm test         # vitest (272 tests)
node plugin-contract-test.mjs   # standalone contract tests

The repo is self-contained: only published packages (@deepseek-ai/cordis, @deepseek-ai/schemastery, @larksuite/channel) are dependencies, no host source needed.

Packaging notes (why lib/ is committed):

• Git-dependency installs (github:user/repo) never ran a build, and without a

committed lib/ the plugin failed at boot with ERR_MODULE_NOT_FOUND — fixed by committing the compiled output.

• The prepare hook is a safety net for source clones: it exits immediately

when lib/ exists and only rebuilds when it is genuinely missing.

• build cleans lib/ first (tsdown itself runs clean: false because its

entry points live inside the output dir).

📋 Known limitations

• Configuration is read once at startup; changes need a restart
• Events during a long-connection outage are not replayed (transport has no cursor)
• The Feishu app must use long-connection event subscription (self-built app);

webhook mode receives no events

• schedule_create/list/delete tools require composing @deepseek-ai/dsh-schedule

in your dsh profile (the bridge already listens for schedule/change and renders /schedules; the tools are the model-side half)

📄 License

BSD-3-Clause. Architecture inspired by dsh-lark (also BSD-3-Clause).