@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/lark-tools/cli-skills/lark-doc/references/lark-doc-update.md

@@ -0,0 +1,264 @@
+
+# docs +update（更新飞书云文档）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新飞书云文档内容，支持 7 种更新模式。优先使用局部更新（replace_range/append/insert_before/insert_after），慎用 overwrite（会清空文档重写，可能丢失图片、评论等）。
+
+## 重要说明
+> **⚠️ 本文档中提到的 html 标签不需要在 Markdown 中转义！若转义，会导致相关的表格，多维表格，画板等 block 插入失败**
+
+## 命令
+
+```bash
+# 追加内容
+lark-cli docs +update --doc "<doc_id_or_url>" --mode append --markdown "## 新章节\n\n追加内容"
+
+# 定位替换（内容定位）
+lark-cli docs +update --doc "<doc_id>" --mode replace_range --selection-with-ellipsis "旧标题...旧结尾" --markdown "## 新内容"
+
+# 定位替换（标题定位）
+lark-cli docs +update --doc "<doc_id>" --mode replace_range --selection-by-title "## 功能说明" --markdown "## 功能说明\n\n新内容"
+
+# 全文替换
+lark-cli docs +update --doc "<doc_id>" --mode replace_all --selection-with-ellipsis "张三" --markdown "李四"
+
+# 前插入
+lark-cli docs +update --doc "<doc_id>" --mode insert_before --selection-with-ellipsis "## 危险操作" --markdown "> 警告：以下需谨慎！"
+
+# 后插入
+lark-cli docs +update --doc "<doc_id>" --mode insert_after --selection-with-ellipsis "代码示例" --markdown "**输出示例**：result = 42"
+
+# 删除内容
+lark-cli docs +update --doc "<doc_id>" --mode delete_range --selection-by-title "## 废弃章节"
+
+# 覆盖（慎用）
+lark-cli docs +update --doc "<doc_id>" --mode overwrite --markdown "# 全新内容"
+
+# 同时更新标题
+lark-cli docs +update --doc "<doc_id>" --mode append --markdown "## 更新日志" --new-title "文档 v2.0"
+
+# 在指定内容后新增两个空白画板
+lark-cli docs +update --doc "<doc_id>" --mode insert_after --selection-with-ellipsis "有序列表" --markdown $'<whiteboard type="blank"></whiteboard>\n<whiteboard type="blank"></whiteboard>'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc` | 是 | 文档 URL 或 token |
+| `--mode` | 是 | 更新模式（见下方 7 种模式说明） |
+| `--markdown` | 视模式 | 新内容（Lark-flavored Markdown）。delete_range 模式不需要，其他模式必填。若要新增空白画板，直接传 `<whiteboard type="blank"></whiteboard>`；需要多个画板时，在同一个 markdown 里重复多个标签 |
+| `--selection-with-ellipsis` | 视模式 | 内容定位（如 `"开头...结尾"`）。与 `--selection-by-title` 互斥 |
+| `--selection-by-title` | 视模式 | 标题定位（如 `"## 章节名"`）。与 `--selection-with-ellipsis` 互斥 |
+| `--new-title` | 否 | 同时更新文档标题 |
+
+# 定位方式
+
+定位模式（replace_range/replace_all/insert_before/insert_after/delete_range）支持两种定位方式，二选一：
+
+## selection-with-ellipsis - 内容定位
+
+支持两种格式：
+
+1. **范围匹配**：`开头内容...结尾内容`
+   - 匹配从开头到结尾的所有内容（包含中间内容）
+   - 建议 10-20 字符确保唯一性
+
+2. **精确匹配**：`完整内容`（不含 `...`）
+   - 匹配完整的文本内容
+   - 适合替换短文本、关键词等
+
+**转义说明**：如果要匹配的内容本身包含 `...`，使用 `\.\.\.` 表示字面量的三个点。
+
+示例：
+- `你好...世界` → 匹配从"你好"到"世界"之间的任意内容
+- `你好\.\.\.世界` → 匹配字面量 "你好...世界"
+
+**建议**：如果文档中有多个 `...`，建议使用更长的上下文来精确定位，避免歧义。
+
+## selection-by-title - 标题定位
+
+格式：`## 章节标题`（可带或不带 # 前缀）
+
+自动定位整个章节（从该标题到下一个同级或更高级标题之前）。
+
+**示例**：
+- `## 功能说明` → 定位二级标题"功能说明"及其下所有内容
+- `功能说明` → 定位任意级别的"功能说明"标题及其内容
+
+# 可选参数
+
+## new-title
+
+更新文档标题。如果提供此参数，将在更新文档内容后同步更新文档标题。
+
+**特性**：
+- 仅支持纯文本，不支持富文本格式
+- 长度限制：1-800 字符
+- 可以与任何 mode 配合使用
+- 标题更新在内容更新之后执行
+
+# 返回值
+
+## 成功
+
+```json
+{
+  "success": true,
+  "doc_id": "文档ID",
+  "mode": "使用的模式",
+  "board_tokens": ["可选：新建画板 token 列表"],
+  "message": "文档更新成功（xxx模式）",
+  "warnings": ["可选警告列表"],
+  "log_id": "请求日志ID"
+}
+```
+
+如果本次 `docs +update` 创建了画板，响应会额外返回 `board_tokens`。在 CLI 的成功 JSON 输出里，后续编辑画板应读取 `data.board_tokens`。
+
+## 异步模式（大文档超时）
+
+```json
+{
+  "task_id": "async_task_xxxx",
+  "message": "文档更新已提交异步处理，请使用 task_id 查询状态",
+  "log_id": "请求日志ID"
+}
+```
+
+## 错误
+
+```json
+{
+  "error": "[错误码] 错误消息\n💡 Suggestion: 修复建议\n📍 Context: 上下文信息",
+  "log_id": "请求日志ID"
+}
+```
+
+---
+
+# 使用示例
+
+## append - 追加到末尾
+
+```bash
+lark-cli docs +update --doc "文档ID或URL" --mode append --markdown "## 新章节\n\n追加的内容..."
+```
+
+## replace_range - 定位替换
+
+使用 `--selection-with-ellipsis`：
+```bash
+lark-cli docs +update --doc "文档ID" --mode replace_range --selection-with-ellipsis "## 旧标题...旧结尾。" --markdown "## 新标题\n\n新的内容..."
+```
+
+使用 `--selection-by-title`（替换整个章节）：
+```bash
+lark-cli docs +update --doc "文档ID" --mode replace_range --selection-by-title "## 功能说明" --markdown "## 功能说明\n\n更新后的内容..."
+```
+
+## replace_all - 全文替换
+
+```bash
+lark-cli docs +update --doc "文档ID" --mode replace_all --selection-with-ellipsis "张三" --markdown "李四"
+```
+
+返回值包含 `replace_count` 字段，表示替换的次数。
+
+**注意**：
+- 与 `replace_range` 不同，`replace_all` 允许多个匹配
+- 如果没有找到匹配内容，会返回错误
+- `--markdown` 可以为空字符串，表示删除所有匹配内容
+
+## delete_range - 删除内容
+
+```bash
+lark-cli docs +update --doc "文档ID" --mode delete_range --selection-by-title "## 废弃章节"
+```
+
+注意：delete_range 模式不需要 `--markdown` 参数。
+
+## overwrite - 完全覆盖
+
+⚠️ 会清空文档后重写，可能丢失图片、评论等，仅在需要完全重建文档时使用。
+
+```bash
+lark-cli docs +update --doc "文档ID" --mode overwrite --markdown "# 新文档\n\n全新的内容..."
+```
+
+## 创建空白画板
+
+当用户要“新增空白画板”时，不要用 Mermaid 占位图；直接按 whiteboard 标签传 `--markdown`。
+
+自然语言请求示例：
+- “给我在这个文档末尾新增一个空白画板”
+
+```bash
+# 追加一个空白画板
+lark-cli docs +update --doc "文档ID" --mode append --markdown '<whiteboard type="blank"></whiteboard>'
+
+# 在指定内容后新增两个空白画板
+lark-cli docs +update --doc "文档ID" --mode insert_after --selection-with-ellipsis "有序列表" --markdown $'<whiteboard type="blank"></whiteboard>\n<whiteboard type="blank"></whiteboard>'
+```
+
+成功后，响应里的 `data.board_tokens` 就是新建画板的 token 列表；如果后续要继续编辑这些画板，直接使用这些 token。
+
+---
+
+# 最佳实践
+
+## 重要：画板编辑
+
+> **⚠️ docs +update 不能编辑已有画板内容，但可以创建新的空白画板**
+
+画板编辑：详见 [SKILL.md](../SKILL.md#重要说明画板编辑)
+
+## 小粒度精确替换
+
+修改文档内容时，**定位范围越小越安全**。尤其是表格、分栏等嵌套块，应精确定位到需要修改的文本，避免影响其他内容。
+
+## 保护不可重建的内容
+
+图片、画板、电子表格、多维表格、任务等内容以 token 形式存储，**无法读出后原样写入**。
+
+**保护策略**：
+- 替换时避开包含这些内容的区域
+- 精确定位到纯文本部分进行修改
+
+## 分步更新优于整体覆盖
+
+修改多处内容时：
+- ✅ 多次小范围替换，逐步修改
+- ⚠️ 谨慎使用 `overwrite` 重写整个文档，除非你认为风险完全可控
+
+**原因**：局部更新保留原有媒体、评论、协作历史，更安全可靠。
+
+## insert 模式扩大定位范围时注意插入位置
+
+使用 `insert_before` 或 `insert_after` 时，如果目标内容重复出现，需要扩大 `--selection-with-ellipsis` 范围来唯一定位。
+
+**关键**：插入位置基于匹配范围的**边界**：
+- `insert_after` → 插入在匹配范围的**结尾**之后
+- `insert_before` → 插入在匹配范围的**开头**之前
+
+## 修复画板语法错误
+
+当 `docs +create` 或 `docs +update` 返回画板写入失败的 warning 时：
+1. warning 中包含 whiteboard 标签（如 `<whiteboard token="xxx"/>`）
+2. 分析错误信息，修正 Mermaid/PlantUML 语法
+3. 用 `--mode replace_range` 替换：`--selection-with-ellipsis` 使用 warning 中的 whiteboard 标签，`--markdown` 提供修正后的代码块
+4. 重新提交验证
+
+---
+
+# 注意事项
+
+- **Markdown 语法**：支持飞书扩展语法，详见 [lark-doc-create](lark-doc-create.md) 工具文档
+
+## 参考
+
+- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档
+- [lark-doc-create](lark-doc-create.md) — 创建文档（含完整 Markdown 格式参考）
+- [lark-doc-media-insert](lark-doc-media-insert.md) — 插入图片/文件到文档
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-doc/references/lark-doc-whiteboard-update.md

@@ -0,0 +1,6 @@
+
+# docs +whiteboard-update（更新飞书画板）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+本 shortcut 仅为兼容历史调用保留，具体使用方式请参考 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)

package/server/assets/skills/lark-tools/cli-skills/lark-drive/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: lark-drive
+version: 1.0.0
+description: "飞书云空间：管理云空间中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题（docx、sheet、bitable、file、folder、wiki）；也负责把本地 Word/Markdown/Excel/CSV 导入为飞书在线云文档（docx、sheet、bitable）。当用户需要上传或下载文件、整理云空间目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格/Base 时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli drive --help"
+---
+
+# drive (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+> **导入分流规则：** 如果用户要把本地 Excel / CSV 导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。
+
+## 快速决策
+
+- 用户要把本地 `.xlsx` / `.csv` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
+- 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
+- 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
+- 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
+- `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
+
+## 修改标题
+- 使用 `drive files patch` 命令，通过new_title字段可以修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型
+
+## 核心概念
+
+### 文档类型与 Token
+
+飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的 `file_token`。
+
+### 文档 URL 格式与 Token 处理
+
+| URL 格式 | 示例                                                      | Token 类型 | 处理方式 |
+|----------|---------------------------------------------------------|-----------|----------|
+| `/docx/` | `https://example.larksuite.com/docx/doxcnxxxxxxxxx`    | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
+| `/doc/` | `https://example.larksuite.com/doc/doccnxxxxxxxxx`     | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
+| `/wiki/` | `https://example.larksuite.com/wiki/wikcnxxxxxxxxx`    | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
+| `/sheets/` | `https://example.larksuite.com/sheets/shtcnxxxxxxxxx`  | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
+| `/drive/folder/` | `https://example.larksuite.com/drive/folder/fldcnxxxx` | `folder_token` | URL 路径中的 token 作为文件夹 token 使用 |
+
+### Wiki 链接特殊处理（关键！）
+
+知识库链接（`/wiki/TOKEN`）背后可能是云文档、电子表格、多维表格等不同类型的文档。**不能直接假设 URL 中的 token 就是 file_token**，必须先查询实际类型和真实 token。
+
+#### 处理流程
+
+1. **使用 `wiki.spaces.get_node` 查询节点信息**
+   ```bash
+   lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
+   ```
+
+2. **从返回结果中提取关键信息**
+   - `node.obj_type`：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）
+   - `node.obj_token`：**真实的文档 token**（用于后续操作）
+   - `node.title`：文档标题
+
+3. **根据 `obj_type` 使用对应的 API**
+
+   | obj_type | 说明 | 使用的 API |
+   |----------|------|-----------|
+   | `docx` | 新版云文档 | `drive file.comments.*`、`docx.*` |
+   | `doc` | 旧版云文档 | `drive file.comments.*` |
+   | `sheet` | 电子表格 | `sheets.*` |
+   | `bitable` | 多维表格 | `bitable.*` |
+   | `slides` | 幻灯片 | `drive.*` |
+   | `file` | 文件 | `drive.*` |
+   | `mindnote` | 思维导图 | `drive.*` |
+
+#### 查询示例
+
+```bash
+# 查询 wiki 节点
+lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
+```
+
+返回结果示例：
+```json
+{
+  "node": {
+    "obj_type": "docx",
+    "obj_token": "xxxx",
+    "title": "标题",
+    "node_type": "origin",
+    "space_id": "12345678910"
+  }
+}
+```
+
+### 资源关系
+
+```
+Wiki Space (知识空间)
+└── Wiki Node (知识库节点)
+    ├── obj_type: docx (新版文档)
+    │   └── obj_token (真实文档 token)
+    ├── obj_type: doc (旧版文档)
+    │   └── obj_token (真实文档 token)
+    ├── obj_type: sheet (电子表格)
+    │   └── obj_token (真实文档 token)
+    ├── obj_type: bitable (多维表格)
+    │   └── obj_token (真实文档 token)
+    └── obj_type: file/slides/mindnote
+        └── obj_token (真实文档 token)
+
+Drive Folder (云空间文件夹)
+└── File (文件/文档)
+    └── file_token (直接使用)
+```
+
+### 常见操作 Token 需求
+
+| 操作 | 需要的 Token | 说明 |
+|------|-------------|------|
+| 读取文档内容 | `file_token` / 通过 `docs +fetch` 自动处理 | `docs +fetch` 支持直接传入 URL |
+| 添加局部评论（划词评论） | `file_token` | 传 `--selection-with-ellipsis` 或 `--block-id` 时，`drive +add-comment` 会创建局部评论；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL |
+| 添加全文评论 | `file_token` | 不传 `--selection-with-ellipsis` / `--block-id` 时，`drive +add-comment` 默认创建全文评论；支持 `docx`、旧版 `doc` URL，以及最终解析为 `doc`/`docx` 的 wiki URL |
+| 下载文件 | `file_token` | 从文件 URL 中直接提取 |
+| 上传文件 | `folder_token` / `wiki_node_token` | 目标位置的 token |
+| 列出文档评论 | `file_token` | 同添加评论 |
+
+### 评论能力边界（关键！）
+
+- `drive +add-comment` 支持两种模式。
+- 全文评论：未传 `--selection-with-ellipsis` / `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL，以及最终解析为 `doc`/`docx` 的 wiki URL。
+- 局部评论：传 `--selection-with-ellipsis` 或 `--block-id` 时启用；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL。
+- `drive +add-comment` 的 `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。
+- 如果 wiki 解析后不是 `doc`/`docx`，不要用 `+add-comment`。
+- 如果需要更底层地直接调用评论 V2 协议，再走原生 API：先执行 `lark-cli schema drive.file.comments.create_v2`，再执行 `lark-cli drive file.comments create_v2 ...`。全文评论省略 `anchor`，局部评论传 `anchor.block_id`。
+
+### 评论查询与统计口径（关键！）
+
+- 查询文档评论时，使用 `drive file.comments list`。
+- `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` 降序排列，取第一条
+  - "最早评论"：按 `create_time` 升序排列，取第一条
+- 如果用户只说"第一条评论"，直接使用 `drive file.comments list` 返回的第一条即可，不需要额外排序。
+
+#### 评论回复限制
+- **添加评论回复前先检查是否存在以下限制**
+- **全文评论不支持回复**：`is_whole=true` 的评论（全文评论）无法添加回复，遇到此类评论应提示用户"全文评论不支持回复"。
+- **已解决评论不支持回复**：`is_solved=true` 的评论无法添加回复，遇到此类评论应提示用户"该评论已被解决，无法回复"。
+- **注意**：当用户要回复某条评论但该评论因上述限制不能回复时，只提示不能回复即可，**不要自动帮用户找其他可以回复的评论**，避免不符合用户预期。
+
+#### 批量查询与列表查询的选择
+- 使用 `drive file.comments batch_query` 是**已知评论 ID 后**的批量查询，需要传入具体的评论 ID 列表。
+- 使用 `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论，或获取"最新/最后 N 条评论"等场景。
+
+#### Reaction / 表情场景
+- 遇到评论 / 回复上的 reaction（表情、各表情数量、谁点了什么、添加/删除表情）相关问题时，**先阅读 [lark-drive-reactions.md](references/lark-drive-reactions.md) 了解如何使用**。
+
+### 典型错误与解决方案
+
+| 错误信息 | 原因 | 解决方案 |
+|----------|------|----------|
+| `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
+| `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
+| `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet） |
+
+### 授权当前应用访问文档
+
+当需要将文档权限授予**当前应用（bot）自身**时，先通过 bot info 接口获取应用的 open_id，再调用权限接口授权：
+
+```bash
+# 1. 获取当前应用的 open_id
+lark-cli api GET /open-apis/bot/v3/info --as bot
+# 从返回值中取 bot.open_id
+
+# 2. 授权当前应用访问文档
+lark-cli drive permission.members create \
+  --params '{"token":"<doc_token>","type":"<resource_type>"}' \
+  --data '{"member_type":"openid","member_id":"<bot_open_id>","perm":"view","type":"user"}'
+```
+
+> **注意**：此方式仅适用于需要授权给**当前应用**的场景。授权给其他用户时，直接使用对方的 open_id 即可，无需调用 bot info 接口。
+
+`<resource_type>` 可选值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`。
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+upload`](references/lark-drive-upload.md) | Upload a local file to Drive |
+| [`+create-folder`](references/lark-drive-create-folder.md) | Create a Drive folder, optionally under a parent folder, with bot auto-grant support |
+| [`+download`](references/lark-drive-download.md) | Download a file from Drive to local |
+| [`+create-shortcut`](references/lark-drive-create-shortcut.md) | Create a shortcut to an existing Drive file in another folder |
+| [`+add-comment`](references/lark-drive-add-comment.md) | Add a full-document comment, or a local comment to selected docx text (also supports wiki URL resolving to doc/docx) |
+| [`+export`](references/lark-drive-export.md) | Export a doc/docx/sheet/bitable to a local file with limited polling |
+| [`+export-download`](references/lark-drive-export-download.md) | Download an exported file by file_token |
+| [`+import`](references/lark-drive-import.md) | Import a local file to Drive as a cloud document (docx, sheet, bitable) |
+| [`+move`](references/lark-drive-move.md) | Move a file or folder to another location in Drive |
+| [`+delete`](references/lark-drive-delete.md) | Delete a Drive file or folder with limited polling for folder deletes |
+| [`+task_result`](references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations |
+
+## API Resources
+
+```bash
+lark-cli schema drive.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli drive <resource> <method> [flags] # 调用 API
+```
+
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+### files
+
+  - `copy` — 复制文件
+  - `create_folder` — 新建文件夹
+  - `list` — 获取文件夹下的清单
+  - `patch` — 修改文件标题
+
+### file.comments
+
+  - `batch_query` — 批量获取评论
+  - `create_v2` — 添加全文/局部（划词）评论
+  - `list` — 分页获取文档评论
+  - `patch` — 解决/恢复 评论
+
+### file.comment.replys
+
+  - `create` — 添加回复
+  - `delete` — 删除回复
+  - `list` — 获取回复
+  - `update` — 更新回复
+
+### permission.members
+
+  - `auth` — 
+  - `create` — 增加协作者权限
+  - `transfer_owner` — 
+
+### metas
+
+  - `batch_query` — 获取文档元数据
+
+### user
+
+  - `remove_subscription` — 取消订阅用户、应用维度事件
+  - `subscription` — 订阅用户、应用维度事件（本次开放评论添加事件）
+  - `subscription_status` — 查询用户、应用对指定事件的订阅状态
+
+### file.statistics
+
+  - `get` — 获取文件统计信息
+
+### file.view_records
+
+  - `list` — 获取文档的访问者记录
+
+### file.comment.reply.reactions
+
+  - `update_reaction` — 添加/删除 reaction
+
+## 权限表
+
+| 方法 | 所需 scope |
+|------|-----------|
+| `files.copy` | `docs:document:copy` |
+| `files.create_folder` | `space:folder:create` |
+| `files.list` | `space:document:retrieve` |
+| `files.patch` | `docx:document:write_only` |
+| `file.comments.batch_query` | `docs:document.comment:read` |
+| `file.comments.create_v2` | `docs:document.comment:create` |
+| `file.comments.list` | `docs:document.comment:read` |
+| `file.comments.patch` | `docs:document.comment:update` |
+| `file.comment.replys.create` | `docs:document.comment:create` |
+| `file.comment.replys.delete` | `docs:document.comment:delete` |
+| `file.comment.replys.list` | `docs:document.comment:read` |
+| `file.comment.replys.update` | `docs:document.comment:update` |
+| `permission.members.auth` | `docs:permission.member:auth` |
+| `permission.members.create` | `docs:permission.member:create` |
+| `permission.members.transfer_owner` | `docs:permission.member:transfer` |
+| `metas.batch_query` | `drive:drive.metadata:readonly` |
+| `user.remove_subscription` | `docs:event:subscribe` |
+| `user.subscription` | `docs:event:subscribe` |
+| `user.subscription_status` | `docs:event:subscribe` |
+| `file.statistics.get` | `drive:drive.metadata:readonly` |
+| `file.view_records.list` | `drive:file:view_record:readonly` |
+| `file.comment.reply.reactions.update_reaction` | `docs:document.comment:create` |

package/server/assets/skills/lark-tools/cli-skills/lark-drive/references/lark-drive-add-comment.md

@@ -0,0 +1,99 @@
+
+# drive +add-comment
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+给文档添加评论。底层统一走 `/open-apis/drive/v1/files/:file_token/new_comments`（`create_v2`）接口；未指定位置时省略 `anchor` 创建全文评论，指定 `--selection-with-ellipsis` 或 `--block-id` 时传入 `anchor.block_id` 创建局部评论。支持直接传 docx URL/token、旧版 doc URL（仅全文评论），也支持传最终可解析为 doc/docx 的 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":"这里需要一段全文评论"}]'
+
+# 给 docx 文档里匹配到的文字添加局部评论
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
+  --selection-with-ellipsis "流程" \
+  --content '[{"type":"text","text":"请补充流程说明"}]'
+
+# wiki 链接也支持局部评论，但解析结果必须是 docx
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
+  --selection-with-ellipsis "流程" \
+  --content '[{"type":"text","text":"请补充更细的开发步骤"}]'
+
+# 组合文本、@用户、链接元素
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
+  --selection-with-ellipsis "流程" \
+  --content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 处理，参考 "},{"type":"link","text":"https://example.com"}]'
+
+# 已知 block_id 时可跳过 MCP 直接创建局部评论
+lark-cli drive +add-comment \
+  --doc "<DOCX_TOKEN>" \
+  --block-id "<BLOCK_ID>" \
+  --content '[{"type":"text","text":"评论内容"}]'
+
+# 如果需要更底层的原生 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":"全文评论内容"}]}'
+
+# 预览底层调用链
+lark-cli drive +add-comment \
+  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
+  --selection-with-ellipsis "流程" \
+  --content '[{"type":"text","text":"请补充流程说明"}]' \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc` | 是 | 文档 URL / token，或可解析到 `doc`/`docx` 的 wiki URL。原始 token 默认按 `docx` 处理；旧版 `doc` 请传 URL 或 wiki 链接 |
+| `--content` | 是 | `reply_elements` JSON 数组字符串。示例：`'[{"type":"text","text":"文本"},{"type":"mention_user","text":"ou_xxx"},{"type":"link","text":"https://example.com"}]'` |
+| `--full-comment` | 否 | 显式指定创建全文评论；未传 `--selection-with-ellipsis` / `--block-id` 时也会默认走全文评论 |
+| `--selection-with-ellipsis` | 局部评论时二选一 | 目标文本定位表达式，支持纯文本或 `开头...结尾`；与 `--block-id` 互斥 |
+| `--block-id` | 局部评论时二选一 | 已知目标块 ID 时直接使用；与 `--selection-with-ellipsis` 互斥 |
+
+## 行为说明
+
+- **无需预先获取文档内容**：使用 `--selection-with-ellipsis` 时，shortcut 内部会自动调用 `locate-doc` 定位目标文本，不需要先调用 `docs +fetch` 获取文档。
+- 未传 `--selection-with-ellipsis` / `--block-id` 时，shortcut 默认创建**全文评论**；也可以显式传 `--full-comment`。
+- 全文评论支持 `docx`、旧版 `doc` URL，以及最终可解析为 `doc`/`docx` 的 wiki URL。
+- 传 `--selection-with-ellipsis` 或 `--block-id` 时，shortcut 创建**局部评论（划词评论）**；该模式仅支持 `docx`，以及最终可解析为 `docx` 的 wiki URL。
+- `--content` 接收结构化评论元素数组；`type` 支持 `text`、`mention_user`、`link`。为便于书写，`mention_user` / `link` 元素可以直接把用户 ID 或链接地址放在 `text` 字段中，shortcut 会转换成 OpenAPI 所需字段。
+- 局部评论走 `locate-doc` 时，内部固定使用 `limit=10`。
+- 当 `locate-doc` 命中多处时，shortcut 会中止并提示用户继续收窄 `--selection-with-ellipsis`，不支持手动指定匹配序号。
+- 写入评论前会自动生成符合 OpenAPI 定义的请求体：
+- 统一接口：`POST /new_comments`
+- 统一字段：`file_type` + `reply_elements`
+- 全文评论：省略 `anchor`
+- 局部评论：传入 `anchor.block_id`
+- `--dry-run` 仅预览调用链和请求体，不会实际写入。
+- 如果需要更底层的控制，仍可改用 `lark-cli schema drive.file.comments.create_v2` + `lark-cli drive file.comments create_v2`。
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数