@yandy0725/pi-lark 0.1.0

package/skills/lark-drive/references/lark-drive-add-comment.md

@@ -0,0 +1,193 @@
+
+# drive +add-comment
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+给文档、受支持的 Drive 普通文件、电子表格、飞书幻灯片或 Base 添加评论。未指定位置时创建全文评论，但仅适用于 doc/docx、白名单 Drive file，以及解析为这些类型的 wiki；sheet、slides、Base(bitable) 必须指定 `--block-id`。不同类型的 `--block-id` 格式见下文。支持直接传 docx URL/token、旧版 doc URL（仅全文评论）、Drive file URL/token（**仅支持白名单扩展名，且只支持全文评论**）、sheet URL、slides URL、base/bitable URL，也支持传最终可解析为 doc/docx/file/sheet/slides/base(bitable) 的 wiki URL。
+
+## 命令
+
+```bash
+# 默认：未指定位置时添加全文评论
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
+  --content '[{"type":"text","text":"请补充发布说明"}]'
+
+# 也可以显式指定为全文评论；旧版 doc URL 仅支持全文评论
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/doc/<DOC_ID>" \
+  --full-comment \
+  --content '[{"type":"text","text":"请补充旧版文档的背景信息"}]'
+
+# wiki 链接也可以，shortcut 会先解析到真实 doc/docx token
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
+  --content '[{"type":"text","text":"这里需要一段全文评论"}]'
+
+# 给受支持的 Drive 普通文件添加全文评论
+# 注意：CLI 会先查询 drive metas，只有白名单扩展名才允许评论
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/file/<FILE_TOKEN>" \
+  --content '[{"type":"text","text":"请补充文件说明"}]'
+
+# 裸 token 也支持，但必须显式声明 --type file
+lark-cli drive +add-comment \
+  --doc "<FILE_TOKEN>" --type file \
+  --content '[{"type":"text","text":"请补充目录说明"}]'
+
+# 给 docx 文档的指定 block 添加局部评论（block_id 可通过 docs +fetch --detail with-ids 获取）
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
+  --block-id "<BLOCK_ID>" \
+  --content '[{"type":"text","text":"请补充流程说明"}]'
+
+# wiki 链接也支持局部评论；解析结果可以是 docx/sheet/slides，block-id 格式按目标类型传
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
+  --block-id "<BLOCK_ID>" \
+  --content '[{"type":"text","text":"请补充更细的开发步骤"}]'
+
+# 组合文本、@用户、链接元素
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
+  --block-id "<BLOCK_ID>" \
+  --content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 处理，参考 "},{"type":"link","text":"https://example.com"}]'
+
+# 给电子表格单元格添加评论（--block-id 格式为 <sheetId>!<cell>）
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/sheets/<SHEET_TOKEN>" \
+  --block-id "<SHEET_ID>!D6" \
+  --content '[{"type":"text","text":"请检查此单元格数据"}]'
+
+# wiki 链接指向的 sheet 也支持
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
+  --block-id "<SHEET_ID>!A1" \
+  --content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 确认"}]'
+
+# 给幻灯片元素添加评论（--block-id 格式为 <slide-block-type>!<xml-id>）
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
+  --block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>" \
+  --content '[{"type":"text","text":"请调整这个元素的位置"}]'
+
+# 例如：给整页 slide 添加评论
+# <slide id="pkk"> ... </slide>  =>  --block-id slide!pkk
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
+  --block-id "slide!pkk" \
+  --content '[{"type":"text","text":"这一页需要补充过渡说明"}]'
+
+# 例如：给图片元素添加评论
+# <img id="bPk" ... />  =>  --block-id img!bPk
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
+  --block-id "img!bPk" \
+  --content '[{"type":"text","text":"这张图片建议换成更清晰的版本"}]'
+
+# 例如：给文本 shape 添加评论
+# <shape type="text" id="bPq"> ... </shape>  =>  --block-id shape!bPq
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
+  --block-id "shape!bPq" \
+  --content '[{"type":"text","text":"这段文案可以再精简"}]'
+
+# wiki 链接指向的 slides 也支持
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
+  --block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>" \
+  --content '[{"type":"text","text":"这里需要补充说明"}]'
+
+# 传裸 token 时需要 --type 指定文档类型
+lark-cli drive +add-comment \
+  --doc "<SHEET_TOKEN>" --type sheet \
+  --block-id "<SHEET_ID>!D6" \
+  --content '[{"type":"text","text":"请检查"}]'
+
+lark-cli drive +add-comment \
+  --doc "<DOCX_TOKEN>" --type docx \
+  --content '[{"type":"text","text":"全文评论"}]'
+
+# 裸 token + 已知 block_id 的局部评论
+lark-cli drive +add-comment \
+  --doc "<PRESENTATION_ID>" --type slides \
+  --block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>" \
+  --content '[{"type":"text","text":"slide block comment"}]'
+
+# 裸 token + 已知 block_id 的局部评论
+lark-cli drive +add-comment \
+  --doc "<DOCX_TOKEN>" --type docx \
+  --block-id "<BLOCK_ID>" \
+  --content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 处理，参考 "},{"type":"link","text":"https://example.com"}]'
+
+# 如果需要更底层的原生 API，也可以直接调用 V2 协议
+lark-cli schema drive.file.comments.create_v2
+
+lark-cli drive file.comments create_v2 \
+  --params '{"file_token":"<DOC_TOKEN>"}' \
+  --data '{"file_type":"docx","reply_elements":[{"type":"text","text":"全文评论内容"}]}'
+
+# Base 记录局部评论；原生 file_type 传 bitable。
+lark-cli drive +add-comment \
+  --doc "<BASE_TOKEN>" --type bitable \
+  --block-id "<TABLE_ID>!<RECORD_ID>!<VIEW_ID>" \
+  --content '[{"type":"text","text":"Base record-local comment"}]'
+
+# `base` 也可作为裸 token 类型别名；/base/ 与 /bitable/ URL 都会自动识别为 Base。
+lark-cli drive +add-comment \
+  --doc "<BASE_TOKEN>" --type base \
+  --block-id "<TABLE_ID>!<RECORD_ID>!<VIEW_ID>" \
+  --content '[{"type":"text","text":"Base alias comment"}]'
+
+# 预览底层调用链
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
+  --block-id "<BLOCK_ID>" \
+  --content '[{"type":"text","text":"请补充流程说明"}]' \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc` | 是 | 文档 URL / token、file / sheet / slides / base / bitable URL，或可解析到 `doc`/`docx`/`file`/`sheet`/`slides`/`base(bitable)` 的 wiki URL |
+| `--type` | 裸 token 时必填 | 文档类型：`doc`、`docx`、`file`、`sheet`、`slides`、`bitable`、`base`；评论 Base 文档推荐传 `bitable`，`base` 仅作为兼容别名兜底。URL 输入时自动识别，无需传 |
+| `--content` | 是 | `reply_elements` JSON 数组字符串。示例：`'[{"type":"text","text":"文本"},{"type":"mention_user","text":"ou_xxx"},{"type":"link","text":"https://example.com"}]'` |
+| `--full-comment` | 否 | 显式指定创建全文评论；未传 `--block-id` 时也会默认走全文评论（仅适用于 doc/docx、白名单 Drive file，以及解析为这些类型的 wiki；不适用于 sheet、slides、Base / bitable） |
+| `--block-id` | 局部评论时必填 | 目标块 ID，可通过 `docs +fetch --detail with-ids` 获取；sheet 用 `<sheetId>!<cell>`，slides 用 `<slide-block-type>!<xml-id>`，Base 用 `<table-id>!<record-id>!<view-id>` |
+
+## 行为说明
+
+- **局部评论需要先获取 block ID**：先调用 `docs +fetch --doc <TOKEN> --detail with-ids` 获取带有 block ID 的文档内容，然后使用 `--block-id` 指定目标块。
+- **Review 场景优先局部评论**：审阅、校对、逐条指出问题时，必须先尝试定位到具体 block / 单元格 / slide 元素，并逐问题创建局部评论；不要把所有问题合并成一条全文评论。
+- 未传 `--block-id` 时，shortcut 默认创建**全文评论**；也可以显式传 `--full-comment`。全文评论支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终可解析为 `doc`/`docx`/`file` 的 wiki URL。
+- **Drive file 评论**：仅支持白名单扩展名的普通文件。当前支持：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。
+- **Drive file 暂不支持**：`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件会被 CLI 拒绝，并提示“当前还不支持这种类型的评论”。这些类型虽然可能接受 OpenAPI 请求，但在页面评论展示上存在问题。
+- **Drive file 只支持全文评论**：file 目标不支持局部评论，不允许传 `--block-id` 或 `--selection-with-ellipsis`。
+- 传 `--block-id` 时，shortcut 创建**局部评论（划词评论）**；该模式支持 `docx`、`sheet`、`slides`、Base / bitable，以及最终可解析为这些类型的 wiki URL。
+- **Sheet 评论**：当 `--doc` 为 sheet URL 或 wiki 解析为 sheet 时，使用 `--block-id "<sheetId>!<cell>"` 指定单元格（如 `a281f9!D6`）；sheet 没有全文评论，`--full-comment` 不可用。
+- **Slide 评论**：当 `--doc` 为 slides URL、`--type slides`，或 wiki 解析为 slides 时，必须传 `--block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>"`。此时 `--full-comment` 和 `--selection-with-ellipsis` 不可用。
+- **Base 记录局部评论**：Base 不支持全局评论，所有评论都挂在记录上；裸 token 可传 `--type bitable` 或 `--type base`，推荐 `bitable`。定位信息必须是 file token（base token）+ `--block-id "<table-id>!<record-id>!<view-id>"`，其中 table/record/view ID 通常分别以 `tbl`/`rec`/`vew` 开头；view_id 只决定被提及时点击通知打开哪个视图，不影响评论挂载点，但必须传。ID 获取参考 [`lark-base`](../../lark-base/SKILL.md)。
+- **Slide 参数映射示例**：`--block-id` 由 PPT XML 元素类型和元素 `id` 组成。例如：
+    - `<slide id="pkk">` 对应 `--block-id slide!pkk`，表示给整页评论。
+    - `<img id="bPk" ... />` 对应 `--block-id img!bPk`，表示给图片元素评论。
+    - `<shape type="text" id="bPq">...</shape>` 对应 `--block-id shape!bPq`，表示给文本 shape 评论。
+
+- `--content` 接收结构化评论元素数组；`type` 支持 `text`、`mention_user`、`link`。为便于书写，`mention_user` / `link` 元素可以直接把用户 ID 或链接地址放在 `text` 字段中，shortcut 会转换成 OpenAPI 所需字段。
+- `type=text` 的评论文本不能直接包含 `<`、`>`；应优先传 `&lt;`、`&gt;`。shortcut 在发送前也会自动将 `<`、`>` 转义为 `&lt;`、`&gt;` 作为兜底。
+- **所有 `type=text` 元素的字符总和 ≤ 10000**（按字符算，中英文 / 符号一视同仁）。超过会被 shortcut 在发送前拒绝，并指出累计超长的元素。**拆成多个 text element 不能绕过这个上限**——上限是总额，不是每元素。需要更长内容就缩短或拆成多条评论。
+- 长度限制只对 `type=text` 生效，`mention_user` / `link` 不计入。
+- 写入评论前会自动生成符合 OpenAPI 定义的请求体；shortcut 用户只需要传 `--doc`、`--content`，局部评论再传对应格式的 `--block-id`。
+- `--dry-run` 仅预览调用链和请求体，不会实际写入。
+- 如果需要更底层的控制，仍可改用 `lark-cli schema drive.file.comments.create_v2` + `lark-cli drive file.comments create_v2`。
+- 直接调用原生 `drive.file.comments.create_v2` 时，全文评论省略 `anchor`；docx/sheet/slides 局部评论传 `anchor.block_id`，Base 记录局部评论传 `anchor.block_id`（table_id）、`anchor.base_record_id`、`anchor.base_view_id`。
+- 直接调用原生 `drive.file.comments.*` / `drive.file.comment.replys.*` 评论 Base 文档时，`file_type` 填 `bitable`，不要填 `base`。
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,77 @@
+
+# drive +apply-permission（申请文档权限）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 skill 对应 shortcut：`lark-cli drive +apply-permission`。
+
+向云文档 **Owner** 发起 `view` 或 `edit` 权限申请。申请会以卡片形式推送给 Owner，由 Owner 决定是否通过。
+
+> [!CAUTION]
+> 这是**写入操作** —— 会给 Owner 发推送通知，不要批量或自动化调用。可以先用 `--dry-run` 预览。
+
+## 身份要求
+
+- **仅支持 `user` 身份**（使用 `user_access_token`），不支持 `bot` / `tenant_access_token`；shortcut 已在 `AuthTypes` 中强制限定为 `user`，使用 bot 会被拒。
+- 所需 scope：`docs:permission.member:apply`（若用户缺权限会走统一的 permission 错误路径）。
+
+## 命令
+
+```bash
+# 通过 URL 申请（type 自动从 URL 推断）
+lark-cli drive +apply-permission \
+  --token "https://example.larksuite.com/docx/doxcnxxxxxxxxx" \
+  --perm view \
+  --remark "安全评估：需查看需求文档内容" --as user
+
+# 通过 bare token + 显式 --type
+lark-cli drive +apply-permission \
+  --token "doxcnxxxxxxxxx" --type docx \
+  --perm edit --as user
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token` | 是 | 目标文档 token 或完整 URL（`/docx/`、`/sheets/`、`/base/`、`/bitable/`、`/file/`、`/wiki/`、`/doc/`、`/mindnote/`、`/slides/` 路径里的 token 会被自动提取） |
+| `--type` | 否 | 目标类型，可选值 `doc` / `sheet` / `file` / `wiki` / `bitable` / `docx` / `mindnote` / `slides`。传 URL 时可由 shortcut 自动推断；bare token 必须显式传 |
+| `--perm` | 是 | 申请的权限，仅支持 `view` 或 `edit`（**不支持 `full_access`**，CLI 侧会直接拒绝） |
+| `--remark` | 否 | 备注，会显示在权限申请卡片上 |
+| `--dry-run` | 否 | 仅打印请求内容，不实际发送 |
+
+## 输出
+
+API 成功时返回空 `data`（仅 `code: 0, msg: "success"`），对应 CLI 输出：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {}
+}
+```
+
+## 频率限制
+
+- **应用级**：每应用每租户每分钟最多 10 次。
+- **用户级**：同一用户对**同一篇文档**一天不超过 5 次。
+
+## 常见错误
+
+| 错误码 | 含义 | CLI 处理 |
+|---|---|---|
+| `1063006` | 申请次数已达上限（5 次/日） | CLI 自动加 hint：`permission-apply quota reached: each user may request access on the same document at most 5 times per day` |
+| `1063007` | 当前文档无法申请（如：文档禁用外部申请、申请者已拥有对应权限、目标类型不支持 apply） | CLI 自动加 hint：`this document does not accept a permission-apply request ... contact the owner directly` |
+| `1063002` | 无操作权限（如该租户关闭了外部申请） | 由统一 permission 错误路径处理 |
+| `1063004` | 用户所在组织无分享权限 | 由统一 permission 错误路径处理 |
+| `1063005` | 资源已删除 | 需要确认目标文档/节点是否仍存在 |
+| `1066001/1066002` | 服务端异常 / 并发冲突 | 稍后重试 |
+
+## 与 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` 调本命令。
+
+## 参考
+
+- OpenAPI 端点：`POST /open-apis/drive/v1/permissions/:token/members/apply`

package/skills/lark-drive/references/lark-drive-comment-location.md

@@ -0,0 +1,193 @@
+# 文档评论定位字段
+
+当用户需要根据评论定位文档正文位置、对文档做 review、区分多处相同引用文本，或把评论落点映射到 `docs +fetch --detail with-ids` 的内容时，docx 文档的评论查询必须带 `need_relation=true`。
+
+## 适用范围
+
+- 当前只有 `file_type=docx` 支持通过 `need_relation=true` 查询评论的位置，并返回可用于定位正文 block 的 `relation`、`parent_type`、`parent_token` 等字段。
+- 其他文件类型暂不支持通过 `need_relation` 查询评论位置。遇到 sheet、bitable、slides、普通文件等类型的评论时，不要承诺可以用 `need_relation` 精确定位正文位置，应退回普通评论字段、对应资源能力下钻或人工确认。
+
+## 调用方式
+
+分页列出评论时，把 `need_relation` 放在 query params：
+
+```bash
+lark-cli drive file.comments list \
+  --params '{"file_token":"<doc_token>","file_type":"docx","is_solved":false,"need_relation":true}'
+```
+
+已知评论 ID 批量查询时，把 `need_relation` 放在请求体里：
+
+```bash
+lark-cli drive file.comments batch_query \
+  --params '{"file_token":"<doc_token>","file_type":"docx"}' \
+  --data '{"comment_ids":["<comment_id>"],"need_relation":true}'
+```
+
+同时获取文档内容，并要求返回 block id：
+
+```bash
+lark-cli docs +fetch --doc '<doc_token_or_url>' --detail with-ids
+```
+
+## 字段含义
+
+- `relation`：评论在文档内容中的结构化位置。`relation.relation` 是一个 JSON 字符串，需要再解析一次；其中 `positionInfo.blockID` 是最关键字段，用于匹配 `docs +fetch --detail with-ids` 返回的文档 block。
+- `relation.content_deleted`：评论引用的内容是否已被删除。为 `true` 时，不要假设还能在当前正文中找到原位置。
+- `parent_type`：评论所在的父级嵌入资源类型。常见值包括 `SHEET_BLOCK`、`BITABLE_BLOCK`、`WHITEBOARD_BLOCK`，表示评论落在文档内嵌电子表格、多维表格或画板内部。
+- `parent_token`：父级嵌入资源 token。对 sheet / bitable / whiteboard 内部评论，服务端可能无法给出内部单元格、记录或画板节点的文档 block 级 `relation`，但可以通过 `parent_type` + `parent_token` 定位到文档里的父级嵌入 block。
+
+## 准确度分级
+
+输出定位结论时，必须区分以下三类，不要把弱推断说成精确定位：
+
+| 等级 | 判定条件 | 输出口径 |
+|---|---|---|
+| `relation 精确` | `relation.relation` 中有 `positionInfo.blockID`，且能在 `docs +fetch --detail with-ids` 中匹配到同一 block | 可说“准确定位到 block” |
+| `父级资源精确，内部需下钻` | 只有父级嵌入资源的 `blockID` / `parent_type` / `parent_token`，或内部资源的 `positionInfo` 为空 | 可说“准确定位到嵌入资源；内部单元格/记录/节点需用对应 skill 下钻确认” |
+| `弱匹配/推断` | 只能依赖 `quote`、序号、当前展示顺序或文本搜索 | 必须标明“推断”，说明歧义来源和需要的补充信息 |
+
+## 返回示例
+
+普通 docx block 上的评论会返回 `relation`。注意 `relation.relation` 本身是字符串，需要再 JSON parse 一次：
+
+```json
+{
+  "comment_id": "7646774324967295982",
+  "quote": "code2",
+  "relation": {
+    "content_deleted": false,
+    "relation": "{\"22-doc_token_xxx\":{\"objType\":22,\"index\":2,\"objVersion\":10,\"positionInfo\":{\"blockID\":\"block_id_xxx\"}}}"
+  },
+  "parent_type": null,
+  "parent_token": null
+}
+```
+
+把 `relation.relation` 再解析后，取 `positionInfo.blockID`：
+
+```json
+{
+  "22-doc_token_xxx": {
+    "objType": 22,
+    "index": 2,
+    "objVersion": 10,
+    "positionInfo": {
+      "blockID": "block_id_xxx"
+    }
+  }
+}
+```
+
+然后在 `docs +fetch --detail with-ids` 的结果里查找同一个 block id，例如：
+
+```json
+{
+  "block_id": "block_id_xxx",
+  "block_type": "code",
+  "text": "code1\ncode2"
+}
+```
+
+嵌入 sheet / bitable / whiteboard 内部评论可能没有可用 `relation`，但会返回父级标记：
+
+```json
+{
+  "comment_id": "7646775036988148672",
+  "quote": "记录 2",
+  "relation": null,
+  "parent_type": "BITABLE_BLOCK",
+  "parent_token": "bitable_app_token_xxx_table_id_xxx"
+}
+```
+
+这种情况下，用 `parent_type` 判断目标是嵌入资源，再用 `parent_token` 匹配 `docs +fetch --detail with-ids` 中的 bitable / sheet block。定位粒度是文档里的父级嵌入 block，不是内部记录、字段或单元格。
+
+画板内部评论的返回形态类似：
+
+```json
+{
+  "comment_id": "7646775036988148673",
+  "quote": "画板节点文本",
+  "relation": null,
+  "parent_type": "WHITEBOARD_BLOCK",
+  "parent_token": "whiteboard_token_xxx"
+}
+```
+
+此时 `parent_token` 对应 `docs +fetch --detail with-ids` 结果中 `<whiteboard>` 的 `token` 属性，例如：
+
+```xml
+<whiteboard id="whiteboard_block_id_xxx" token="whiteboard_token_xxx"></whiteboard>
+```
+
+匹配到这个 `<whiteboard>` 后，`id` 就是文档正文里的父级画板 block id。定位粒度是文档里的画板 block；如果需要继续定位到画板内部具体节点，需要再用画板能力读取画板内部结构。
+
+## 定位流程
+
+1. 确认目标是 `file_type=docx`；只有 docx 文档支持通过 `need_relation` 查询评论位置。
+2. 用 `drive file.comments list` 或 `drive file.comments batch_query` 获取评论，并带 `need_relation=true`。
+3. 用 `docs +fetch --detail with-ids` 获取文档内容。
+4. 对每条评论先看 `relation`：
+   - 如果存在 `relation.relation`，解析这个 JSON 字符串。
+   - 从解析结果里取 `positionInfo.blockID`。
+   - 在 `docs +fetch` 结果中查找相同 block id，这就是评论对应的文档 block。
+5. 如果没有可用 `relation`，但有 `parent_type` 和 `parent_token`：
+   - `SHEET_BLOCK`：定位到文档中的 sheet 嵌入 block；`parent_token` 通常包含 sheet token 和 sheet id，必要时取 `_` 前的 token 与文档 block 的嵌入资源 token 对比。
+   - `BITABLE_BLOCK`：定位到文档中的 bitable 嵌入 block；`parent_token` 通常包含 bitable app token 和 table id，必要时取 `_` 前的 token 与文档 block 的嵌入资源 token 对比。
+   - `WHITEBOARD_BLOCK`：定位到文档中的 whiteboard 嵌入 block；`parent_token` 对应 `docs +fetch --detail with-ids` 中 `<whiteboard>` 的 `token` 属性。
+   - 这种场景能定位到父级嵌入 block，但通常不能仅凭评论接口定位到嵌入资源内部的具体单元格、字段、记录或画板节点。
+6. 只有在 `relation`、`parent_type`、`parent_token` 都缺失时，才退回使用 `quote` 文本做弱匹配；`quote` 是评论接口返回的引用文本字段。弱匹配不能区分多处相同文本。
+
+## 嵌入资源内部定位
+
+### Sheet 内部评论
+
+- `parent_token` 常见格式是 `<spreadsheet_token>_<sheet_id>`；也可能在 `relation.relation` 中看到 `subToken` 为 `3-<spreadsheet_token>`。
+- 评论接口通常只把 `positionInfo.blockID` 指到文档里的 `<sheet>` block，内部 sheet 的 `positionInfo` 可能为空。
+- 如果 `quote` 是 `C3`、`A1` 这类单元格坐标，可拆出 `spreadsheet_token` / `sheet_id` 后用 `lark-sheets` 读取该单元格确认：
+
+```bash
+lark-cli sheets +read \
+  --spreadsheet-token '<spreadsheet_token>' \
+  --sheet-id '<sheet_id>' \
+  --range '<cell>'
+```
+
+- 准确度口径：父级 sheet block 可由 relation/parent token 精确定位；单元格坐标若只来自 `quote`，应说明“单元格来自 quote，已通过 sheets 读取验证”，不要说它来自 `positionInfo`。
+
+### Bitable / Base 内部评论
+
+- `parent_token` 常见格式是 `<base_token>_<table_id>`，其中 `table_id` 通常以 `tbl` 开头。解析时优先按最后一个 `_tbl` 边界拆分，避免 base token 内出现 `_` 时误拆。
+- 评论接口可能只返回 `parent_type=BITABLE_BLOCK` 和 `parent_token`，没有 `relation`；即使有 relation，也通常只足够定位到文档里的 `<bitable>` block。
+- 下钻读取时切到 `lark-base`，最少确认表、字段、记录：
+
+```bash
+lark-cli base +table-list --base-token '<base_token>'
+lark-cli base +field-list --base-token '<base_token>' --table-id '<table_id>'
+lark-cli base +record-list --base-token '<base_token>' --table-id '<table_id>' --limit 200 --format json
+```
+
+- 如果 `quote` 是某个稳定业务值，优先用字段/记录数据做精确匹配；如果 `quote` 只是“第 N 条”“第 N 行”这类 UI 序号，只能基于当前记录顺序推断对应记录，必须输出为“推断”，并说明评论接口没有返回 `record_id` / `field_id`。
+- 如果 `record-list` 返回 `has_more=true`，不要基于第一页下全局结论；继续分页或说明只能覆盖已读取范围。
+- 需要写入时，如果评论没有字段信息，不要自行猜字段；除非用户给出默认规则，否则请求用户确认字段，或明确说明将使用哪个字段作为默认。
+
+### Whiteboard 内部评论
+
+- `parent_token` 对应文档 XML 中 `<whiteboard token="...">`；先用它匹配文档里的 whiteboard block。
+- 若要定位画板内部节点，切到 `lark-whiteboard` 读取 raw 节点结构：
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token '<whiteboard_token>' \
+  --output_as raw
+```
+
+- 如果 raw 节点中存在唯一匹配 `quote` 的文本节点，可定位到该节点；如果有多个相同文本节点，仍然是弱匹配，需要结合位置、样式、用户描述或人工确认。
+- 修改画板节点前，先说明匹配到的节点 id 和文本；复杂画板不要只凭 `quote` 批量替换全部同名节点。
+
+## 使用原则
+
+- Review 文档时，不要只依赖 `quote` 文本定位评论；多处相同文本会产生歧义。
+- 能拿到 `relation.positionInfo.blockID` 时，以 block id 为准，再用 block 内容理解上下文。
+- 对嵌入 sheet / bitable / whiteboard 内的评论，以父级嵌入 block 作为文档正文定位点；如需继续定位到表格单元格、多维表格记录或画板内部节点，需要再调用对应 sheet / bitable / whiteboard 能力读取内部数据。

package/skills/lark-drive/references/lark-drive-comments-guide.md

@@ -0,0 +1,72 @@
+# Drive 评论查询、统计与回复指南
+
+> 前置条件：先阅读 [`../SKILL.md`](../SKILL.md) 的“评论能力入口”，添加评论参数细节见 [`lark-drive-add-comment.md`](lark-drive-add-comment.md)，reaction 见 [`lark-drive-reactions.md`](lark-drive-reactions.md)。
+
+## 评论模式
+
+- `drive +add-comment` 支持全文评论和局部评论。
+- 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc` / `docx` / `file` 的 wiki URL。
+- 局部评论：传 `--block-id` 时启用；`docx` 支持文本定位或 block id，`sheet` 支持 `<sheetId>!<cell>`，`slides` 支持 `<slide-block-type>!<xml-id>`，wiki URL 解析到这些类型时也支持对应局部评论。
+- Drive file 只支持全文评论，不支持局部评论。支持扩展名：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件暂不支持。
+- Review / 审阅 / 校对 / 逐条指出问题场景优先使用局部评论，不要把多个可定位问题汇总成一条全文评论。
+- `drive +add-comment` 的 `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。
+- `slides` 评论要求显式传 `--block-id <slide-block-type>!<xml-id>`；CLI 会将其拆分后写入 `anchor.block_id` 和 `anchor.slide_block_type`。其中 `<xml-id>` 是 PPT XML 协议中的元素 `id`；不支持 `--selection-with-ellipsis` 和 `--full-comment`。
+- 评论写入内容里的文本不能直接出现 `<`、`>`；提交前应转义为 `&lt;`、`&gt;`。`drive +add-comment` 会对 `type=text` 文本元素自动兜底转义；直接调用原生评论 API 时需要自行转义。
+- 如果 wiki 解析后不是 `doc` / `docx` / `file` / `sheet` / `slides`，不要用 `+add-comment`。
+
+## 查询默认口径
+
+`drive file.comments list` 默认必须传 `is_solved:false`，即仅查询未解决评论。即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确提到要包含已解决评论，仍然按默认口径查询未解决评论。仅当用户明确要求包含已解决评论时，才可省略 `is_solved` 参数。
+
+```bash
+# 默认查询：仅未解决评论
+lark-cli drive file.comments list --params '{"file_token":"xxx","file_type":"docx","is_solved":false}'
+
+# 包含已解决评论：仅当用户明确要求时使用
+lark-cli drive file.comments list --params '{"file_token":"xxx","file_type":"docx"}'
+```
+
+## 评论卡片与统计
+
+- `drive file.comments list` 返回的 `items` 是评论卡片列表，每个 `item` 对应用户界面中的一张评论卡片，不是平铺的互动消息列表。
+- 创建第一条评论时会同时创建该卡片里的第一条 reply；真正承载正文的是 `item.reply_list.replies`，其中第一条 reply 在用户视角下就是这张卡片里的“评论本身”。
+- 统计“评论数”或“评论卡片数”：统计 `items` 长度；全量统计时对所有分页返回的 `items` 长度累加。
+- 统计“回复数”：统计所有 `item.reply_list.replies` 长度之和，再减去 `items` 长度。
+- 统计“总互动数”：统计所有 `item.reply_list.replies` 长度之和，包含每张评论卡片里的首条评论。
+- 如果 `item.has_more=true`，说明该评论卡片下还有更多回复未包含在当前返回中；需要继续调用 `drive file.comment.replys list` 拉全后，再做全量回复数或总互动数统计。
+
+## 排序
+
+- 只有当用户明确提到“最新评论”“最后评论”“最早评论”时，才需要按 `create_time` 排序。
+- 排序前必须拉完所有评论分页，不能只取第一页。
+- “最新评论”/“最后评论”：按 `create_time` 降序取第一条。
+- “最早评论”：按 `create_time` 升序取第一条。
+- 用户只说“第一条评论”时，直接使用 `drive file.comments list` 返回的第一条，不需要额外排序。
+
+## 回复限制
+
+- 回复前先检查目标评论状态。
+- `is_whole=true` 的全文评论不支持回复；遇到时提示“全文评论不支持回复”。
+- `is_solved=true` 的已解决评论不支持回复；遇到时提示“该评论已被解决，无法回复”。
+- 当目标评论不能回复时，只提示限制，不要自动替用户寻找其他可回复评论。
+
+## batch_query 与 list
+
+- `drive file.comments batch_query` 用于已知评论 ID 后的批量查询，需要传入具体评论 ID 列表。
+- `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论、获取最新或最后 N 条评论等场景。
+
+## 评论定位字段
+
+- 需要根据评论定位到文档正文位置时（例如根据评论 review 文档、区分多处相同引用文本、把评论落点映射到 `docs +fetch` 的 block），先确认目标是 `file_type=docx`，再阅读 [`lark-drive-comment-location.md`](lark-drive-comment-location.md)。
+- 其他文档类型暂不支持返回定位字段。
+
+## 原生 API
+
+需要更底层地直接调用评论 V2 协议时，先查看 schema，再调用原生命令。全文评论省略 `anchor`，局部评论传 `anchor.block_id`。
+
+```bash
+lark-cli schema drive.file.comments.create_v2
+lark-cli drive file.comments create_v2 \
+  --params '{"file_token":"<DOC_TOKEN>"}' \
+  --data '{"file_type":"docx","reply_elements":[{"type":"text","text":"全文评论内容"}]}'
+```

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

@@ -0,0 +1,79 @@
+## `drive +cover`
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
+
+列出或下载 Drive 文件的稳定封面预设。这个 shortcut 只暴露 `spec`，不暴露底层 `cover_option` 细节。
+
+### 命令
+
+```bash
+# 列出内置封面规格
+lark-cli drive +cover \
+  --file-token "<FILE_TOKEN>" \
+  --list-only
+
+# 下载 square 规格封面
+lark-cli drive +cover \
+  --file-token "<FILE_TOKEN>" \
+  --spec square \
+  --output ./artifacts/report-cover
+
+# 下载默认大图封面，并在文件冲突时覆盖
+lark-cli drive +cover \
+  --file-token "<FILE_TOKEN>" \
+  --spec default \
+  --output ./artifacts/report-cover.png \
+  --if-exists overwrite
+```
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | Drive 文件 token |
+| `--spec` | 条件必填 | 封面预设：`default` / `icon` / `grid` / `small` / `middle` / `big` / `square` |
+| `--version` | 否 | 文件版本号 |
+| `--list-only` | 否 | 仅返回可选规格，不下载 |
+| `--output` | 条件必填 | 下载到本地的输出路径 |
+| `--if-exists` | 否 | 输出冲突策略：`error`（默认）/ `overwrite` / `rename` |
+
+### 输出约定
+
+- 查询态返回：
+  - `mode=list`
+  - `file_token`
+  - `candidates[]`
+  - `next_action`
+- 下载态返回：
+  - `mode=download`
+  - `file_token`
+  - `selected_spec`
+  - `output_path`
+  - `status`
+
+### 内置规格
+
+- `default` -- 标准大图封面
+- `icon` -- 列表小图标
+- `grid` -- 网格/卡片流小封面
+- `small` -- PC 小图
+- `middle` -- 中等尺寸封面
+- `big` -- 偏移动端的大图封面
+- `square` -- 正方形裁剪封面
+
+### 关键约束
+
+- 不传 `--list-only` 时，必须显式传 `--spec` 和 `--output`
+- `drive +cover` 只返回静态预设规格，不伪造后端“可下载状态”
+- 不返回底层 `bus_type` / `platform` / `width` / `height` / `policy` 等实现细节
+- 下载时直接调用 `preview_download`
+- 未显式带扩展名时，会优先根据响应头补扩展名，缺失时回退到 `.png`
+
+### 错误提示
+
+- 下载某个 `--spec` 时如果返回 **HTTP 404**，表示这个文件**没有该规格对应的封面产物**，应视为“该规格不可用”，而不是默认按网络抖动或临时失败处理
+
+### 参考
+
+- [lark-drive](../SKILL.md) -- Drive 总入口
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数