@amaster.ai/pi-lark 0.1.6 → 0.1.7

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

@@ -1,11 +1,12 @@
 # 文档评论定位字段
 
-当用户需要根据评论定位文档正文位置、对文档做 review、区分多处相同引用文本，或把评论落点映射到 `docs +fetch --detail with-ids` 的内容时，优先使用 `drive +list-comments --need-relation` 查询 docx 评论位置。
+当用户需要根据评论定位文档正文位置、对文档做 review、区分多处相同引用文本，或把评论落点映射到 `docs +fetch --detail with-ids` 的内容时，优先使用 `drive +list-comments --need-relation` 查询 docx 评论位置；已知评论 ID 时用 `drive +batch-query-comments --need-relation`。
 
 ## 适用范围
 
 - 当前只有 `file_type=docx` 支持通过 `need_relation=true` 查询评论的位置，并返回可用于定位正文 block 的 `relation`、`parent_type`、`parent_token` 等字段。
-- `drive +list-comments` 会在目标不是 docx 时静默忽略 `--need-relation`，避免把无效参数传给 OpenAPI。遇到 sheet、bitable、slides、普通文件等类型的评论时，不要承诺可以用 `need_relation` 精确定位正文位置，应退回普通评论字段、对应资源能力下钻或人工确认。
+- `drive +list-comments` 和 `drive +batch-query-comments` 都会在目标不是 docx 时静默忽略 `--need-relation`，避免把无效参数传给 OpenAPI。遇到 sheet、bitable、slides、普通文件等类型的评论时，不要承诺可以用 `need_relation` 精确定位正文位置，应退回普通评论字段、对应资源能力下钻或人工确认。
+- 注意参数位置差异：list 的 `need_relation` 在 query params，batch_query 的在请求 body（直接调 raw OpenAPI 时才需要关心；两个 shortcut 已各自处理）。
 
 ## 调用方式
 
@@ -21,20 +22,13 @@ lark-cli drive +list-comments --url '<docx_or_wiki_url>' --need-relation
 lark-cli drive +list-comments --token '<wiki_token>' --type wiki --need-relation
 ```
 
-只有在需要未被 shortcut 暴露的底层参数时，才直接调用 raw OpenAPI。此时把 `need_relation` 放在 query params：
+已知评论 ID 时，用 `drive +batch-query-comments --need-relation` 直接按 ID 取：
 
 ```bash
-lark-cli drive file.comments list \
-  --params '{"file_token":"<doc_token>","file_type":"docx","is_solved":false,"need_relation":true}'
+lark-cli drive +batch-query-comments --url '<docx_or_wiki_url>' --comment-ids '<comment_id>' --need-relation
 ```
 
-已知评论 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}'
-```
+只有在需要 shortcut 未暴露的底层参数时，才直接调 raw OpenAPI（两个 shortcut 已各自处理 `need_relation` 的位置差异：list 在 query params，batch_query 在请求 body）。
 
 同时获取文档内容，并要求返回 block id：
 
@@ -138,7 +132,7 @@ lark-cli docs +fetch --doc '<doc_token_or_url>' --detail with-ids
 ## 定位流程
 
 1. 确认目标是 `file_type=docx`；只有 docx 文档支持通过 `need_relation` 查询评论位置。
-2. 用 `drive +list-comments --need-relation` 获取评论；已知评论 ID 且需要批量查询时，可用 `drive file.comments batch_query` 并带 `need_relation=true`。raw `drive file.comments list` 仅作为低层参数兜底。
+2. 用 `drive +list-comments --need-relation` 获取评论；已知评论 ID 且需要批量查询时，用 `drive +batch-query-comments --need-relation`。原生 `drive file.comments list/batch_query` 仅在需要 shortcut 未暴露的底层参数时兜底。
 3. 用 `docs +fetch --detail with-ids` 获取文档内容。
 4. 对每条评论先看 `relation`：
    - 如果存在 `relation.relation`，解析这个 JSON 字符串。
@@ -190,9 +184,9 @@ lark-cli base +record-list --base-token '<base_token>' --table-id '<table_id>' -
 - 若要定位画板内部节点，切到 `lark-whiteboard` 读取 raw 节点结构：
 
 ```bash
-lark-cli whiteboard +query \
+lark-cli whiteboard +export \
   --whiteboard-token '<whiteboard_token>' \
-  --output_as raw
+  --output-type raw
 ```
 
 - 如果 raw 节点中存在唯一匹配 `quote` 的文本节点，可定位到该节点；如果有多个相同文本节点，仍然是弱匹配，需要结合位置、样式、用户描述或人工确认。

package/skills/lark-drive/references/lark-drive-delete-reply.md

@@ -0,0 +1,48 @@
+# drive +delete-reply
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和权限处理。
+
+删除某条回复。**高风险写操作**：真实执行需要按 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 的高风险审批协议向用户确认后追加 `--yes`；删除不可恢复。
+
+## 命令
+
+```bash
+# 先预览（--dry-run 不需要 --yes）
+lark-cli drive +delete-reply --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" --comment-id '<id>' --reply-id '<id>' --dry-run
+
+# 确认后真实删除（把 --dry-run 换成 --yes）
+lark-cli drive +delete-reply --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" --comment-id '<id>' --reply-id '<id>' --yes
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--url` | 与 `--token` 二选一 | 推荐入口。支持 doc/docx/sheet/file/slides/base/bitable/apps/wiki URL；apps 妙搭 URL 使用 `/page/<token>`；wiki URL 会自动解析到真实文档。 |
+| `--token` | 与 `--url` 二选一 | 裸 token 或 URL。裸 token 必须搭配 `--type`；wiki token 使用 `--type wiki`。 |
+| `--type` | 裸 token 时必填 | 传 token 对应类型：`doc`、`docx`、`sheet`、`file`、`slides`、`bitable`、`base`、`apps`、`wiki`。wiki token 使用 `wiki`；传 `base` 时，CLI 会按 `bitable` 类型处理。 |
+| `--comment-id` | 是 | 回复所属的评论 ID；来自 `drive +list-comments` |
+| `--reply-id` | 是 | 要删除的回复 ID；来自 `drive +list-replies` 的 `items[].reply_id`，或 `drive +list-comments` 的 `items[].reply_list.replies[].reply_id` |
+| `--yes` | 真实执行时是 | 高风险确认；`--dry-run` 预览不需要 |
+
+## 行为说明
+
+- 删除永久生效，回复没有回收站或撤销。
+- 删除按 reply 逐条生效：删除某条回复（包括第一条/根回复）不影响其它回复；把该评论卡片下的所有回复都删完后，评论卡片在前端页面才不再显示。
+- **删除整条评论没有专门的命令，需要用本命令删光该卡片下的所有回复**（先用 `drive +list-replies` 拉全回复 id）。删除前先和用户确认删的是某条回复还是整条评论。
+
+## 输出
+
+```json
+{
+  "file_token": "docx_token",
+  "file_type": "docx",
+  "comment_id": "<comment_id>",
+  "reply_id": "<reply_id>",
+  "deleted": true
+}
+```
+
+## 参考
+
+- [lark-drive-list-replies](lark-drive-list-replies.md) -- 获取回复与 reply_id

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

@@ -11,7 +11,7 @@
 # 下载到指定路径
 lark-cli drive +download --file-token boxbc_xxx --output ./report.pdf
 
-# 只提供 token，默认保存为当前目录下同名文件
+# 只提供 token，默认保存到当前目录
 lark-cli drive +download --file-token boxbc_xxx
 ```
 
@@ -25,6 +25,10 @@ https://xxx.feishu.cn/drive/file/boxbc_xxx
                                   file_token
 ```
 
+## 排障
+
+- 如果返回 `HTTP 403`，可以使用 [lark-drive-preview](lark-drive-preview.md) 下载源文件产物。
+
 ## 参考
 
 - [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令

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

@@ -14,72 +14,10 @@
 
 ```bash
 # 推荐：直接传用户给出的完整 URL。默认只查未解决评论。
-lark-cli drive +list-comments \
-  --url "<DOCUMENT_URL>"
-
-# 只有用户明确要求包含已解决评论时，才查询已解决和未解决的全部评论。
-lark-cli drive +list-comments \
-  --url "<DOCUMENT_URL>" \
-  --solved-status all
-
-# 查询已解决评论。
-lark-cli drive +list-comments \
-  --url "<DOCUMENT_URL>" \
-  --solved-status true
-
-# 只查全文评论或局部评论。
-lark-cli drive +list-comments \
-  --url "<DOCUMENT_URL>" \
-  --comment-scope whole
-
-lark-cli drive +list-comments \
-  --url "<DOCUMENT_URL>" \
-  --comment-scope partial
-
-# 电子表格 URL 保留 /sheets/ 路径，直接原样传入；不要把 sheet token 拼成 /docx/<token>。
-lark-cli drive +list-comments \
-  --url "https://example.larksuite.com/sheets/<SHEET_TOKEN>"
-
-# 妙搭 apps URL 使用 /page/<token>，shortcut 会识别为 file_type=apps。
-lark-cli drive +list-comments \
-  --url "https://example.feishu.cn/page/<APPS_TOKEN>/"
-
-# wiki URL 会自动解包。
-lark-cli drive +list-comments \
-  --url "https://example.larksuite.com/wiki/<WIKI_TOKEN>"
-
-# 裸 wiki token 也支持，但必须显式声明 --type wiki。
-lark-cli drive +list-comments \
-  --token "<WIKI_TOKEN>" \
-  --type wiki
-
-# 裸 token 需要声明 token 对应类型；不要默认当作 docx。这里以 sheet 为例。
-lark-cli drive +list-comments \
-  --token "<DOCUMENT_TOKEN>" \
-  --type sheet \
-  --page-size 100
-
-# 妙搭裸 apps token 需要显式声明 --type apps。
-lark-cli drive +list-comments \
-  --token "<APPS_TOKEN>" \
-  --type apps
-
-# docx 需要评论定位关系时再带 need-relation；非 docx 会静默忽略。
-lark-cli drive +list-comments \
-  --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" \
-  --need-relation
-
-# 分页续跑。
-# 先看上一页输出的 has_more；只有 has_more=true 时，才用返回的 page_token 继续。
-lark-cli drive +list-comments \
-  --url "<DOCUMENT_URL>" \
-  --page-size 100 \
-  --page-token "<NEXT_PAGE_TOKEN>"
-
-# 预览请求链路，不发真实请求。
-lark-cli drive +list-comments \
-  --url "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
-  --dry-run
+lark-cli drive +list-comments --url "<DOCUMENT_URL>"
+
+# 只有用户明确要求包含已解决评论时，才传 --solved-status all。
+lark-cli drive +list-comments --url "<DOCUMENT_URL>" --solved-status all
 ```
 
 ## 参数
@@ -103,7 +41,26 @@ lark-cli drive +list-comments \
 - URL 输入时不需要传 `--type`；如果 URL 类型和显式 `--type` 冲突，shortcut 会返回 validation error，建议移除 `--type`。
 - wiki 输入会自动解析到真实文档，再查询评论列表。JSON 输出不额外返回 wiki token 或 wiki node。
 - 输出中的 `items` 保留评论卡片字段，外层补充 `file_token`、`file_type`、`has_more`、`page_token`、`count`；`count` 是当前页返回的评论卡片数。是否继续分页以 `has_more` 为准，而不是只看 `page_token` 是否存在。
-- 如果需要批量按评论 ID 查询、获取更多回复、创建/编辑/删除回复，继续使用原生 `drive file.comments batch_query` 或 `drive file.comment.replys.*`。
+
+## 评论卡片模型
+
+- 返回的 `items` 是评论卡片列表，每个 `item` 对应用户界面中的一张评论卡片，不是平铺的互动消息列表。
+- 创建评论时会同时创建该卡片里的第一条 reply；真正承载正文的是 `item.reply_list.replies`，其中第一条 reply（根回复）在用户视角下就是这张卡片里的“评论本身”。更新根回复即改写评论正文（见 [`lark-drive-update-reply.md`](lark-drive-update-reply.md)）；删除按 reply 逐条生效，卡片在最后一条回复被删时才消失（见 [`lark-drive-delete-reply.md`](lark-drive-delete-reply.md)）。
+- `item.has_more=true` 表示该评论卡片下还有回复未包含在本次返回中；这与外层 `has_more`（是否还有下一页评论卡片）是两个不同字段。需要完整回复时继续用 `drive +list-replies --comment-id <id>` 分页拉全。
+
+## 统计口径
+
+- 统计“评论数”或“评论卡片数”：统计 `items` 长度；全量统计时对所有分页返回的 `items` 长度累加。
+- 统计“回复数”：统计所有 `item.reply_list.replies` 长度之和，再减去 `items` 长度。
+- 统计“总互动数”：统计所有 `item.reply_list.replies` 长度之和，包含每张评论卡片里的首条评论。
+- 任一 `item.has_more=true` 时，先用 `drive +list-replies --comment-id <id>` 把该卡片的回复拉全，再做回复数或总互动数统计，否则会少算。
+
+## 排序
+
+- 只有当用户明确提到“最新评论”“最后评论”“最早评论”时，才需要按 `create_time` 排序。
+- 排序前必须拉完所有评论分页，不能只取第一页。
+- “最新评论”/“最后评论”：按 `create_time` 降序取第一条。“最早评论”：按 `create_time` 升序取第一条。
+- 用户只说“第一条评论”时，直接使用返回的第一条，不需要额外排序。
 
 ## 输出
 
@@ -121,5 +78,5 @@ lark-cli drive +list-comments \
 ## 参考
 
 - [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
-- [lark-drive-comments-guide](lark-drive-comments-guide.md) -- 评论统计、回复限制和原生 API 说明
+- [lark-drive-list-replies](lark-drive-list-replies.md) -- 拉全某张卡片下的回复（统计与 `item.has_more` 补全）
 - [lark-drive-comment-location](lark-drive-comment-location.md) -- 使用 `need_relation` 定位 docx 正文

package/skills/lark-drive/references/lark-drive-list-replies.md

@@ -0,0 +1,54 @@
+# drive +list-replies
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和权限处理。
+
+分页获取某条评论下的回复。
+
+## 命令
+
+```bash
+# 推荐：完整 URL + 评论 ID
+lark-cli drive +list-replies --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" --comment-id '<id>'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--url` | 与 `--token` 二选一 | 推荐入口。支持 doc/docx/sheet/file/slides/base/bitable/apps/wiki URL；apps 妙搭 URL 使用 `/page/<token>`；wiki URL 会自动解析到真实文档。 |
+| `--token` | 与 `--url` 二选一 | 裸 token 或 URL。裸 token 必须搭配 `--type`；wiki token 使用 `--type wiki`。 |
+| `--type` | 裸 token 时必填 | 传 token 对应类型：`doc`、`docx`、`sheet`、`file`、`slides`、`bitable`、`base`、`apps`、`wiki`。wiki token 使用 `wiki`；传 `base` 时，CLI 会按 `bitable` 类型处理。 |
+| `--comment-id` | 是 | 评论 ID；来自 `drive +list-comments` 的 `items[].comment_id` |
+| `--page-size` | 否 | 1-100，默认 50 |
+| `--page-token` | 否 | 上次输出的 `page_token`；`has_more=true` 时用它续拉 |
+| `--need-reaction` | 否 | 在回复上返回 reaction 数据，见 [`lark-drive-reactions.md`](lark-drive-reactions.md) |
+
+## 行为说明
+
+- 根回复承载评论正文本身，是回复列表中创建最早的一条：**仅第一页（未传 `--page-token`）的 `items[0]` 是根回复**；翻页后（传了 `--page-token`）返回的 `items[0]` 只是普通回复，不要按位置当作根回复去更新或删除。
+- 输出字段：`items[].reply_id` / `user_id` / `create_time` / `update_time` / `content.elements`，供 `+update-reply`、`+delete-reply` 使用。
+- 检查回复归属（更新/删除前）：比对 `items[].user_id`（open_id）与当前身份，判断是不是自己创建的回复。
+- 输出的 `items` 始终是 JSON 数组（服务端省略时归一化为 `[]`）。
+
+## 输出
+
+```json
+{
+  "file_token": "docx_token",
+  "file_type": "docx",
+  "comment_id": "<comment_id>",
+  "items": [],
+  "has_more": false,
+  "page_token": "",
+  "count": 0
+}
+```
+
+`items` 是回复数组；是否继续翻页以 `has_more` 为准，`has_more=true` 时用返回的 `page_token` 续拉。
+
+## 参考
+
+- [lark-drive-list-comments](lark-drive-list-comments.md) -- 评论卡片模型与统计口径
+- [lark-drive-update-reply](lark-drive-update-reply.md) -- 更新回复
+- [lark-drive-delete-reply](lark-drive-delete-reply.md) -- 删除回复
+- [lark-drive-reactions](lark-drive-reactions.md) -- reaction 查询与写入

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

@@ -20,8 +20,8 @@ lark-cli drive +member-add \
 
 | 参数 | 必填 | 说明                                                                                                                                                                                  |
 |------|----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `--token` | 是 | 裸 token 或完整 URL。路径支持 `/drive/folder/`、`/docx/`、`/doc/`、`/sheets/`、`/base/`、`/bitable/`、`/wiki/`、`/file/`、`/mindnotes/`、`/slides/`、`/minutes/`；URL 输入可从路径推断 `--type`，裸 token 不做前缀推断 |
-| `--type` | 必填 | 目标资源类型：`docx` / `doc` / `sheet` / `bitable` / `file` / `folder` / `wiki` / `mindnote` / `slides` / `minutes`。传 URL 时可省略；裸 token 必须显式传；若同时传 URL 和 `--type`，显式 `--type` 覆盖 URL 推断                 |
+| `--token` | 是 | 裸 token 或完整 URL。路径支持 `/drive/folder/`、`/docx/`、`/doc/`、`/sheets/`、`/base/`、`/bitable/`、`/wiki/`、`/file/`、`/mindnotes/`、`/slides/`、`/minutes/`、`/page/`；URL 输入可从路径推断 `--type`，裸 token 不做前缀推断 |
+| `--type` | 必填 | 目标资源类型：`docx` / `doc` / `sheet` / `bitable` / `file` / `folder` / `wiki` / `mindnote` / `slides` / `minutes` / `apps`。传 URL 时可省略；裸 token 必须显式传；若同时传 URL 和 `--type`，显式 `--type` 覆盖 URL 推断 |
 | `--member-id` | 是 | 协作者 ID；逗号分隔可批量添加，最多 10 个                                                                                                                                                            |
 | `--member-type` | 是 | member-id 的类型；支持 `email` / `openid` / `unionid` / `openchat` / `opendepartmentid` / `groupid` / `appid` / `wikispaceid`。在实际使用里，给当前应用授权仍优先推荐 bot `open_id` + `openid`。                               |
 | `--member-kind` | 条件必填 | 仅当 `--member-type=wikispaceid` 时填写，映射到请求 body 的 `type` 字段。取值：`wiki_space_member` / `wiki_space_viewer` / `wiki_space_editor`。其他 member-type 禁止传此参数。 |

package/skills/lark-drive/references/lark-drive-member-list.md

@@ -0,0 +1,65 @@
+# drive +member-list（查询协作者/授权成员列表）
+
+本 skill 对应 shortcut：`lark-cli drive +member-list`。它读取 Drive 文档、文件、文件夹或 wiki 节点的协作者/授权成员列表。
+
+## 命令
+
+```bash
+#  URL 自动推断 type
+lark-cli drive +member-list \
+  --token 'https://example.feishu.cn/drive/folder/<folder_token>' \
+  --as user --format json
+
+# 查询附加字段
+lark-cli drive +member-list \
+  --token '<token>' \
+  --type docx \
+  --fields 'name,type,external_label' \
+  --as user --format json
+
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token` | 是 | 裸 token 或完整 URL。URL 路径支持 `/folder/`、`/docx/`、`/doc/`、`/sheets/`、`/base/`、`/bitable/`、`/wiki/`、`/file/`、`/mindnotes/`、`/slides/`、`/minutes/`、`/page/`。 |
+| `--type` | 裸 token 必填 | 目标类型：`doc` / `sheet` / `file` / `wiki` / `bitable` / `docx` / `mindnote` / `minutes` / `slides` / `folder` / `apps`。URL 可自动推断；如果同时传 URL 和冲突的 `--type`，CLI 会拒绝。 |
+| `--fields` | 否 | 默认不传。可取 `name` / `type` / `avatar` / `external_label`，支持逗号分隔；也可传 `*` 请求当前支持的所有附加字段。该参数只声明期望返回的字段，不授予字段级权限。 |
+| `--perm-type` | 否 | 仅 `--type wiki` 有效；取值 `container` / `single_page`。 |
+| `--dry-run` | 否 | 只打印请求，不调用 API。 |
+
+## 输出
+
+JSON 输出原样透传 API 的 `data` ：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "items": [
+      {
+        "member_type": "openid",
+        "member_id": "ou_xxx",
+        "perm": "view",
+        "perm_type": "container",
+        "type": "user",
+        "name": "zhangsan",
+        "external_label": false
+      }
+    ]
+  }
+}
+```
+
+`--format pretty` 会轻量展示成员 ID、成员类型、权限、wiki `perm_type` 和已返回的附加字段。机器读取优先使用 `--format json`。
+
+## 行为说明
+
+- **身份支持**：`--as user` 和 `--as bot` 均可用；缺 scope 或目标权限时按统一 permission 错误路径处理。
+- **接口 scope**：查询成员列表需要 `docs:permission.member:retrieve`。
+- **fields 默认**：不传 `--fields` 时按官方 API 默认，不请求姓名、头像、外部标签等附加字段；需要时显式指定。
+- **字段级权限**：`--fields` 只控制请求哪些附加字段，不保证服务端一定返回。请求用户的 `name` / `avatar` 时，应用还需开通 `contact:user.base:readonly`（“获取用户基本信息”；已具备官方兼容的历史通讯录权限也可满足要求）。
+- **缺字段语义**：字段级权限或数据可见性不足时，接口仍可能成功，但会省略相应敏感字段。响应中缺少已请求字段表示“服务端未返回”，不能解释为字段值为空，也不能据此认定成员信息完整。
+- **folder 支持**：CLI 支持 `--type folder` 并会按需求发送 `type=folder`；部分环境的后端如果尚未放开 folder 枚举，可能返回 `99992402 field validation failed`。

package/skills/lark-drive/references/lark-drive-permission-get-setting.md

@@ -0,0 +1,48 @@
+# drive +permission-get-setting（查询权限设置）
+
+本 skill 对应 shortcut：`lark-cli drive +permission-get-setting`。它读取单个 Drive 资源自身的公开访问、分享、协作者管理、安全与评论权限设置，不递归读取文件夹中的子资源。
+
+## 命令
+
+```bash
+# 通过 URL 自动推断 type
+lark-cli drive +permission-get-setting \
+  --token 'https://example.feishu.cn/drive/folder/<folder_token>' \
+  --as user --format json
+
+# 通过 bare token 显式指定 type
+lark-cli drive +permission-get-setting \
+  --token '<folder_token>' \
+  --type folder \
+  --as user --format json
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token` | 是 | bare token 或完整 URL。URL 路径支持 `/folder/`、`/docx/`、`/doc/`、`/sheets/`、`/base/`、`/bitable/`、`/wiki/`、`/file/`、`/mindnotes/`、`/slides/`、`/minutes/`、`/page/`。 |
+| `--type` | bare token 必填 | 目标类型：`doc` / `sheet` / `file` / `wiki` / `bitable` / `docx` / `mindnote` / `minutes` / `slides` / `folder` / `apps`。URL 可自动推断；如果同时传 URL 和冲突的 `--type`，CLI 会拒绝。 |
+| `--dry-run` | 否 | 只打印请求，不调用 API。 |
+
+## 输出
+
+JSON 输出中的 `data.permission_public` 是目标当前的权限设置；服务端未返回该字段时，命令会报响应结构错误，而不会把其他字段伪装成权限设置。
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "permission_public": {}
+  }
+}
+```
+
+`--format pretty` 会展示完整的 `permission_public` 对象，包括服务端将来新增的字段。
+
+## 行为说明
+
+- **身份支持**：`--as user` 和 `--as bot` 均可用。
+- **所需 scope**：`docs:permission.setting:read`。
+- **单目标读取**：命令只读取 `--token` 指向资源自身的权限设置；`--type folder` 不会递归读取子资源。

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

@@ -2,15 +2,24 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
 
-列出或下载 Drive 文件可用的预览产物。这个 shortcut 不猜测默认类型：
+查看或下载 Drive 文件内容，或列出并获取文件可用的预览产物。这个 shortcut 不猜测默认类型：
 
+- 如果只需要查看或下载文件内容，或不关心 PDF/text/image 等转换预览，优先使用 `--type source_file --output <path>`
 - 只想看候选项时，用 `--list-only`
+- 如果需要服务端生成的预览效果，例如 doc/docx 的 PDF 版式预览，先用 `--list-only` 查看候选项，再按候选项选择 `--type pdf` / `text` / `image` 等
 - 想下载时，必须显式传 `--type` 和 `--output`
+- 如果 `--list-only` 没有可用预览候选项，或错误提示明确建议使用 `--type source_file`，可以改用 `--type source_file --output <path>` 查看文件内容；资源不存在、token 无效等终态错误需要先修正输入
 - 如果某个候选项还在生成中，会返回结构化错误并提示先重新 `--list-only`
 
 ### 命令
 
 ```bash
+# 查看文件内容
+lark-cli drive +preview \
+  --file-token "<FILE_TOKEN>" \
+  --type source_file \
+  --output ./artifacts/source
+
 # 列出可用预览候选项
 lark-cli drive +preview \
   --file-token "<FILE_TOKEN>" \
@@ -78,6 +87,7 @@ lark-cli drive +preview \
 
 - 不传 `--list-only` 时，必须显式传 `--type` 和 `--output`
 - 不会隐式选择“第一个候选项”作为默认下载目标
+- `--type source_file` 用于查看文件内容，不依赖 `--list-only` 返回的候选项；它适合读取或保存源内容，不等同于 PDF/text/image 等转换预览
 - 候选项状态来自后端 `preview_status` 枚举，例如 `READY` / `PROCESSING` / `FAILED` / `NO_SUPPORT`
 - 本地文件名在未显式带扩展名时，会结合响应头自动补扩展名
 

package/skills/lark-drive/references/lark-drive-react-reply.md

@@ -0,0 +1,51 @@
+# drive +react-reply
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和权限处理。reaction 查询规则、语义联想与完整 `reaction_type` 枚举见跨切面专题 [`lark-drive-reactions.md`](lark-drive-reactions.md)。
+
+给一条回复添加或删除表情回应（reaction）。操作对象始终是 `reply_id`。
+
+## 命令
+
+```bash
+# 加 reaction
+lark-cli drive +react-reply --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" --reply-id '<id>' --emoji THUMBSUP --action add
+
+# 删除自己加的 reaction：仍需传要删除的那个 --emoji
+lark-cli drive +react-reply --url "https://example.larksuite.com/docx/<DOCX_TOKEN>" --reply-id '<id>' --emoji THUMBSUP --action delete
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--url` | 与 `--token` 二选一 | 推荐入口。支持 doc/docx/sheet/file/slides/base/bitable/apps/wiki URL；apps 妙搭 URL 使用 `/page/<token>`；wiki URL 会自动解析到真实文档。 |
+| `--token` | 与 `--url` 二选一 | 裸 token 或 URL。裸 token 必须搭配 `--type`；wiki token 使用 `--type wiki`。 |
+| `--type` | 裸 token 时必填 | 传 token 对应类型：`doc`、`docx`、`sheet`、`file`、`slides`、`bitable`、`base`、`apps`、`wiki`。wiki token 使用 `wiki`；传 `base` 时，CLI 会按 `bitable` 类型处理。 |
+| `--reply-id` | 是 | 要操作的回复 ID；来自 `drive +list-replies` 的 `items[].reply_id`。给“这条评论”加/删表情时取该评论根回复（第一页 `items[0]`）的 `reply_id` |
+| `--emoji` | 是 | `reaction_type` 值，大小写敏感；本地按平台枚举校验。完整列表与语义映射见 [`lark-drive-reactions.md`](lark-drive-reactions.md) |
+| `--action` | 是 | `add` 添加；`delete` 删除当前身份自己加的 reaction |
+
+## 行为说明
+
+- `--emoji` 大小写敏感（如 `THUMBSUP` 与 `ThumbsDown`），并做本地枚举校验兜底。服务端不校验 `reaction_type`：任意字符串都会被接受并持久化成一条损坏的 reaction，所以本地校验是唯一防线；直接调原生命令时必须自行保证取值合法。
+- add / delete 幂等：重复添加已有 reaction、删除不存在的 reaction 都会成功返回且无副作用；delete 只取消当前身份自己加的 reaction。
+- 对根回复操作等价于给评论本身加 / 删表情。
+- 读回 reaction：在 `drive +list-replies` / `drive +batch-query-comments` 上带 `--need-reaction`；`count=0` 的条目是已删除 reaction 的残留，判断存在与否按 `count>0` 过滤。
+
+## 输出
+
+```json
+{
+  "file_token": "docx_token",
+  "file_type": "docx",
+  "reply_id": "<reply_id>",
+  "reaction_type": "THUMBSUP",
+  "action": "add",
+  "updated": true
+}
+```
+
+## 参考
+
+- [lark-drive-reactions](lark-drive-reactions.md) -- reaction 查询规则、语义与完整枚举
+- [lark-drive-list-replies](lark-drive-list-replies.md) -- 获取 reply_id

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

@@ -1,8 +1,8 @@
 # drive reactions
 
-> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 评论入口，再阅读 [`lark-drive-comments-guide.md`](lark-drive-comments-guide.md) 了解评论卡片模型、评论数/回复数统计口径、`file_token` / `file_type` 规则；同时阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 评论入口，再阅读 [`lark-drive-list-comments.md`](lark-drive-list-comments.md) 了解评论卡片模型、评论数/回复数统计口径、`file_token` / `file_type` 规则；同时阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-处理文档评论 / 回复上的 reaction（点赞、表情、各表情数量、谁点了什么、添加/删除表情）。这个场景不常见，但规则比较集中：查询时只有在用户明确需要 reaction 信息时才带 `need_reaction=true`；写入时统一使用 `drive file.comment.reply.reactions update_reaction`，操作对象始终是 `reply_id`。
+处理文档评论 / 回复上的 reaction（点赞、表情、各表情数量、谁点了什么、添加/删除表情）。这个场景不常见，但规则比较集中：查询时只有在用户明确需要 reaction 信息时才在 `drive +list-comments` / `+batch-query-comments` / `+list-replies` 上带 `--need-reaction`；写入优先使用 `drive +react-reply`（命令参数细节见 [`lark-drive-react-reply.md`](lark-drive-react-reply.md)），操作对象始终是 `reply_id`。本文是跨切面专题，集中放 reaction 的查询规则、语义联想和完整枚举。
 
 > [!IMPORTANT]
 > **`reaction_type` 只能使用本文下方“完整 `reaction_type` 列表”中定义的枚举值。**
@@ -16,49 +16,50 @@
 
 ## 查询规则
 
-- `drive file.comments list`、`drive file.comments batch_query`、`drive file.comment.replys list` 都支持通过指定`need_reaction`查询reaction信息。
-- `need_reaction` 只在用户明确需要 reaction 信息时再带；如果用户只关心评论正文、回复正文、评论数 / 回复数，默认不要加。
-- 遍历评论卡片并顺带拿 reaction：使用 `drive file.comments list`。
-- 已知评论 ID，批量查看 reaction：使用 `drive file.comments batch_query`，并在请求体里带 `need_reaction=true`。
-- 某张评论卡片下继续翻页拉 reply reaction：使用 `drive file.comment.replys list`。
-- 如果 `drive file.comments list` 返回的某个 `item.has_more=true`，且用户要完整的 reply reaction 数据，后续每一页 `drive file.comment.replys list` 都要持续带 `need_reaction=true`。
+- `drive +list-comments`、`drive +batch-query-comments`、`drive +list-replies` 都支持 `--need-reaction`。
+- `--need-reaction` 只在用户明确需要 reaction 信息时再带；如果用户只关心评论正文、回复正文、评论数 / 回复数，默认不要加。
+- 遍历评论卡片并顺带拿 reaction：使用 `drive +list-comments --need-reaction`。
+- 已知评论 ID，批量查看 reaction：使用 `drive +batch-query-comments --need-reaction`。
+- 某张评论卡片下继续翻页拉 reply reaction：使用 `drive +list-replies --need-reaction`，每一页都要持续带。
+- 返回形状：`items[].reactions[]` 为 `{reaction_key, count, ahead_users[]}`；**`count=0` 的条目是已删除 reaction 的残留，统计与判断是否存在都要按 `count>0` 过滤**。
 
 ## 查询示例
 
 ```bash
 # 遍历评论卡片，并把 reaction 一起拿回来
-lark-cli drive file.comments list \
-  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx","need_reaction":true}'
+lark-cli drive +list-comments --url '<DOC_URL>' --need-reaction
 
 # 已知 comment_id，批量查询评论卡片 reaction
-lark-cli drive file.comments batch_query \
-  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
-  --data '{"comment_ids":["<COMMENT_ID>"],"need_reaction":true}'
+lark-cli drive +batch-query-comments --url '<DOC_URL>' --comment-ids '<COMMENT_ID>' --need-reaction
 
 # 继续翻某张评论卡片下的 replies，并把 reaction 一起拿回来
-lark-cli drive file.comment.replys list \
-  --params '{"file_token":"<DOC_TOKEN>","comment_id":"<COMMENT_ID>","file_type":"docx","need_reaction":true}'
+lark-cli drive +list-replies --url '<DOC_URL>' --comment-id '<COMMENT_ID>' --need-reaction
 ```
 
 ## 写入规则
 
-- 添加 / 删除 reaction 时，使用 `drive file.comment.reply.reactions update_reaction`。
-- 请求里必须带正确的 `file_type`，并在 body 中传 `action=add|delete`、`reply_id`、`reaction_type`。
-- `update_reaction` 的操作对象是 `reply_id`，不是 `comment_id`。
-- 如果用户说要给“这条评论”加 / 删 reaction，通常需要定位到该评论卡片首条 reply 的 `reply_id` 再操作。
+- 添加 / 删除 reaction 优先使用 `drive +react-reply`；命令参数、目标定位和 dry-run 见 [`lark-drive-react-reply.md`](lark-drive-react-reply.md)。
+- 操作对象是 `reply_id`（来自 `drive +list-replies` 的 `items[].reply_id`），不是 `comment_id`。
+- 如果用户说要给"这条评论"加 / 删 reaction，取该评论卡片根回复（第一页 `items[0]`）的 `reply_id` 再操作。
+- add / delete 幂等：重复添加已有 reaction、删除不存在的 reaction 都会成功返回且无副作用；delete 只取消当前身份自己加的 reaction。
+- **服务端不校验 `reaction_type`：任意字符串都会被接受并持久化成一条损坏的 reaction**；`+react-reply --emoji` 会按平台枚举做本地校验兜底，直接调原生命令时必须自行保证取值合法。
+- 原生 `drive file.comment.reply.reactions update_reaction` 只在需要 shortcut 未暴露的字段时兜底使用，`--params` 带 `file_token`/`file_type`，`--data` 传 `action=add|delete`、`reply_id`、`reaction_type`。
 
 ## 写入示例
 
 ```bash
 # 给某条 reply 添加一个点赞 reaction
-lark-cli drive file.comment.reply.reactions update_reaction \
-  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
-  --data '{"action":"add","reply_id":"<REPLY_ID>","reaction_type":"THUMBSUP"}'
+lark-cli drive +react-reply --url '<DOC_URL>' \
+  --reply-id '<REPLY_ID>' --emoji THUMBSUP --action add
+
+# 删除某条 reply 上已有的 DONE reaction（wiki URL 自动解包）
+lark-cli drive +react-reply --url '<WIKI_URL>' \
+  --reply-id '<REPLY_ID>' --emoji DONE --action delete
 
-# 删除某条 reply 上已有的 DONE reaction
+# 原生命令兜底（注意：原生路径没有本地枚举校验）
 lark-cli drive file.comment.reply.reactions update_reaction \
   --params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
-  --data '{"action":"delete","reply_id":"<REPLY_ID>","reaction_type":"DONE"}'
+  --data '{"action":"add","reply_id":"<REPLY_ID>","reaction_type":"THUMBSUP"}'
 ```
 
 > [!CAUTION]
@@ -66,7 +67,7 @@ lark-cli drive file.comment.reply.reactions update_reaction \
 
 ## `reaction_type` 使用规则
 
-- `reaction_type` 必须传平台定义的枚举字符串，大小写敏感。
+- `reaction_type` 必须传平台定义的枚举字符串，大小写敏感；`drive +react-reply` 的 `--emoji` 会本地校验（原生命令不校验、服务端也不校验）。
 - 不要擅自把 mixed-case 值改成全大写，例如 `Yes`、`No`、`Get`、`EatingFood`、`CheckMark`、`CrossMark` 都要按原值传。
 - **不要编造列表外的 `reaction_type`，也不要把自然语言描述臆造成平台未定义的新枚举**。
 - 如果用户给的是自然语言语义（如“点赞”“在处理中”“确认一下”），可以在下方枚举列表内选择语义最接近的现有值；如果是近似映射，应在执行时明确告知用户。
@@ -110,4 +111,5 @@ Music, Typing, Pepper, CheckMark, CrossMark
 ## 参考
 
 - [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
+- [lark-drive-react-reply](lark-drive-react-reply.md) -- `+react-reply` 命令参数
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数