dsh-channel-feishu

Feishu (Lark) channel plugin for DeepSeek Harness — turn a Feishu bot into a full DSH agent with the same capabilities as the Web UI: tool calls, filesystem access, shell commands, skills, web search, everything.

飞书通道插件:让飞书机器人具备与 DeepSeek Harness Web UI 完全一致的 Agent 能力(工具调用、文件系统、Shell、Skills 等)。

English | 简体中文

---

Features

• 🧠 Full DSH agent capability — the bot drives a real DSH agent via ctx.agents, so it can read files, run shell commands, use skills, and more — identical to a Web UI session.
• 🤖 Multiple bots in parallel — each bot uses its own lark-cli profile (larkCliProfile), so any number of bots run side by side without interfering.
• 🔌 Independent of any external gateway — the plugin owns its Feishu connection (WebSocket long connection) and drives agents in-process; it never depends on Hermes or another process.
• 🧩 Standard DSH bundle — installable with dsh plugin add ./plugin; follows the official dsh.bundle manifest.
• 🔒 Secret-safe — credentials live in the lark-cli keychain / profile, never in patch files or logs.

---

How it works

Feishu user ──chat──▶ Feishu bot
                          │  WebSocket long connection
                          ▼
               lark-cli event consume im.message.receive_v1
                          │  NDJSON event stream
                          ▼
        dsh-channel-feishu plugin (in-process)
                          │  ctx.agents.create/resume + agent.send()
                          ▼
              DSH agent runtime (full native tools)
                          │  assistant/message events
                          ▼
Feishu user ◀──reply── Feishu bot

• One chat = one persistent DSH session (feishu:<chat_id>), history survives restarts via DSH session persistence.
• Agents join the standard agent preset through agentPresets.mount(), which is what gives the bot the full tool set.
• Self-echo guard, per-chat turn lock, and auto-reconnect are built in.

---

Requirements

• DeepSeek Harness installed and built (see DSH README):

  git clone https://github.com/deepseek-ai/deepseek-harness.git
  cd deepseek-harness && pnpm install && pnpm run build
  

• lark-cli installed (npm i -g @larksuite/cli).
• A Feishu bot with the scopes and event subscription configured (see Setup Guide).

---

Quick start

The scripts/ are designed to be run by an LLM agent (including a low-capability local LLM) following SKILL.md. They are self-guarding, absolute-path, and write progress to progress.log.

# 1. Environment check
bash scripts/doctor.sh --deps          # expect "DEPS OK"

# 2. Install the plugin into a profile (default: web)
bash scripts/install.sh --dir ~/deepseek-harness
#    expect "INSTALLED"

# 3. Configure a bot (appId + secret → credentials file + profile patch)
bash scripts/configure.sh --app-id cli_xxx --secret <SECRET> --profile web
#    expect "CONFIGURED"

# 4. Start & verify (double check: PROCESS OK + PROGRESS OK)
bash scripts/verify.sh --profile web
#    expect "VERIFY OK"

Feishu console setup (scopes + im.message.receive_v1 long connection) must be done manually by the user — see Setup Guide. The permission JSON template is in required_scopes.json.

---

Multiple bots

Each bot is one plugin instance with its own lark-cli profile:

# 1. Create a lark-cli profile for the second bot
printf '%s' '<SECRET>' | lark-cli profile add \
  --name mybot2 --app-id cli_xxx --app-secret-stdin --brand feishu

# 2. Add a second instance in ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: feishu-channel-mybot2
      name: '@deepseek-ai/dsh-channel-feishu'
      config:
        appId: cli_xxx
        larkCli: /path/to/lark-cli
        larkCliProfile: mybot2
        sessionPrefix: feishu
        agentPreset: standard
        provider: deepseek-official
        model: deepseek-v4-flash

Restart the web profile. Both bots now run in parallel with isolated credentials and session namespaces.

---

Configuration reference

Key	Default	Description
appId	— (required)	Feishu app id (cli_xxx)
appSecret	—	App secret (omit when larkCliProfile is set)
secretEnv	LARK_APP_SECRET	Env var holding the secret
larkCli	lark-cli (PATH)	Path to lark-cli executable
larkCliProfile	—	lark-cli profile name (multi-bot isolation)
sessionPrefix	feishu	Session id prefix
agentPreset	standard	Agent preset joined by the bot's agents
cwd	DSH workspace	Working dir for the bot's sessions ({{cwd}})
provider	deepseek-official	LLM provider route
model	deepseek-v4-flash	LLM model id
reconnectDelayMs	3000	Event stream reconnect backoff

Secret resolution order: config.appSecret → env var → DSH credentials file. The secret is never logged.

---

Repository layout

dsh-channel-feishu/
├── SKILL.md                    # Executable install Skill (for LLM agents)
├── README.md                   # English docs
├── README.zh.md                # 简体中文 docs
├── plugin/                     # The DSH bundle (source + prebuilt lib)
│   ├── src/index.ts            # Plugin source
│   ├── lib/index.js            # Prebuilt bundle (no build needed to install)
│   ├── package.json            # dsh.bundle manifest
│   ├── cordis.patch.yml        # Bundle patch
│   └── tsdown.standalone.config.ts  # Standalone rebuild config
├── scripts/                    # Self-guarding helper scripts
│   ├── doctor.sh               # Dependency check
│   ├── install.sh              # Install + peer-dep auto-linking
│   ├── configure.sh            # Write config + credentials
│   └── verify.sh               # Startup verification (double check)
├── references/
│   ├── SETUP_GUIDE.zh.md       # Feishu console setup + DSH version compat
│   ├── TROUBLESHOOTING.md      # Troubleshooting
│   └── CHANGELOG.md            # Version history
└── required_scopes.json        # Feishu permission import template

---

Troubleshooting & compatibility

See references/TROUBLESHOOTING.md and the Setup Guide — including the "lib 不可用 / DSH version upgrade" flow:

• lib/index.js broken after a DSH upgrade? Rebuild with npm run build (uses tsdown.standalone.config.ts) after checking the DSH docs for peer-API changes.
• Bot receives messages but never replies? Check DSH_PERMISSION_MODE (must be danger-full-access for headless channels), keepalive scripts must use absolute pnpm path, and stale sessions may need clearing + restart. Details in the changelog.

---

License

MIT