# dsh-lark-cli

English | [简体中文](README.md)

In one sentence: **let your AI assistant operate Feishu for you directly** — send messages, write docs, check schedules, manage tasks, and work spreadsheets without leaving the chat.

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) plugin for Feishu / Lark access. Once installed, you give instructions in natural language and the model drives the official `lark-cli` through the `lark_cli` tool:

| You say | The model does |
|---|---|
| "Send the meeting notes to the product group" | `lark-im` posts the message to the chat |
| "Write a PRD from this material and save it to Docs" | `lark-doc` creates the doc and fills it in |
| "What meetings do I have next week" | `lark-calendar` queries your agenda |
| "Turn the to-dos in this sheet into tasks" | `lark-sheets` reads the data → `lark-task` creates tasks |
| "Add a page about X to the wiki" | `lark-wiki` creates the node → `lark-doc` writes the content |

Design principle: **the official `lark-cli` does the work, skills teach the model how to drive it** — execution and knowledge are separated.

- **One tool**: `lark_cli`, whose arguments are `argv` (the command split into words, without the leading `lark-cli`) plus an optional `stdin`. No shell, so no quoting, escaping, or injection surface.
- **Nine skills**: `lark-shared`, `lark-doc`, `lark-im`, `lark-calendar`, `lark-task`, `lark-drive`, `lark-sheets`, `lark-base`, `lark-wiki`, shipped with the plugin and loaded on demand.
- **Zero credentials in the plugin**: login state and secrets stay with `lark-cli` (`~/.lark-cli/config.json` plus the system keychain). Nothing is stored or forwarded here.

## Requirements

| Item | Requirement |
|---|---|
| dsh compatibility | [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) **>= 0.2.0-rc.2** (verified version; requires the `defineTool` / `ctx.subprocess` / `ctx.skills.registerProvider` plugin APIs and the `dsh.profile.bundles` bundle mechanism) |
| Operating system | **Windows 10/11** (primary verified platform, with built-in `.cmd` shim → `.exe` auto-detection); **macOS / Linux** should work (`lark-cli` itself is cross-platform) but are not individually verified |
| Node.js | >= 22.0.0 |
| lark-cli | >= 1.0.96 (`npm install -g @larksuite/cli`) |
| Network | Access to the Feishu OpenAPI endpoints |

## Prerequisites

1. `lark-cli` >= 1.0.96 installed: `npm install -g @larksuite/cli`.
2. CLI-side setup and login done once in a terminal:
   - `lark-cli config init` (first run, configure the app)
   - `lark-cli auth login` / `lark-cli auth status` (confirm the identity)

The plugin never logs in and never stores appId / appSecret.

## Install

Four install options — pick one; after any of them, finish wiring with "[Mount into a profile](#mount-into-a-profile)".

### Option 1: Release tarball (recommended, zero-clone)

Download the Source code (tar.gz) for a version from the [Releases](https://github.com/aminuoshi-378/dsh-lark/releases) page, or fetch it directly (replace `v0.1.0` with the target version):

```bash
curl -LO https://github.com/aminuoshi-378/dsh-lark/archive/refs/tags/v0.1.0.tar.gz
tar -xzf v0.1.0.tar.gz              # unpacks to dsh-lark-0.1.0/
cd dsh-lark-0.1.0
npm install                          # the prepare script runs tsc to produce dist/
```

Alternatively, hand the Release link to the model in a dsh session and let it download, unpack, install, and wire everything up.

### Option 2: one-shot install from the GitHub link

No clone needed — register the GitHub repo directly as a dependency (the package's `prepare` script runs the build automatically during install):

```bash
# inside ~/.dsh/profiles/web
pnpm add dsh-lark-cli@github:aminuoshi-378/dsh-lark#main
```

> How it parses: `dsh-lark-cli` is the package name (must match the repo's `package.json` `name`); `@github:user/repo#main` installs from the `main` branch on GitHub (`#` can also take a tag, e.g. `#v0.1.0`). pnpm shallow-clones the branch → runs the `prepare` script (the `tsc` build) → installs what `files` declares (`dist / cordis.yml / skills`) into `node_modules`.

### Option 3: build from source

Best when you plan to modify skills or source locally:

```bash
git clone https://github.com/aminuoshi-378/dsh-lark.git dsh-lark-cli
cd dsh-lark-cli
npm install
npm run build
```

Then point the profile at your local directory with `link:` (see "Mount into a profile"); local edits take effect immediately with no re-publish.

### Option 4: prompt-driven install (let the AI session do it)

Paste this into a dsh chat and the model performs the install for you:

```text
Please install the dsh-lark-cli plugin for me:
1. Clone https://github.com/aminuoshi-378/dsh-lark locally;
2. Run npm install && npm run build in the repo;
3. Following the README "Mount into a profile" section, wire the plugin into
   ~/.dsh/profiles/web (package.json dependency + bundle + cordis.patch.yml);
4. Run dsh --profile web --dump-config and verify the lark-cli entry appears.
```

The model executes each step with its shell tool; writes to profile config files are outside the workspace, so it will ask for your approval first.

## Mount into a profile

After installing via any option, mount the plugin into a profile (`web` shown here):

1. `~/.dsh/profiles/web/package.json`
   - add `"dsh-lark-cli": "link:D:/Code/projects/dsh-lark-cli"` to `dependencies`
   - append `"dsh-lark-cli"` to `dsh.profile.bundles`
2. `~/.dsh/profiles/web/node_modules/dsh-lark-cli` must point at this repository (`pnpm install` creates it; otherwise create a directory link / junction yourself).
3. Append to `~/.dsh/profiles/web/cordis.patch.yml`:

```yaml
- id: lark-cli
  name: 'dsh-lark-cli'
  config:
    executable: lark-cli
    timeoutMs: 60000
```

4. Restart `dsh web`. Verify: no `did not activate` warning on startup, and `dsh --profile web --dump-config | grep lark-cli` shows the entry.

Rollback: remove the three changes above and restart. The plugin repository and workspace are unaffected.

## Upgrading

When a new version is released, update according to how you installed; the profile wiring (package.json / bundle / cordis.patch.yml) never needs changes — just restart `dsh web` after updating.

**Option 1 / Option 3 (GitHub link install)**: pull and rebuild:

```bash
cd dsh-lark-cli          # or whatever you named the clone
git pull
npm install && npm run build
```

If you installed via `pnpm add dsh-lark-cli@github:...`, run the same `pnpm add` command again to fetch the new version. You can also have the model in a dsh session do it for you (paste the commands above, or reuse the "Option 3: prompt-driven install" prompt, saying it's an upgrade).

**Option 2 (source build)**: in your local repo run `git pull && npm install && npm run build`; since the profile points at the directory via `link:`, the update takes effect after restarting `dsh web`.

**Check your version**: `git describe --tags` (clone install) or the `version` field in `package.json`; release notes live on the [Releases](https://github.com/aminuoshi-378/dsh-lark/releases) page. After upgrading, run `npm test` once to confirm the environment is healthy.

## Skills

Nine skills ship with the plugin; the model loads the relevant one per task. Each skill directory also carries `references/` sub-documents (read on demand by relative path) with finer-grained command syntax and scenario playbooks.

### `lark-shared` — shared rules & auth (required reading)

The common foundation for every Feishu operation: identity selection (`--as user` vs `--as bot`), auth and login-state troubleshooting, the JSON output contract, the high-risk write confirmation gate, and the key "**in dsh**" execution rule — no shell here; every `lark-cli` command is split into `lark_cli` tool `argv` (how to rewrite pipes / `&&` / redirections, and how to filter with `--jq`). The model reads this skill before using any other lark skill.

### `lark-doc` — cloud docs / Docx

Create, read, and update docs (including the XML block-level structure), Markdown round-trip, version history; insert and download images/attachments; mind notes; whiteboards; a dozen writing-genre templates (PRD, weekly report, meeting minutes, Xiaohongshu, official letters, research reports, ... in `references/genres/`); plus create-then-run-workflow combos.

### `lark-im` — messaging

Send / reply / edit / unsend semantics for DMs and group messages; message and chat search; group members, settings, and topic groups; interactive cards (full Card 2.0 component schema: buttons, forms, charts, columns, images, ...); reactions; urgent pings (in-app / SMS / phone call); feed pins and tag management.

### `lark-calendar` — calendar

Event create / update / cancel (including recurring RRULE events), all-day and fuzzy time expressions, attendee management and RSVP, free/busy queries and slot suggestions, meeting-room search and booking, cross-calendar event transfer, event-to-meeting (video conference) relations.

### `lark-task` — tasks

Task create / update / complete / reopen, subtask decomposition and ancestor setting, tasklist management and members, task search and related-task queries, collaborators and followers, reminders and attachment upload, task-agent registration/unregistration and homepage data.

### `lark-drive` — drive

Browse / search / move / copy / delete files, upload and download (including export to docx/sheet formats), folders, shortcuts, version history; comments and replies (with reactions); permissions (member management, settings, permission requests); secure labels; plus several multi-step playbooks: knowledge organization, topic-move collectors, permission governance.

### `lark-sheets` — spreadsheets

Sheet and row/column structure (add/remove, merge, freeze, group, hide), cell read/write (values / formulas / styles / comments / in-cell images), range copy-move-sort, pivot tables, conditional formatting, dropdowns, charts and sparklines, floating images, formula validation; Excel / CSV import and export.

### `lark-base` — Bitable

Data tables and fields, record CRUD and batch operations, views, grouping / filtering / sorting, formula and lookup fields, form views, dashboards, automation workflows (including the AI text-generation action), field-extension bulk writes, roles and permissions, templates; AppMode (Base app) pages and components; `.base` file import/export.

### `lark-wiki` — knowledge base

Wiki space list, node tree browsing and search, node create / move / copy / delete, space member management; plus the "wiki URL → underlying object token" routing rule (a `/wiki/` link is unwrapped to a docx/sheet/bitable and routed to the matching skill).

> Each skill's directory is exposed through `resourceBase`, so `references/...` links resolve by relative path.

## Tests

```bash
npm test              # pure functions + skill snapshot + registration behaviour (offline)
npm run test:tool     # real lark-cli: auth status / calendar +agenda / error routing / argv defence
npm run test:live     # read-only probe: resolution path, --version, auth status
```