mirror of
https://github.com/larksuite/cli.git
synced 2026-07-03 22:24:31 +08:00
Compare commits
1 Commits
main
...
docs/lark-
| Author | SHA1 | Date | |
|---|---|---|---|
|
09d5c5d99b |
@@ -1,168 +1,31 @@
|
||||
---
|
||||
name: lark-shared
|
||||
version: 1.0.0
|
||||
description: "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."
|
||||
version: 1.1.0
|
||||
description: "lark-cli 通用规则：user/bot 身份、认证授权、安全与高风险确认门禁。当首次配置 lark-cli、需要 auth login、遇到权限或 scope 错误、命令以退出码 10 要求确认、或输出包含 _notice 升级提示时使用。"
|
||||
---
|
||||
|
||||
# lark-cli 共享规则
|
||||
|
||||
本技能指导你如何通过lark-cli操作飞书资源, 以及有哪些注意事项。
|
||||
所有 lark-* skill 共享的底座：lark-cli 的身份、认证、安全与高风险操作通用规则。
|
||||
|
||||
## 配置初始化
|
||||
## 通用准则
|
||||
|
||||
首次使用需运行 `lark-cli config init` 完成应用配置。
|
||||
1. **调用前先懂用法**：执行 shortcut 前先读对应 reference 或跑 `-h` 弄懂用法，别猜 flag 盲调。
|
||||
|
||||
当你帮用户初始化配置时，使用background方式使用下面的命令发起配置应用流程，启动后读取输出，从中提取授权链接并发给用户。
|
||||
2. **身份决定你代表谁操作**：`--as user` 代表用户本人（能看到、也能操作其日历 / 云空间 / 邮箱等个人资源），`--as bot` 代表应用自己（只涉及 bot 的资源，发消息、建文档都归 bot）。用 `--as bot` 碰用户资源**可能静默返空**而非报错，别误判成"没有数据"。身份模型与权限恢复 → [`references/lark-shared-identity-and-permissions.md`](references/lark-shared-identity-and-permissions.md)。
|
||||
|
||||
**URL 转发规则**：当命令输出 `verification_url`、`verification_uri_complete`、`console_url` 等 URL 字段时：**必须生成二维码**：你必须调用 `lark-cli auth qrcode` 将 URL 转为二维码并展示给用户，这是必须步骤，不要跳过。优先生成 PNG 二维码（--output）；仅当用户明确要求时才使用 ASCII（--ascii）。**URL 输出规则**：将 URL 视为不可修改的 opaque string，不要做任何修改（包括 URL 编码/解码、添加空格或标点、重新拼接 query），二维码和链接请一起展示给用户。
|
||||
3. **代表用户发起 `auth login` 授权时绝不阻塞**：走 split-flow（发起后交还控制权、下一轮再完成），别在同一轮阻塞等授权。完整步骤 **执行前必读** → [`references/lark-shared-auth-split-flow.md`](references/lark-shared-auth-split-flow.md)。
|
||||
|
||||
```bash
|
||||
# 发起配置（该命令会阻塞直到用户打开链接并完成操作或过期）
|
||||
lark-cli config init --new
|
||||
```
|
||||
4. **授权 / 配置类 URL 必须配二维码**：用 `lark-cli auth qrcode` 生成、URL 在前二维码在后，URL 原样不改写。
|
||||
|
||||
## 认证
|
||||
5. **退出码 10 是高风险确认门禁，不是错误**：停下、取得用户**显式同意**后才按 `hint` 重试，**绝不**静默加确认 flag 绕过。机制 → [`references/lark-shared-high-risk-approval.md`](references/lark-shared-high-risk-approval.md)。
|
||||
|
||||
### 身份类型
|
||||
6. **路径参数只接受 cwd 相对路径**：绝对路径会被拒（`unsafe file path`），规划时就用相对路径。
|
||||
|
||||
两种身份类型，通过 `--as` 切换：
|
||||
7. **不输出密钥明文**（appSecret、accessToken）。
|
||||
|
||||
| 身份 | 标识 | 获取方式 | 适用场景 |
|
||||
|------|------|---------|---------|
|
||||
| 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`）
|
||||
|
||||
```bash
|
||||
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，避免在同一轮对话中阻塞等待用户授权：
|
||||
|
||||
```bash
|
||||
# 发起授权（立即返回 device_code 和 verification_url）
|
||||
lark-cli auth login --scope "calendar:calendar:readonly" --no-wait --json
|
||||
```
|
||||
|
||||
拿到 `verification_url` 后，将它原样作为本轮最终消息发给用户，并结束本轮/交还控制权。不要在同一轮中展示 URL 后立刻执行 `--device-code` 阻塞轮询；在不透传中间输出的 agent harness 里，这会导致用户永远看不到 URL。
|
||||
|
||||
用户回复已完成授权后，再在后续步骤执行：
|
||||
|
||||
```bash
|
||||
lark-cli auth login --device-code <device_code>
|
||||
```
|
||||
|
||||
**Split-Flow 完整步骤**：
|
||||
|
||||
**第一步：发起授权（当前轮）**
|
||||
|
||||
1. 执行 `lark-cli auth login --scope "xxx" --no-wait --json`（必须加 `--no-wait --json`）
|
||||
2. 从 JSON 输出中提取 `verification_url` 和 `device_code`
|
||||
3. 生成二维码：`lark-cli auth qrcode <verification_url> --output "xxx"`
|
||||
4. 将 URL 和二维码展示给用户（先 URL，后二维码）
|
||||
5. **结束本轮对话前，必须明确告知用户**："请完成授权后，回来告诉我已授权完成，我会帮你完成后续步骤"
|
||||
|
||||
**第二步：完成授权（后续轮）**
|
||||
|
||||
1. 等待用户回复"已完成授权"
|
||||
2. **由你（AI agent）亲自执行**：`lark-cli auth login --device-code <device_code>`
|
||||
3. 此命令会轮询授权状态并完成登录
|
||||
4. 如果返回授权成功，流程结束
|
||||
|
||||
**关键规则**：
|
||||
|
||||
- **你必须亲自执行 `--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.update` 时，完成用户当前请求后，主动提议帮用户更新**：
|
||||
|
||||
1. 告知用户当前版本和最新版本号
|
||||
2. 提议执行更新（同时更新 CLI 和 Skills）：
|
||||
```bash
|
||||
lark-cli update
|
||||
```
|
||||
3. 更新完成后提醒用户：**退出并重新打开 AI Agent** 以加载最新 Skills
|
||||
|
||||
**重要**：始终使用 `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：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": false,
|
||||
"error": {
|
||||
"type": "confirmation_required",
|
||||
"message": "drive +delete requires confirmation",
|
||||
"hint": "add --yes to confirm",
|
||||
"risk": {
|
||||
"level": "high-risk-write",
|
||||
"action": "drive +delete"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**遇到这种情况，不要当普通错误放弃。** 按以下流程处理：
|
||||
|
||||
1. **识别**：看到子进程 exit code = `10` 且 stderr JSON 里 `error.type == "confirmation_required"`
|
||||
2. **向用户确认**：把 `error.risk.action` 和关键参数展示给用户，明确告知"这是高风险操作"，等待用户显式同意
|
||||
3. **用户同意** → 在你**原始 argv 的末尾追加 `--yes`** 后重试
|
||||
4. **用户拒绝** → 终止流程，不要擅自改写参数或跳过门禁
|
||||
|
||||
**绝对不允许**：
|
||||
- 看到 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"`
|
||||
- 首次配置 lark-cli（`config init`）→ [`references/lark-shared-config-init.md`](references/lark-shared-config-init.md)
|
||||
- 拿到 `/wiki/` 链接或 wiki token → [`references/lark-wiki-token-routing.md`](references/lark-wiki-token-routing.md)
|
||||
- 输出含 `_notice`（升级 / skills 落后 / 废弃命令提示）→ [`references/lark-shared-update-notice.md`](references/lark-shared-update-notice.md)
|
||||
|
||||
18
skills/lark-shared/references/lark-shared-auth-split-flow.md
Normal file
18
skills/lark-shared/references/lark-shared-auth-split-flow.md
Normal file
@@ -0,0 +1,18 @@
|
||||
# Agent 代理发起授权（split-flow）
|
||||
|
||||
帮用户完成 user 身份授权。背景：如果运行环境只把最终消息发给用户、不显示中间命令输出，阻塞式 `auth login` 会让用户永远看不到授权链接，所以把"发起"和"完成"拆到两轮。
|
||||
|
||||
## 第一步：发起（当前轮）
|
||||
|
||||
1. 执行 `lark-cli auth login --scope "<scope>" --no-wait --json`，从输出提取 `verification_url` 和 `device_code`。
|
||||
2. 把 `verification_url` 按正文准则配二维码展示给用户（生成二维码、URL 在前、原样不改写）。
|
||||
3. 明确告知用户"完成授权后回来告诉我"，然后交还控制权。**不要**在同一轮接着执行 `--device-code` 阻塞轮询——否则用户看不到链接。
|
||||
|
||||
## 第二步：完成（后续轮）
|
||||
|
||||
等用户回复已授权，**由你（agent）亲自执行** `lark-cli auth login --device-code <device_code>`（别让用户自己跑）。该命令轮询授权状态并完成登录，成功即结束。
|
||||
|
||||
## 规则
|
||||
|
||||
- **禁止缓存 `verification_url` / `device_code`**：每次授权都重新 `--no-wait` 发起拿新值，不要存旧值复用。
|
||||
- **范围必须显式指定**：`--scope`（推荐，最小权限）或 `--domain`；多次 login 的 scope 累积（增量授权）。`--exclude` 排除特定 scope，`--recommend` 只请求可自动批准的 scope。
|
||||
11
skills/lark-shared/references/lark-shared-config-init.md
Normal file
11
skills/lark-shared/references/lark-shared-config-init.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# 首次配置 lark-cli
|
||||
|
||||
首次使用需运行 `lark-cli config init --new` 完成应用配置。
|
||||
|
||||
**注意：`config init` 是阻塞命令，没有 `--no-wait`，不要套用 `auth login` 的 split-flow。** 它会一直阻塞到用户在浏览器完成配置或过期。帮用户初始化时，用 background 方式执行命令，启动后读取输出，从中提取授权链接发给用户：
|
||||
|
||||
```bash
|
||||
lark-cli config init --new
|
||||
```
|
||||
|
||||
输出里的授权 URL 按正文准则处理（生成二维码、URL 原样不改写）。
|
||||
@@ -0,0 +1,58 @@
|
||||
# 确认门禁 envelope 参考（exit 10）
|
||||
|
||||
处理协议见 SKILL.md 正文准则。本文讲报错 JSON 的两种形态、字段位置，以及重试 / 预览的两个坑。
|
||||
|
||||
## 可靠信号是退出码 10，不是 type 字符串
|
||||
|
||||
仓库正从扁平式迁往 typed 式，过渡期两种并存——扁平式仍是 shortcut / service 命令的当前形态（多数高风险命令），typed 式是已迁移命令（如 `config bind`）的新形态。**别认 `type` 字符串（迁移中会变），认退出码 10**：
|
||||
|
||||
**扁平式：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": false,
|
||||
"error": {
|
||||
"type": "confirmation_required",
|
||||
"message": "drive +delete requires confirmation",
|
||||
"hint": "add --yes to confirm",
|
||||
"risk": { "level": "high-risk-write", "action": "drive +delete" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**typed 式：**
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": false,
|
||||
"error": {
|
||||
"type": "confirmation",
|
||||
"subtype": "confirmation_required",
|
||||
"risk": "high-risk-write",
|
||||
"action": "config bind --force",
|
||||
"hint": "若用户确认切换，附加 --force 重新运行：`lark-cli config bind --identity user-default --force`"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
识别条件：exit code = 10，且 `error` 命中任一形态——`type == "confirmation_required"`（扁平），或 `type == "confirmation" && subtype == "confirmation_required"`（typed）。只判 `type == "confirmation_required"` 会漏掉 typed 式。
|
||||
|
||||
## 字段位置速查
|
||||
|
||||
| 信息 | 扁平式 | typed 式 |
|
||||
|------|--------|----------|
|
||||
| 操作名 | `error.risk.action` | `error.action` |
|
||||
| 风险级别 | `error.risk.level`（`risk` 是对象） | `error.risk`（字符串） |
|
||||
| 确认 flag | `error.hint` | `error.hint` |
|
||||
|
||||
取操作名：typed 式看 `error.action`，没有再看扁平式的 `error.risk.action`（哪个有用哪个）。`hint` 是给你看的自然语言提示，里面写明了该加哪个确认 flag（扁平式如 "add --yes to confirm" → `--yes`；`config bind` 的 hint 提示 `--force`）。**提取那个 flag 加到你自己的原始命令上**，别照抄 hint 里的完整示例命令——示例不含用户的原始参数，照抄会丢参数。
|
||||
|
||||
## 先预览再执行（可选，不触发门禁）
|
||||
|
||||
想让用户先 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"`（schema 同时注入 `yes` 布尔字段标记需确认）。
|
||||
- 注意：标注 `high-risk-write` ≠ 一定走 exit-10 门禁（如 `lark-cli update` 有 risk 标注但没有 `--yes` flag、不走该门禁）。以**实际 exit 10 + envelope** 为准，不要臆造 `--yes`。
|
||||
@@ -0,0 +1,27 @@
|
||||
# 身份与权限
|
||||
|
||||
基本心智模型——`--as` 代表谁操作、`--as bot` 碰用户资源可能静默返空——见 SKILL.md 正文准则。本文补充：身份怎么获得、授权分几层、权限不足时怎么恢复。
|
||||
|
||||
## 获取方式与授权层级
|
||||
|
||||
- **user 身份**（`--as user`）：用户通过 `lark-cli auth login` 授权获得。要能访问，需**两层都满足**——后台开通对应 scope + 用户 auth login 授权。
|
||||
- **bot 身份**（`--as bot`）：自动，只需 appId + appSecret；只需后台开通 scope，无需 auth login。
|
||||
|
||||
输出里的 `[identity: bot/user]` 是当前身份。
|
||||
|
||||
## bot 碰用户资源的失败形态
|
||||
|
||||
因命令而异：有的静默返回空结果（如查日程落到 bot 自己的空日历），有的明确报"未登录 / 越权"。**无论哪种，都别把 bot 的结果当成用户的真实数据。**
|
||||
|
||||
## 权限 / scope 不足恢复
|
||||
|
||||
错误响应中的关键字段：
|
||||
|
||||
- 缺失的 scope：`permission_violations`（原始 API 错误块，元素形如 `{subject: "<scope>"}`）或 `missing_scopes`（CLI 结构化错误，已抽好的 scope 字符串数组）。
|
||||
- `console_url`：飞书开发者后台的权限配置链接。
|
||||
- `hint`：建议的修复命令。
|
||||
|
||||
按身份分流：
|
||||
|
||||
- **Bot 身份**：把 `console_url` 提供给用户（按正文准则配二维码转发），引导去后台开通 scope。**禁止**对 bot 执行 `auth login`，也不要因为 user 报错就降级到 bot 重试。
|
||||
- **User 身份**：补授权用 `lark-cli auth login --scope "<missing_scope>"`（推荐，最小权限）或 `--domain <domain>`；必须指定其一，多次 login 的 scope 会累积（增量授权）。作为 agent 代发起时走 split-flow，见 [`lark-shared-auth-split-flow.md`](lark-shared-auth-split-flow.md)。
|
||||
@@ -0,0 +1,9 @@
|
||||
# 升级提示（_notice）
|
||||
|
||||
命令执行后 JSON 输出可能包含 `_notice`，其下三种通知的处置都是升级：
|
||||
|
||||
- `update`：CLI 有新版本（字段 `current` / `latest` / `message` / `command`）。
|
||||
- `skills`：内置 AI Skills 落后于 CLI（字段 `current` / `target`）。
|
||||
- `deprecated_command`：本次用了已废弃的命令别名（`replacement` 为新命令名）。
|
||||
|
||||
看到任一通知都**不要静默忽略**，即使与当前任务无关：完成用户当前请求后告知情况，主动提议执行 `lark-cli update`（同时更新 CLI 和 AI Skills；加 `--check` 可只检查不安装）。更新完成后提醒用户**退出并重新打开 AI Agent** 以加载最新 Skills。
|
||||
Reference in New Issue
Block a user