deepseek-harness-lark

Readme

# DeepSeek Harness Lark / Feishu plugin

A DeepSeek Harness channel powered by the official `@larksuiteoapi/node-sdk`. It uses the official WebSocket transport, so no public callback server is required, and supports both Feishu and international Lark.

## Features

- Official WebSocket connection and automatic reconnection
- Direct and group access policies; groups require a bot mention by default
- Text, rich-text, image, and ordinary-file input
- Durable Harness attachments with model-aware multimodal input
- Ordinary files are downloaded into `.dsh-lark/inbox/` under the Agent workspace so filesystem tools can inspect them
- Model text replies, generated-image upload, and workspace-file delivery
- Persistent, isolated Harness sessions per chat; `/new` retains old history and switches to a blank session
- Agent presets are mounted and recorded for both creation and resume; the default is `standard`
- Registered Harness slash commands execute directly instead of being sent to the model
- Same-conversation `/approve <code>` and `/reject <code>` decisions for one-shot tool approvals
- `/bot-ping`, `/bot-help`, `/bot-image-test`, `/bot-file-test`, `/bot-status`, `/bot-cancel`
- App Secret resolution through the Harness credential service
- Dormant startup when App ID or App Secret is not configured, so installation alone never blocks Harness Web

## Requirements

- Node.js 22.19 or later
- pnpm 10.33.4
- DeepSeek Harness 0.1.0-rc.7 or later

## Install

```sh
pnpm dsh plugin --profile web add github:sliverp/DeepSeek-harness-lark
```

For a local checkout:

```sh
pnpm dsh plugin --profile web add /absolute/path/to/DeepSeek-harness-lark
```

## Configure the Lark application

1. Create a custom application in the [Feishu developer console](https://open.feishu.cn/app) and enable its bot capability.
2. Grant `im:message.p2p_msg:readonly`, `im:message.group_at_msg:readonly`, `im:message:readonly`, `im:message:send_as_bot`, and `im:resource`. The `im:message:readonly` scope is required by Feishu's message-resource download endpoint for user-sent images and files.
3. Select long-connection event delivery and subscribe to `im.message.receive_v1`.
4. Publish an application version and add the bot to the required chats.
5. Put the App ID in `LARK_APP_ID` and store the App Secret under the Harness credential reference `LARK_APP_SECRET`.

Environment injection is supported for development:

```sh
export LARK_APP_ID='cli_your-app-id'
export LARK_APP_SECRET='your-app-secret'
pnpm dsh --profile web
```

For durable use, put the App ID in `~/.dsh/.env` and store the App Secret through the Harness credential settings surface. Never commit credentials.

## Bundle configuration

```yaml
- id: lark-channel
  name: deepseek-harness-lark
  config:
    appId: !!js process.env.LARK_APP_ID
    appSecretRef: LARK_APP_SECRET
    cwd: !!js process.env.DSH_LARK_CWD ?? process.cwd()
```

International Lark and restrictive policy example:

```yaml
    domain: lark
    singlePolicy: allowlist
    singleAllowFrom: [ou_xxx]
    groupPolicy: allowlist
    groupAllowChats: [oc_xxx]
    groupRequireMention: true
    imageInputMode: auto
    maxInboundFiles: 10
    maxInboundFileBytes: 52428800
    maxInboundMessageFileBytes: 104857600
    maxReplyFiles: 5
    maxOutboundFileBytes: 31457280
    approvalTimeoutMs: 240000
    agentPreset: standard
```

Access policies accept `open`, `allowlist`, or `disabled`. Use allowlists and least-privilege Harness permissions in production.

Connection and authentication run in the background. Missing or invalid Lark credentials leave this channel offline and are logged without blocking Harness startup.

Inbound images and ordinary files are downloaded through the message-scoped resource endpoint using their matching `message_id` and resource key; this requires `im:message:readonly` (or the broader `im:message`). The separate `im:resource` scope remains necessary for bot-side image/file upload. Filenames are reduced to safe leaf names, files are created without overwriting existing paths, and each message gets a private directory below `<cwd>/.dsh-lark/inbox/`. The defaults allow 10 files, 50 MiB per file, and 100 MiB total per message. The model receives the saved path and must use its normal filesystem tools to read the file; file contents are not executed or silently injected into the prompt.

When the model intentionally returns a regular workspace file, it places an explicit Markdown link to that file in the final visible answer. The plugin resolves the canonical path, rejects missing files, directories, symlink escapes, and every target outside the session `cwd`, then uploads the bounded bytes with Lark's file API. Only the final assistant message is inspected; intermediate tool output cannot trigger a file send. By default, one reply may send up to 5 non-empty files of at most 30 MiB each.

When Harness requests tool approval, the plugin sends a requester-bound six-digit code to the originating chat. Reply `/approve <code>` to allow that operation once or `/reject <code>` to deny it. Codes are one-shot, cannot cross chats, bypass ordinary message capacity while the original turn waits, and fail closed on timeout, cancellation, send failure, or shutdown. `approvalTimeoutMs` must remain below `responseTimeoutMs`.

`agentPreset` is the explicit fallback for new sessions and persisted records without a preset. The tool-loop fix advances the plugin session namespace from `lark-v1-*` to `lark-v2-*`: existing files are neither deleted nor rewritten, but the plugin no longer appends to potentially DSML-contaminated `lark-v1-*` records. They remain available for inspection in the Web UI.

## Verify

Send `/bot-ping`, `/bot-image-test`, `/bot-file-test`, and `/new`. The bot should return `pong`, a blue diagnostic image, a downloadable text file, and confirmation that it switched to a blank session. Send ordinary text, an image, and a CSV file; ask the bot to inspect the CSV and verify that it uses the downloaded workspace path. Then ask it to create and send a CSV; the final reply should contain the file attachment. Request an operation that needs approval and reply with the exact `/approve <code>` or `/reject <code>` shown; the same turn should continue or stop without using the Web approval panel.

## Develop

```sh
pnpm install
pnpm run check
pnpm pack
```

The repository uses PNPM `10.33.4`. Plugin runtime requires Node.js `>=22.19` and does not require PNPM 11.

Protocol and configuration behavior were cross-checked against [larksuite/openclaw-lark](https://github.com/larksuite/openclaw-lark). Transport and media operations use the official Lark Node SDK. MIT licensed.