🕊️ dsh-lark-bridge

Run a full DeepSeek Harness coding agent inside Feishu / Lark
Native thinking process · approval cards · web/desktop/CLI fleet sync · one-tap account switching · balance & peak/off-peak awareness — no public webhook URL needed.

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

🖼️ Screenshots

_{Illustrative Feishu-style renders. Left: /balance (live balance + peak/off-peak phase), the /bot account switcher card, task ack and the thinking state. Right: /manual — the full in-chat user guide — and the /bot devices fleet roster.}

🤔 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.
• 🌐 Three-surface fleet sync — web (browser), desktop (DSH Desktop) and the CLI share one ~/.dsh session library; cloud arbitration keyed per ENDPOINT (deviceId:form:profile) means exactly one surface replies, and if the active one goes silent the fleet elects a successor automatically.
• 🔄 One-tap account switching — /bot account renders an interactive card of saved Feishu-app credentials; two taps to switch, synced to every surface.
• 💰 Balance & peak/off-peak awareness — /balance queries the DeepSeek open-platform balance live (per currency, timestamped); the model prompt carries the peak/off-peak tariff table so deferrable heavy work lands in the half-price windows.
• 📖 /manual in chat — the full eight-section user guide, one command away.

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.

Harness version: this bridge targets DeepSeek Harness >= 0.1.5-rc.2. It talks to the harness through the plugin seam, and 0.1.5 moved the user-questions seam from a provider registry to the user-questions/request waterfall — see the CHANGELOG for the one-line compatibility note.

# 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.

[!TIP] Not sure what the bot can do? Send it /manual — the full eight-section user guide arrives right in the chat. /help lists every command. The only skill you need is "say what you want".

[!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.

🗨️ Use it like a user

• Just say what you want: "why are the tests failing in this project?" — drag files and images straight into the chat.
• Three surfaces, one conversation: open http://127.0.0.1:18787 for the web UI (same session library as the Feishu side); once DSH Desktop runs the plugin it joins the same fleet. Exactly one surface replies; /bot devices shows who.
• Switch Feishu apps in two taps: /bot account → tap Use on the card → /restart.
• Guidance is built in: new chats get a short starter guide; /manual is the full one; /balance is the wallet.

The complete handbook lives at docs/用户手册.md (Chinese; /manual serves the same content in chat).

✨ Features

Highlights — the ones other bridges don't have:

vs. other Feishu/Lark bridges

Verification basis: re-checked against each project's public README on 2026-09-09 (links under Listings & Community). "Not found" means not seen in public docs — not proof of absence. Different bets: dsh-im is a multi-platform gateway (8+ channels) where breadth is the point; this bridge bets on single-platform depth plus a multi-surface fleet.

💬 Slash Commands

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

/bot subcommands (bridge admin): set / unset / peers / sync-plugins / account (save·use·forget, interactive card) / export / import / devices / retire / activate / name. The slash panel has a single writer — the arbitration-active endpoint — so it always matches what actually runs.

⚙️ 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
  feishu-tools.ts    native Feishu agent tools (notify / cloud drive)
  sync/              dual-end sync: settings source of truth, peers, control API,
                     migration, account book, endpoint arbitration
  pricing.ts         live DeepSeek peak/off-peak phase
  user-guide.ts      single source of the /manual content
  chronicle.ts     optional external-ledger ingest hook (integration example)
  config.ts        schema + defaults
tests/             vitest suites (397) 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                        # 397 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.

🧱 Development & MR Flow

main is the stable baseline and only receives reviewed merge requests. All development happens on feature branches (feat/<name>), never directly on main.

Per-MR checklist:

1. Branch from main; keep the change small and single-purpose.
2. Full quality gate green (pnpm hygiene, pnpm test, node plugin-contract-test.mjs, node scripts/verify-dsh-contract.mjs, pnpm typecheck && pnpm build).
3. Repo hygiene scan — pnpm hygiene — must exit 0. Deployment-specific terms go in a local .leak-patterns file (see .leak-patterns.example), never in the repo.
4. Reviewer approves → merge to main → deploy from main.
5. Production incidents revert on the spot (history stays in git); the reverted branch is rebased and re-MR'd with a fix.

Releases are tags. Pushing a v* tag runs the same gate as CI, verifies the tag matches package.json, and publishes the CHANGELOG section as the release notes — so a tag can never point at a commit that would have failed CI.

This is enforced because past direct-to-main experiments had to be rolled back as a multi-commit revert in one batch — feature branches keep main shippable at all times.

📦 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.

Moving to a new harness version

The bridge consumes the harness through the plugin seam, so a harness upgrade can move the seam under it. The check is one command:

node scripts/verify-dsh-contract.mjs   # compares the bridge's host mirrors with upstream

It fetches the harness source it declares a contract against and fails when an entry the bridge mirrors has moved or vanished — run it before and after an upgrade. When it fails, the fix belongs in the bridge (src/bridge.ts, src/questions.ts), not in a pin: the bridge follows the newest harness, and the host-contract mirrors in those files are the single place that records what the seam looked like when it was last verified.

Two rules keep the upgrade honest:

1. Upgrade the engine by switching trees, not by layering one on top. A dsh profile resolves the harness's own packages from the tree the CLI runs out of, so pointing the launcher at a new checkout is the whole switch. Side-by-side trees fight over the profile's node_modules.
2. A profile declares only its own additions (this bridge, extra plugins). Harness packages are not profile dependencies — declaring them pins the profile to a version and hides the seam behind a stale copy.

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).