lark-shared

by larksuite

Use when first setting up lark-cli, running auth login, switching user/bot identity (--as), handling permission denied or scope errors, needing to update lark-cli, or seeing _notice in JSON output. npx skills add https://github.com/larksuite/cli --skill lark-shared Download ZIPGitHub15.1k

lark-cli 共享规则

本技能指导你如何通过lark-cli操作飞书资源, 以及有哪些注意事项。

配置初始化

首次使用需运行 lark-cli config init 完成应用配置。

当你帮用户初始化配置时，使用background方式使用下面的命令发起配置应用流程，启动后读取输出，从中提取授权链接并发给用户。

URL 转发规则：当命令输出 verification_url、verification_uri_complete、console_url 等 URL 字段时：必须生成二维码：你必须调用 lark-cli auth qrcode 将 URL 转为二维码并展示给用户，这是必须步骤，不要跳过。优先生成 PNG 二维码（--output）；仅当用户明确要求时才使用 ASCII（--ascii）。URL 输出规则：将 URL 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点、重新拼接 query），二维码和链接请一起展示给用户。

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

认证

认证任务速查

认证、scope、业务域、登录态、退出登录态、撤销授权问题都走本技能。

用户意图 首选命令 / 回答 获取全部权限 lark-cli auth login --domain all --no-wait --json 按业务域授权 lark-cli auth login --domain docs --domain drive --no-wait --json；--domain 可重复，也可用逗号分隔 指定单个 scope 授权 lark-cli auth login --scope "<scope>" --no-wait --json 检查当前登录态、是谁登录、token 是否有效 lark-cli auth status --json --verify；回答时引用 identity、verified、identities.user.status、identities.user.userName、identities.user.openId（用户 open id）、identities.user.tokenStatus、identities.user.scope 快速查看当前身份状态 lark-cli whoami；实际生效的那一个身份 退出当前机器的用户登录态 lark-cli auth logout --json；loggedOut:true 表示注销成功 bot 缺少权限 不要执行 auth login；引导用户在开发者后台开通 bot scope，优先复用错误里的 console_url 取消用户对应用的全部服务端授权 auth logout 只清本机登录态；服务端授权需用户在飞书授权管理页取消 只取消一个 scope CLI 不支持单独撤销一个已授予 scope；可重新走最小 scope 授权，或让用户在授权管理页处理

机器读取 JSON 时，为减少 _notice 干扰，可在命令前加：

LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 lark-cli auth status --json --verify

身份类型

两种身份类型，通过 --as 切换：

身份 标识 获取方式 适用场景 user 用户身份 --as user lark-cli auth login 等 访问用户自己的资源（日历、云空间/云盘/云存储等） bot 应用身份 --as bot 自动，只需 appId + appSecret 应用级操作,访问bot自己的资源

身份选择原则

输出的 [identity: bot/user] 代表当前身份。bot 与 user 表现差异很大，需确认身份符合目标需求：

• Bot 看不到用户资源：无法访问用户的日历、云空间（云盘/云存储）文档、邮箱等个人资源。例如 --as bot 查日程返回 bot 自己的（空）日历

• Bot 无法代表用户操作：发消息以应用名义发送，创建文档归属 bot

• Bot 权限：只需在飞书开发者后台开通 scope，无需 auth login

• User 权限：后台开通 scope + 用户通过 auth login 授权，两层都要满足

权限不足处理

遇到权限相关错误时，根据当前身份类型采取不同解决方案。

错误响应中包含关键信息：

• permission_violations：列出缺失的 scope (N选1)

• console_url：飞书开发者后台的权限配置链接

• hint：建议的修复命令

Bot 身份（--as bot）

将错误中的 console_url 原样提供给用户，引导去后台开通 scope。禁止对 bot 执行 auth login。

User 身份（--as user）

lark-cli auth login --domain # 按业务域授权
lark-cli auth login --scope " " # 按具体 scope 授权（推荐,符合最小权限原则）

规则：auth login 必须指定范围（--domain 或 --scope）。多次 login 的 scope 会累积（增量授权）。

Agent 代理发起认证（推荐）

当你作为 AI agent 需要帮用户完成认证时，优先使用 split-flow，避免在同一轮对话中阻塞等待用户授权：

# 发起授权（立即返回 device_code 和 verification_url）
lark-cli auth login --scope "calendar:calendar:readonly" --no-wait --json

拿到 verification_url 后，将它原样作为本轮最终消息发给用户，并结束本轮/交还控制权。不要在同一轮中展示 URL 后立刻执行 --device-code 阻塞轮询；在不透传中间输出的 agent harness 里，这会导致用户永远看不到 URL。

用户回复已完成授权后，再在后续步骤执行：

lark-cli auth login --device-code 

Split-Flow 完整步骤：

第一步：发起授权（当前轮）

• 执行 lark-cli auth login --scope "xxx" --no-wait --json（必须加 --no-wait --json）

• 从 JSON 输出中提取 verification_url 和 device_code

• 生成二维码：lark-cli auth qrcode <verification_url> --output "xxx"

• 将 URL 和二维码展示给用户（先 URL，后二维码）

• 结束本轮对话前，必须明确告知用户："请完成授权后，回来告诉我已授权完成，我会帮你完成后续步骤"

第二步：完成授权（后续轮）

• 等待用户回复"已完成授权"

• 由你（AI agent）亲自执行：lark-cli auth login --device-code <device_code>

• 此命令会轮询授权状态并完成登录

• 如果返回授权成功，流程结束

关键规则：

• 你必须亲自执行 --device-code 命令，不要指示用户自行执行

• 不要在同一轮中展示 URL 后立刻执行 --device-code，这会导致用户看不到 URL

• 禁止缓存 verification_url 或 device_code：每次需要授权时，必须重新执行 lark-cli auth login --no-wait --json 生成新的链接。不要将授权链接和 device code 存入上下文供后续复用

更新检查

lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 _notice.update 字段（含 message、command 等）。

除非用户正在询问更新、版本或 notice，否则不要把 _notice 原样复制为当前任务的主要答案，也不要为了 notice 中断当前任务去反复查 help。

需要稳定 JSON 给脚本或机器读取时，可以在命令前设置：

LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 

当你在输出中看到 _notice.update 时，先完成用户当前请求；如仍相关，再简短告知可运行：

lark-cli update

重要：始终使用 lark-cli update 更新，它会同时更新 CLI 和 AI Skills。

安全规则

• 禁止输出密钥（appSecret、accessToken）到终端明文。

• 写入/删除操作前必须确认用户意图。

• 用 --dry-run 预览危险请求。

• 文件路径只接受相对路径：--file、--output、--output-dir、@file 等路径参数只接受 cwd 下的相对路径，传绝对路径会报 unsafe file path。数据输入（@file、大 JSON）优先用 stdin 传入，避免路径和转义问题。

高风险操作的审批协议（exit 10）

lark-cli 对高风险写操作（risk: "high-risk-write"）有强制确认门禁。当你不带 --yes 调用这类命令时，CLI 会退出码 10、并在 stderr 返回如下结构化 envelope：

{
 "ok": false,
 "error": {
 "type": "confirmation_required",
 "message": "drive +delete requires confirmation",
 "hint": "add --yes to confirm",
 "risk": {
 "level": "high-risk-write",
 "action": "drive +delete"
 }
 }
}

遇到这种情况，不要当普通错误放弃。 按以下流程处理：

• 识别：看到子进程 exit code = 10 且 stderr JSON 里 error.type == "confirmation_required"

• 向用户确认：把 error.risk.action 和关键参数展示给用户，明确告知"这是高风险操作"，等待用户显式同意

• 用户同意 → 在你原始 argv 的末尾追加 --yes 后重试

• 用户拒绝 → 终止流程，不要擅自改写参数或跳过门禁

绝对不允许：

• 看到 exit 10 就默认加 --yes 静默重试（这等于禁用门禁）

• 把 confirmation_required 当网络错误/权限错误处理

• 在用户没明确同意的前提下追加 --yes 重试

• 用 sh -c 等 shell 方式拼接命令重试——用 exec.Command(argv...) 参数数组形式，避免 shell 解析把用户参数当作语法

提前预判：想先让用户 review 危险操作的具体请求，调用时加 --dry-run——它不触发门禁，会打印完整请求详情（URL / body / params），你可以把这个预览给用户看过再去真正执行。

如何识别一条命令是高风险

• shortcut：lark-cli <service> +<cmd> --help 顶部会显示 Risk: high-risk-write

• service 命令：lark-cli schema <service>.<resource>.<method> --format json 的返回值里 "risk": "high-risk-write"