🕊️ dsh-lark-bridge

Run a full DeepSeek Harness coding agent inside Feishu / Lark
Native thinking process · approval cards · live goal/todo cards · subagent fan-out · bilingual slash panel — no public webhook URL needed.

中文文档 · Quick Start · Features · Extend It · FAQ

🤔 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, and everything the desktop UI shows lives in the chat:

• 🧠 Native thinking process — reasoning renders as Feishu's own "thinking" message; tool calls with icons, results as code blocks. No black box.
• ✅ Interactive approval cards — risky operations become Allow-once / Deny cards, decision and decider written back.
• 🎯 Live goal & todo cards — long-running tasks update a card in real time instead of going silent; goals auto-resume after restarts.
• 🔌 WebSocket long connection — no public callback URL, no reverse proxy.
• 🔄 Dual-end sync — bot settings and plugin lists stay in step between the web profile and the Desktop 2.0.0 app (/bot sync-plugins).

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

🚀 Quick Start in 60 Seconds

Prerequisites: Node 18+, pnpm (recommended, see note), a DeepSeek API key, and the Feishu app on your phone.

# 1. install the plugin into a dsh profile & boot (pnpm — ~20s, parallel install)
pnpm dlx @deepseek-ai/dsh plugin --profile web add @moyu-good/dsh-lark-bridge \
  && pnpm dlx @deepseek-ai/dsh web

# 2. a QR code prints → scan it with Feishu
#    (this creates the app + event subscription automatically)

# 3. open the dsh console → Settings → Models → paste your DeepSeek API key

# 4. DM the bot, or @ it in a group. That's it.

[!NOTE] First-time plugin add fails once with ERR_PNPM_IGNORED_BUILDS ... protobufjs — pnpm 11 blocks the postinstall of protobufjs (a Feishu SDK dependency; its script is a harmless no-op). Open <your-home>/.dsh/profiles/web/pnpm-workspace.yaml and change the placeholder line to protobufjs: true, then re-run the same command. This is a one-time step per profile.

[!WARNING] Use pnpm, not bare npx/npm, to run the upstream dsh CLI. Measured on the same machine: pnpm dlx installs dsh's dependency tree (197 packages, ~250 MB) in ~20 s including downloads, while npx/npm install takes ~25 minutes (npm's serial reify) even with a warm cache — and on machines with ≤4 GB RAM the npm process itself dies with "JavaScript heap out of memory" mid-install. If you must use npm, pre-set NODE_OPTIONS=--max-old-space-size=2048.

Do NOT npm i -g dsh-lark-bridge — that name on npm belongs to an unrelated project. This plugin is published as @moyu-good/dsh-lark-bridge (the GitHub source also works, but installing a git-hosted plugin makes pnpm block its prepare script until you whitelist it under allowBuilds in the profile's pnpm-workspace.yaml — the registry package needs no build at all).

Daily ops: run pnpm dlx @deepseek-ai/dsh web again (subsequent runs hit the pnpm store, so they're fast), or host it under systemd/supervisor. The package ships prebuilt (lib/ committed) — nothing compiles on install.

📦 Moving to a new machine

The bridge carries its own migration path — on the old machine:

/bot export include-secrets --to-feishu   # uploads to the app's own Feishu drive
/bot export include-secrets               # or a local file, credentials masked

The Feishu route needs no copying at all: the file lands in the app's own cloud space (visible only to this app), and the new machine pulls it with /bot import --from-feishu. For the local-file route, copy the printed file (the sync directory, e.g. ~/.dsh/dsh-lark-bridge/migrate.json) to the same path on the new machine, install the plugin there (Quick Start above), then:

/bot import                       # preview: settings + plugin plan + warnings
/bot import apply                 # execute (add --from-feishu for the cloud slot)

What travels: shared settings and per-profile plugin lists (installed through the upstream CLI, so cross-platform moves just work). What never travels: peer heartbeats, control tokens, node_modules, session history — sessions live under ~/.dsh (upstream-owned); copy that directory to carry them.

Device lifecycle: every machine mints a stable deviceId on first boot (/bot devices shows the roster: this machine, heartbeat-live peers, the cloud-active endpoint, and migration provenance). Instead of stopping the old service by hand, retire it — /bot retire on the old machine puts it out of the reply path (messages get a one-line notice, not an agent turn; the flag is per-machine local state and is never synced), and /bot activate brings it back — and when the cloud carrier is available it also claims the active slot, so other machines stand down on their next message. Every live machine renews its presence in the cloud ledger each minute; if the active machine goessilent, the freshest machine with the smallest deviceId is elected automatically on the next inbound message. /bot name <readable-name> names a device for the roster.

✨ Features

Highlights — the ones other bridges don't have:

vs. other Feishu/Lark bridges

💬 Slash Commands

Set locale: zh|en to force a language; otherwise it follows the platform domain.

⚙️ Configuration

Essentials:

Full option reference: README.zh.md 配置 · credentials resolve in three layers (bundle patch config → settings document plugin section → first-boot QR registration).

🧭 Architecture

Feishu / Lark ── WebSocket long connection ──►  dsh-lark-bridge (feishu-channel plugin
   (chat/approval/images)                        INSIDE the dsh process)
                                                      │  host service contracts:
                                                      │  agents / sessions / tools /
                                                      ▼  approval / goal / settings
                                              DeepSeek Harness itself

Any launcher works (shell, systemd, supervisor) — no dependency on any other agent framework.

🧩 Extend It

Three invariants keep the bridge maintainable:

1. Grafted channel, not re-integration — the bridge only normalizes messages; every capability comes from official opt-in dsh plugin families composed in your profile. Zero bridge code = zero upgrade cost when upstream ships features.
2. Everything through host service contracts — agents, agentPresets, approval, goals, settings… self-contained against published packages only.
3. Every change archives a design card first — see docs/design/; implementation notes are backfilled, and blocked investigations are archived as assets too.

Repo map

src/
  bridge.ts        message pipeline: normalize → authorize → ack → agent turn → render
  commands.ts      slash commands (i18n bilingual)
  cot.ts outbound.ts  thinking-process & answer rendering
  chronicle.ts     optional external-ledger ingest hook (integration example)
  config.ts        schema + defaults
tests/             vitest suites (293) incl. harness-based fakes
scripts/           verify-dsh-contract.mjs — asserts no drift vs upstream master
plugin-contract-test.mjs   43 assertions on the host contract surface

Quality gates

pnpm test                        # 293 unit/integration tests
node plugin-contract-test.mjs    # 43 host-contract assertions
node scripts/verify-dsh-contract.mjs   # drift check against upstream master
pnpm typecheck && pnpm run build # tsc + tsdown (lib/ is committed)

CI runs all of the above on every push and pull request, with the upstream drift check pinned to dsh master — if upstream changes a contract, the build tells you before users do.

Adding a feature? Write the design card first (template in docs/design/), implement, backfill the change record. For an integration that only needs message visibility, prefer the chronicleEndpoint hook over modifying the pipeline — see src/chronicle.ts.

📦 Version & Release Policy

Two tracks, written down so nobody guesses:

• preview track — development/experimentation. Pull the latest upstream (GitHub releases including alpha/rc, or master) and the newest bridge features; breakage is expected here.
• stable track — production deployments. Pin the npm latest / release-candidate line. Production never runs an alpha.

Promoting preview → stable requires the full quality gate to pass: pnpm test → node plugin-contract-test.mjs → node scripts/verify-dsh-contract.mjs → pnpm typecheck && pnpm run build → live smoke.

❓ FAQ

🌍 Listings & Community

• dshbase.com — listed & verified (headless L3: install + load + Q&A) · 中文页
• awesome-dsh-plugin — merged
• dsh-suite catalog — accepted (orchestration)

Issues and PRs welcome — design cards first, please.

📋 Known limitations

• Transport-level config (credentials, requireMention, allowlists) is read once at startup; other config edits hot-reload via dsh Config-only HMR (/config shows live values)
• Events during a long-connection outage are not replayed (no cursor); outbound sends are queued by the replay port
• schedule_* model tools need composing @deepseek-ai/dsh-schedule in your profile

📄 License

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