@amaster.ai/pi-lark 0.1.2-beta.59 → 0.1.2-beta.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.2-beta.59",
+  "version": "0.1.2-beta.60",
   "description": "Pi extension for Lark/Feishu workspace — calendar, docs, drive, sheets, tasks, mail and more via lark-cli.",
   "keywords": [
     "pi-package",
@@ -61,7 +61,7 @@
     "vitest": "^4.0.0"
   },
   "dependencies": {
-    "@amaster.ai/pi-shared": "0.1.2-beta.59"
+    "@amaster.ai/pi-shared": "0.1.2-beta.60"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

package/skills/lark-base/references/lark-base-record-history-list.md

@@ -2,6 +2,16 @@
 
 查询单条记录的变更历史。它返回历史事件，不返回记录当前值，也不支持整表审计扫描。
 
+## 使用前置
+
+`+record-history-list` 仅查询单条记录。调用前必须获得能唯一对应用户指定目标、且与 `table_id` 属于同一张表的 `record_id`。
+
+如果当前信息无法唯一确定目标记录，先向用户确认，必要时用 `+record-list` 辅助定位；不得自行选择记录，也不得扩展为批量或整表扫描。需要查询多条记录时，先确认范围，再逐条调用。
+
+用 `+record-list` 展示候选时，可重复传入 `--field-id` 做最小投影。字段名包含空格时，需要给完整值加引号，例如 `--field-id "Project Owner"`。
+
+用户明确指定某个视图的第 N 行时，先用同一 `view_id` 调用 `+record-list`，并将 `--offset` 设为 N-1、`--limit` 设为 1。默认 Markdown 输出从 `_record_id` 列读取唯一记录 ID；显式使用 `--format json` 时从 `.data.record_id_list[0]` 读取。`_record_id` 不是 JSON 顶层字段；视图或排序上下文不明确时仍需先确认。
+
 ## 推荐命令
 
 ```bash
@@ -16,14 +26,21 @@ lark-cli base +record-history-list \
   --record-id <record_id> \
   --page-size 30 \
   --max-version <next_max_version>
+
+lark-cli base +record-history-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --record-id <record_id> \
+  --format pretty
 ```
 
 ## 返回解释
 
 - 历史条目通常按版本号降序返回，最新在前。
 - 每条历史包含版本号、操作人、操作时间、操作类型和字段变更。
-- `create_time` 是秒级 Unix 时间戳。
+- 默认 JSON 中的 `create_time` 是秒级 Unix 时间戳；`--format pretty` 会将其转换为带 UTC 偏移的本地时间，并和操作人、字段变化放在同一行。
 - `field_changes` 描述字段变更，重点看字段名/字段类型、`before` 和 `after`。
+- `--format pretty` 中空的 `before` 或 `after` 显示为 `-`；默认 JSON 保留原始值。
 - `activity_type` 常见值：`create`（创建记录）、`update`（编辑记录）、`delete`（删除记录）。
 
 以下字段类型的变化可能不会出现在 `field_changes` 中：
@@ -40,4 +57,4 @@ lark-cli base +record-history-list \
 ## 注意
 
 - `table-id` 和 `record-id` 必须来自同一张表。
-- 这是单条记录历史，不是表级审计；需要查多条记录时串行调用。
+- 这是单条记录历史，不是表级审计；用户明确要求查询多条记录时，先确认目标范围，再按记录串行调用。

package/skills/lark-minutes/references/lark-minutes-apply-permission.md

@@ -92,4 +92,4 @@ lark-cli minutes +apply-permission --minute-token obcnxxxxxxxxxxxxxxxxxxxx --per
 
 - [lark-minutes](../SKILL.md) — 妙记全部命令
 - [minutes +detail](lark-minutes-detail.md) — 妙记内容与产物查询
-- [lark-shared](../../lark-shared/SKILL.md) — 身份延续与权限恢复规则
+- [lark-shared](../../lark-shared/SKILL.md) — 身份延续与权限管理

package/skills/lark-minutes/references/lark-minutes-download.md

@@ -121,7 +121,7 @@ API 限流 5 次/秒，批量下载时需注意控制频率。
 | 妙记尚未准备好 | 2091003 | 转写未完成 | 等待转写完成后重试 |
 | 资源已删除 | 2091004 | 妙记已被删除 | 确认妙记文件仍然存在 |
 | 权限不足 | 2091005 | 无阅读权限 | 检查是否有该妙记的访问权限 |
-| `missing required scope(s)` | — | 当前身份缺少 scope | `--as user`：运行 `auth login --scope "minutes:minutes.media:export"`；`--as bot`：使用错误中的 `console_url` 去开发者后台开通，**禁止**对 bot 执行 `auth login`（见 [lark-shared](../../lark-shared/SKILL.md) 的权限恢复表） |
+| `missing required scope(s)` | — | 当前身份缺少 scope | `--as user`：运行 `auth login --scope "minutes:minutes.media:export"`；`--as bot`：使用错误中的 `console_url` 去开发者后台开通，**禁止**对 bot 执行 `auth login`（见 [lark-shared](../../lark-shared/SKILL.md) 的权限管理） |
 
 ## 提示
 

package/skills/lark-shared/SKILL.md

@@ -1,247 +1,48 @@
 ---
 name: lark-shared
-version: 1.0.0
+version: 1.1.0
 description: "Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling _notice JSON."
+metadata:
+  requires:
+    bins: ["lark-cli"]
 ---
 
 # lark-cli 共享规则
 
-本技能指导你如何通过lark-cli操作飞书资源, 以及有哪些注意事项。
+所有 `lark-*` skill 共享的底座：身份、认证、输出契约与高风险操作。
 
-## 配置初始化
+## 通用准则
 
-首次使用需运行 `lark-cli config init` 完成应用配置。
+1. **调用前先确认用法**：执行前读对应 reference 或跑 `--help`，别猜 flag 盲调。
 
-当你帮用户初始化配置时，使用background方式使用下面的命令发起配置应用流程，启动后读取输出，从中提取授权链接并发给用户。
+2. **身份决定你代表谁操作**：`--as user` 代表用户本人（能看到、也能操作其日历、云空间/云盘/云存储等个人资源），`--as bot` 代表应用自己，应用级操作，只能访问bot自己的资源，bot 查用户资源会返回空成功而非报错。动手前先搞清楚身份`identity`。身份模型和权限管理 → [`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. **授权 / 配置类 URL 必须配二维码**：当命令输出 `verification_url`、`verification_uri_complete`、`console_url` 等 URL 字段时，必须用 `lark-cli auth qrcode` 生成并在回复中展示，URL 在前二维码在后；优先生成 PNG（`--output`），仅当用户明确要求时才使用 ASCII（`--ascii`）。URL 原样转发——不编解码、不加标点、不重拼 query，二维码和链接请一起展示给用户。
 
-```bash
-# 发起配置（该命令会阻塞直到用户打开链接并完成操作或过期）
-lark-cli config init --new
-```
+4. **`--format json`（默认）下，判断成功用 `ok == true`（或进程退出码 0），不要用 `code == 0`**：成功信封没有顶层 `code` / `msg` 字段，`code` 只出现在错误信封的 `error` 内。按 OpenAPI 老格式 `{"code": 0, "msg": "ok"}`判断会把所有成功调用误判为失败——封装写入类命令时尤其危险。JSON 输出契约 → [`lark-shared-output-contract.md`](references/lark-shared-output-contract.md)。
 
-## 认证
 
-### 认证任务速查
-
-认证、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` 干扰，可在命令前加：
-
-```bash
-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` 不代表"保持当前身份"，而是把身份选择交回下面这条优先级链：
-
-```text
-显式 --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 的身份小节只标注会影响路由决策的例外，不重复维护完整矩阵。
-
-```bash
-# 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`）
-
-```bash
-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，避免在同一轮对话中阻塞等待用户授权：
-
-```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`**：每次需要重新发起授权时，必须沿用所需的 `--scope`、`--domain` 或 `--recommend` 选择以及任何 `--exclude` 值，并附加 `--no-wait --json` 生成新的链接。不要复用已过期的授权链接或 device code
-
-## 更新检查
-
-lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_notice.update` 字段（含 `message`、`command` 等）。
-
-除非用户正在询问更新、版本或 notice，否则不要把 `_notice` 原样复制为当前任务的主要答案，也不要为了 notice 中断当前任务去反复查 help。
-
-需要稳定 JSON 给脚本或机器读取时，可以在命令前设置：
-
-```bash
-LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 <lark-cli command>
-```
-
-当你在输出中看到 `_notice.update` 时，先完成用户当前请求；如仍相关，再简短告知可运行：
-
-```bash
-lark-cli update
-```
-
-**重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。
+## 安全规则
 
-## JSON 输出契约
+1. **禁止输出密钥**（appSecret、accessToken等）到终端明文。
 
-`--format json`（默认）下，成功与错误的信封结构不同：
+2. **写入/删除操作前必须确认用户意图**。
 
-成功信封写入 **stdout**（退出码 0）：
+3. 目标命令支持 `--dry-run` 时，用 `--dry-run` 预览危险请求。
 
-```json
-{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
-```
+4. **退出码 10 是高风险确认门禁（`risk: "high-risk-write"`），不是错误**：停下 → **向用户确认**（展示 `action`、`risk` 和关键参数）→ 取得**用户显式同意**后，将 `hint` 指出的确认 flag **追加到你原始 argv 的末尾**后重试；**绝不**静默加确认 flag 绕过 → [`lark-shared-high-risk-approval.md`](references/lark-shared-high-risk-approval.md)。
 
-错误信封写入 **stderr**（退出码非 0）：
+5. **文件路径只接受相对路径**：`--file`、`--output`、`--output-dir`、`@file` 等路径参数只接受 cwd 下的相对路径，传绝对路径会报 `unsafe file path`。数据输入（`@file`、大 JSON）优先用 stdin 传入，避免路径和转义问题。
 
-```json
-{ "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`）时尤其危险，误判会绕过幂等逻辑导致重复创建。
+## Reference 强触发索引
 
-## 安全规则
+命中任一触发条件时，**MUST 在执行下一步前读取对应 reference**。命中多条时按表中顺序读取，同一reference只读取一次。
 
-- **禁止输出密钥**（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,
-  "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"
-  }
-}
-```
-
-**遇到这种情况，不要当普通错误放弃。** 按以下流程处理：
-
-1. **识别**：看到子进程 exit code = `10` 且 stderr JSON 里 `error.type == "confirmation"`、`error.subtype == "confirmation_required"`
-2. **向用户确认**：把 `error.action`、`error.risk` 和关键参数展示给用户，明确告知"这是高风险操作"，等待用户显式同意
-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"`
+| 强触发条件（命中任一即必读） | Reference |
+|---|---|
+| 查看自己是谁(user/bot)、获取当前身份详细字段信息、身份诊断、`--as`选择逻辑、身份延续、登录态、认证、scope、授权和权限管理、`missing_scopes` 或 `console_url`、Agent 准备发起或完成 `auth login` | [`lark-shared-identity-and-permissions.md`](references/lark-shared-identity-and-permissions.md) |
+| 需要依赖 JSON 输出契约判断成功 / 失败、读取 stdout / stderr，或为命令编写脚本与封装 | [`lark-shared-output-contract.md`](references/lark-shared-output-contract.md) |
+| 准备执行high-risk-write(高风险操作)、判断命令风险等级、遇到退出码 exit 10、`confirmation_required`、确认后重试 | [`lark-shared-high-risk-approval.md`](references/lark-shared-high-risk-approval.md) |
+| 首次使用CLI需运行 `lark-cli config init` 完成应用配置、或 CLI 明确提示 `config init --new` | [`lark-shared-config-init.md`](references/lark-shared-config-init.md) |
+| 用户询问 notice、CLI版本更新、或输出含 `_notice`（升级 / skills 落后 / 废弃命令提示）| [`lark-shared-update-notice.md`](references/lark-shared-update-notice.md) |

package/skills/lark-shared/references/lark-shared-config-init.md

@@ -0,0 +1,12 @@
+# 首次配置 lark-cli
+
+首次使用需运行 `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
+```

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

@@ -0,0 +1,38 @@
+# 高风险操作的审批协议（exit 10）
+
+lark-cli 对高风险写操作（`risk: "high-risk-write"`）有强制确认门禁。当缺少命令要求的确认 flag（通常是 `--yes`）时，CLI 会退出码 `10`、并在 stderr 返回如下结构化 envelope：
+
+```json
+{
+  "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"
+  }
+}
+```
+
+**遇到这种情况，不要当普通错误放弃。** 按以下流程处理：
+
+1. **识别**：看到子进程 exit code = `10` 且 stderr JSON 里 `error.type == "confirmation"`、`error.subtype == "confirmation_required"`
+2. **向用户确认**：把 `error.action`、`error.risk` 和关键参数展示给用户，明确告知"这是高风险操作"，等待用户显式同意
+3. **用户同意** → 按 `error.hint` 确定确认 flag，并追加到你**自己的原始 argv** 后重试。多数命令使用 `--yes`
+4. **用户拒绝** → 终止流程，不要擅自改写参数或跳过门禁
+
+**绝对不允许**：
+- 看到 exit 10 就默认加确认 flag 静默重试（这等于禁用门禁）
+- 把 `confirmation_required` 当网络错误/权限错误处理
+- 在用户没明确同意的前提下追加确认 flag 重试
+- 用 `sh -c` 等 shell 方式拼接命令重试——用参数数组（argv）形式传参，避免 shell 解析把用户参数当作语法
+
+提前预判：想先让用户 review 危险操作的具体请求，且目标命令支持 `--dry-run` 时，调用时加 `--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"`

package/skills/lark-shared/references/lark-shared-identity-and-permissions.md

@@ -0,0 +1,105 @@
+# 身份与权限
+
+## 认证任务速查
+
+| 用户意图 | 首选命令 / 回答 |
+|---|---|
+| 获取全部权限 | `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` 干扰，可在命令前加：
+
+```bash
+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` 优先；省略时由 CLI 根据当前配置和可用凭证自动选择(可通过 `lark-cli whoami` 查看 `identity` 和选择逻辑)。
+- 因此，盲目省略 `--as` 是不可控的，在明确需要保持某一身份时，建议全程显式选择。
+
+## 权限不足处理
+
+遇到权限相关错误时，**根据当前身份类型采取不同解决方案**。
+
+错误响应中包含关键信息：
+- `missing_scopes`：列出缺失的 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> --no-wait --json          # 按业务域发起授权
+lark-cli auth login --scope "<missing_scope>" --no-wait --json  # 按具体 scope 发起授权（推荐，符合最小权限原则）
+```
+
+**规则**：auth login 必须指定范围（`--scope`、`--domain` 或 `--recommend`）。多次 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`**：每次需要重新发起授权时，必须沿用所需的 `--scope`、`--domain` 或 `--recommend` 选择以及任何 `--exclude` 值，并附加 `--no-wait --json` 生成新的链接。不要复用已过期的授权链接或 device code

package/skills/lark-shared/references/lark-shared-output-contract.md

@@ -0,0 +1,17 @@
+# JSON 输出契约
+
+`--format json`（默认）下，成功与错误的信封结构不同：
+
+成功信封写入 **stdout**（退出码 0）：
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+错误信封写入 **stderr**（退出码非 0）：
+
+```json
+{ "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`）时尤其危险，误判会绕过幂等逻辑导致重复创建。

package/skills/lark-shared/references/lark-shared-update-notice.md

@@ -0,0 +1,23 @@
+# 更新与 `_notice`
+
+lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_notice.update` 字段（含 `message`、`command` 等）。
+
+除非用户正在询问更新、版本或 notice，否则不要把 `_notice` 原样复制为当前任务的主要答案，也不要为了 notice 中断当前任务去反复查 help。
+
+需要稳定 JSON 给脚本或机器读取时，可以在命令前设置：
+
+```bash
+LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 <lark-cli command>
+```
+
+当你在输出中看到 `_notice.update` 时，先完成用户当前请求；如仍相关，再简短告知可运行：
+
+```bash
+lark-cli update
+```
+
+**重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。
+
+另外两类 notice：
+- `_notice.skills`：本地 Skills 与当前 CLI 不同步。
+- `_notice.deprecated_command`：本次使用了兼容保留的旧命令；后续调用改用 `replacement`。如果同时提供 `action: "lark-cli update"`，同样建议升级。

package/skills/lark-vc/references/lark-vc-recording.md

@@ -138,7 +138,7 @@ lark-cli minutes +download --minute-tokens <minute_token>
 | `no recording available` | 该会议无录制或录制未完成 | 确认会议已结束且开启了录制 |
 | `121005 no permission` | 无权查看该会议录制 | 确认是会议参与者或有录制权限 |
 | `124002 recording generating` | 录制文件仍在生成中 | 等待录制完成后重试 |
-| `missing required scope(s)` | 权限不足 | `--as user`：按提示运行 `auth login --scope`；`--as bot`：使用错误中的 `console_url` 去开发者后台开通，**禁止**对 bot 执行 `auth login`（见 [lark-shared](../../lark-shared/SKILL.md) 的权限恢复表） |
+| `missing required scope(s)` | 权限不足 | `--as user`：按提示运行 `auth login --scope`；`--as bot`：使用错误中的 `console_url` 去开发者后台开通，**禁止**对 bot 执行 `auth login`（见 [lark-shared](../../lark-shared/SKILL.md) 的权限管理） |
 
 ## 提示
 

package/skills/lark-workflow-meeting-summary/SKILL.md

@@ -29,6 +29,7 @@ metadata:
 ```bash
 lark-cli auth login --domain vc        # 基础（查询+纪要）
 lark-cli auth login --domain vc,drive   # 含读取纪要文档正文、生成文档
+lark-cli auth login --domain vc,drive,minutes  # 含无 note_id 时的妙记备选路径
 ```
 
 ## 工作流
@@ -80,9 +81,18 @@ lark-cli note +detail --note-id "note_id"
 ```
 - 根据上一步搜集到的 `meeting-id` 查询。
 - 单次最多查询 50 个，超过 50 个需分批调用。
-- 部分会议没有 `note_id` 或报错 `no notes available`，在最终输出中标注"无纪要"。
+- 部分会议没有 `note_id` 或报错 `no notes available`，**不要直接标注"无纪要"**：先看 `vc +detail` 是否返回了 `minute_token`，有则走下面的妙记备选路径；`note_id` 和 `minute_token` 都没有时才标注"无纪要"。
 - 记录每个纪要的 `note_id`（纪要 ID）、`note_display_type`（展示类型：`unknown` / `normal` / `unified`）、`note_doc_token`（纪要文档 Token）和 `verbatim_doc_token`（逐字稿文档 Token）。
 
+> **妙记备选路径（无 `note_id`、有 `minute_token` 时）**：智能纪要与妙记是两条独立产物链路，缺少智能纪要不代表这场会没有内容。
+>
+> ```bash
+> # --minute-tokens 是复数形式（+download 同）；--output-dir 只接受相对路径
+> lark-cli minutes +detail --minute-tokens "<minute_token>" --transcript --output-dir ./transcripts --as user
+> ```
+>
+> 逐字稿会落盘，供 Step 4 基于原始发言独立提炼（不要照搬 AI 总结）。若返回 `No read permission`（`2091005`），先把无权限事实告知用户，用户明确同意后再用单数 flag 申请：`lark-cli minutes +apply-permission --minute-token "<minute_token>" --perm view --as user`；申请需 owner 在客户端批准后才可重试。详见 [lark-minutes](../lark-minutes/SKILL.md)。
+
 > **逐字稿路由按 `note_display_type` 决定**（详见 [vc-domain-boundaries.md](../lark-vc/references/vc-domain-boundaries.md) 的 Note 域）：
 > - `normal`：逐字稿是独立文档，链接/正文走 `verbatim_doc_token`。
 > - `unified`：逐字稿**不是独立文档**，没有可分享的逐字稿文档链接；需要逐字稿内容时用 `note +transcript --note-id <note_id>`（[lark-note](../lark-note/SKILL.md)）拉取到本地，报告中标注"unified 纪要"即可。
@@ -119,4 +129,5 @@ lark-cli docs +update --doc "<url_or_token>" --command append --doc-format markd
 - [lark-shared](../lark-shared/SKILL.md) — 认证、权限（必读）
 - [lark-vc](../lark-vc/SKILL.md) — `+search`、`+detail` 详细用法
 - [lark-note](../lark-note/SKILL.md) — `note +detail`、`note +transcript`（unified 纪要逐字稿）
+- [lark-minutes](../lark-minutes/SKILL.md) — `minutes +detail`、`+apply-permission`（无 `note_id` 时的妙记备选路径）
 - [lark-doc](../lark-doc/SKILL.md) — `+fetch`、`+create`、`+update` 详细用法