From 8a254d32095e5aed6fe0ad5820b9a4dd7e7535f9 Mon Sep 17 00:00:00 2001 From: wangweiming Date: Wed, 20 May 2026 11:38:53 +0800 Subject: [PATCH 1/2] docs: prefer local comments for drive reviews Change-Id: Ie2eaa54320cd2612b66b2d617750d23b950e38db --- skills/lark-drive/SKILL.md | 9 ++++++++- skills/lark-drive/references/lark-drive-add-comment.md | 1 + 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/skills/lark-drive/SKILL.md b/skills/lark-drive/SKILL.md index 1599bd7e08..1db025ffa8 100644 --- a/skills/lark-drive/SKILL.md +++ b/skills/lark-drive/SKILL.md @@ -139,7 +139,8 @@ Drive Folder (云空间文件夹) - `drive +add-comment` 支持两种模式。 - 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL，以及最终解析为 `doc`/`docx` 的 wiki URL。 -- 局部评论：传 `--block-id` 时启用；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL。block ID 可通过 `docs +fetch --api-version v2 --detail with-ids` 获取。 +- 局部评论：传 `--block-id` 时启用；不同文档类型的支持范围与参数格式见 [`drive +add-comment` 行为说明](references/lark-drive-add-comment.md#行为说明)。 +- Review / 审阅 / 校对 / 逐条指出问题场景优先使用局部评论，不要把多个可定位问题汇总成一条全文评论；具体参数和定位方式见 [`drive +add-comment` 行为说明](references/lark-drive-add-comment.md#行为说明)。 - `drive +add-comment` 的 `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。 - `slides` 评论要求显式传 `--block-id !`；CLI 会将其拆分后写入 `anchor.block_id` 和 `anchor.slide_block_type`。其中 `` 是 PPT XML 协议中的元素 `id`；不支持 `--selection-with-ellipsis` 和 `--full-comment`。 @@ -182,6 +183,12 @@ lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": " ### 评论业务特性与引导（关键！） +#### Review 场景评论落点 +- 默认策略是“能局部就局部”：用户说 review、审阅、检查文档、标注问题、给修改建议、逐条评论时，优先创建局部评论。 +- 多个独立问题应分别创建多条局部评论；不要为了省调用次数把 review 发现的问题合并到全文评论。 +- 只有在用户明确要求全文/总体评论、评论内容确实是文档级总结、目标类型不支持局部评论，或无法稳定定位到具体位置时，才退回全文评论。 +- 具体参数、定位方式和不同文档类型的约束见 [`drive +add-comment` 行为说明](references/lark-drive-add-comment.md#行为说明)。 + #### 评论排序引导 - 一个文档通常有多个评论，评论按 `create_time`（创建时间）排序。 - **重要**：只有当用户明确提到"最新评论"、"最后评论"、"最早评论"时，才需要根据 `create_time` 进行排序： diff --git a/skills/lark-drive/references/lark-drive-add-comment.md b/skills/lark-drive/references/lark-drive-add-comment.md index 183b537f50..97436fc14c 100644 --- a/skills/lark-drive/references/lark-drive-add-comment.md +++ b/skills/lark-drive/references/lark-drive-add-comment.md @@ -137,6 +137,7 @@ lark-cli drive +add-comment \ ## 行为说明 - **局部评论需要先获取 block ID**：先调用 `docs +fetch --api-version v2 --doc --detail with-ids` 获取带有 block ID 的文档内容，然后使用 `--block-id` 指定目标块。 +- **Review 场景优先局部评论**：审阅、校对、逐条指出问题时，必须先尝试定位到具体 block / 单元格 / slide 元素，并逐问题创建局部评论；不要把所有问题合并成一条全文评论。 - 未传 `--block-id` 时，shortcut 默认创建**全文评论**；也可以显式传 `--full-comment`。全文评论支持 `docx`、旧版 `doc` URL，以及最终可解析为 `doc`/`docx` 的 wiki URL。 - 传 `--block-id` 时，shortcut 创建**局部评论（划词评论）**；该模式支持 `docx`、`slides`，以及最终可解析为这些类型的 wiki URL。 - **Sheet 评论**：当 `--doc` 为 sheet URL 或 wiki 解析为 sheet 时，使用 `--block-id "!"` 指定单元格（如 `a281f9!D6`）；sheet 没有全文评论，`--full-comment` 不可用。 From 89bc5abedee9e93421863e67252bceb75353f984 Mon Sep 17 00:00:00 2001 From: wangweiming Date: Wed, 20 May 2026 14:18:55 +0800 Subject: [PATCH 2/2] docs: align drive comment fallback guidance Change-Id: Ia7512babe3656b57374c86068198c8192871ff81 --- skills/lark-drive/SKILL.md | 4 ++-- skills/lark-drive/references/lark-drive-add-comment.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/lark-drive/SKILL.md b/skills/lark-drive/SKILL.md index 1db025ffa8..15c4301891 100644 --- a/skills/lark-drive/SKILL.md +++ b/skills/lark-drive/SKILL.md @@ -129,7 +129,7 @@ Drive Folder (云空间文件夹) | 操作 | 需要的 Token | 说明 | |------|-------------|------| | 读取文档内容 | `file_token` / 通过 `docs +fetch --api-version v2` 自动处理 | `docs +fetch --api-version v2` 支持直接传入 URL | -| 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；`docx` 支持文本定位或 block_id，`slides` 仅支持 block_id，且都支持最终解析到对应类型的 wiki URL | +| 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；`docx` 支持文本定位或 block_id，`sheet` 使用 `!`，`slides` 使用 `!`，且都支持最终解析到对应类型的 wiki URL | | 添加全文评论 | `file_token` | 不传 `--block-id` 时，`drive +add-comment` 默认创建全文评论；支持 `docx`、旧版 `doc` URL，以及最终解析为 `doc`/`docx` 的 wiki URL | | 下载文件 | `file_token` | 从文件 URL 中直接提取 | | 上传文件 | `folder_token` / `wiki_node_token` | 目标位置的 token | @@ -186,7 +186,7 @@ lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": " #### Review 场景评论落点 - 默认策略是“能局部就局部”：用户说 review、审阅、检查文档、标注问题、给修改建议、逐条评论时，优先创建局部评论。 - 多个独立问题应分别创建多条局部评论；不要为了省调用次数把 review 发现的问题合并到全文评论。 -- 只有在用户明确要求全文/总体评论、评论内容确实是文档级总结、目标类型不支持局部评论，或无法稳定定位到具体位置时，才退回全文评论。 +- 只有在目标类型支持全文评论，且出现以下任一情况时，才退回全文评论：用户明确要求全文/总体评论、评论内容确实是文档级总结、目标类型不支持局部评论，或无法稳定定位到具体位置；否则应说明限制并请求用户提供可定位位置。 - 具体参数、定位方式和不同文档类型的约束见 [`drive +add-comment` 行为说明](references/lark-drive-add-comment.md#行为说明)。 #### 评论排序引导 diff --git a/skills/lark-drive/references/lark-drive-add-comment.md b/skills/lark-drive/references/lark-drive-add-comment.md index 97436fc14c..41ac999756 100644 --- a/skills/lark-drive/references/lark-drive-add-comment.md +++ b/skills/lark-drive/references/lark-drive-add-comment.md @@ -139,7 +139,7 @@ lark-cli drive +add-comment \ - **局部评论需要先获取 block ID**：先调用 `docs +fetch --api-version v2 --doc --detail with-ids` 获取带有 block ID 的文档内容，然后使用 `--block-id` 指定目标块。 - **Review 场景优先局部评论**：审阅、校对、逐条指出问题时，必须先尝试定位到具体 block / 单元格 / slide 元素，并逐问题创建局部评论；不要把所有问题合并成一条全文评论。 - 未传 `--block-id` 时，shortcut 默认创建**全文评论**；也可以显式传 `--full-comment`。全文评论支持 `docx`、旧版 `doc` URL，以及最终可解析为 `doc`/`docx` 的 wiki URL。 -- 传 `--block-id` 时，shortcut 创建**局部评论（划词评论）**；该模式支持 `docx`、`slides`，以及最终可解析为这些类型的 wiki URL。 +- 传 `--block-id` 时，shortcut 创建**局部评论（划词评论）**；该模式支持 `docx`、`sheet`、`slides`，以及最终可解析为这些类型的 wiki URL。 - **Sheet 评论**：当 `--doc` 为 sheet URL 或 wiki 解析为 sheet 时，使用 `--block-id "!"` 指定单元格（如 `a281f9!D6`）；sheet 没有全文评论，`--full-comment` 不可用。 - **Slide 评论**：当 `--doc` 为 slides URL、`--type slides`，或 wiki 解析为 slides 时，必须传 `--block-id "!"`。CLI 会将其拆分映射到 `anchor.block_id` / `anchor.slide_block_type`。此时 `--full-comment` 和 `--selection-with-ellipsis` 不可用。 - **Slide 参数映射示例**：`--block-id` 由 PPT XML 元素类型和元素 `id` 组成。例如：