Back to Details

lark-shared

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

lark-cli 共享规则

Lark CLI Shared Rules

本技能指导你如何通过lark-cli操作飞书资源, 以及有哪些注意事项。
This skill guides you on how to operate Lark resources via lark-cli and what precautions to take.

配置初始化

Configuration Initialization

首次使用需运行 
lark-cli config init
完成应用配置。
当你帮用户初始化配置时，使用background方式使用下面的命令发起配置应用流程，启动后读取输出，从中提取授权链接并发给用户：
bash
undefined
Run 
lark-cli config init
to complete application configuration for first-time use.
When helping users initialize configuration, use the background mode to initiate the application configuration process with the following command. After starting, read the output, extract the authorization link, and send it to the user:
bash
undefined

发起配置（该命令会阻塞直到用户打开链接并完成操作或过期）

Initiate configuration (this command will block until the user opens the link and completes the operation or it expires)

lark-cli config init --new
undefined
lark-cli config init --new
undefined

认证

Authentication

身份类型

Identity Types

两种身份类型，通过 
--as
切换：
身份标识获取方式适用场景
user 用户身份
--as user
lark-cli auth login
等		访问用户自己的资源（日历、云空间等）
bot 应用身份
--as bot
自动，只需 appId + appSecret应用级操作,访问bot自己的资源
There are two identity types, switchable via 
--as
:
IdentityIdentifierObtaining MethodApplicable Scenarios
User Identity
--as user
lark-cli auth login
, etc.		Access the user's own resources (calendar, cloud storage, etc.)
Bot Application Identity
--as bot
Automatic, only requires appId + appSecretApplication-level operations, access the bot's own resources

身份选择原则

Identity Selection Principles

输出的 
[identity: bot/user]
代表当前身份。bot 与 user 表现差异很大，需确认身份符合目标需求：
  • Bot 看不到用户资源：无法访问用户的日历、云空间文档、邮箱等个人资源。例如 
    --as bot
    查日程返回 bot 自己的（空）日历
  • Bot 无法代表用户操作：发消息以应用名义发送，创建文档归属 bot
  • Bot 权限：只需在飞书开发者后台开通 scope，无需 
    auth login
  • User 权限：后台开通 scope + 用户通过 
    auth login
    授权，两层都要满足
The output 
[identity: bot/user]
represents the current identity. Bot and user identities behave very differently, so ensure the identity meets the target requirements:
  • Bots cannot view user resources: Unable to access the user's calendar, cloud storage documents, email, and other personal resources. For example, querying schedules with 
    --as bot
    returns the bot's own (empty) calendar
  • Bots cannot operate on behalf of users: Messages are sent in the application's name, and created documents belong to the bot
  • Bot Permissions: Only need to enable scopes in the Lark Developer Backend, no 
    auth login
    required
  • User Permissions: Both enabling scopes in the backend and user authorization via 
    auth login
    are required

权限不足处理

Handling Insufficient Permissions

遇到权限相关错误时，根据当前身份类型采取不同解决方案。
错误响应中包含关键信息：
  • permission_violations
    ：列出缺失的 scope (N选1)
  • console_url
    ：飞书开发者后台的权限配置链接
  • hint
    ：建议的修复命令
When encountering permission-related errors, adopt different solutions based on the current identity type.
Error responses contain key information:
  • permission_violations
    : Lists missing scopes (choose one from N)
  • console_url
    : Link to permission configuration in the Lark Developer Backend
  • hint
    : Recommended fix command

Bot 身份（
--as bot
）

Bot Identity (
--as bot
)

将错误中的 
console_url
提供给用户，引导去后台开通 scope。禁止对 bot 执行 
auth login
。
Provide the 
console_url
from the error to the user and guide them to enable the required scopes in the backend. Prohibit executing 
auth login
for bots.

User 身份（
--as user
）

User Identity (
--as user
)

bash
lark-cli auth login --domain <domain>           # 按业务域授权
lark-cli auth login --scope "<missing_scope>"   # 按具体 scope 授权（推荐,符合最小权限原则）
规则：auth login 必须指定范围（
--domain
或 
--scope
）。多次 login 的 scope 会累积（增量授权）。
bash
lark-cli auth login --domain <domain>           # Authorize by business domain
lark-cli auth login --scope "<missing_scope>"   # Authorize by specific scope (recommended, follows the principle of least privilege)
Rule: auth login must specify a scope (
--domain
or 
--scope
). Scopes from multiple logins will accumulate (incremental authorization).

Agent 代理发起认证（推荐）

Agent-initiated Authentication (Recommended)

当你作为 AI agent 需要帮用户完成认证时，使用background方式 执行以下命令发起授权流程, 并将授权链接发给用户：
bash
undefined
When you, as an AI agent, need to help users complete authentication, use background mode to execute the following command to initiate the authorization process, and send the authorization link to the user:
bash
undefined

发起授权（阻塞直到用户授权完成或过期）

Initiate authorization (blocks until the user completes authorization or it expires)

lark-cli auth login --scope "calendar:calendar:readonly"
undefined
lark-cli auth login --scope "calendar:calendar:readonly"
undefined

安全规则

Security Rules

  • 禁止输出密钥（appSecret、accessToken）到终端明文。
  • 写入/删除操作前必须确认用户意图。
  • 用 
    --dry-run
    预览危险请求。
  • Prohibit outputting secrets (appSecret, accessToken) in plaintext to the terminal.
  • Must confirm user intent before performing write/delete operations.
  • Use 
    --dry-run
    to preview dangerous requests.