docs(lark-shared): dedup shared rules and prefix reference filenames

Apply the skill quality spec to existing content (no new rules added):
- Single-source the URL/QR-code rule in the security section; the auth
  and config sections reference it instead of restating.
- Remove the now-redundant config-init reference (its content already
  lives in the config-init and security sections of the entry).
- Prefix lark-shared's own reference files with lark-shared- per the
  reference-naming rule.
- Move identity routing to the top of the body.

skills/lark-shared/SKILL.md

@@ -1,168 +1,89 @@
 ---
 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."
+description: "首次配置 lark-cli、运行 auth login、用 --as 切换 user/bot 身份、处理权限不足或 scope 错误、遇到高风险写操作的确认门禁（exit 10 / confirmation）、更新 lark-cli、或看到 JSON 输出里的 _notice 时使用。"
 ---
 
 # lark-cli 共享规则
 
-本技能指导你如何通过lark-cli操作飞书资源, 以及有哪些注意事项。
+通过 lark-cli 操作飞书资源的通用规则。正文是常驻核心；以下细节按需读取（`lark-cli skills read lark-shared references/<file>`）：
 
-## 配置初始化
+- **遇到 exit 10 / confirmation 错误** → 读 [`references/lark-shared-high-risk-approval.md`](references/lark-shared-high-risk-approval.md)（错误形态、识别、按 hint 重试、如何识别高风险）
+- **要帮用户做 user 身份授权** → 读 [`references/lark-shared-auth-split-flow.md`](references/lark-shared-auth-split-flow.md)（split-flow 完整步骤）
+- **拿到 `/wiki/` 链接或 wiki token** → 读 [`references/lark-wiki-token-routing.md`](references/lark-wiki-token-routing.md)（token 解包与按底层对象路由）
 
-首次使用需运行 `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），二维码和链接请一起展示给用户。
-
-```bash
-# 发起配置（该命令会阻塞直到用户打开链接并完成操作或过期）
-lark-cli config init --new
-```
-
-## 认证
+## 认证与身份
 
 ### 身份类型
 
-两种身份类型，通过 `--as` 切换：
+两种身份，通过 `--as` 切换：
 
 | 身份 | 标识 | 获取方式 | 适用场景 |
 |------|------|---------|---------|
-| user 用户身份 | `--as user` | `lark-cli auth login` 等 | 访问用户自己的资源（日历、云空间/云盘/云存储等） |
-| bot 应用身份 | `--as bot` | 自动，只需 appId + appSecret | 应用级操作,访问bot自己的资源 |
+| 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` 授权，两层都要满足
-
+- **Bot 看不到用户资源**：无法访问用户的日历、云空间文档、邮箱等个人资源。例如 `--as bot` 查日程返回 bot 自己的（空）日历。
+- **Bot 无法代表用户操作**：发消息以应用名义发送，创建文档归属 bot。
+- **Bot 权限**：只需在飞书开发者后台开通 scope，无需 `auth login`。
+- **User 权限**：后台开通 scope + 用户通过 `auth login` 授权，两层都要满足。
 
 ### 权限不足处理
 
-遇到权限相关错误时，**根据当前身份类型采取不同解决方案**。
+遇到权限相关错误时，**根据当前身份采取不同方案**。错误响应中的关键字段（注意区分来源）：
 
-错误响应中包含关键信息：
-- `permission_violations`：列出缺失的 scope (N选1)
-- `console_url`：飞书开发者后台的权限配置链接
-- `hint`：建议的修复命令
+- 缺失的 scope：`permission_violations`（原始 API 错误块，元素形如 `{subject: "<scope>"}`）；CLI 结构化错误里则是已抽取好的 `missing_scopes`（scope 字符串数组）。
+- `console_url`：飞书开发者后台的权限配置链接。
+- `hint`：建议的修复命令。
 
-#### Bot 身份（`--as bot`）
+- **Bot 身份**：将 `console_url` 提供给用户（按下方「安全规则」的 URL 规则展示），引导去后台开通 scope。**禁止**对 bot 执行 `auth login`。
+- **User 身份**：
+  ```bash
+  lark-cli auth login --domain <domain>           # 按业务域授权
+  lark-cli auth login --scope "<missing_scope>"   # 按具体 scope 授权（推荐，最小权限）
+  ```
+  auth login 必须指定范围（`--domain` 或 `--scope`）；多次 login 的 scope 会累积（增量授权）。
 
-将错误中的 `console_url` 原样提供给用户，引导去后台开通 scope。**禁止**对 bot 执行 `auth login`。
+### Agent 代理发起认证
 
-#### User 身份（`--as user`）
+优先用 split-flow（`--no-wait` 发起 → 展示给用户 → 后续轮 `--device-code` 完成），避免同轮阻塞。三条铁律：① 不在同一轮展示 URL 后立刻阻塞轮询 `--device-code`（交还控制权，等用户回来）；② `--device-code` 由你亲自执行，不要让用户自己跑；③ 不缓存 `verification_url` / `device_code`，每次需要授权都重新发起。授权 URL 的二维码展示按「安全规则」。完整步骤详见 [`references/lark-shared-auth-split-flow.md`](references/lark-shared-auth-split-flow.md)。
 
-```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 config init --new`：帮用户初始化时**非阻塞启动**该命令、**持续读取输出**、从中提取授权链接发给用户（URL 的二维码展示按「安全规则」）。
 
 ## 更新检查
 
-lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_notice.update` 字段（含 `message`、`command` 等）。
+命令执行后若检测到新版本，JSON 输出会包含 `_notice.update`（字段：`current`、`latest`、`message`、`command`）。
 
-**当你在输出中看到 `_notice.update` 时，完成用户当前请求后，主动提议帮用户更新**：
+**看到 `_notice.update` 时，完成用户当前请求后，主动提议更新**：
 
-1. 告知用户当前版本和最新版本号
-2. 提议执行更新（同时更新 CLI 和 Skills）：
-   ```bash
-   lark-cli update
-   ```
-3. 更新完成后提醒用户：**退出并重新打开 AI Agent** 以加载最新 Skills
+1. 告知用户当前版本和最新版本号（也可用 `lark-cli update --check` 只检查不安装）。
+2. 提议执行 `lark-cli update`（同时更新 CLI 和 AI Skills）。
+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 传入，避免路径和转义问题。
+- **文件路径只接受相对路径**：`--file`、`--output`、`--output-dir`、`@file` 等路径参数只接受 cwd 下的相对路径，传绝对路径会报 `unsafe file path`。数据输入（`@file`、大 JSON）优先用 stdin，避免路径和转义问题。
+- **输出任何授权 / 配置类 URL（`verification_url` / `verification_uri_complete` / `console_url` 等）时**：必须用 `lark-cli auth qrcode` 生成并展示二维码（URL 在前、二维码在后，不可跳过）；URL 视为 opaque string，不改写（不编码/解码、不加空格标点、不重拼 query）。
 
-## 高风险操作的审批协议（exit 10）
+## 高风险操作的确认门禁（exit 10）
 
-lark-cli 对高风险写操作（`risk: "high-risk-write"`）有强制确认门禁。当你不带 `--yes` 调用这类命令时，CLI 会退出码 `10`、并在 stderr 返回如下结构化 envelope：
+高风险写操作（`risk: "high-risk-write"`）未确认时，CLI **退出码 `10`**，并返回确认 envelope（`type` 为 `confirmation` / `confirmation_required`）。
 
-```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"
-    }
-  }
-}
-```
+**遇到 exit 10：绝不当普通错误放弃，绝不静默加 `--yes`。**
 
-**遇到这种情况，不要当普通错误放弃。** 按以下流程处理：
+1. **停下**，把这次高风险操作和关键参数讲给用户，等其**显式同意**。
+2. 同意后，从 envelope 的 `hint` 读出确认 flag（`--yes` / `--force`），以 argv 数组**追加到原始命令**重试——不写死 `--yes`，不用 `sh -c` 拼接。
+3. 用户拒绝则终止。
 
-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"`
+**错误形态识别、`action` 字段位置、如何判断高风险、`--dry-run` 预览 → 详见 [`references/lark-shared-high-risk-approval.md`](references/lark-shared-high-risk-approval.md)。**

skills/lark-shared/references/lark-shared-auth-split-flow.md

@@ -0,0 +1,36 @@
+# Agent 代理发起认证（split-flow）
+
+当你作为 AI agent 需要帮用户完成 user 身份认证时，优先使用 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。
+
+## 第一步：发起授权（当前轮）
+
+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. 此命令会轮询授权状态并完成登录；返回成功即结束。
+
+## 关键规则
+
+- **你必须亲自执行 `--device-code` 命令**，不要指示用户自行执行。
+- **不要在同一轮中展示 URL 后立刻执行 `--device-code`**，这会导致用户看不到 URL。
+- **禁止缓存 `verification_url` / `device_code`**：每次需要授权时都重新执行 `lark-cli auth login --no-wait --json` 生成新链接，不要将授权链接和 device code 存入上下文供后续复用。
+
+## 授权范围
+
+- auth login 必须指定范围（`--domain <domain>` 或 `--scope "<scope>"`）；推荐 `--scope`，符合最小权限原则。
+- 多次 login 的 scope 会累积（增量授权）。
+- 可用 `--exclude "<scope>"` 排除特定 scope、`--recommend` 只请求推荐（可自动批准）的 scope。

skills/lark-shared/references/lark-shared-high-risk-approval.md

@@ -0,0 +1,71 @@
+# 高风险操作的确认门禁（exit 10）
+
+lark-cli 对高风险写操作（`risk: "high-risk-write"`）有强制确认门禁。不带确认标志调用这类命令时，CLI 退出码 `10`，并在 stderr 返回结构化 envelope。
+
+> 正文已给出安全默认（停下、绝不静默 `--yes`、从 `hint` 取 flag 追加到原始 argv 重试）。本文件是机制细节，遇到 exit 10 时按需读取。
+
+## 关键：可靠信号是退出码 10，不是 type 字符串
+
+仓库正在从「扁平错误」迁移到「typed 错误」，同一个门禁可能以两种形态出现，但**都以 exit 10 为信号**：
+
+- **扁平式**（service / shortcut 命令，旧形态）：
+
+  ```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 式**（如 `config bind`，新形态）：
+
+  ```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`"
+    }
+  }
+  ```
+
+只用 `error.type == "confirmation_required"` 判断会**漏掉 typed 式**。正确识别：**子进程 exit code = 10**，且 `error` 命中任一：
+
+- `type == "confirmation_required"`（扁平），或
+- `type == "confirmation" && subtype == "confirmation_required"`（typed）。
+
+## 处理流程
+
+1. **识别**：exit code = 10 且命中上述任一形态。
+2. **向用户确认**：把操作名和关键参数展示给用户，明确告知"这是高风险操作"，等待显式同意。
+   - 操作名位置随形态而异：typed 在 `error.action`；扁平在 `error.risk.action`。取 `error.action || error.risk.action`。
+   - 注意 `error.risk` 形态也不同：扁平是对象 `{level, action}`，typed 是字符串（如 `"high-risk-write"`）。
+3. **用户同意 → 从 `hint` 读出确认 flag，追加到原始 argv 后重试**。`hint` 是给 Agent 看的自然语言提示，写明了该用哪个 flag——**提取那个 flag（如 `--yes` / `--force`）追加到你的原始命令**，不要写死 `--yes`，也**不要照抄 hint 里的示例命令**（示例不含用户原始参数，照抄会丢参数）：
+   - 扁平式：`hint = "add --yes to confirm"` → 原始 argv 末尾追加 `--yes`。
+   - typed 式（bind）：`hint` 提示用 `--force` → 原始 argv 末尾追加 `--force`。
+4. **用户拒绝 → 终止流程**，不擅自改写参数或跳过门禁。
+
+## 绝对不允许
+
+- 看到 exit 10 就默认加 `--yes` 静默重试（等于禁用门禁）。
+- 把 `confirmation` / `confirmation_required` 当网络错误 / 权限错误处理。
+- 用户没明确同意就追加确认 flag 重试。
+- 用 `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"`（同时 schema 会注入 `yes` 字段标记需确认）。
+- 注意：被标注 `high-risk-write` ≠ 一定走 exit-10 门禁。例如 `lark-cli update` 标了 risk 但没有 `--yes` flag、不走该门禁——以**实际 exit 10 + envelope** 为准，不要臆造 `--yes`。