docs(lark-shared): restructure into prioritized rules + on-demand references

Rewrite the always-loaded SKILL.md from a 168-line monolith into a slim core: a positioning line plus 7 mental-model "通用准则" ordered by agent attention priority (silent/proactive rules first; loud-triggered and low-frequency ones last), and a short routing list. Mechanics and edge cases move into on-demand references/ (loaded only when relevant). References (named with the lark-shared- prefix, matching the per-domain convention): - lark-shared-auth-split-flow.md split-flow steps (marked must-read) - lark-shared-high-risk-approval.md exit-10 envelope forms + predict/preview - lark-shared-identity-and-permissions.md identity model + scope recovery - lark-shared-config-init.md first-run config (blocking, no split-flow) - lark-shared-update-notice.md _notice handling (update/skills/deprecated) Fix doc-vs-implementation drift confirmed against the code: - exit-10 keys on exit code 10, not the type string; covers both the flat (type=confirmation_required) and typed (type=confirmation + subtype) envelopes, and reads the confirm flag from hint (--yes / --force). - distinguish permission_violations (raw API) vs missing_scopes (CLI error). - complete _notice keys (update / skills / deprecated_command). - identity failure is silent-or-loud per command, not always empty. Switch description to Chinese; bump version 1.0.0 -> 1.1.0. Change-Id: I2dff478ecdc05a13f2d750944f637ed2374961e7
2026-07-03 14:02:43 +08:00 · 2026-06-13 17:43:27 +08:00
parent 0fbfe68726
commit feed8fb884
6 changed files with 138 additions and 152 deletions
--- a/skills/lark-shared/SKILL.md
+++ b/skills/lark-shared/SKILL.md
@@ -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)
--- a/skills/lark-shared/references/lark-shared-auth-split-flow.md
+++ b/skills/lark-shared/references/lark-shared-auth-split-flow.md
@@ -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。
--- a/skills/lark-shared/references/lark-shared-config-init.md
+++ b/skills/lark-shared/references/lark-shared-config-init.md
@@ -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 原样不改写）。
--- a/skills/lark-shared/references/lark-shared-high-risk-approval.md
+++ b/skills/lark-shared/references/lark-shared-high-risk-approval.md
@@ -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`。
--- a/skills/lark-shared/references/lark-shared-identity-and-permissions.md
+++ b/skills/lark-shared/references/lark-shared-identity-and-permissions.md
@@ -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)。
--- a/skills/lark-shared/references/lark-shared-update-notice.md
+++ b/skills/lark-shared/references/lark-shared-update-notice.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。