@amaster.ai/pi-lark 0.1.4 → 0.1.6

package/skills/lark-okr/references/lark-okr-progress-update.md

@@ -0,0 +1,85 @@
+# okr +progress-update
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新指定 ID 的 OKR 进展记录内容。
+
+## 推荐命令
+
+```bash
+# 更新进展记录内容（默认 simple 风格，半纯文本格式）
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content '{"text":"更新后的进展内容","mention":["ou_123"]}'
+
+# 更新进展记录内容并同时更新进度（richtext 风格，完整 ContentBlock 格式）
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content '{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"进度已更新至 90%"}}]}}]}' \
+  --style richtext \
+  --progress-percent 90 \
+  --progress-status normal
+
+# 从文件读取 content（适用于较长的进展内容）
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content @updated_progress.json
+
+# 预览 API 调用而不实际执行
+lark-cli okr +progress-update \
+  --progress-id 1234567890123456789 \
+  --content '{"text":"test"}' \
+  --dry-run
+```
+
+## 参数
+
+| 参数                   | 必填 | 默认值       | 说明                                                                                                             |
+|----------------------|----|-----------|----------------------------------------------------------------------------------------------------------------|
+| `--progress-id`      | 是  | —         | 进展记录 ID（int64 类型，正整数）                                                                                          |
+| `--content`          | 是  | —         | 进展内容。根据 `--style` 指定格式：`simple` 风格为 SemiPlainContent JSON，`richtext` 风格为 ContentBlock JSON。支持 `@文件路径` 从文件读取。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。 |
+| `--style`            | 否  | `simple`  | 输入风格：`simple`（半纯文本 JSON，推荐） \| `richtext`（完整 ContentBlock JSON）。请参考 [ContentBlock 格式](lark-okr-contentblock.md) 了解两种格式。          |
+| `--progress-percent` | 否  | —         | 进度百分比(-99999999999 - 99999999999)。百分比的取值通常在 0-100，但允许超过此范围，以表示超额完成或负增长等情况。挂载的目标或关键结果的量化指标不使用百分比单位时，以这个字段更新当前值。系统内最多保留两位小数 |
+| `--progress-status`  | 否  | —         | 进度状态：`normal`（正常） \| `overdue`（逾期） \| `done`（已完成）。仅在指定 `--progress-percent` 时生效。                               |
+| `--user-id-type`     | 否  | `open_id` | 用户 ID 类型：`open_id` \| `union_id` \| `user_id`                                                                  |
+| `--dry-run`          | 否  | —         | 预览 API 调用而不实际执行。                                                                                               |
+| `--format`           | 否  | `json`    | 输出格式。                                                                                                          |
+
+## 工作流程
+
+1. 使用 `+progress-get` 获取要更新的进展记录的 ID 和当前内容。
+2. 修改进展内容：
+   - **推荐**：使用 `simple` 风格（默认），构造 SemiPlainContent JSON：`{"text":"内容","mention":["ou_xxx"]}`，mention 中提及的用户会统一连接在文本末尾。
+   - 如需复杂格式：使用 `richtext` 风格，构造 ContentBlock JSON。请参考 [ContentBlock 格式](lark-okr-contentblock.md)。若需要插入图片/飞书文档或复杂文本格式，则必须使用 richtext 风格
+3. 执行 `lark-cli okr +progress-update --progress-id "..." --content "..."`。
+4. 报告结果：更新后的进展记录 ID、修改时间、进度百分比等。
+
+## 输出
+
+返回 JSON：
+
+```json
+{
+  "progress": {
+    "progress_id": "1234567890123456789",
+    "modify_time": "2025-01-15 14:30:00",
+    "content": "{...}",
+    "progress_rate": {
+      "percent": 90.0,
+      "status": "normal"
+    }
+  }
+}
+```
+
+其中：
+
+- `content` 字段是 JSON 字符串，为 OKR ContentBlock
+  富文本格式。请参考 [lark-okr-contentblock.md](lark-okr-contentblock.md) 了解详细信息。
+- `progress_rate.status` 返回可读字符串：`normal`（正常）、`overdue`（逾期）、`done`（已完成）。
+
+## 参考
+
+- [lark-okr](../SKILL.md) -- 所有 OKR 命令(shortcut 和 API 接口)
+- [ContentBlock 格式](lark-okr-contentblock.md) -- 进展内容使用的富文本格式
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/lark-okr/references/lark-okr-reorder.md

@@ -0,0 +1,81 @@
+# okr +reorder
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+调整 OKR 周期下目标（Objective）或目标下关键结果（Key Result）的顺序。
+
+## 推荐命令
+
+```bash
+# 调整 Objective 顺位
+lark-cli okr +reorder \
+  --cycle-id 7000000000000000001 \
+  --level objective \
+  --ops '[
+    {"id": "7000000000000000002", "position": 2},
+    {"id": "7000000000000000003", "position": 1}
+  ]' \
+  --as user
+
+# 调整 KR 顺位（需指定 --objective-id）
+lark-cli okr +reorder \
+  --cycle-id 7000000000000000001 \
+  --level key-result \
+  --objective-id 7000000000000000002 \
+  --ops '[
+    {"id": "7000000000000000004", "position": 1},
+    {"id": "7000000000000000005", "position": 2}
+  ]' \
+  --as user
+
+# 从文件读取 ops
+lark-cli okr +reorder \
+  --cycle-id 7000000000000000001 \
+  --level objective \
+  --ops @reorder_ops.json \
+  --as user
+```
+
+- 不允许将多个 objective/key-result 放在同一个位置下
+
+## 参数
+
+| 参数               | 必填 | 默认值    | 说明                                                      |
+|------------------|----|--------|---------------------------------------------------------|
+| `--level`        | 是  | —      | 调整层级：`objective`（调整周期下目标顺序）\| `key-result`（调整目标下 KR 顺序） |
+| `--cycle-id`     | 是  | —      | OKR 周期 ID（int64 类型）。                                    |
+| `--objective-id` | 条件 | —      | 目标 ID。当 `--level=key-result` 时**必填**，用于定位父目标。           |
+| `--ops`          | 是  | —      | JSON 数组格式的顺位调整操作。支持 `@文件路径` 或 `@-` 从 stdin 读取。          |
+| `--dry-run`      | 否  | —      | 预览 API 调用而不实际执行                                         |
+| `--format`       | 否  | `json` | 输出格式                                                    |
+
+## 工作流程
+
+1. 使用 `+cycle-list` 和 `+cycle-detail` 获取周期 ID、目标 ID 和 KR ID。
+2. 构造 `--ops` JSON 数组，指定要调整的 ID 和新 position，执行命令。
+3. 返回调整后的完整顺序。
+
+## 输出
+
+成功返回 JSON（以调整 Objective 位置为例）：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "level": "objective",
+    "cycle_id": "7000000000000000001",
+    "total": 3,
+    "ordered": [
+      "7000000000000000003",
+      "7000000000000000002",
+      "7000000000000000004"
+    ]
+  }
+}
+```
+
+## 参考
+
+- [OKR 业务实体](lark-okr-entities.md) -- OKR 实体结构定义
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/lark-okr/references/lark-okr-weight.md

@@ -0,0 +1,96 @@
+# okr +weight
+
+> **前置条件：** 先阅读 [`lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+调整 OKR 周期下目标（Objective）或目标下关键结果（Key Result）的权重。支持部分指定权重，未指定的按原权重比例自动分配。
+
+## 推荐命令
+
+```bash
+# 调整 Objective 权重（部分指定，剩余自动分配）
+lark-cli okr +weight \
+  --cycle-id 7000000000000000001 \
+  --level objective \
+  --weights '[
+    {"id": "7000000000000000002", "weight": 0.6},
+    {"id": "7000000000000000003", "weight": 0.3}
+  ]' \
+  --as user
+
+# 调整 KR 权重（全部指定，和为 1）
+lark-cli okr +weight \
+  --cycle-id 7000000000000000001 \
+  --level key-result \
+  --objective-id 7000000000000000002 \
+  --weights '[
+    {"id": "7000000000000000004", "weight": 0.6},
+    {"id": "7000000000000000005", "weight": 0.4}
+  ]' \
+  --as user
+
+# 从文件读取 weights
+lark-cli okr +weight \
+  --cycle-id 7000000000000000001 \
+  --level objective \
+  --weights @weights.json \
+  --as user
+```
+
+参数限制: 请求中的权重保留三位小数，分配的所有权重和不能大于 1 (小于等于 1 是允许的)。
+
+### 权重归一化
+
+- 在 OKR 中，一个周期下所有 Objective 和 一个 Objective 下所有 Key Result 的权重和固定为 1.
+- 在使用 +weight shortcut 分配 OKR 权重时，已分配的总权重不得超过 1。
+- 若已分配的权重 < 1，剩余的权重会按照原始权重的比例均分到未指定的 Objective/Key Result 下。
+  - 若所有 Objective/Key Result 均分配了权重但和 < 1，剩余的权重会计算在最后一个 Objective/Key Result 下。
+
+
+
+## 参数
+
+| 参数               | 必填 | 默认值    | 说明                                                                  |
+|------------------|----|--------|---------------------------------------------------------------------|
+| `--level`        | 是  | —      | 调整层级：`objective`（调整周期下目标权重）\| `key-result`（调整目标下 KR 权重）             |
+| `--cycle-id`     | 是  | —      | OKR 周期 ID（int64 类型）                                                 |
+| `--objective-id` | 条件 | —      | 目标 ID。当 `--level=key-result` 时**必填**，用于定位父目标。                       |
+| `--weights`      | 是  | —      | JSON 数组格式的权重分配。支持 `@文件路径` 或 `@-` 从 stdin 读取。权重保留三位小数，分配的所有权重和不能大于 1 |
+| `--dry-run`      | 否  | —      | 预览 API 调用而不实际执行                                                     |
+| `--format`       | 否  | `json` | 输出格式                                                                |
+
+## 工作流程
+
+1. 使用 `+cycle-list` 和 `+cycle-detail` 获取周期 ID、目标 ID、KR ID 和当前权重。
+2. 构造 `--weights` JSON 数组，指定要调整的 ID 和权重，执行命令。
+3. 返回调整后的完整权重列表。
+
+## 输出
+
+成功返回 JSON：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "level": "objective",
+    "cycle_id": "7000000000000000001",
+    "total": 3,
+    "weights": [
+      {"id": "7000000000000000002", "weight": 0.6},
+      {"id": "7000000000000000003", "weight": 0.3},
+      {"id": "7000000000000000004", "weight": 0.1}
+    ]
+  }
+}
+```
+
+## 关于 1001001 错误
+
+有时，即使输入的参数完全正确， +weight 也会返回 1001001 错误。这是因为你的租户设置中，不一定开启了目标或关键结果的设置权重功能。
+若你确认输入的参数无误（cycle-id/objective-id 正确，weights 中的 id 均是同一个周期下的目标或同一个目标下的关键结果，weights 中的权重和 <1）,
+不必进一步尝试，你需要向用户确认 OKR 应用目前是否开启了目标或关键结果的设置权重功能。
+
+## 参考
+
+- [OKR 业务实体](lark-okr-entities.md) -- OKR 实体结构定义
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/lark-openapi-explorer/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: lark-openapi-explorer
+version: 1.0.0
+description: "飞书/Lark 原生 OpenAPI 探索：从官方文档库中挖掘未经 CLI 封装的原生 OpenAPI 接口。当用户的需求无法被现有 lark-* skill 或 lark-cli 已注册命令满足，需要查找并调用原生飞书 OpenAPI 时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+---
+
+# OpenAPI Explorer
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 了解认证、身份切换和安全规则。
+
+当用户的需求**无法被现有 skill 或 CLI 已注册 API 覆盖**时，使用本技能从飞书官方 markdown 文档库中逐层挖掘原生 OpenAPI 接口，然后通过 `lark-cli api` 裸调完成任务。
+
+## 文档库结构
+
+飞书 OpenAPI 文档以 markdown 层级组织：
+
+```
+llms.txt                          ← 顶层索引，列出所有模块文档链接
+  └─ llms-<module>.txt            ← 模块文档，包含功能概述 + 底层 API 文档链接
+       └─ <api-doc>.md            ← 单个 API 的完整说明（方法/路径/参数/响应/错误码）
+```
+
+文档入口：
+
+| 品牌 | 入口 URL |
+|------|----------|
+| 飞书 (Feishu) | `https://open.feishu.cn/llms.txt` |
+| Lark | `https://open.larksuite.com/llms.txt` |
+
+> 所有文档以**中文**编写。如果用户使用英文交流，需将文档内容翻译为英文后输出。
+
+## 挖掘流程
+
+严格按以下步骤逐层检索，**不要跳步或猜测 API**：
+
+### Step 1：确认现有能力不足
+
+```bash
+# 先检查是否已有对应的 skill 或已注册 API
+lark-cli <可能的service> --help
+```
+
+如果已有对应命令或 shortcut，直接使用，**不需要继续挖掘**。
+
+### Step 2：从顶层索引定位模块
+
+用 WebFetch 获取顶层索引，找到与需求相关的模块文档链接：
+
+```
+WebFetch https://open.feishu.cn/llms.txt
+  → 提取问题："列出所有模块文档链接，找出与 <用户需求关键词> 相关的链接"
+```
+
+- 飞书品牌使用 `open.feishu.cn`
+- Lark 品牌使用 `open.larksuite.com`
+- 如不确定用户品牌，默认使用飞书
+
+### Step 3：从模块文档定位具体 API
+
+用 WebFetch 获取模块文档，找到具体 API 的文档链接：
+
+```
+WebFetch https://open.feishu.cn/llms-docs/zh-CN/llms-<module>.txt
+  → 提取问题："找出与 <用户需求> 相关的 API 说明和文档链接"
+```
+
+### Step 4：获取 API 完整规范
+
+用 WebFetch 获取具体 API 文档，提取完整的调用规范：
+
+```
+WebFetch https://open.feishu.cn/document/server-docs/.../<api>.md
+  → 提取问题："返回完整 API 规范：HTTP 方法、URL 路径、路径参数、查询参数、请求体字段（名称/类型/必填/说明）、响应字段、所需权限、错误码"
+```
+
+### Step 5：通过 CLI 调用 API
+
+使用 `lark-cli api` 裸调：
+
+```bash
+# GET 请求
+lark-cli api GET /open-apis/<path> --params '{"key":"value"}'
+
+# POST 请求
+lark-cli api POST /open-apis/<path> --data '{"key":"value"}'
+
+# PUT 请求
+lark-cli api PUT /open-apis/<path> --data '{"key":"value"}'
+
+# DELETE 请求
+lark-cli api DELETE /open-apis/<path>
+```
+
+## 输出规范
+
+向用户呈现挖掘结果时，按以下格式组织：
+
+1. **API 名称与功能**：一句话描述
+2. **HTTP 方法与路径**：`METHOD /open-apis/...`
+3. **关键参数**：列出必填和常用可选参数
+4. **所需权限**：scope 列表
+5. **调用示例**：给出 `lark-cli api` 的完整命令
+6. **注意事项**：频率限制、特殊约束等
+
+如果用户使用英文交流，将以上所有内容翻译为英文。
+
+## 安全规则
+
+- **写入/删除类 API**（POST/PUT/DELETE）调用前必须确认用户意图
+- 建议先用 `--dry-run` 预览请求（如支持）
+- 不要猜测 API 路径或参数——必须从文档中获取确认
+- 涉及敏感操作（删除群、移除成员等）时，向用户说明影响范围
+
+## 使用场景示例
+
+### 场景 1：用户需要拉人进群（未被 CLI 封装）
+
+```bash
+# Step 1: 确认 CLI 没有封装
+lark-cli im --help
+# → 发现没有 chat_members 相关的 create 命令
+
+# Step 2-4: 通过文档挖掘获得 API 规范
+# → POST /open-apis/im/v1/chats/:chat_id/members
+
+# Step 5: 调用
+lark-cli api POST /open-apis/im/v1/chats/oc_xxx/members \
+  --data '{"id_list":["ou_xxx","ou_yyy"]}' \
+  --params '{"member_id_type":"open_id"}'
+```
+
+### 场景 2：用户需要设置群公告
+
+```bash
+# Step 1: 确认 CLI 没有封装
+lark-cli im --help
+# → 没有 announcement 相关命令
+
+# Step 2-4: 挖掘文档
+# → PATCH /open-apis/im/v1/chats/:chat_id/announcement
+
+# Step 5: 调用
+lark-cli api PATCH /open-apis/im/v1/chats/oc_xxx/announcement \
+  --data '{"revision":"0","requests":["<html>公告内容</html>"]}'
+```
+
+## 参考
+
+- [lark-shared](../lark-shared/SKILL.md) — 认证和全局参数
+- [lark-skill-maker](../lark-skill-maker/SKILL.md) — 如需将挖掘到的 API 固化为新 Skill

package/skills/lark-shared/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: lark-shared
+version: 1.0.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."
+---
+
+# lark-cli 共享规则
+
+本技能指导你如何通过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
+```
+
+## 认证
+
+### 认证任务速查
+
+认证、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` 授权，两层都要满足
+
+
+### 权限不足处理
+
+遇到权限相关错误时，**根据当前身份类型采取不同解决方案**。
+
+错误响应中包含关键信息：
+- `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>           # 按业务域授权
+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，否则不要把 `_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 输出契约
+
+`--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`）时尤其危险，误判会绕过幂等逻辑导致重复创建。
+
+## 安全规则
+
+- **禁止输出密钥**（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"`

package/skills/lark-shared/references/lark-wiki-token-routing.md

@@ -0,0 +1,42 @@
+# Wiki token routing
+
+Wiki URL 中的 `/wiki/<token>` 是节点 token，不一定是底层文档、表格、Base、文件或幻灯片的对象 token。需要对底层对象做读取、评论、导出、下载、表内操作等动作时，先解包，再按底层类型路由。
+
+## 推荐方式
+
+优先使用 `lark-drive` 的 `drive +inspect`：
+
+```bash
+lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/<wiki_token>'
+```
+
+输出中的 `type` 是底层对象类型，`token` 是后续命令应使用的 canonical token。`wiki_node` 字段保留节点侧信息，如 `space_id`、`node_token`、`obj_token`、`obj_type`。
+
+## 手动方式
+
+如果不能使用 shortcut，再调用 Wiki 节点接口：
+
+```bash
+lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'
+```
+
+从返回值中读取：
+
+| 字段 | 含义 |
+|------|------|
+| `node.obj_type` | 底层对象类型，如 `docx`、`doc`、`sheet`、`bitable`、`slides`、`file`、`mindnote` |
+| `node.obj_token` | 底层对象 token，用于对应业务 skill 或原生 API |
+| `node.node_token` / `token` | Wiki 节点 token，用于 Wiki 节点层级操作 |
+| `node.space_id` | 所属知识空间 |
+
+## 路由
+
+| `obj_type` | 后续操作 |
+|------------|----------|
+| `docx` / `doc` | 文档内容走 `lark-doc`；评论、权限、导出等云空间能力走 `lark-drive` |
+| `sheet` | 表内数据走 `lark-sheets`；评论、权限、导出等云空间能力走 `lark-drive` |
+| `bitable` | 表内数据走 `lark-base`；评论、权限、导出等云空间能力走 `lark-drive` |
+| `slides` | 幻灯片内容编辑走 `lark-slides`；评论、权限、导出等云空间能力走 `lark-drive` |
+| `file` | 普通文件上传、下载、评论、权限等走 `lark-drive` |
+| `mindnote` | 思维笔记的移动、删除、快捷方式、权限、安全标签等云空间能力走 `lark-drive`；知识库节点层级操作走 `lark-wiki` |
+| wiki 节点层级 / 空间成员 | 走 `lark-wiki`，不要把底层对象 token 当节点 token |