lark-cli-router

Lark CLI Router

Use this as the only model-visible Lark entry point. The CLI's embedded lark-* guides are the version-synced source of truth; this router selects and loads them instead of copying their domain instructions into another static catalog.

Boundaries

• Tencent IMA is a different product. Route IMA notes or knowledge-base tasks to ima-skill, not here.
• Do not load all Lark guides. Select the smallest matching guide set for the current task.
• Do not bypass lark-cli with browser automation, raw curl, or guessed API contracts while the CLI or one of its embedded guides covers the task.

Workflow

1. Confirm the runtime

Run lark-cli --version. If the binary is absent, fail visibly and report that lark-cli is required; do not invent another transport or confuse the separate Skill-install command with a CLI-binary installer.

Set LARK_CLI_NO_PROXY=1 for every invocation in this environment. When stable machine-readable JSON is needed, also set LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 and LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 so notices do not pollute the result.

2. Select the embedded guide

Run lark-cli skills list --json. Match the user's intent and any URL path or token to the returned name, description, and metadata.cliHelp.

Do not derive the CLI domain by stripping lark- from the guide name: exceptions exist, and metadata.cliHelp or the guide itself is authoritative. These high-confusion routes need explicit care:

Intent	Guide
auth, login, profile identity, missing scope, user vs bot	lark-shared
/wiki/ document content	lark-doc
wiki space, membership, or node hierarchy	lark-wiki
future meeting or room scheduling	lark-calendar
ended meeting search, participants, or meeting artifacts	lark-vc
known note_id	lark-note
minute_token, 妙记 content, or audio-to-minutes	lark-minutes
live meeting participation or in-meeting events	lark-vc-agent
file upload, download, move, permissions, metadata, or Office import	lark-drive

For ordinary docs, sheets, Base, slides, mail, IM, tasks, approval, apps, and other domains, the live skills list descriptions are the routing table. A multi-domain request may select a workflow guide or a small ordered set of domain guides.

3. Load the selected instructions completely

Read the selected guide before acting:

lark-cli skills read lark-doc
lark-cli skills read lark-doc/references/lark-doc-fetch.md

The first form prints the guide's SKILL.md; the second reads a referenced file. Read every file the selected guide marks required for the current branch.

Embedded reads reject ... Rebase a sibling pointer such as ../lark-whiteboard/references/x.md to:

lark-cli skills read lark-whiteboard/references/x.md

Always try lark-cli skills read first for Markdown and reference files. If it returns reference ... not found, resolve that exact guide-relative path under ~/.agents/skills/<guide-name>/. Before the first such fallback for a guide, confirm with the host's SHA-256 tool that its installed SKILL.md is byte-identical to lark-cli skills read <guide-name>; a mismatch must fail visibly and trigger a bundle refresh. This explicitly keeps lark-apps/creative-design/ reachable even though the current binary does not embed it.

Machine resources under scripts/ or assets/ are never embedded, so resolve them directly in the same installed bundle. If a required file is absent, stop and report that the disk bundle must be installed or refreshed; do not fabricate a replacement.

4. Inspect, execute, and verify

1. Treat metadata.cliHelp as a help recipe, not always a literal command. Run its concrete commands; resolve any placeholder from the loaded guide first. If the field is absent, use the guide's own commands or the selected domain's --help.
2. Prefer a matching +shortcut; otherwise use a typed resource command.
3. Before a typed call whose parameters are not already explicit in the guide, run lark-cli schema <service.resource.method>.
4. Use lark-cli api only as the documented escape hatch when no shortcut or typed command covers the endpoint.
5. Preserve any explicitly supplied --profile; never guess a profile or identity. Use lark-cli whoami when identity is material or ambiguous. Before a read through another existing profile, confirm that it belongs to the requesting user and that the profile/read is already authorized. Keep --profile explicit; do not switch the global profile or enumerate unrelated accounts. If ownership is unknown, skip that candidate and report the gap. Different app-specific openIds alone do not establish different people.
6. For writes, use --dry-run when the command supports a useful preview. If a high-risk write exits 10, present the proposed action and wait for explicit human confirmation; never append --yes automatically.
7. Separate transport completion from business success. Process exit 0 alone does not prove the requested result; for JSON output, inspect ok and errors as well. Outer ok == true does not prove each item succeeded. Do not test for a top-level code == 0; interpret domain results using the loaded guide. For batches, reconcile each requested resource identity with its returned item, error and expected result/artifact. Identify missing, duplicate and unrequested items; a duplicate never fills a missing request. Count verified successes, explicit failures and missing/unknown results against the request total, counting each requested identity at most once; report anomalies separately, and report partial whenever any requested result is not verified. For example, three requested items with one verified result, one permission error and one missing item are partial: 1/3 successful, 1 failed, 1 missing, even with exit 0 and outer ok == true.
8. After a write, follow the selected guide's domain-specific verification contract. If it defines none, perform the narrowest independent read that proves the requested state changed. A guide that explicitly forbids an opportunistic second query takes precedence. Report partial results or missing coverage.

On authentication or permission errors, load lark-shared and its embedded lark-shared/references/lark-shared-identity-and-permissions.md. Follow its user/bot and missing-scope branch, and interpret the current CLI's auth status:

lark-cli --profile "<authorized-profile>" auth status --json

Do not classify needs_refresh as unusable login. When the status says it will auto-refresh on the next user API call, an already-authorized ordinary read may proceed with explicit --profile and --as user; let the CLI renew normally. Do not initiate login, new grants/scopes or manual credential writes merely to handle that state. A ready token still does not prove target read permission.

Scope an actual target read-permission denial to its target/profile/identity and stop that route. Do not turn authentication failures or that refusal into retry loops or browser/raw-API fallbacks. It does not prove that every other already-authorized profile of the requesting user is denied. Assess another profile only after the ownership/authorization check above, and verify its own target result rather than assuming access.