๐๏ธ 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](https://pnpm.io/installation) (recommended, see note), a DeepSeek API key, and the Feishu app on your phone.
```sh
# 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 `/.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:
```text
/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:
```text
/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 ` names
a device for the roster.
## โจ Features
Highlights โ the ones other bridges don't have:
| | |
|---|---|
| ๐ง **Native Feishu CoT** | Reasoning renders as the platform's own thinking message (`cot`), typewriter card fallback (`stream`) |
| ๐ **Approval cards + decider trail** | Click to decide; who decided is written back |
| ๐ฏ **Live goal / todo cards + auto-resume** | Phase changes stream into chat; `autoResumeGoals` re-arms after restarts |
| ๐ **Session history search** | `/sessions ` full-text search over this chat's stored history |
| ๐ **Bilingual slash panel** | English on international Lark, Chinese on domestic Feishu โ auto |
All capabilities
| | |
|---|---|
| ๐๏ธ One agent per conversation | `sessionScope`: whole chat / topic thread / single sender; sessions persist across restarts |
| โ
Live reactions | `OK` โ `THINKING` โ `DONE`/`ERROR`, states replace each other, configurable |
| ๐ฆ Compaction transparency | "Compactingโฆ" โ summary + released tokens; prunes report trimmed count |
| ๐ง๐ป Subagent fan-out | Workflow runs stream as text lines: run start, child open/end, run end |
| โฐ Scheduled reminders | `/schedules` view (compose `@deepseek-ai/dsh-schedule` for the model-side tools) |
| โ๏ธ Background job notifications | `run_in_background` jobs announce their terminal outcome |
| ๐งฉ Skill ecosystem surface | `/skills` lists workspace skills, `/skills ` peeks at one |
| ๐ค Model switching | `/model /` through the host `saveSelection` seam (persistent) |
| ๐ฅ๏ธ PC-parity tooling | Compose `dsh-terminal*` / `code-runtime-worker-thread` / `dsh-mcp-client` โ persistent PTY, Code Mode, external MCP servers |
| ๐บ๏ธ Workspace visibility | `/ws` lists workspaces and marks where new sessions land |
| ๐ผ๏ธ Image input (opt-in) | `attachImages` passes chat images to the model |
| ๐ File delivery | Agent `send_file` delivers artifacts with caption (default-deny local dirs) |
| ๐ QR onboarding | First boot prints a QR; scanning creates the app with event subscription |
| ๐ Authorization narrowing | `senderAllowlist` / `groupAllowlist` / `approvers` |
| ๐งฉ Chronicle hook | `chronicleEndpoint`: fire-and-forget full-transcript POST per inbound message |
| ๐ก๏ธ Deep dsh adaptation | Everything through host service contracts โ self-contained, no host source needed |
### vs. other Feishu/Lark bridges
| Capability | **dsh-lark-bridge** | xmanrui/dsh-im | omdsh-dev/dsh-lark | AX1202/ax-feishu-bridge |
|---|---|---|---|---|
| Positioning | Deep Harness channel | Multi-platform gateway | Scan-to-use | Pi + DSH dual bridge |
| Native thinking process (Feishu CoT) | โ
| โ | โ | โ |
| Approval cards + decider trail | โ
| โ | โ | remote approve |
| Live goal/todo cards | โ
| โ | โ | โ |
| Workflow fan-out + phase/log lines | โ
| โ | โ | โ |
| Compaction transparency | โ
| โ | โ | โ |
| Goal auto-resume after restart | โ
| โ | crash-safe | โ |
| Bilingual slash panel sync | โ
| โ | โ | panel buttons |
| Session history search + skills/model/ws panels | โ
| โ | โ | โ |
## ๐ฌ Slash Commands
| Command | Description |
|---|---|
| `/stop` | Cancel the running turn |
| `/help` | Show this listing |
| `/preset` | View / switch agent preset (standard / code / minimal / cordis) |
| `/permission` | View / switch permission mode (host) |
| `/goal` | View / set the goal (host) |
| `/plan` | Enter / leave plan mode (host) |
| `/compact` | Compact older history (host) |
| `/sessions` | Search this chat's session history |
| `/tools` | View / deny / allow tools at runtime |
| `/skills` | List skills, or peek at one |
| `/model` | View / switch the default model |
| `/ws` | List registered workspaces |
| `/jobs` | This chat's background jobs |
| `/schedules` | This chat's scheduled reminders |
| `/context` | Current context token pressure |
| `/audit` | Operation audit summary |
| `/config` | The bridge's live configuration |
| `/feedback` | Rate the last answer |
Set `locale: zh|en` to force a language; otherwise it follows the platform domain.
## โ๏ธ Configuration
Essentials:
| Field | Default | Meaning |
|---|---|---|
| `appId`, `appSecret` | first-boot QR registration | Feishu/Lark app credentials |
| `cwd` | host process cwd | Absolute workspace directory for chat agents |
| `provider`, `model` | host default | Model routing for chat agents |
| `output` | `cot` | Native thinking message vs typewriter card |
| `requireMention` | `true` | In groups, respond only when @-mentioned |
| `outbound.allowedFileDirs` | unset โ disabled | Local dirs `send_file` may read from |
| `chronicleEndpoint` | `''` | Optional external full-transcript ledger |
Full option reference: [README.zh.md ้
็ฝฎ](README.zh.md#๏ธ-้
็ฝฎ) ยท credentials resolve in three
layers (bundle patch config โ settings document plugin section โ first-boot QR registration).
Required app permissions (manual app creation)
| Scope | Needed for |
|---|---|
| `application:app_slash_command` (read + write) | Slash panel โ without it sync fails with `99991672` |
| `im:message` / `im:message:readonly` | Send / read messages |
| `im:message.receive_v1` event | Receive messages (Events โ long connection) |
| `im:resource` | Upload images and files |
| `im:chat:read` | Group info |
| `im:message.reactions:read` / `write_only` | Reaction feedback |
QR onboarding grants these automatically; manually created apps must publish a new
version after adding scopes. Panel sync runs on session create/resume โ send the bot
one message after granting.
## ๐งญ 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/`](docs/design/README.md);
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**
```sh
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
Do I need a public IP or webhook?
No. The transport is a WebSocket long connection; the app must use long-connection event
subscription (self-built app).
Which models work?
Any model routable by your dsh deployment โ the bridge is model-agnostic and `/model`
switches at runtime.
The agent says it sent a file but nothing arrives
File delivery is default-deny: configure outbound.allowedFileDirs. URLs and
raw buffers always work.
The slash panel is empty or partial after a restart
Boot registers constant commands; the full panel sync runs on the first message of a
session. Send the bot anything. If it stays empty, check the
application:app_slash_command scope and publish an app version.
What survives a restart?
Sessions resume from their logs; active goals re-arm (autoResumeGoals);
permission and preset choices ride with the session state.
## ๐ Listings & Community
- [dshbase.com](https://dshbase.com/plugins/moyu-good-dsh-lark-bridge/) โ listed & **verified**
(headless L3: install + load + Q&A) ยท [ไธญๆ้กต](https://dshbase.com/zh/plugins/moyu-good-dsh-lark-bridge/)
- [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/2160) โ merged
- [dsh-suite catalog](https://github.com/whyihaveyou/dsh-suite/issues/32) โ 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](https://github.com/Roy-oss1/dsh-lark) (also BSD-3-Clause).