soia-cwork-feishu-cli

soia-cwork-feishu-cli

Use the official Feishu lark-cli to connect to a Feishu app explicitly authorized by the user, and perform read-only inventory, search, and document analysis separately for "knowledge base/Wiki" and "cloud drive/Drive". By default, use the app identity bot; only when the user explicitly requests access to a personal cloud drive, personal knowledge base, or private resources should user OAuth be used. By default, do not modify remote Feishu content; writing, moving, deleting, permission changes, sending messages, and exporting personal data must all be confirmed separately.

Scenario routing: knowledge base and cloud drive must not be mixed

Scenario	Default identity	Primary objects	When to use user OAuth	Detailed rules
Knowledge base / Wiki	bot	Knowledge spaces, Wiki nodes, Wiki documents	The user explicitly requests a personal knowledge base or a private knowledge base not visible to the bot	wiki-workflow.md
Cloud drive / Drive	bot	Shared folders, documents visible to the app, file metadata	The user explicitly requests "my cloud drive / my folders / personal documents"	drive-workflow.md

Do not treat Wiki space/node APIs as cloud drive directories, and do not interpret the bot's empty search results as the user's personal cloud drive being empty.

Two permission types: whether both need to be requested

Feishu manages permissions separately for the same API capability by calling identity:

• App identity permissions：tenant_access_token, at runtime it is bot. Request them on the "App identity permissions" tab; you also need to configure app data permissions, availability scope, or add the app to the target knowledge base/folder.
• User identity permissions：user_access_token, at runtime it is user. Request them on the "User identity permissions" tab; then the user executes lark-cli auth login to complete OAuth, and the access scope follows the logged-in user.

If the goal is "Bot reads the enterprise knowledge base + user OAuth reads the personal cloud drive", you need to request the corresponding minimal read-only scopes separately on the two tabs. When using only one of these identities, do not request the other permission redundantly. For the specific list, refer to permissions.yml the identity_modes of

Customer-readable explanation

What this skill can do

Customer wants	The skill will do	Customer can see
Research Feishu cloud drive and knowledge base usage	Check app identity, visible spaces, node tree, document types, files, and permission metadata	Structured inventory, accessed scope, invisible scope, and evidence commands
Read, summarize, or compare Feishu documents	First identify the URL type, then follow lark-doc rules to read the body and outline	Document summaries, citation locations, formatting, and permission restrictions
Search Feishu knowledge bases, documents, and cloud drives	Use Drive Search or Wiki node queries; do not guess tokens or parameters	Matching documents, titles, types, spaces, and the next reading scope
Install or repair the Feishu CLI	Install the official CLI, configure app credentials, and check token, identity, scope, and connectivity	Command output summaries; never print App Secret or access token

How customers use it

You can say directly:

• "Use the Feishu CLI to inventory the knowledge base hierarchy and cloud drive document types I can see."
• "Read this Feishu Wiki page and determine which open-source, locally deployed product it is better suited for migration to."
• "Check which knowledge spaces and documents the Feishu app can currently see, and do not modify anything."

Before execution, resolve source、target、scope、as and output. For this skill's research tasks, the default is as=bot、read_only=true、dry_run=true(when write operations are involved); do not silently switch to user OAuth just because the bot cannot see the user's personal resources.

Dependencies and installation

Install this skill:

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-cwork-office@soia

When you only need this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if plugins are also installed, the same skill will have two indexes and they will drift independently, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-cwork-office-skills -g -a '*' -s soia-cwork-feishu-cli -y

Dependency	Type	Installation / configuration	What to do when missing
Node.js/npm or an environment that can run npx	Hard dependency	After installing Node.js, run npx @larksuite/cli@latest install	Stop and explain that Node.js/npm needs to be installed
Official lark-cli	Hard dependency	npx @larksuite/cli@latest install; install the official companion skills as needed:npx skills add larksuite/cli -g -y	Can only conduct public information research; must not claim to have read the user's Feishu
Feishu app credentials	Hard dependency	Use profile add or this skill's script to write the provider-owned CLI configuration	Stop remote research; do not ask the user to send the Secret into the chat
API permissions already enabled for the Feishu app	Hard dependency	Enable the required scopes on the Feishu Open Platform; prefer read-only permissions	Record the missing scopes and the official console link

After installation, first run:

lark-cli doctor
lark-cli profile list
lark-cli auth status --json --verify
lark-cli whoami

WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it; it needs to be installed separately, see docs/install/workbuddy.md。

Permission enablement and app release

Before the first research session, or when the CLI returns an error, first readMachine-readable permission catalogandError catalog, then followPermission Enablement Guideto explain the application process to the customer. First determine whether the target is a knowledge base or cloud drive, then determine whether to use bot or user OAuth; do not treat user OAuth scopes as bot permissions, and do not apply for write, delete, upload, or member management permissions just to read.

The Open Platform entry is assembled using LARK_APP_ID from the private configuration:

https://open.feishu.cn/app/<APP_ID>/auth

The complete loop must be completed: in "Development Configuration → Permission Management," enable and save according to the permission requirements of the target API → check the tenant app data permissions and resource visibility scope → create a version for permissions requiring review and submit it for online release → wait for enterprise administrator approval → rerun setup_app_credentials.py --use、auth status --json --verify and representative read-only commands. Review-exempt permissions can be tested directly; "under review" is not considered as permissions having formally taken effect.

Each time you report permissions back to the customer, divide them into three categories: "required," "optional," and "do not enable by default," and list the missing scopes, official console entry, and release steps; do not write the customer's real App ID into public skill files.

App credential login (bot mode)

App credentials are the default login method for this skill and do not call lark-cli auth login as the default flow. App credentials only obtain a bot identity: they can only read resources that are visible to the app, granted app access, or allowed by tenant policies; they cannot automatically read personal knowledge bases, personal cloud drives, or private documents on behalf of a user.

It is recommended to place credentials in a skill-specific private configuration, without committing them to a repository or writing them into a vault:

~/.config/soia-skills/soia-cwork-feishu-cli/config.yml
SOIA_CWORK_FEISHU_CONFIG_FILE=<custom-config-path>

For a configuration example, see assets/config.example.yml. The configuration may only contain placeholders or the user's own local values:

version: 1
env:
  LARK_APP_ID: "<YOUR_APP_ID>"
  LARK_APP_SECRET: "<YOUR_APP_SECRET>"
  LARK_PROFILE: "feishu-reader"
  LARK_BRAND: "feishu"

When using the configuration to initialize an app profile, the script passes the Secret via stdin and does not put the Secret into process arguments or logs:

python3 <skill-path>/scripts/setup_app_credentials.py

On first initialization or when the local profile does not exist, use --use to make it the current profile:

python3 <skill-path>/scripts/setup_app_credentials.py --use

When refreshing the App Secret, App ID, or brand of an existing profile, it must be explicitly initiated by the user, then use:

python3 <skill-path>/scripts/setup_app_credentials.py --replace --use

Because lark-cli does not allow the same App ID to exist in two profiles at the same time, refreshing will first delete the old profile and then write the new profile; therefore, only execute it when the private configuration has been confirmed correct and the user has explicitly requested a refresh. If the write fails, check the private configuration and rerun initialization. After completion, verify:

lark-cli profile list
lark-cli auth status --json --verify
lark-cli whoami
lark-cli doctor

If invalid_client, error code 20140 , or "The auth method is not supported." appears, this is a profile/app credential authentication failure, not a missing scope; first fix the profile according to errors.yml , then check permissions.

If you need to switch a new profile to the default profile, you must explicitly use:

python3 <skill-path>/scripts/setup_app_credentials.py --use

The equivalent manual method is:

printf '%s' '<YOUR_APP_SECRET>' | lark-cli profile add \
  --name feishu-reader \
  --app-id '<YOUR_APP_ID>' \
  --app-secret-stdin \
  --brand feishu

Do not put LARK_APP_SECRET into shell history, command-line arguments, logs, commit records, or Feishu documents.auth login is user OAuth authorization and can only be used when the user explicitly requests personal resources or explicitly specifies --as user .

User OAuth login (personal resources only)

When the user explicitly requests a personal cloud drive, personal knowledge base, or private resources, first read the corresponding wiki-workflow.md or drive-workflow.md, confirm the user identity scope, then use split-flow:

mkdir -p "${TMPDIR:-/tmp}/soia-cwork-feishu-cli"
lark-cli auth login --scope "<minimal-user-scopes>" --no-wait --json
lark-cli auth qrcode '<verification_url>' --output "${TMPDIR:-/tmp}/soia-cwork-feishu-cli/feishu-user-oauth.png"

After handing the authorization link and QR code to the user, end this round; after the user confirms completion, the agent executes lark-cli auth login --device-code <device_code>, then checks whether auth status --json --verify is user: ready. Do not treat user OAuth as a bot repair method, and do not silently switch identities when the user has not explicitly requested it.

The authentication chain must be distinguished:

• lark-cli auth login: the official CLI's user identity OAuth/device flow; only after completion will user: ready。
• https://accounts.feishu.cn/oauth/v1/device/verify?...appear: the verification entry point for the CLI device flow. If it redirects to open.feishu.cn/page/scope-authorization and displays "Application submitted, under review", it means the app's user identity scope or app version has not yet taken effect; this does not mean the user has completed login.
• https://open.feishu.cn/open-apis/authen/v1/user_info: the "Get user info" API after login is completed, which requires an existing user_access_tokenand cannot be used as a login entry point.
• If a self-built web app implements OAuth on its own, use the official authorization code endpoint /open-apis/authen/v1/authorize, configure redirect_uri , and then exchange for user_access_token; do not manually assemble this URL for CLI tasks, as the CLI already encapsulates it with device flow.

The same App ID can generate both the Bot's tenant_access_tokenand, as an OAuth client, the user's user_access_token; the page showing the same app name cannot prove whether it is currently Bot or User. Use auth status --json --verify 's identities.bot / identities.user and the command's --as as the standard.

Read-only research workflow

1. Check identity and scope: first readmachine-readable permission catalog, and if necessary readerror catalogandpermission enablement guide; run lark-cli auth status --json --verify、lark-cli whoami; record identity, profile, token status, and non-sensitive scopes; do not output secrets.
2. Read the matching official embedded skill: run lark-cli skills read lark-shared; for knowledge base tasks read lark-wiki, for cloud drive tasks read lark-drive, for body tasks also read lark-doc. Do not guess parameters based on --help .
3. Inventory knowledge base/Wiki: select the identity according to wiki-workflow.md ; bot runs wiki +space-list / wiki +node-list, user runs the corresponding --as user command only after explicit user authorization. Personal library my_library can only use the user identity.
4. Inventory cloud drive/Drive: select the identity according to drive-workflow.md ; Drive search run by bot can only cover app-visible resources; personal cloud drive must explicitly run after OAuth --as user。
5. Read document: first run with the corresponding identity lark-cli drive +inspect --as <bot|user> --url '<URL>' --format json to resolve the real type and token; then according to lark-doc use the corresponding identity's instructions docs +fetch。
6. Analyze migration requirements: determine the target product based only on the structure, type, attachments, permissions, and collaboration traces already read; write “observed,” “inferred,” and “unverified” separately.
7. Verify: re-paginate and check key counts; sample representative documents; check personal resources invisible to the bot and list them separately as gaps; if the API requires application data permissions, verify its data scope separately. Do not treat a single search result as a full inventory.

For detailed commands and product boundaries see references/cli-workflows.md。

Write operations and risk boundaries

• Read-only by default: search, list spaces, list nodes, read body, view metadata, view comments and permissions.
• Creating, editing, commenting, uploading, moving, copying, exporting, downloading, public sharing, member management, deleting, rolling back, and sending messages are all write or sensitive data actions; first show the target, scope, command, and impact, and wait for explicit user confirmation.
• When the CLI returns confirmation_required, do not silently append --yes; hand high-risk actions to the user for confirmation.
• When encountering invalid_client / 20140, do not classify it as a missing scope, and do not request permissions first; fix the application credential profile first.
• When encountering a missing scope, handle it first according to the console_url in the error and the missing scope; do not silently switch user OAuth; only when the user explicitly requests personal resources or explicitly specifies --as user should OAuth be started.
• Do not read browser cookies, passwords, browser profiles, raw keychain contents, or token storage not provided by the user.

Logging and completion receipt

Each run must report at least:

• started: CLI version, profile name, bot/user identity, non-sensitive scopes, and research scope; do not print secrets.
• processed: number of spaces, nodes, files, or documents, and whether pagination is complete.
• created/updated: by default write “remote unchanged”; if there are user-confirmed writes, list the actual objects and results.
• skipped/failed: Insufficient permissions, bot invisible, pagination limits, parsing failures, and reasons.
• verification: Executed status, schema, pagination, sample reads, and backup/export checks.

Recommended receipt:

完成：<一句话说明本次飞书调研或配置结果>。

日志摘要：
- started: <profile / identity / 非敏感范围>
- processed: <空间、节点、文档或文件数量>
- created/updated: 未改动远端 / <已确认的写入结果>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的 CLI 检查、分页核对、抽样读取>

问题与下一步：
- <缺 scope、bot 不可见资源、需要用户授权或无>

Resources

• Configuration example:assets/config.example.yml
• CLI workflow:references/cli-workflows.md
• Provider selection and credential boundaries:references/providers.md
• Source of truth for permissions:references/permissions.yml
• Knowledge base/Wiki workflow:references/wiki-workflow.md
• Cloud drive/Drive workflow:references/drive-workflow.md
• Source of truth for common errors:references/errors.yml
• Permission request process:references/permissions.md
• App credential initialization script:scripts/setup_app_credentials.py

Verification

python3 <skill-path>/scripts/setup_app_credentials.py --help
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py <skill-path>

Repository-level verification is defined by this repository's AGENTS.md and requires at minimum running unit tests, skill directory generation checks, skill audits, and git diff --check。

forward testing

Before complex research or permission changes, first run a forward test using desensitized fixtures or representative read-only objects explicitly authorized by the customer: verify permission prompts, bot identity, count pagination, failure classification, and the final receipt; do not treat a command's successful exit as evidence of content completeness.