pinvou lark-cli 共享规则
本技能指导你如何通过lark-cli操作飞书资源, 以及有哪些注意事项。
配置初始化
首次使用需运行 lark-cli config init 完成应用配置。
当你帮用户初始化配置时，以后台方式运行下面的命令发起配置应用流程，启动后读取输出，从中提取授权链接并发给用户。
URL 转发规则：当命令输出 verification_url、verification_uri_complete、console_url 等 URL 字段时：必须生成二维码：你必须调用 lark-cli auth qrcode 将 URL 转为二维码并展示给用户，这是必须步骤，不要跳过。优先生成 PNG 二维码（--output）；仅当用户明确要求时才使用 ASCII（--ascii）。URL 输出规则：将 URL 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点、重新拼接 query），二维码和链接请一起展示给用户。split-flow 场景见下文『Agent 代理发起认证』。
# 发起配置（该命令会阻塞直到用户打开链接并完成操作或过期）
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授权，两层都要满足
身份延续（跨命令工作流）
身份是整个工作流的状态，不是单条命令的局部参数。CLI 不会在进程之间继承"上一步用的身份"——省略 --as 不代表"保持当前身份"，而是把身份选择交回下面这条优先级链：
显式 --as > profile default-as > credential auto-detect
因此，只要用户显式选择了身份，或某个 ID / Token 是通过某个身份取得的（例如 vc +detail --as bot 返回的 note_id），后续每一条消费该 ID/Token 的命令都必须显式带上相同的 --as，跨 skill 传递也不例外：
- 禁止依赖 profile 默认身份让后续命令"自动"沿用同一身份。
- 禁止仅仅因为遇到权限错误就切换身份去绕过它——先如实报告，只有用户明确同意才切换。
- 下游命令根本不支持来源身份时（如
--as bot拿到的note_id指向note_display_type=unified，而note +transcript仅支持--as user），停止并向用户说明这个边界，不要静默省略--as把身份交给默认值。 - 命令支持的精确身份以
<command> --help/schema为准；各 skill 的身份小节只标注会影响路由决策的例外，不重复维护完整矩阵。
# GOOD — note_id 来自 bot 链路，下一步显式沿用 bot
lark-cli vc +detail --meeting-ids <meeting_id> --as bot
lark-cli note +detail --note-id <note_id> --as bot
lark-cli docs +fetch --doc <note_doc_token> --as bot
# BAD — 省略 --as，身份可能被 profile 默认值悄悄换成 user
lark-cli vc +detail --meeting-ids <meeting_id> --as bot
lark-cli note +detail --note-id <note_id>
权限不足处理
遇到权限相关错误时，根据当前身份类型采取不同解决方案。
错误响应中包含关键信息：
missing_scopes：列出缺失的 scope (N选1)console_url：飞书开发者后台的权限配置链接hint：建议的修复命令
missing_scope 与资源 ACL（无权访问某具体资源）是两类不同问题，恢复方式也不同：
| 失败类型 | user | bot |
|---|---|---|
| missing scope（应用/用户完全没有这个权限） | auth login --scope ... |
使用错误中的 console_url 去开发者后台开通，禁止 auth login |
| 资源 ACL（有 scope，但对这一条具体资源没有访问权限） | 请求资源所有者给当前用户授权 | 请求资源所有者给当前应用/bot 授权 |
| 资源在当前身份下不可见 | 保持当前身份，如实报告不可见，不要切换身份重试 | 保持当前身份，如实报告不可见，不要切换身份重试 |
任何权限恢复完成后，都必须用触发错误时的原身份重试，不要在恢复过程中换成另一个身份。
Bot 身份（--as bot）
将错误中的 console_url 原样提供给用户，引导去后台开通 scope。禁止对 bot 执行 auth login。
User 身份（--as user）
lark-cli auth login --domain <domain> --no-wait --json # 按业务域发起授权
lark-cli auth login --scope "<missing_scope>" --no-wait --json # 按具体 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 <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" - 结束本轮对话前，必须明确告知用户："请完成授权后，回来告诉我已授权完成，我会帮你完成后续步骤"
第二步：完成授权（后续轮）
- 等待用户回复"已完成授权"
- 由你（AI agent）亲自执行：
lark-cli auth login --device-code <device_code> - 此命令会轮询授权状态并完成登录
- 如果返回授权成功，流程结束
关键规则：
- 你必须亲自执行
--device-code命令，不要指示用户自行执行 - 禁止缓存
verification_url或device_code：每次需要重新发起授权时，必须沿用所需的--scope、--domain或--recommend选择以及任何--exclude值，并附加--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 <lark-cli command>
当你在输出中看到 _notice.update 时，先完成用户当前请求；如仍相关，再简短告知用户：品悟内 lark-cli 由应用按锁文件钉扎分发与升级，不要执行 lark-cli update 自行更新（自行更新会脱离品悟校验，导致下次使用时被重装回钉扎版本）；新版本会随品悟应用更新自动就位。
JSON 输出契约
--format json（默认）下，成功与错误的信封结构不同：
成功信封写入 stdout（退出码 0）：
{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
错误信封写入 stderr（退出码非 0）：
{ "ok": false, "identity": "user", "error": { "type": "authorization", "subtype": "missing_scope", "code": 99991679, "message": "...", "hint": "...", "missing_scopes": ["..."] } }
判断成功必须用 ok == true（或进程退出码 0），不要用 code == 0：成功信封没有顶层 code / msg 字段，code 只出现在错误信封的 error 内，含义是上游 OpenAPI 的 numeric code。按 OpenAPI 老格式 {"code": 0, "msg": "ok"} 判断会把所有成功调用误判为失败；封装写入类命令（如 task +create）时尤其危险，误判会绕过幂等逻辑导致重复创建。
安全规则
- 禁止输出密钥（appSecret、accessToken）到终端明文。
- 写入/删除操作前必须确认用户意图。
- 用
--dry-run预览危险请求。 - 文件路径只接受相对路径：
--file、--output、--output-dir、@file等路径参数只接受 cwd 下的相对路径，传绝对路径会报unsafe file path。数据输入（@file、大 JSON）优先用 stdin 传入，避免路径和转义问题。 - 临时文件一律写
tmp/子目录,别落工作目录根：CLI 入参、API 响应、分步数据等中间文件,统一写到 cwd 下的tmp/子目录(如--data @tmp/params.json、lark-cli ... > tmp/resp.json,相对路径仍合法)。原因:工作目录根的文件会被当作「产出物」展示给用户,过程文件会污染产物列表。能用 stdin 不落文件就别落;必须落就放tmp/(必要时先mkdir -p tmp)。
高风险操作的审批协议（exit 10）
lark-cli 对高风险写操作（risk: "high-risk-write"）有强制确认门禁。当你不带 --yes 调用这类命令时，CLI 会退出码 10、并在 stderr 返回如下结构化 envelope：
{
"ok": false,
"identity": "bot",
"error": {
"type": "confirmation",
"subtype": "confirmation_required",
"message": "drive +delete requires confirmation",
"hint": "add --yes to confirm",
"risk": "high-risk-write",
"action": "drive +delete"
}
}
遇到这种情况，不要当普通错误放弃。 按以下流程处理：
- 识别：看到子进程 exit code =
10且 stderr JSON 里error.type == "confirmation"、error.subtype == "confirmation_required" - 向用户确认：把
error.action、error.risk和关键参数展示给用户，明确告知"这是高风险操作"，等待用户显式同意 - 用户同意 → 在你原始 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"