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

package/skills/lark-calendar/references/lark-calendar-create.md

@@ -36,6 +36,7 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 | `--attendee-ids <id_list>` | 否 | 参与人 ID 列表（逗号分隔）。支持用户（`ou_`）、群组（`oc_`）和会议室（`omm_`）。AI 提取时请务必保留对应前缀。bot 可作为合法参会人，无需剔除 |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
 | `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。示例值："FREQ=DAILY;INTERVAL=1;UNTIL=<具体日期>" |
+| `--meeting-owner-id <ou_>` | 否 | 设置 VC 会议 owner。仅以应用（bot）身份在应用日历上操作时生效（需 `--as bot`）；owner 必须为本租户用户身份的 open_id（`ou_`） |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
 
 > 当用户表达'每周 X'、'每周重复'、'连续 N 周'时，必须使用 rrule 创建重复性日程，而非创建多个独立日程
@@ -49,7 +50,8 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 
 ## 高级用法（完整 API 命令）
 
-如需配置 `location`（地理位置，不含会议室位置）、`visibility`（日程公开范围）、自定义 `reminders`（提醒设置）、自定义 `attendee_ability`（参与人权限）、自定义 `free_busy_status`（日程忙闲状态）、参与人可选参加状态或全天日程等高级参数，请使用完整的 API 命令：
+> 优先策略：创建日程优先走 `+create`。遇到 `+create` 不支持的高级参数（如 `location`（地理位置，不含会议室位置）、`visibility`（日程公开范围）、自定义 `reminders`（提醒设置）、自定义 `attendee_ability`（参与人权限）、自定义 `free_busy_status`（日程忙闲状态）、参与人可选参加状态或全天日程等），**优先先用 `+create` 创建成功，再用完整 API update 对这些字段做编辑补齐**，而非整体改用完整 API 从零创建。
+
 **注意**：
 - 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天。如果只有一天的话，开始日期和结束日期是相同。
 
@@ -60,12 +62,10 @@ lark-cli calendar event.attendees create \
   --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
   --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}'
 
-完整 API 命令的关键差异：
-- `+create` 在传入 `--attendee-ids`（即需要邀请其他参会人）时，会自动把当前身份一并加进参会人，但 `calendar events create` / `calendar event.attendees create` 等完整 API **不会**自动加。需自行把调用身份的 open_id 以 `type:user` 写入 attendees，与邀请的其他参会人合并去重后添加。open_id 用 `lark-cli auth status --json --verify` 获取：bot 取 `identities.bot.openId`（`--verify` 才会填充），user 取 `identities.user.openId`。
+完整 API 命令的关键差异和处理策略：
 - 时间参数是 **Unix 秒字符串**（非 ISO 8601）。换算时**禁止依赖容器默认时区**（常为 UTC，会导致 8 小时偏移），必须显式指定目标时区。
 - 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天；单日全天日程两者相同。
 - 手动拆成“创建日程 + 添加参会人”两步时，若第二步失败，建议删除刚创建的空日程，避免遗留无参会人的日程。
-- 设置会议 owner：`+create` 不支持，需用完整 API 命令在 `vchat.meeting_settings.owner_id` 中设置，且必须同时设置 `vchat.vc_type` 为 `vc`（代表该日程为 VC 视频会议）。仅当以应用（bot）身份在应用日历上操作时生效；owner 必须为用户身份（`ou_` open_id），不能为非用户或外部租户用户。
 
 ## 参会人类型
 

package/skills/lark-doc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-doc
-description: "飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由。文档内嵌资源按读取参考中的统一规则分流。文档评论走 lark-drive；表格或 Base 内部数据操作不在本 skill。"
+description: "飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -14,7 +14,7 @@ metadata:
 
 **CRITICAL：先判断场景，再读取该场景的参考文件；不要在任务开始时一次性读取全部参考文件。每个文件只在首次进入对应阶段时读取一次。**
 
-**身份：文档操作推荐显式指定 `--as user`。例外：如果 `doc_token` / `note_doc_token` 等是从 bot 链路（如 `vc +detail --as bot` → `note +detail --as bot`）取得的，应继续显式使用 `--as bot`，不要无条件切回 user——身份延续规则见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。**
+**身份：文档操作推荐显式指定 `--as user`。**
 
 **所有表示本地文件的 `@path` 均使用 `@./xxx` 形式的相对路径，并以运行 `lark-cli` 时的当前工作目录（CWD）为基准。**
 
@@ -33,7 +33,7 @@ metadata:
 ### 资源、画板与思维笔记
 
 - **插入本地素材 — [`+media-insert`](references/lark-doc-media-insert.md)**：在文末插入本地图片或文件。
-- **预览素材 — [`+media-preview`](references/lark-doc-media-preview.md)**：预览文档中的图片、附件或素材。
+- **预览素材 — [`+media-preview`](references/lark-doc-media-preview.md)**：预览文档或评论中的图片、附件或素材。
 - **下载素材 — [`+media-download`](references/lark-doc-media-download.md)**：下载文档中的图片、附件、素材或画板缩略图。
 - **Docx 封面 — [`+resource-download` / `+resource-update` / `+resource-delete`](references/lark-doc-resource-cover.md)**：下载、更新或删除 Docx 封面。
 - **画板 — [`画板工作流`](references/lark-doc-whiteboard.md)**：创建或更新画板时先读取工作流；更新已有画板必须复用现有 token，禁止新建空白画板；使用 [`whiteboard +update`](../lark-whiteboard/references/lark-whiteboard-update.md) 写入。
@@ -46,4 +46,4 @@ metadata:
 ## 不在本 Skill 范围
 
 - **Drive 文件级操作**：找文档、导入导出、云空间文件上传 / 下载 / 权限管理 → [`lark-drive`](../lark-drive/SKILL.md)。复制文档、创建副本或另存为副本时，按其指引使用 `lark-cli drive files copy`；不要用 `docs +fetch` + `docs +create` 重建正文。
-- **文档评论**：添加、查看、回复评论或增删 reaction → [`lark-drive`](../lark-drive/SKILL.md)。
+- **独立评论操作**：添加、分页查看、回复评论或增删 reaction → [`lark-drive`](../lark-drive/SKILL.md)；只需紧凑评论上下文时，直接使用默认 JSON 响应的 `docs +fetch`。

package/skills/lark-doc/references/lark-doc-fetch.md

@@ -5,7 +5,7 @@
 ## 常用示例
 
 ```bash
-# 读取整篇文档
+# 读取整篇文档，并附带当前用户可见的未解决评论；
 lark-cli docs +fetch --doc "文档URL或token"
 
 # 按 URL 中的 #share 锚点局部读取
@@ -34,7 +34,6 @@ lark-cli docs +fetch --doc Z1Fj...tnAc --scope section --start-block-id blkTitle
 |`--context-before`|否|返回命中项之前的顶层兄弟块数量（默认 `0`）|
 |`--context-after`|否|返回命中项之后的顶层兄弟块数量（默认 `0`）|
 |`--max-depth`|否|`outline` 表示标题层级上限；其它模式表示子树深度（默认 `-1`，不限）|
-|`--format`|否|`json`（默认）\| `pretty`|
 
 ## 选择详细度：`--detail`
 
@@ -90,6 +89,11 @@ lark-cli docs +fetch --doc Z1Fj...tnAc --scope section --start-block-id blkTitle
           "<ref>": {
             "<real-attr-key>": "<real-attr-value>"
           }
+        },
+        "comments": {
+          "c1": {
+            "data": "<comment comment-id=\"xx\" block-id=\"xx\"><quote>引用内容</quote><msg>评论内容</msg></comment>"
+          }
         }
       },
       "tips": "<safe replay or degradation guidance>"
@@ -97,7 +101,8 @@ lark-cli docs +fetch --doc Z1Fj...tnAc --scope section --start-block-id blkTitle
   }
 }
 ```
-`content` 的格式由 `--doc-format` 决定。`reference_map` 是正文引用数据的结构化 sidecar：一级键 `block_type` 表示引用所在的块类型，二级键 `ref` 对应正文中的临时引用；每个引用的值是由 `real-attr-key` 和 `real-attr-value` 组成的真实属性映射，具体属性由块类型决定。没有提取数据时，`reference_map` 可能为空。`content` 和 `reference_map` 属于同一份响应，保留或回放内容时应配套处理。`tips` 给出安全回放或降级提示。`im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用。设置 `--scope` 时会被 `<fragment>` 包裹，详见上文"局部读取的输出结构"。
+- `content` 的格式由 `--doc-format` 决定。`reference_map` 是结构化 sidecar，一级键表示引用组：普通资源组通常以 `block_type` 命名，二级键 `ref` 对应正文中的临时引用，其值由真实属性组成；保留组 `comments` 使用 `<ref>.data` 保存评论。XML、Markdown 和 IM Markdown 在存在可见评论时都会返回该组；Markdown 正文没有与评论 key 对应的内联引用，这是有意的协议设计。没有提取数据时，`reference_map` 可能为空。`comments.tips.data` 表示评论因数量上限被截断，文档顶层 `tips` 则给出安全回放或依赖降级提示。`content` 和 `reference_map` 属于同一份响应，应保留完整 JSON 响应；`im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用。设置 `--scope` 时会被 `<fragment>` 包裹，详见下文“局部读取的输出结构”。
+- 评论内容不保证全部返回，需要详细信息时使用  `drive +list-comments` 获取完整评论。
 
 ### 理解局部读取结果
 

package/skills/lark-doc/references/lark-doc-update.md

@@ -13,12 +13,15 @@ lark-cli docs +fetch --doc "文档URL或token" --scope keyword --keyword "key1|k
 # 替换文本；--content "" 可删除文本
 lark-cli docs +update --doc "xx" --command str_replace --pattern "旧内容" --content "新内容"
 
-# 替换或插入 block
+# 替换单个 block，或同父连续范围内的 block
 lark-cli docs +update --doc "xx" --command block_replace --block-id blkTarget --content '<p>新段落</p>'
+lark-cli docs +update --doc "xx" --command block_replace --start-block-id blkFirst --end-block-id blkLast --content '<p></p>'
+
 lark-cli docs +update --doc "xx" --command block_insert_after --block-id blkAnchor --content '<h2>新章节</h2><p>章节内容</p>'
 
-# 删除多个 block
-lark-cli docs +update --doc "xx" --command block_delete --block-id "blkA,blkB"
+# 删除单个 block 或范围内的 block
+lark-cli docs +update --doc "xx" --command block_delete --block-id blkA
+lark-cli docs +update --doc "xx" --command block_delete --start-block-id blkFirst --end-block-id blkLast
 ```
 
 ## 推荐流程
@@ -29,8 +32,8 @@ lark-cli docs +update --doc "xx" --command block_delete --block-id "blkA,blkB"
    - 只有模糊关键词：用 `--scope keyword --keyword "key1|key2" --context-before 1 --context-after 1 --detail with-ids`
    - 明确整篇重构才读 `--detail with-ids` 全文；只读摘要或确认事实时用更轻的 fetch
 2. **Diagnose（诊断问题）**：判断用户目标、当前结构、语气、重复、断流、事实口径和需要保留的资源；识别哪些 block 必须原样保留。
-3. **Patch Plan（制定局部计划）**：把修改拆成最小安全操作：简单行内文本替换用 `str_replace`，但它不支持资源替换，涉及多个 block 时优先使用 `block_replace`；整段/整块重写用 `block_replace`；增补章节用 `block_insert_after`；删冗余用 `block_delete`；调整顺序用 `block_move_after`。
-4. **Patch（精确修改）**：按 block / section 执行局部命令。保护 `<cite>`、`<img>`、`<source>`、`<whiteboard>`、`<sheet>`、`<bitable>`、`<synced_reference>` 等 token 化内容，不要改成纯文本或占位符。同一 block 的多处修改合并成一次 `block_replace`。
+3. **Patch Plan（制定局部计划）**：把修改拆成最小安全操作：简单行内文本替换用 `str_replace`，但它不支持资源替换；单个 block 用一个 `--block-id`，同一直接父节点下的连续 block 用 `--start-block-id`/`--end-block-id`。连续范围适用于 `block_replace` 和 `block_delete`。整段/整块重写用 `block_replace`；增补章节用 `block_insert_after`；删冗余用 `block_delete`；调整顺序用 `block_move_after`。
+4. **Patch（精确修改）**：按 block / section 执行局部命令。替换内容必须符合目标父容器的结构；例如替换列表项范围时使用 `<li>...</li>`。保护 `<cite>`、`<img>`、`<source>`、`<whiteboard>`、`<sheet>`、`<bitable>`、`<synced_reference>` 等 token 化内容，不要改成纯文本或占位符。同一 block 的多处修改合并成一次 `block_replace`。
 5. **Verify（fetch 验证）**：每轮写操作后按影响范围重新 fetch，检查用户要求、结构、语气、事实、资源块和 block ID 是否符合预期；不满足就基于最新 fetch 结果继续 Diagnose / Patch，不要沿用上一轮 block ID。
 
 除非用户明确要求完全重建，或原文已无保留价值，否则不要使用 `overwrite`；它可能丢失评论和暂不支持的资源。
@@ -51,7 +54,8 @@ lark-cli docs +update --doc "xx" --command block_delete --block-id "blkA,blkB"
 |`--doc-format`|否|`xml`（默认）或 `markdown`|
 |`--content`|视指令|写入内容；`str_replace` 传空字符串可删除文本|
 |`--pattern`|视指令|`str_replace` 的简单行内匹配文本；不要用于多行、整段或多个 block|
-|`--block-id`|视指令|目标 block ID；批量删除时用逗号分隔；`-1` 表示文档末尾，`0` 表示文档开头（仅适用于支持这些锚点的指令）|
+|`--block-id`|视指令|目标 block ID；`-1` 表示文档末尾，`0` 表示文档开头（仅适用于支持这些锚点的指令）|
+|`--start-block-id` / `--end-block-id`|视指令|`block_replace` / `block_delete` 的同父连续闭区间，必须成对使用，且不能与 `--block-id` 混用；`--start-block-id` 用 `0` 表示从文档开头开始，`--end-block-id` 用 `-1` 表示到文档末尾结束|
 |`--src-block-ids`|视指令|要复制或移动的源 block ID，多个 ID 用逗号分隔|
 |`--reference-map`|否|保留或回放既有 `reference_map`，需与 `--content` 配合；支持 JSON、任务目录内的相对 `@file` 或 stdin `-`|
 |`--revision-id`|否|基准版本号，默认 `-1`（最新版本）|
@@ -63,8 +67,8 @@ lark-cli docs +update --doc "xx" --command block_delete --block-id "blkA,blkB"
 |`str_replace`|全文查找替换；支持富文本内的文本替换，但不支持资源替换；涉及多个 block 时建议用 `block_replace`；空 `--content` 表示删除|`--pattern`、`--content`|
 |`block_insert_after`|在指定 block 后插入内容；逐章填充时指定对应标题的 block ID|`--block-id`、`--content`|
 |`block_copy_insert_after`|按 ID 顺序复制源 block，源 block 不变；基础标签均支持，资源块仅支持 `img`、`source`、`whiteboard`、`sheet`、`chat_card`、`sub-page-list`，不支持 `task`、`bitable`、`base_ref`、`synced_reference`、`synced_source`、`okr`|`--block-id`、`--src-block-ids`|
-|`block_replace`|替换指定 block；同一 block 一次操作中只能替换一次|`--block-id`、`--content`|
-|`block_delete`|删除一个或多个 block|`--block-id`|
+|`block_replace`|替换单个 block（`--block-id`）或同父连续闭区间（`--start-block-id`/`--end-block-id`）；不支持跨容器或反向区间|`--content`，以及 `--block-id` 或 `--start-block-id`+`--end-block-id`|
+|`block_delete`|删除单个 block（`--block-id`）或同父连续闭区间（`--start-block-id`/`--end-block-id`）；不支持跨容器或反向区间|`--block-id` 或 `--start-block-id`+`--end-block-id`|
 |`block_move_after`|移动已有 block，支持所有块类型；|`--block-id`、`--src-block-ids`|
 |`append`|仅在文末追加，等价于 `block_insert_after --block-id -1`|`--content`|
 |`overwrite`|清空后重写全文，丢失图片、评论等内容，非必要不使用|`--content`|

package/skills/lark-im/SKILL.md

@@ -190,7 +190,11 @@ lark-cli im <resource> <method> [flags] # 调用 API
 
 ### images
 
-  - `create` — 上传图片。Identity: `bot` only (`tenant_access_token`).
+  - `create` — 上传图片。Identity: supports `user` and `bot`; user identity requires `im:resource` scope on the UAT.
+
+### files
+
+  - `create` — 上传文件。Identity: supports `user` and `bot`; user identity requires `im:resource` scope on the UAT.
 
 ### pins
 
@@ -238,6 +242,7 @@ lark-cli im <resource> <method> [flags] # 调用 API
 | `reactions.list` | `im:message.reactions:read` |
 | `threads.forward` | `im:message` |
 | `images.create` | `im:resource` |
+| `files.create` | `im:resource` |
 | `pins.create` | `im:message.pins:write_only` |
 | `pins.delete` | `im:message.pins:write_only` |
 | `pins.list` | `im:message.pins:read` |

package/skills/lark-note/SKILL.md

@@ -12,6 +12,8 @@ metadata:
 
 身份：`+detail` 支持 `--as user` / `--as bot`；`+transcript` 仅支持 `--as user`。`note_id` 若由某个身份取得（例如 `vc +detail --as bot`），`+detail` 必须显式沿用同一个 `--as`——不要依赖 profile 默认身份。完整身份延续规则见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，使用前必读。
 
+`+detail` 返回的 `note_doc_token` / `verbatim_doc_token` / `shared_doc_tokens` 交给 [lark-doc](../lark-doc/SKILL.md) 读正文时，仍要显式带上同一个 `--as`。lark-doc 对普通文档推荐 `--as user`，**不覆盖这些纪要文档 token 的来源身份**。
+
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-vc/references/vc-domain-boundaries.md`](../lark-vc/references/vc-domain-boundaries.md)**，不读将导致命令使用、会议产物决策、领域边界职责判断错误：
 > 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
 > 2. 了解会议产物（妙记和纪要）之间的关联关系，例如：**妙记和纪要产生条件相互独立**

package/skills/lark-slides/references/cli/lark-slides-update-slide.md

@@ -54,6 +54,22 @@ lark-cli slides +update-slide --as user \
 
 一次请求就能同时做完改样式、插入、删除、换备注、换背景——这是 `+replace-slide` 逐元素 part 做不到的（它没法寻址背景，也没有 move 操作）。
 
+## 本地图片：`@路径` 占位符
+
+`--content` 的 XML 里写 `<img src="@./chart.png" .../>`，CLI 会：先把每个不重复的本地文件上传到这份演示文稿（`parent_type=slide_file`），再把 `src` 替换成返回的 `file_token`，最后才整页写回。
+
+占位符路径按**执行命令时的 CWD** 解析，跟 `--content @file` 所在目录无关；`@./assets/x.png` 找的是 `$PWD/assets/x.png`。
+
+```bash
+lark-cli slides +update-slide --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" \
+  --content '<slide xmlns="https://www.larkoffice.com/sml/2.0"><data><img src="@./chart.png" topLeftX="100" topLeftY="100" width="320" height="180"/></data></slide>'
+```
+
+- 文件不存在、不是普通文件、超过 20 MB，都在**调用任何接口之前**报错，不会留下半成品。
+- 去重只在**单次调用内**生效：多页共用同一张图时，逐页更新会把它每页重传一次。这种图先用 [`+media-upload`](lark-slides-media-upload.md) 传一次，把 `file_token` 写进各页的 `src`。
+- 整页只发一个 part，所以上传是这条命令里**唯一不可逆的一半**：图先落进演示文稿的 media store，若随后 replace 失败，报错 hint 会告诉你已经传了几张，直接重试会再传一份。先 `--dry-run` 可提前看到 `images_to_upload` 和上传步骤。
+
 ## 标准读-改-写流程
 
 ```bash
@@ -130,6 +146,7 @@ lark-cli slides +xml-get --as user \
 | `xml_presentation_id` | 实际写入的演示文稿 ID |
 | `slide_id` | 与传入相同——整页覆盖不换页 id |
 | `revision_id` | 写入后的新版本号 |
+| `images_uploaded` | 仅当 `--content` 带 `@` 占位符时出现：本次去重后实际上传的图片张数 |
 
 服务端拒绝这次写入时（`failed_reason` 非空）**不会**返回成功输出，而是报错并带上原因——单个 part 承载整页，任何失败都意味着页面没被写入。
 
@@ -143,4 +160,4 @@ lark-cli slides +xml-get --as user \
 | 3350001，原因包含 `not found` | `--presentation` 不匹配，或 `--slide-id` 对应的页面已被删除 | 检查 `--presentation` 和 `--slide-id`，再用 `slides +xml-get` 回读当前页面 ID |
 | 3350001，其他 invalid param | `--content` 的 XML 结构有问题（如 `<shape>` 缺 `<content/>`、包含服务端不支持的元素） | 按 [error-handling.md](../workflow/error-handling.md) 检查 `--content` 的 XML 结构 |
 | 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或真实存在的 `revision_id` |
-| 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |
+| 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`，`@` 占位符另需 `docs:document.media:upload`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |

package/skills/lark-vc/SKILL.md

@@ -22,6 +22,8 @@ metadata:
 
 身份是跨命令工作流的状态，不是单条命令的局部参数：一旦某个 ID（如 `note_id`、`minute_token`）由某个身份取得，后续消费它的命令（包括跨到 lark-minutes / lark-note / lark-doc）必须显式沿用相同 `--as`；不要依赖 profile 默认身份，也不要为绕过权限错误切换身份。完整规则见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 的「身份延续」。
 
+**本链路的身份策略覆盖到最后一跳读正文**：`vc +detail` → `note +detail` → `docs +fetch --doc <note_doc_token> / <verbatim_doc_token>` 全程用同一个 `--as`。[lark-doc](../lark-doc/SKILL.md) 对普通文档推荐 `--as user`，**不覆盖本链路取得的纪要文档 token**；读正文时不要因此切回 user。
+
 本 skill 默认使用 `--as user`。`+detail`、`+recording`、`meeting get`、`+meeting-list-active`、`+meeting-events` 和 `+meeting-message-send` 也支持 `--as bot`；`+meeting-events` 和 `+meeting-message-send` 必须沿用 `meeting_id` 的来源身份。`+search` 仅支持 `--as user`。
 
 ```bash

package/skills/lark-vc/references/vc-domain-boundaries.md

@@ -143,6 +143,8 @@ lark-cli minutes +detail --minute-tokens '<minute_token1>,<minute_token2>' \
 
 智能纪要（`note_doc_token`）是飞书文档，使用 `docs +fetch` 读取正文内容；**逐字稿的读取方式由 `note_display_type` 决定**：
 
+读正文是本链路的最后一跳，身份仍由本链路决定：`--as <user|bot>` 一律填 Step 2 取得 token 时用的那个身份。[lark-doc](../../lark-doc/SKILL.md) 对普通文档推荐 `--as user`，那是用户自有文档的默认建议，**不适用于这里的纪要文档 token**，不要因此切回 user。
+
 ```bash
 # 纪要正文（两种展示类型都适用）
 lark-cli docs +fetch --doc <note_doc_token> --doc-format markdown

package/skills/lark-wiki/references/lark-wiki-node-copy.md

@@ -50,6 +50,7 @@ lark-cli wiki +node-copy \
 
 - Copying is non-recursive: only the requested node and its content are copied.
 - Descendant nodes must be copied separately.
+- When the Wiki service returns `131009` lock contention, the CLI retries twice with bounded exponential backoff. If contention remains, wait before retrying again and avoid concurrent writes under the same target parent.
 - To move an existing Wiki node without keeping the source, use [`wiki +move`](lark-wiki-move.md) instead of copy-then-delete.
 
 ## Required Scope

package/skills/lark-wiki/references/lark-wiki-node-get.md

@@ -63,6 +63,10 @@ These HTTP 200 responses carry a non-zero business code and are not retryable wi
 | `131013` | The resource token is invalid | Do not switch identity or reauthorize; correct the URL/token |
 | `131014` | The document is not mounted in Wiki | Stop Wiki resolution; use the corresponding docs/sheets/base/drive command, or provide a Wiki URL/node_token |
 
+## Rate limiting
+
+For `99991400` / `rate_limit`: Do not retry immediately. Wait `retry_after_seconds`, or use exponential backoff with jitter. Stop after 3 total attempts (1 initial + 2 retries).
+
 ## Required Scope
 
 `wiki:node:retrieve`

package/skills/lark-base/references/lark-base-data-query-guide.md

@@ -1,67 +0,0 @@
-# Base data-query guide
-
-Read this guide after the [data analysis SOP](lark-base-data-analysis-sop.md) enters the Cloud path and selects `+data-query`, or directly when the user explicitly asks about the `+data-query` command or DSL. It provides common aggregation fewshots; use [lark-base-data-query.md](lark-base-data-query.md) only for complete DSL fields, operators, limits, response details, or error recovery.
-
-## When to use
-
-Use `+data-query` when the user asks for server-side:
-
-- group by / aggregation
-- sum, average, min, max, count, distinct count
-- filtered aggregation
-- sorted Top N or Bottom N
-- global statistical conclusions
-
-`+data-query` can return dimension field rows, but those rows are grouped by dimension values and do not include `record_id`. Use `+record-list`, `+record-search`, or `+record-get` for row-level output, record identity, or full raw record details.
-
-## Common Fewshots
-
-Count records by a category field:
-
-```bash
-lark-cli base +data-query \
-  --base-token <base_token> \
-  --dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Status","alias":"status"}],"measures":[{"field_name":"Status","aggregation":"count","alias":"count"}],"shaper":{"format":"flat"}}'
-```
-
-Sum a number field by category and return Top 10:
-
-```bash
-lark-cli base +data-query \
-  --base-token <base_token> \
-  --dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Region","alias":"region"}],"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"sort":[{"field_name":"total_amount","order":"desc"}],"pagination":{"limit":10},"shaper":{"format":"flat"}}'
-```
-
-Aggregate only records matching a filter:
-
-```bash
-lark-cli base +data-query \
-  --base-token <base_token> \
-  --dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Owner","alias":"owner"}],"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"filters":{"type":1,"conjunction":"and","conditions":[{"field_name":"Status","operator":"is","value":["Done"]}]},"shaper":{"format":"flat"}}'
-```
-
-## Common filter values
-
-Common `Condition.value` shapes: select `is` / `isNot` uses exactly one option
-name; datetime `is` / `isGreater` / `isLess` uses `["Today"]` or
-`["ExactDate","<epoch_ms>"]`; `isEmpty` / `isNotEmpty` uses `[]`.
-Use relative date keywords only for relative requests; see
-[lark-base-data-query.md](lark-base-data-query.md) for other field types and operators.
-
-Use `tableName` when the table ID is unavailable but the table name is known:
-
-```bash
-lark-cli base +data-query \
-  --base-token <base_token> \
-  --dsl '{"datasource":{"type":"table","table":{"tableName":"Orders"}},"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"shaper":{"format":"flat"}}'
-```
-
-## Routing to the DSL SSOT
-
-Read [lark-base-data-query.md](lark-base-data-query.md) when you need:
-
-- the full DSL field reference
-- supported aggregations and field types
-- filter operator details
-- pagination and result limits
-- response shape and error recovery

package/skills/lark-base/references/lark-base-record-upsert.md

@@ -1,63 +0,0 @@
-# base +record-upsert
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-创建记录，或在带 `--record-id` 时更新记录。
-
-## 推荐命令
-
-```bash
-# 创建记录
-lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> \
-  --json '{"项目名称":"Apollo","状态":"进行中"}'
-
-# 更新记录
-lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> --record-id <record_id> \
-  --json '{"项目名称":"Apollo","状态":"完成","完成时间":"2026-03-24 10:00"}'
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token |
-| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
-| `--record-id <id>` | 否 | 传入时走更新，不传时走创建 |
-| `--json <body>` | 是 | 字段写入对象，类型 `Map<FieldNameOrID, CellValue>` |
-
-## API
-
-- 创建：`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records`
-- 更新：带 `--record-id` 时改走 `PATCH /records/:record_id`
-
-## `--json` 结构
-
-- `--json` 必须是 **JSON object map**，形状是 `Map<FieldNameOrID, CellValue>`。
-- key 是字段名或字段 ID；value 是该字段的 `CellValue`。
-- 一次请求里同一字段只用一种标识，避免重复写入冲突。
-- 写入前先 `+field-list` 确认字段类型和字段名/ID。
-- CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
-
-```json
-{
-  "项目名称": "Apollo",
-  "状态": "进行中",
-  "完成时间": "2026-03-24 10:00"
-}
-```
-
-## 返回重点
-
-- 创建时返回 `record` 和 `created: true`。
-- 更新时返回 `record` 和 `updated: true`。
-- 如果写入了 `formula / lookup / created_at / updated_at / created_by / updated_by` 等只读字段，返回里可能出现 `ignored_fields`，这些字段不会被更新。
-
-## 坑点
-
-- 有 `--record-id` 就一定更新；不传就一定创建，不会自动查重或按业务键 upsert。
-- `select` 字段只支持写入字段中已有的选项；构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
-- 这是写入操作，执行前必须确认目标表和字段。
-
-## 参考
-
-- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范