@amaster.ai/pi-lark 0.1.7 → 0.1.8

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

@@ -1,183 +1,54 @@
-基于 HTML 子集的 XML 格式描述飞书文档内容。
-
-# 一、标准 HTML 标签
-p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr, img, b, em, u, del, a, br, span 语义不变
-
-# 二、扩展标签速查表
-## 块级标签
-|标签|说明|关键属性|
-|-|-|-|
-| `<title>` | 文档标题（每篇唯一）| `align` |
-| `<checkbox>` | 待办项| `done="true"\|"false"` |
-
-## 容器标签
-|标签|说明|关键属性|
-|-|-|-|
-| `<callout>` | 高亮框，子块仅支持文本块（如 `<p>`）、标题、列表、待办、引用；禁止裸文本及 `<table>`、`<img>`、`<pre>`、`<hr>`、`<grid>`、`<whiteboard>`、`<sheet>` 等其他块级标签或资源块 | `emoji`(默认 bulb), `background-color`, `border-color`, `text-color` |
-| `<grid>` + `<column>` | 分栏布局，各列 width-ratio 之和为 1 | `width-ratio` |
-| `<whiteboard>` | 嵌入画板 | `type`: `blank` \| `mermaid` \| `plantuml` \| `svg` |
-| `<pre>` | （代码块，内含 `code`）| `lang`, `caption` |
-| `<figure>` | 视图容器 | `view-type` |
-| `<bookmark>` | 书签链接 | `<bookmark name="标题" href="https://..."></bookmark>`，必传 name 和 href |
-
-## 行内组件
-| 标签 | 说明 | 关键属性 |
-|-|-|-|
-| `<cite type="user">` | @人 | XML 导入时必须显式传入 `user-id`：`<cite type="user" user-id="userID"></cite>` |
-| `<cite type="doc">` | @文档 | `<cite type="doc" doc-id="docx_token"></cite>` |
-| `<latex>` | 行内公式 | `<latex>E = mc^2</latex>` |
-| `<img>` | 图片（可独立成块或内联） | `<img width="800" height="600" caption="说明" name="图.png" href="http 或 https"/>` |
-| `<source>` | 文件附件（可独立成块或内联） | `<source name="报告.pdf"/>` |
-| `<a type="url-preview">` | 预览卡片 | `<a type="url-preview" href="...">标题</a>` |
-| `<button>` | 操作按钮 | `background-color`、`src`，必须包含 `action=OpenLink\|DuplicatePage\|FollowPage` |
-| `<time>` | 提醒 | 必包含 `expire-time`、`notify-time`（毫秒时间戳）、`should-notify=true\|false` |
-
-## 文本块通用属性
-- `align` — `"left"`|`"center"`|`"right"`（适用于 p / h1-h9 / li / checkbox）
-- 有序列表项用 `seq="auto"` 自动编号
-
-# 三、资源块
-
-文档中可嵌入外部资源块（属于容器标签的特殊形式），需要额外语法创建：
-
-- `<img>` — `<img href="https://..."/>` 上传网络图片
-- `<whiteboard>` — 简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整自包含 SVG</whiteboard>`；也可用本地文件简写 `<whiteboard type="svg" path="@diagram.svg"></whiteboard>`、`<whiteboard type="mermaid" path="@flow.mmd"></whiteboard>`、`<whiteboard type="plantuml" path="@sequence.puml"></whiteboard>`，CLI 会写入前展开为内联内容；复杂图使用 `<whiteboard type="blank"></whiteboard>` 先创建空白画板，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 调用 `lark-whiteboard` 写入；
-- `<sheet>` — `<sheet type="blank"></sheet>` 空白；`<sheet sheet-id="SID" token="TOKEN"></sheet>` 复制已有
-- `<task>` — `<task task-id="GUID"></task>`，必传 task-id（任务 guid）
-- `<chat_card>` — `<chat_card chat-id="CHAT_ID"></chat_card>`，必传 chat-id
-- `<sub-page-list>` — `<sub-page-list></sub-page-list>` 子页面列表块；仅 wiki 文档可插入
-- `<html5-block>`、`<okr>` — 前者在飞书文档「HTML 块」iframe 中加载单文件 HTML，内容可用 HTML 渲染时直接使用；后者创建时仅支持 root-only `<okr cycle-id="..."/>` 挂载已有 OKR。完整语法与字段规则见 [`lark-doc-xml-extended-blocks.md`](lark-doc-xml-extended-blocks.md)。
-- bitable、base_ref、synced_reference、synced_source — 不可创建，仅支持移动
-
-# 四、块级复制与移动
-
-## 移动（block_move_after）
-支持**所有**块类型（块级标签、容器标签、行内组件、资源块），使用 `docs +update --command block_move_after --block-id "<锚点>" --src-block-ids "id1,id2"`。
-
-## 复制（block_copy_insert_after）
-- **基础标签**（块级标签、容器标签、行内组件）：均支持复制
-- **资源块**：仅 img、source、whiteboard、sheet、chat_card、sub-page-list 支持复制；task、bitable、base_ref、synced_reference、synced_source、okr 不支持复制
-
-使用 `docs +update --command block_copy_insert_after --block-id "<锚点>" --src-block-ids "id1,id2"`。
-
-> 详见 [lark-doc-update.md](lark-doc-update.md)。
-
-# 五、补充规则
-
-## 富文本样式嵌套顺序
-- 行内样式标签必须按以下固定顺序嵌套（外 → 内），关闭顺序严格反转：`<a> → <b> → <em> → <del> → <u> → <code> → <span> → 文本内容`
-
-## 列表分组
-- 连续同类型列表项自动合并为一个 `<ul>` 或 `<ol>`
-- 嵌套子列表放在 `<li>` 内部
-- 新增列表项必须包在 `<ul>` 或 `<ol>` 内：
-   ```xml
-   <ul>
-     <li>第一项</li>
-     <li>第二项</li>
-   </ul>
-   ```
+# 飞书 XML 语法
 
-## 代码块
-- 代码块必须写成 `<pre lang="xxx" caption="可选说明"><code>代码内容</code></pre>`。
-- 不要将代码文本直接放在 `<pre>` 下；应放在内层 `<code>` 中。
+**语法采用类 HTML 标签，渲染采用纵向块级文档流：顶层 Block 按文档顺序纵向排列，块内支持富文本和子块嵌套。默认宽度约 820 px，宽版模式约 1020 px**
 
+以下为 XML 语法示例，使用时需替换其中的示例值。属性必须写成 `name="value"`，禁止省略引号。
 
-## 用户名写入规则
+## 常用标签
 
-- 任何包含 `<cite type="user">` 的 XML 在导入、新建或编辑回写时，都必须显式传入 `user-id`；其值为用户的 `open_id`，不得省略。
-- 当从 IM 消息、日历、审批、任务等来源获取到用户的 `open_id` 时，写入文档**必须**使用 `<cite type="user" user-id="open_id">` 标签，而非纯文本名字。这样文档中会渲染为可点击的 @人。
-- 典型场景：IM 消息的 `sender`、`mentions`、reactions 的 `operator`、卡片消息中引用的用户、系统消息中的用户名、合并转发中的用户名。
-- 当只有纯文本名字而没有 `open_id` 时（如系统消息、合并转发内容），先通过 `lark-cli contact +search-user --query "名字" --as user` 反查 `open_id`，再写入 cite 标签。
+- `p, h1-h9, blockquote, hr, img, b, em, u, del, br, span` 语义不变。普通文档建议只使用 `h1-h6`，`h7-h9` 仅在确需更深层级时使用。
+- `<a type="url-preview" href="URL">链接标题</a>`
+- `<latex>E = mc^2</latex>`：适用行内公式，也适用于上标、下标写法。
+- `<ol><li>第一项<ul><li>子项</li></ul></li><li>第二项</li></ol>`：子列表放在 `<li>` 内；新增列表项必须放在 `<ul>` 或 `<ol>` 内。
+- `<pre lang="go" caption="示例"><code>fmt.Println(&quot;hello&quot;)</code></pre>`：代码必须放在 `<code>` 内，禁止直接放在 `<pre>` 下；`caption` 可省略。
+- `<img path="@./photo.png"/>`：上传当前工作目录内的本地图片。也可用 `<img href="URL"/>` 上传公开 HTTP(S) 网络图片，或用 `<img src="token"/>` 复制原始图片；三者任选一个，可选 `width`、`height`、`caption`、`name`。使用 `href` 时，CLI 会将远程图片转为本地资源并完成上传；响应须为 PNG、JPEG、GIF 或 WebP，单图不超过 20MiB。内部网络图片须先下载到本地再使用 `path`。
+- `<source path="@./report.pdf" name="报告.pdf"/>`：上传本地附件；也可使用 `<source token="token" name="xx"/>` 复制已有附件。可独立使用、放入 `<p>` 作为行内附件，或写成 `<figure view-type="Card|Preview"><source/></figure>`；
+- `<checkbox done="true|false">todo</checkbox>`
+- `p, h1-h9, li, checkbox, title` 支持可选属性 `align`，可选值为 `left`、`center`、`right`，例如 `<p align="center">居中正文</p>`。
 
-## 表格扩展
-标准 HTML table 结构不变，扩展点：
-- `<colgroup>` / `<col>` 定义列宽，紧跟 `<table>` 之后：`<col span="2" width="100"/>`
-- `<th>` / `<td>` 增加 `background-color` 和 `vertical-align`（top | middle | bottom）
-- 有表头时第一行在 `<thead>` 用 `<th>`，其余在 `<tbody>` 用 `<td>`
-- 合并单元格仅起始格输出 `colspan` / `rowspan`，被合并的格不出现
+## 标题与列表编号
 
-# 六、美化系统
-- 颜色优先使用命名色，也可写 `rgb(r,g,b)` / `rgba(r,g,b,a)`。**基础色（7 色）**：red, orange, yellow, green, blue, purple, gray
-  | 属性 | 支持的命名色 |                                                                                                                                                                                                        
-  |-|-|
-  | 文字颜色 `<span text-color>` | 基础色 |
-  | 高亮框字色 `<callout text-color>` | 基础色 |
-  | 高亮框边框 `<callout border-color>` | 基础色 |                                                                                                                                                                                 
-  | 文字背景 `<span background-color>` | 基础色 + `light-{色}` + `medium-gray` |                                                                                                                                                   
-  | 高亮框填充 `<callout background-color>` | `gray` + `light-{色}` + `medium-{色}` |                                                                                                                                              
-  | 单元格背景 `<th/td background-color>` | 同文字背景 |                                                                                                                                                                           
-  | 按钮背景 `<button background-color>` | 同文字背景 |
-- 常用 emoji： 💡(默认)✅❌📝❓❗👍❤️📌🏁⭐
+- 完整文档以唯一的 `<title>` 开头；正文标题使用 `<h1>` 至 `<h9>`，层级须连续，不跳级，例如 `<h1>` 后不能直接使用 `<h3>`，应先出现 `<h2>`。需要自动编号时设置 `seq="auto"`，系统会按标题层级生成并递增阿拉伯数字编号，例如一级标题为 `1`，二级标题为 `1.1`。
+- 有序列表：默认属性 `seq="auto"`，需从指定数字开始时设置对应值，如 `seq="3"`。
 
-# 七、**重要规则**
-## 转义规则：标签本身 **禁止转义**，只有标签内部的文本内容才需要转义
+## 表格
 
-**错误** ❌：`&lt;p&gt;内容&lt;/p&gt;`（把标签也转义了）
-**正确** ✅：`<p>A &amp; B 的对比：1 &lt; 2</p>`（标签保持原样，文本中的 `&` 和 `<` 才转义）
+- `<table><thead><tr><th><p>表头</p></th></tr></thead><tbody><tr><td><p>内容</p></td></tr></tbody></table>`
+- `<colgroup><col /></colgroup>` 紧跟 `<table>` 定义列宽；`width` 表示列宽，可选 `span` 表示连续作用的列数。
+- `<th>` / `<td>` 支持 `background-color`、`vertical-align`、`colspan`、`rowspan`；`vertical-align`：`top | middle | bottom`；`background-color` 支持基础色相、`light-{色相}`、`medium-gray`，表头优先使用 `light-gray` 或 `medium-gray`，彩色单元格仅用于表达状态或分类。被合并的单元格不再写入。
 
-转义字符表：
-- `<` → `&lt;`
-- `>` → `&gt;`
-- `&` → `&amp;`
-- `\n`（换行符） → `<br/>`
+## 扩展标签
 
+- `<cite type="user" user-id="ou_xxx"/>`：@人，会渲染为用户头像；必须显式传入用户 `open_id`，不得用纯文本名字冒充 @人。
+- `<cite type="doc" doc-id="DOC_TOKEN"/>`：@文档，会渲染为文档标题。
+- `<cite type="citation"><a href="URL" url-type="N"></a></cite>`：参考文献容器，仅含多个 `<a>`。`url-type` 标识链接类型：`5`（WebURL）须在`<a></a>`中填写渲染标题；`1`（Docx）、`6`（Minutes）、`12`（Base）、`13`（Sheet）可留空。
+- `<whiteboard></whiteboard>`：`type | src` 二选一。`type=blank` 为新建；`type=mermaid|plantuml|svg` 时，支持 `path=@./file` 导入，也支持在标签内直接写入内容；`src=token` 表示复制已有画板。复杂图需读取 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md)；
+- `<grid><column width-ratio="0.5"><p>左栏</p></column><column width-ratio="0.5"><p>右栏</p></column></grid>`：各列 `width-ratio` 之和为 1。
+- `<callout emoji="💡" background-color="light-*" border-color="*"><p>高亮块内容</p></callout>`：子块仅支持 `p`、`ol`、`ul`、`checkbox`、行内标签；禁止 `<table>`、`<img>`、`<pre>`、`<hr>`、`<grid>`、`<whiteboard>`、等其他块级标签或资源块。可选 `text-color`。
+- 其他扩展标签 `html5-block`、`bookmark`、`button`、`time`、`sheet`、`task`、`chat_card`、`sub-page-list`、`okr` 见 [`lark-doc-xml-extended-blocks.md`](lark-doc-xml-extended-blocks.md)。
 
-# 八、完整示例
+## 颜色
 
-```xml
-<title>文档标题</title>
+颜色用于表达语义，并在全文保持一致；默认保持中性色排版，避免仅为装饰而着色。
 
-<h1>一级标题</h1>
+- **合法值**：色相为 `red, orange, yellow, green, blue, purple, gray`；`text-color`、`border-color` 使用基础色相；`<span>`、`<th>`、`<td>`、`<button>` 背景支持基础色相、`light-{色相}`、`medium-gray`；高亮块背景支持 `gray`、`light-{色相}`、`medium-{色相}`。
+- **高亮块**：默认使用 `light-*` 背景和默认文字色；强提醒才使用 `medium-*`，彩色文字只强调短语。
+- **表格**：表头优先使用 `light-gray` 或 `medium-gray`；彩色单元格只表达状态或分类，避免整表铺色。
 
-<p><b>加粗文本</b>，<span text-color="green">绿色文本</span></p>
+## 转义规则
 
-<callout emoji="💡" background-color="light-yellow" border-color="yellow">
-  <p>高亮框内容，子块仅支持文本/标题/列表/待办/引用</p>
-</callout>
+禁止转义标签本身；只转义标签内部的文本内容。
 
-<checkbox done="true">已完成事项</checkbox>
-<checkbox done="false">未完成事项</checkbox>
-
-<grid>
-  <column width-ratio="0.5">
-    <p>左栏</p>
-  </column>
-  <column width-ratio="0.5">
-    <p>右栏</p>
-  </column>
-</grid>
-
-<table>
-  <colgroup><col span="2" width="120"/></colgroup>
-  <thead><tr><th background-color="light-gray">表头</th><th background-color="light-gray">表头</th></tr></thead>
-  <tbody><tr><td>单元格</td><td>单元格</td></tr></tbody>
-</table>
-
-<p><cite type="doc" doc-id="DOC_TOKEN"></cite> <cite type="user" user-id="USER_ID"></cite></p>
-
-<ol><li seq="auto">第一项</li><li seq="auto">第二项</li></ol>
-
-<p><a type="url-preview" href="https://example.com">链接标题</a></p>
-
-<p><latex>E = mc^2</latex></p>
-
-<pre lang="go" caption="示例"><code>fmt.Println("hello")</code></pre>
-
-<hr/>
-
-<source name="文件名.pdf"/>
-<img src="IMG_TOKEN" width="800" height="400" caption="说明" name="图.png"/>
-<img href="https://example.com/photo.png"/>
-
-<button action="OpenLink" src="https://example.com">按钮文字</button>
-
-<time expire-time="1775916000000" notify-time="1775912400000" should-notify="false">时间戳毫秒</time>
-
-<cite type="citation"><a href="https://example.com">引文标题</a></cite>
-<bookmark name="书签标题" href="https://example.com"></bookmark>
-
-<task task-id="TASK_GUID"></task>
-<chat_card chat-id="CHAT_ID"></chat_card>
-<sub-page-list></sub-page-list>
-```
+- 文本转义：`<` → `&lt;`，`>` → `&gt;`，`&` → `&amp;`，换行符 `\n` → `<br/>`。
+- 错误：`&lt;p&gt;内容&lt;/p&gt;`
+- 正确：`<p>A &amp; B 的对比：1 &lt; 2</p>`

package/skills/lark-drive/SKILL.md

@@ -16,12 +16,12 @@ metadata:
 
 > **导入分流规则：** 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。
 
-> **副本分流规则：** 如果用户要复制在线文档、创建文档副本、把文档复制到另一个文件夹，必须使用 `lark-cli drive files copy`。不要用 `drive +export` 下载后再 `drive +import` 上传，也不要用 `docs +fetch` + `docs +create` 重建正文；导出/导入只用于本地文件转换或离线产物。
+> **副本分流规则：** 如果用户要复制在线文档、创建文档副本、把文档复制到另一个文件夹，必须使用 `lark-cli drive +copy`。不要用 `drive +export` 下载后再 `drive +import` 上传，也不要用 `docs +fetch` + `docs +create` 重建正文；导出/导入只用于本地文件转换或离线产物。
 
 ## 快速决策
 
 - 用户要把**已有 Wiki 节点移出知识库，放到 Drive 文件夹或“我的空间”根目录**：切到 `lark-wiki`，使用 `lark-cli wiki +move-to-drive`；不要把 Wiki token 直接交给 `drive +move`。这是会改变文档归属和权限继承的写操作，执行前确认源节点与目标位置。
-- 用户要**复制文档 / 创建副本 / 另存为副本**时，使用 `lark-cli drive files copy`。先用 `lark-cli schema drive.files.copy --format json` 确认参数；如果来源是 wiki URL/token，先用 `lark-cli drive +inspect` 获取底层 `token` 和 `type`，不要把 wiki token 直接当 `file_token`。`params.file_token` 传源文档 token，`data.folder_token` 传目标文件夹 token，`data.name` 传副本名称，`data.type` 传源文件类型（如 `docx` / `sheet` / `bitable` / `slides`）。示例：`lark-cli drive files copy --params '{"file_token":"<DOC_TOKEN>"}' --data '{"folder_token":"<FOLDER_TOKEN>","name":"<COPY_NAME>","type":"docx"}'`。如返回 `confirmation_required`，按 `lark-shared` 高风险审批协议向用户确认后，在原命令末尾追加 `--yes` 重试。
+- 用户要**复制文档 / 创建副本 到云盘或者文件夹**时，使用 `lark-cli drive +copy`，用法见 [`references/lark-drive-copy.md`](references/lark-drive-copy.md)。如果是要复制文档 / 创建副本到知识库，使用 `wiki +node-copy`（见 [`lark-wiki-node-copy.md`](../lark-wiki/references/lark-wiki-node-copy.md)）。
 - 用户要**识别飞书 / doubao 云空间 URL 的类型和 token**时，可以先按 URL 路径形态做轻量判断；当路径已明确指向 docx / sheet / bitable / slides / file / folder 等资源时，可直接提取对应 token/type。传入 wiki URL、需要识别标题或 canonical URL、URL/token 有歧义，或后续操作依赖底层真实资源时，再使用 `lark-cli drive +inspect --url '<url>'` 进行识别；具体用法、失败处理和边界见 [`references/lark-drive-inspect.md`](references/lark-drive-inspect.md)。
 - 高风险写操作（删除、公开权限修改、owner 转移、版本删除/回滚、批量移动/覆盖/同步）必须同时满足三个条件才执行：目标已解析为该操作可直接使用的执行对象，执行细节已明确到可直接调用命令（例如删除的 file-token/type、公开权限修改的共享范围、owner 转移的目标 owner、版本删除/回滚的 version id、移动/覆盖/同步的目标位置和冲突策略），且用户在本轮明确确认执行这些具体目标和执行细节。用户只说“删除没用的文件”“开放/共享给大家”“改成开放”“覆盖/移动这些”只表示目标状态；先只读发现并列出候选、权限档位或执行方案，停止等待用户确认。
 - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**，或要”权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
@@ -52,7 +52,7 @@ metadata:
 - `drive +inspect` / `drive +upload` 遇到 `not found`、`permission denied`、`missing scope` 时，默认停止重试；只有 `rate limit` 或临时网络错误才适合有限重试。
 
 ## 修改标题
-- 使用 `drive files patch` 命令，通过new_title字段可以修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型
+- 用户要**重命名 / 改标题 / 改文件名**，使用 `lark-cli drive +update-title`，用法见 [`references/lark-drive-update-title.md`](references/lark-drive-update-title.md)。
 
 ## 核心概念
 
@@ -128,6 +128,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | `+sync` | 双向同步本地目录与 Drive 文件夹：拉取 `new_remote`、推送 `new_local`，`modified` 按 `--on-conflict=remote-wins\|local-wins\|keep-both\|ask` 处理；`--quick` 用修改时间近似比较；`--on-duplicate-remote` 支持 `fail` / `newest` / `oldest`；只同步 `type=file`，跳过在线文档和 shortcut，且不会删除两端多余文件。 |
 | [`+push`](references/lark-drive-push.md) | 将本地目录推送到 Drive 文件夹，支持 skip / smart / overwrite 与确认后删除远端。 |
 | [`+create-shortcut`](references/lark-drive-create-shortcut.md) | 在另一个文件夹里创建现有 Drive 文件的快捷方式。 |
+| [`+copy`](references/lark-drive-copy.md) | 复制资源到目标文件夹；如果要复制到知识库，使用 `wiki +node-copy`； |
 | [`+add-comment`](references/lark-drive-add-comment.md) | 给 doc/docx/file/sheet/slides/base(bitable) 添加全文/局部评论；不支持妙搭 apps。 |
 | [`+list-comments`](references/lark-drive-list-comments.md) | 分页获取评论列表。 |
 | [`+batch-query-comments`](references/lark-drive-batch-query-comments.md) | 按评论 ID 批量获取评论。 |
@@ -146,6 +147,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+version-revert`](references/lark-drive-version-revert.md) | 回滚到指定历史版本。 |
 | [`+version-delete`](references/lark-drive-version-delete.md) | 删除指定历史版本。 |
 | [`+move`](references/lark-drive-move.md) | 移动 Drive 文件或文件夹；Wiki 层级移动走 `lark-wiki`。 |
+| [`+update-title`](references/lark-drive-update-title.md) | 重命名文件、文件夹、在线文档或知识库。 |
 | [`+delete`](references/lark-drive-delete.md) | 删除 Drive 文件或文件夹，文件夹删除会轮询异步任务。 |
 | [`+task_result`](references/lark-drive-task-result.md) | 查询 import/export/move/delete 等异步任务结果。 |
 | [`+inspect`](references/lark-drive-inspect.md) | 检视 URL 的类型、标题和 canonical token；wiki URL 会自动解包到底层文档。 |
@@ -170,10 +172,10 @@ lark-cli drive <resource> <method> [flags] # 调用 API
 
 ### files
 
-  - `copy` — 复制文件；在线文档创建副本的首选能力，完整参数见上方“快速决策”，不要用 `drive +export` / `drive +import` 绕行复制
+  - `copy` — 复制文件；优先使用 [`drive +copy`](references/lark-drive-copy.md)
   - `create_folder` — 新建文件夹
   - `list` — 获取文件夹下的清单；使用前阅读 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md)
-  - `patch` — 修改文件标题
+  - `patch` — 修改文件标题；优先使用 [`drive +update-title`](references/lark-drive-update-title.md) shortcut
 
 ### permission.members
 

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

@@ -70,7 +70,7 @@ API 成功时返回空 `data`（仅 `code: 0, msg: "success"`），对应 CLI
 
 ## 与 wiki URL 的关系
 
-传入 `/wiki/<node_token>` 时，shortcut 会直接用 `node_token` 作为路径参数并以 `type=wiki` 调用接口。如果需要先把 wiki 节点解析成 `obj_token`（例如想显式对底层 docx 申请），自行先调 `wiki spaces get_node` 拿 `obj_token + obj_type`，再用 bare token + `--type docx` 调本命令。
+传入 `/wiki/<node_token>` 时，shortcut 会直接用 `node_token` 作为路径参数并以 `type=wiki` 调用接口。如果需要先把 wiki 节点解析成 `obj_token`，自行先调用 [`wiki +node-get` shortcut](../../lark-wiki/references/lark-wiki-node-get.md) 拿 `obj_token + obj_type`，再用 bare `obj_token` + `--type <obj_type>` 调本命令。
 
 ## 参考
 

package/skills/lark-drive/references/lark-drive-copy.md

@@ -0,0 +1,87 @@
+
+# drive +copy
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+复制一个 Drive 文件（在线文档、表格、多维表格、幻灯片、思维笔记或普通文件）到目标文件夹，生成一个内容相同的新副本。
+
+## 命令
+
+```bash
+# 源文档传 URL（自动识别类型和 token）
+lark-cli drive +copy --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" --name '副本名称' --folder-token <TARGET_FOLDER_TOKEN>
+
+# Wiki URL（自动解包底层资源后复制到 Drive）
+lark-cli drive +copy --url "https://example.larksuite.com/wiki/<WIKI_TOKEN>" --name '副本名称' --folder-token <TARGET_FOLDER_TOKEN>
+
+# Wiki token
+lark-cli drive +copy --token <WIKI_TOKEN> --type wiki --name '副本名称' --folder-token my_space
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 与 `--token` 二选一 | 源文档 URL，支持 `doc` / `docx` / `sheet` / `file` / `mindnote` / `slides` / `base` / `bitable` / `wiki` 路径；wiki 会自动解包底层资源 |
+| `--token` | 与 `--url` 二选一 | 源文档 token 或 URL；裸 token 必须配合 `--type` |
+| `--type` | 裸 token 时必填 | 源文件类型：`doc`、`docx`、`sheet`、`file`、`mindnote`、`slides`、`bitable`（`base` 为兼容别名）或 `wiki`；传 URL 时可省略，显式传入时必须与 URL 类型一致 |
+| `--name` | 是 | 副本名称，最长 256 字节 |
+| `--folder-token` | 是 | 目标文件夹 token、文件夹 URL，或常量 `my_space`（复制到当前身份"我的空间"根目录，内部自动解析根 token） |
+| `--extra` | 否 | 可重复的 `key=value` 对，原样透传给 API 的 `extra` 自定义复制参数；典型用法 `--extra target_type=docx`（复制旧版 doc 时转换为 docx 副本） |
+
+## 输入规则
+
+- `--url` 与 `--token` 互斥，只传一个
+- `--type` 必须与源文件真实类型一致，类型不匹配时服务端会返回失败
+- `base` 与 `bitable` 是同一概念，CLI 会把 `base` 归一化为 `bitable` 后发给服务端
+- 目标文件夹必须是云空间（云盘/云存储）文件夹 token，不能传 wiki 节点 token
+
+## Wiki 场景
+
+`drive +copy` 接受 wiki URL，也接受 `--token <WIKI_TOKEN> --type wiki`。目标仅支持云盘（Drive）文件夹或 `my_space` 根目录；要把副本留在知识库中，使用 `wiki +node-copy`。
+
+## 行为说明
+
+- bot 身份复制成功后，CLI 会自动尝试给当前 CLI 用户授予新副本的 `full_access`，结果在输出的 `data.permission_grant` 字段中；授权失败不影响复制本身的成功状态
+
+## 输出
+
+```json
+{
+  "ok": true,
+  "identity": "bot",
+  "data": {
+    "copied": true,
+    "file_token": "<new_file_token>",
+    "file_type": "docx",
+    "name": "副本名称",
+    "url": "https://example.larksuite.com/docx/<new_file_token>",
+    "source_file_token": "<source_file_token>",
+    "source_type": "docx",
+    "source_wiki_token": "<source_wiki_token, only for wiki input>",
+    "folder_token": "<target_folder_token>",
+    "permission_grant": {
+      "status": "granted",
+      "perm": "full_access",
+      "member_type": "openid",
+      "user_open_id": "<current_user_open_id>",
+      "message": "Granted the current CLI user full_access on the new document."
+    }
+  }
+}
+```
+
+`source_wiki_token` 仅 wiki 输入出现；`permission_grant` 仅 bot 身份出现，user 身份复制时 `data` 下没有该字段。
+
+## 常见错误
+
+| 错误码 | 含义 | 处理 |
+|---|---|---|
+| `99991672` / `99991679` | 缺失 scope | 按错误里的 `missing_scopes`、`hint` 申请/授权所需 scope 后重试 |
+| `99991400` | 命中接口限频 | 等待一段时间后重试；批量复制时保持串行并降低频率 |
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
+- [lark-wiki](../../lark-wiki/SKILL.md) -- 知识库节点复制（`wiki +node-copy`）
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -27,7 +27,8 @@ https://xxx.feishu.cn/drive/file/boxbc_xxx
 
 ## 排障
 
-- 如果返回 `HTTP 403`，可以使用 [lark-drive-preview](lark-drive-preview.md) 下载源文件产物。
+- 如果返回 `permission_denied`，或最终下载返回 `HTTP 403`，按错误 `hint` 使用 `lark-cli drive +preview --file-token <FILE_TOKEN> --type source_file --output <path>` 获取预览产物。
+- 如果返回限流错误，停止立即重试，稍后按指数退避重试。
 
 ## 参考
 

package/skills/lark-drive/references/lark-drive-export.md

@@ -136,6 +136,8 @@ lark-cli drive +export \
 - `--only-schema` 只支持 `bitable` 导出为 `.base`，用于仅导出表结构
 - 如果格式不匹配，CLI 会返回 typed validation error，并在 `hint` 中给出可重试的 `--file-extension` 建议；例如 `docx + csv` 会提示改用 `docx/pdf/markdown`，或改传 sheet/bitable URL
 - shortcut 内部固定有限轮询：最多 10 次，每次间隔 5 秒
+- 创建导出任务时收到 `rate_limit` / `99991400` 不会生成 `ticket`；至少等待 1 分钟后重跑原 `drive +export`，持续限频时从 1 分钟开始指数退避
+- 状态轮询一旦收到 `rate_limit` / `99991400` 会立即停止，不会继续消耗剩余轮询次数；错误会保留原始 typed metadata，并在 `hint` 中提供已有 `ticket` 的续查命令
 - 轮询超时不是失败；会返回 `ticket`、`timed_out=true` 和 `next_command`，供后续继续查询
 
 ## 错误码处理
@@ -144,6 +146,7 @@ lark-cli drive +export \
 |--------|------|----------|
 | `1069914` | token 非法或 token/type 不匹配；常见原因是把 Wiki node token 当作底层 `docx` / `sheet` / `bitable` token 使用，没有传 `--doc-type wiki` | 优先改用 `--url <Wiki URL>`；只有裸 Wiki token 时，用 `--token <WIKI_NODE_TOKEN> --doc-type wiki`。不确定 token 类型时，先用 `lark-cli drive +inspect --url <TOKEN> --type wiki` 检查是否能解包为 Wiki node；如果不是 Wiki token，再检查 token 来源、`--doc-type` 是否与实际资源类型一致 |
 | `1069902` | 没有当前导出任务所需权限 | 不要直接重试同一命令；先确认当前 `--as` 身份是否能访问该文档、是否有下载/导出权限，以及文档是否受分享、密级或租户策略限制。需要补权限时，让文档 owner 或管理员授权后再执行 |
+| `99991400` / `rate_limit` | OpenAPI 请求频率受限 | 立即停止并按错误 `hint` 处理：没有 `ticket` 时，至少等待 1 分钟后重跑原 `drive +export`；已有 `ticket` 时，只执行 `drive +task_result --scenario export` 续查，不要重复创建任务。持续限频时从 1 分钟开始指数退避 |
 | `99991679` | 缺少 OpenAPI scope | 按错误 envelope 中的 `missing_scopes` / `required_scope` / `hint` 补齐授权；常见方式是重新执行 `lark-cli auth login --scope "<缺失 scope>"`。补 scope 前不要反复重试导出命令 |
 
 ## 推荐续跑方式

package/skills/lark-drive/references/lark-drive-task-result.md

@@ -329,6 +329,9 @@ lark-cli drive +export --token <SOURCE_DOC_TOKEN> --doc-type docx --file-extensi
 # 2. 继续查询导出结果
 lark-cli drive +task_result --scenario export --ticket <EXPORT_TICKET> --file-token <SOURCE_DOC_TOKEN>
 
+# 如果返回 rate_limit / 99991400：至少等待 1 分钟后重试同一条 +task_result；
+# 若仍限频，以 1 分钟为起点继续指数退避。
+
 # 3. 拿到 file_token 后下载
 lark-cli drive +export-download --file-token <EXPORTED_FILE_TOKEN>
 ```

package/skills/lark-drive/references/lark-drive-update-title.md

@@ -0,0 +1,78 @@
+# drive +update-title
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+重命名云空间（云盘/云存储）里的文件、文件夹、在线文档或知识库节点。
+
+## 命令
+
+```bash
+# 推荐：传 URL（自动识别类型和 token）
+lark-cli drive +update-title \
+  --url 'https://example.larksuite.com/docx/<DOCX_TOKEN>' \
+  --title '<NEW_TITLE>'
+
+# 裸 token 必须显式传 --type
+lark-cli drive +update-title \
+  --token <FILE_TOKEN> \
+  --type file \
+  --title '<NEW_TITLE>.xlsx'
+
+# 知识库节点：传 /wiki/ URL 里的 node_token
+lark-cli drive +update-title \
+  --url 'https://example.larksuite.com/wiki/<NODE_TOKEN>' \
+  --title '<NEW_TITLE>'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--url` | 与 `--token` 二选一 | 目标 URL，支持 `/docx/`、`/sheets/`、`/base/`、`/bitable/`、`/slides/`、`/file/`、`/drive/folder/`、`/wiki/` |
+| `--token` | 与 `--url` 二选一 | 目标 token 或 URL；裸 token 必须配合 `--type` |
+| `--type` | 裸 token 时必填 | `docx`、`sheet`、`bitable`（`base` 为兼容别名）、`slides`、`file`、`folder`、`wiki`；传 URL 时可省略，显式传入时必须与 URL 类型一致 |
+| `--title` | 是 | 新标题，别名 `--new-title`；不能为空或纯空白，首尾空格会被去掉 |
+| `--on-extension-mismatch` | 否 | 仅 `--type file`：`keep`（默认，标题缺后缀时自动补上当前后缀，后缀不一致时报错）/ `allow`（跳过校验，原样提交）。传给其他 `--type` 会报错 |
+
+## 行为说明
+
+- **空标题会被拒绝**：CLI 拒绝空或纯空白的 `--title`
+- **`file` 类型会校验后缀**：`--type file` 的标题就是完整文件名。CLI 会比对 `--title` 与当前文件名的后缀：没有后缀时默认补上当前后缀（输出里用 `extension_appended` 说明），后缀不一致时拦截（`a.md` → `a.txt`）。要跳过校验加 `--on-extension-mismatch=allow`
+- **wiki 不解包**：`--type wiki` 用 `/wiki/` URL 里的 `wiki_token`，传底层文档 token 会 `981003`
+- **不支持旧版 doc 和思维笔记**：服务端不支持改这两类的标题（`type=doc` / `type=mindnote` 返回 `981002 params error`），CLI 在本地就拒绝，不会白发一次写请求
+- **不支持妙搭 apps**：要改妙搭应用标题，切换到 [`lark-apps`](../../lark-apps/SKILL.md) 业务域处理
+
+## 输出
+
+```json
+{
+  "updated": true,
+  "file_token": "<file_token>",
+  "type": "docx",
+  "title": "<new_title>",
+  "url": "https://example.feishu.cn/docx/<file_token>"
+}
+```
+
+`--type file` 且未用 `allow` 时，额外返回改名前的文件名，改错了可以据此一条命令改回去；自动补了后缀还会带上 `extension_appended`：
+
+```json
+{
+  "updated": true,
+  "title": "<new_title>.txt",
+  "previous_title": "<old_title>.txt",
+  "extension_appended": ".txt"
+}
+```
+
+## 常见错误
+
+| 错误码 | 含义 | 处理 |
+|---|---|---|
+| `99991672` / `99991679` | 缺失 scope | 按错误里的 `missing_scopes`、`hint` 申请/授权所需 scope 后重试 |
+| `99991400` | 命中接口限频 | 等待一段时间后重试；批量改名时保持串行并降低频率 |
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/lark-event/SKILL.md

@@ -32,7 +32,7 @@ metadata:
 | `--max-events N` | Exit after N events. Default 0 = unlimited |
 | `--timeout D` | Exit after duration D (e.g. `30s`, `2m`). Default 0 = no timeout. Whichever of `--max-events` / `--timeout` fires first wins |
 | `--output-dir <dir>` | Write each event as a file (relative paths only; prevents traversal) |
-| `--quiet` | Suppress stderr diagnostics. **AI should not use this** — it silences the ready marker |
+| `--quiet` | Suppress ready/exit markers and per-event stderr diagnostics, including drop warnings. This can hide event loss. **AI should not use this** — it removes readiness and integrity signals |
 | `--as user\|bot\|auto` | Identity for the session (see lark-shared) |
 
 
@@ -42,6 +42,9 @@ metadata:
 # Default: stream every event for the key (no filter, no projection)
 lark-cli event consume im.message.receive_v1 --as bot
 
+# List every EventKey of one domain (the authoritative, always-current catalog)
+lark-cli event list --domain vc --json
+
 # Grab one sample event to inspect payload shape
 lark-cli event consume im.message.receive_v1 --max-events 1 --timeout 30s --as bot
 
@@ -57,7 +60,7 @@ wait
 
 ## Call flow
 
-1. `lark-cli event list --json` → pick a legal key
+1. `lark-cli event list --json` → pick a legal key. `--domain <d>` narrows to one domain; the domains are `application`, `approval`, `board`, `card`, `im`, `minutes`, `task`, `vc`. An unknown domain fails with the valid set listed in the hint.
 2. `lark-cli event schema <key> --json` → read `resolved_output_schema` + `jq_root_path` to determine field paths
 3. `lark-cli event consume <key> [--jq '<expr>']` → consume
 
@@ -94,7 +97,7 @@ Orchestrators should treat `reason: limit/timeout/signal` (all exit 0) as "busin
 
 ### Never `kill -9`
 
-**Avoid `kill -9` on consume processes**: for EventKeys with a **PreConsume hook** (those that register server-side subscriptions via OAPI), `kill -9` skips the OAPI unsubscribe and leaks server-side subscriptions (symptoms: "subscription already exists" on restart, duplicate event delivery). Prefer SIGTERM or closing stdin.
+**Avoid `kill -9` on consume processes** for EventKeys whose PreConsume registers a server-side subscription **and** unsubscribes on exit (minutes, vc, board keys): `kill -9` skips the OAPI unsubscribe and leaks the server-side subscription (symptoms: "subscription already exists" on restart, duplicate event delivery). Keys whose subscription is a durable relation with no cleanup (task, approval keys) do not leak this way, but SIGTERM or closing stdin remains the right shutdown for every key.
 
 ### One consume, one EventKey (multi-key = multi-shell)
 
@@ -151,6 +154,6 @@ Lark-defined semantic tags (**not** JSON Schema's standard `format`). Common val
 | Approval   | [`references/lark-event-approval.md`](references/lark-event-approval.md)     | Catalog of 2 Approval EventKeys (`approval.instance.status_changed_v4`, `approval.task.status_changed_v4`) + optional/multi `subscription_type` pre-registration + user-auth subscription lifecycle + flat output field reference |
 | IM         | [`references/lark-event-im.md`](references/lark-event-im.md)                 | Catalog of 12 IM EventKeys + shape notes (flat vs V2 envelope) + `im.message.receive_v1` field gotchas (`sender_id` is open_id only; `.content` is plain text except for `interactive` cards) + common jq recipes (filter by chat_type / message_type / sender); for `card.action.trigger` see also [`../lark-im/references/lark-im-card-action-reply.md`](../lark-im/references/lark-im-card-action-reply.md) |
 | Task       | [`references/lark-event-task.md`](references/lark-event-task.md)             | Catalog of 1 Task EventKey (`task.task.update_user_access_v2`) + Native V2 envelope shape + task commit types + user/bot subscription notes |
-| VC         | [`references/lark-event-vc.md`](references/lark-event-vc.md)                 | Catalog of 4 VC EventKeys (`vc.meeting.participant_meeting_started_v1`, `vc.meeting.participant_meeting_joined_v1`, `vc.meeting.participant_meeting_ended_v1`, `vc.note.generated_v1`) + field reference + source type semantics (meeting only) |
+| VC         | [`references/lark-event-vc.md`](references/lark-event-vc.md)                 | Catalog of 7 VC EventKeys (meeting lifecycle `participant_meeting_started/joined/ended_v1`, `vc.note.generated_v1`, recording `recording_started/transcript_generated/ended_v1`) + field reference + source type semantics; the live list is always `lark-cli event list --domain vc --json` |
 | Minutes    | [`references/lark-event-minutes.md`](references/lark-event-minutes.md)       | Catalog of 1 Minutes EventKey (`minutes.minute.generated_v1`) + field reference + source type semantics (meeting only) |
 | Whiteboard | [`references/lark-event-whiteboard.md`](references/lark-event-whiteboard.md) | Catalog of 1 Board EventKey (`board.whiteboard.updated_v1`) + per-whiteboard subscription model (requires `-p whiteboard_id=<token>`) + payload field reference (whiteboard_id / operator_ids triple-id) |

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

@@ -2,7 +2,7 @@
 
 > **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
 
-## Key catalog (4)
+## Key catalog (7)
 
 | EventKey | Purpose |
 |---|---|
@@ -10,8 +10,11 @@
 | `vc.meeting.participant_meeting_joined_v1` | The current user has joined a meeting |
 | `vc.meeting.participant_meeting_ended_v1` | A meeting the current user participates in has ended |
 | `vc.note.generated_v1` | A note has been generated (meeting, recording, upload, etc.) |
+| `vc.recording.recording_started_v1` | A recording_bean recording has started (Feishu software only) |
+| `vc.recording.recording_transcript_generated_v1` | Recording_bean transcript items were generated (Feishu software only) |
+| `vc.recording.recording_ended_v1` | A recording_bean recording ended and uploaded successfully (Feishu software only) |
 
-All four keys use a **Custom schema** (flat output) and carry a **PreConsume hook** that auto-subscribes / unsubscribes via OAPI on first / last consumer. All require `--as user`.
+All seven keys use a **Custom schema** (flat output) and carry a **PreConsume hook** that auto-subscribes / unsubscribes via OAPI on first / last consumer. All require `--as user`.
 
 ## Scopes & auth
 
@@ -21,6 +24,9 @@ All four keys use a **Custom schema** (flat output) and carry a **PreConsume hoo
 | `vc.meeting.participant_meeting_joined_v1` | `vc:meeting.meetingevent:read` | user |
 | `vc.meeting.participant_meeting_ended_v1` | `vc:meeting.meetingevent:read` | user |
 | `vc.note.generated_v1` | `vc:note:read` | user |
+| `vc.recording.recording_started_v1` | `vc:recording:read` | user |
+| `vc.recording.recording_transcript_generated_v1` | `vc:recording:read` | user |
+| `vc.recording.recording_ended_v1` | `vc:recording:read` | user |
 
 ---