dsh-lark

English | 中文

A minimal Lark/Feishu gateway plugin for DeepSeek Harness: mention the bot in Feishu (or DM it) to drive the dsh agent on your machine, replies land back in the same conversation. One topic = one agent session.

Inspired by botmux — the pioneer that bridges Feishu/Lark to AI coding CLIs. dsh-lark borrows its "topic = session, mention = task" interaction and brings that experience to DeepSeek Harness as a native plugin.

Three design goals: pleasant to use, clean architecture, lightweight. Four source files, ~600 lines. No card pipelines, no pairing codes, no multi-project routing — just the essential "talk to your agent from Feishu" loop.

Features

• WebSocket long connection — no public callback URL needed, works from a laptop
• Session mapping — one session per DM; topic messages are isolated per topic while plain group messages share one session per chat (configurable); the bot never opens topics on its own — it replies where you spoke; sessions persist and resume across restarts
• Image input — pictures sent in Feishu reach the model natively (when the model supports vision)
• File delivery — agents get a built-in lark_deliver tool to send workspace files/images back to the chat (strictly contained to the working directory)
• Single-card interaction — one task = one card updated in place end to end: status (running → completed/stopped/error), live execution steps (one line per tool call), and the reply body all inside the card, with a dsh Web button at the bottom; nothing is ever recalled, and only oversized replies spill into one extra message
• Tool approvals — sensitive actions pop an approval card with one-tap Allow/Reject buttons in Feishu (/approve / /reject commands and the dsh Web panel also work — first answer wins)
• Safe by default — open_id allowlist is on by default; strangers receive their own open_id once, ready to copy-paste to the operator

Install (one command)

dsh plugin --profile web add "github:keepview/dsh-lark"

The build artifact is committed (lib/), so the plugin works right after install — no local build step.

Setup

1. Create a Feishu/Lark custom app

On the Feishu Open Platform (or Lark Developer with brand: lark):

1. Add the bot capability
2. Grant permissions: im:message, im:message:send_as_bot, im:resource
3. Event subscription: choose long connection mode, subscribe to im.message.receive_v1
4. Callback configuration: under Events & Callbacks → Callback, also choose long connection (approval-card button taps arrive through it)
5. Publish a version and grab the App ID and App Secret

2. Provide credentials

Environment variables are the recommended path (profile config also works):

export DSH_LARK_APP_ID=cli_xxx
export DSH_LARK_APP_SECRET=xxx
export DSH_LARK_ALLOWED_OPEN_IDS=ou_xxx   # your open_id; message the bot once to learn it
cd your-project
npx @deepseek-ai/dsh web

With no credentials configured the plugin stays idle with a hint instead of blocking dsh startup; a failed connection likewise logs an error without taking dsh down.

3. Chat

• DM the bot directly, or
• add it to a group and @mention it; in topic groups every topic is its own session

Configuration

Commands

/steer <text> · /stop · /new · /sessions · /resume <id> · /approve · /reject · /status · /help — any other /command falls through to Harness native commands.

Architecture

src/
  index.ts      Cordis plugin entry (30 lines): inject + lifecycle
  config.ts     config schema + env merging (100 lines)
  sessions.ts   session keys / ids / small utilities (70 lines)
  gateway.ts    Feishu channel ↔ agent bridge (400 lines)

• The Lark protocol layer is fully delegated to the official @larksuiteoapi/node-sdk (long connection, reconnect, dedup, rate limiting, markdown conversion)
• The agent layer only uses public dsh APIs (ctx.agents, session/event, followup)
• The bundle has zero runtime dependencies (Lark SDK is inlined; @deepseek-ai/* stay external and are provided by dsh)

When to pick which

Need progress cards, project routing, or pairing flows? Use dsh-lark-bridge. Want a gateway you can read end-to-end in ten minutes? This one.

Security notes

• Unlisted users are rejected by default; allowAllUsers means anyone who can reach the bot can drive an agent on your machine
• lark_deliver only sends files inside the agent working directory (SDK allowedFileDirs plus a plugin-side check)
• Approval relay forwards dsh approval requests; the approval policy itself is your dsh profile's business
• DeepSeek Harness is a developer preview; evaluate its own sandbox boundaries (broad reads, unrestricted egress) for your deployment

Development

pnpm install
pnpm run check   # typecheck + test + build

License

MIT