ZJU-REAL lark-cli 共享规则
本技能指导你如何通过lark-cli操作飞书资源, 以及有哪些注意事项。
配置初始化（平台已预置，无需你手动 init）
飞书应用配置（app_id / app_secret）由平台管理员在「系统配置」里统一填写，后端会把它注入到沙箱的 lark-cli 中——你不需要、也不应该运行 lark-cli config init。
- 用
lark-cli config show可查看当前应用配置是否就绪。 - 若
config show显示没有 app-id（应用未配置）：不要自己config init，而是告诉用户「飞书应用尚未配置，请联系管理员在系统配置中填写飞书应用的 app_id / app_secret」。
你要做的只是帮用户完成用户授权（下面的「认证」一节，auth login）。
URL 转发规则：当任何命令输出 verification_url、verification_uri_complete、console_url 等 URL 字段时，必须将 URL exactly as returned by the CLI 转发给用户，并把它视为不可修改的 opaque string；不要做 URL encode/decode，不要补 %20、空格或标点，不要重新拼接 query，不要改写成 Markdown link text，建议用只包含原始 URL 的代码块单独输出。
认证
身份类型
两种身份类型，通过 --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 <domain> # 按业务域授权
lark-cli auth login --scope "<missing_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 <device_code>
更新检查（升级由平台管理员走镜像重建，禁止容器内自升级）
lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 _notice.update 字段（含 message、command 等）。
本平台的 lark-cli 版本随沙箱镜像固定，升级由管理员走镜像重建完成——沙箱内不可自升级。因此：
- 不要运行
lark-cli update（沙箱不可变，自升级不会生效，也无法持久化）。 - 若看到
_notice.update：完成用户当前请求后，可顺带告知用户「检测到 lark-cli 有新版本，如需升级请联系管理员更新沙箱镜像」即可，不要尝试自行升级。
安全规则
- 禁止输出密钥（appSecret、accessToken）到终端明文。
- 写入/删除操作前必须确认用户意图。
- 用
--dry-run预览危险请求。
高风险操作的审批协议（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"