diff --git a/skill-template/domains/drive.md b/skill-template/domains/drive.md index 83d7ca008..6b3f2f60e 100644 --- a/skill-template/domains/drive.md +++ b/skill-template/domains/drive.md @@ -1,211 +1,67 @@ -> **导入分流规则：** 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。 +> **术语说明：** 飞书云空间也常被称为"云盘"或"云存储"，三者指的是同一个产品，是飞书官方的云端文件存储与管理中心。 + +## 关键规则速览 + +- Wiki 链接里的 `/wiki/` 不是底层文件 token；优先用 `drive +inspect` 解包，完整规则见 [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md)。 +- 本地文件导入为在线文档统一走 `drive +import`：目标是 Base / 多维表格时用 `--type bitable`（`.xlsx` / `.csv` / `.base`，`.xls` 不支持）；目标是电子表格时用 `--type sheet`（`.xlsx` / `.xls` / `.csv`）；Office / Markdown / HTML / TXT -> `--type docx`，PPTX -> `--type slides`。 +- 原生 `.md` 文件内容读写、patch、diff 走 [`lark-markdown`](../lark-markdown/SKILL.md)；把 Markdown 转成在线 docx 才走 `drive +import --type docx`。 +- 评论默认只查未解决评论；review / 审阅场景优先局部评论。评论细节见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。 +- 权限申请、安全标签、搜索等用户个人资源场景优先 `--as user`；bot 只能处理自己可见或已授权的资源。 ## 快速决策 -- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。 +- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（`--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag。 +- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`；`.xls` 不能直接导入为 bitable，需先转 `.xlsx` 或改导入为 sheet。 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。 +- 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。 +- 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。 +- 用户要比较原生 `.md` 文件的历史版本差异，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。 +- 用户要查看、下载、回滚或删除文件的历史版本，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；自动化场景优先 `--as bot`。 - 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。 -- `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。 +- 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下，仍然使用 `lark-cli drive +upload --wiki-token `；不要误切到 `wiki` 域命令。 +- 用户要修改标题，可用 `drive files patch` 传 `new_title`，支持 docx、sheet、bitable、file、wiki、folder 类型。 -## 修改标题 -- 使用 `drive files patch` 命令，通过new_title字段可以修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型 +## 身份路由 + +| 场景 | 身份建议 | +|------|----------| +| 搜索用户可见资源、申请权限、查看/更新安全标签 | 使用 `--as user`；这些 shortcut 是 user-only 或强依赖用户可见范围 | +| 用户个人云空间、用户拥有的文档/文件夹 | 默认 `--as user` | +| bot 自己创建的资源、已授权给 bot 的资源、自动化版本操作 | 可用 `--as bot`；版本命令自动化场景优先 bot | +| bot 因资源不可见失败 | 不要反复重试；提示用户切 `--as user`，或先把资源授权给当前应用 | ## 核心概念 -### 文档类型与 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。 - -#### 处理流程 - -**推荐方式：使用 `drive +inspect` 自动解包** - -```bash -lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX' -``` - -返回结果包含 `type`（底层文档类型）、`token`（真实 file_token）、`title`、`url` 等字段，直接用于后续操作。 - -**手动方式：使用 `wiki.spaces.get_node` 查询节点信息** - -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 --api-version v2` 自动处理 | `docs +fetch --api-version v2` 支持直接传入 URL | -| 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；仅支持 `docx`，以及最终解析为 `docx` 的 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 | -| 列出文档评论 | `file_token` | 同添加评论 | - -### 评论能力边界（关键！） - -- `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` 获取。 -- `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` 默认必须传 `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", "is_solved": false}' - -# 包含已解决评论（需用户明确要求） -lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}' -``` - -**错误示例：** - -```bash -# 不推荐：用户未明确要求但查询所有评论 -lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}' -``` - -- 查询文档评论时，使用 `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](../../skills/lark-drive/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 +- 直接文档 URL（如 `/docx/`、`/doc/`、`/sheets/`、`/drive/folder/`）通常可从路径直接取得对应 token。 +- Wiki URL（`/wiki/`）必须先解析到底层 `obj_type` 和 `obj_token`，再决定后续调用哪个域。 +- `drive +inspect` 是跨类型 URL 检视的首选入口；当它输出 `type` 和 `token` 后，后续命令使用该 canonical token。 +- 原生 API 调用前先运行 `lark-cli schema drive..` 查看 `--params` / `--data` 结构；不要猜字段。 + +## 原生 API 快速索引 + +- 评论订阅事件：`drive user.subscription`、`drive user.subscription_status`、`drive user.remove_subscription`。 +- 公开权限设置：`drive permission.public get|patch`；错误码和处理建议见 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。 +- 协作者权限：`drive permission.members create|auth|transfer_owner`；授权当前应用访问文档见权限 guide，转移 owner 必须单独确认。 +- 元数据、统计、访问记录：`drive metas batch_query`、`drive file.statistics get`、`drive file.view_records list`。 +- 评论列表、解决状态、回复：`drive file.comments list|batch_query|patch`、`drive file.comment.replys *`；统计口径见评论 guide。 + +## 评论与权限 + +- 添加评论优先使用 [`drive +add-comment`](references/lark-drive-add-comment.md)；查询、统计、回复限制和 reaction 规则见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md) 与 [`lark-drive-reactions.md`](references/lark-drive-reactions.md)。 +- 权限申请优先使用 [`drive +apply-permission`](references/lark-drive-apply-permission.md)；公开权限错误码、授权当前应用访问文档等规则见 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。 + +## 不在本 skill 范围 -# 2. 授权当前应用访问文档 -lark-cli drive permission.members create \ - --params '{"token":"","type":""}' \ - --data '{"member_type":"openid","member_id":"","perm":"view","type":"user"}' -``` +- 文档正文读取、改写、追加、替换、图片/附件插入：切到 [`lark-doc`](../lark-doc/SKILL.md)。 +- 电子表格单元格、工作表、筛选、公式等表内操作：切到 [`lark-sheets`](../lark-sheets/SKILL.md)。 +- Base 表、字段、记录、视图、表单、仪表盘、工作流等表内操作：切到 [`lark-base`](../lark-base/SKILL.md)。 +- 知识空间、Wiki 节点、空间成员管理：切到 [`lark-wiki`](../lark-wiki/SKILL.md)。 +- Drive 原生 Markdown 文件的创建、读取、patch、overwrite、diff：切到 [`lark-markdown`](../lark-markdown/SKILL.md)。 -> **注意**：此方式仅适用于需要授权给**当前应用**的场景。授权给其他用户时，直接使用对方的 open_id 即可，无需调用 bot info 接口。 +## 参考 -`` 可选值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`。 +- [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md) — Wiki token / obj_token / obj_type 路由规则 +- [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md) — 评论查询、统计、回复和 review 落点规则 +- [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md) — 权限错误码和应用授权规则 diff --git a/skill-template/skill-template.md b/skill-template/skill-template.md index e119f852d..41689c755 100644 --- a/skill-template/skill-template.md +++ b/skill-template/skill-template.md @@ -31,11 +31,7 @@ lark-cli {{service}} [flags] # 调用 API ``` > **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。 +> 所需 scope 以 `lark-cli schema {{service}}..` 输出为准；skill 主文不展开完整权限表。 {{resource_sections}} -## 权限表 - -| 方法 | 所需 scope | -|------|-----------| -{{permission_rows}} {{/actions}} diff --git a/skills/lark-drive/SKILL.md b/skills/lark-drive/SKILL.md index 678749fac..3957ce50d 100644 --- a/skills/lark-drive/SKILL.md +++ b/skills/lark-drive/SKILL.md @@ -1,7 +1,7 @@ --- name: lark-drive version: 1.0.0 -description: "飞书云空间（云盘/云存储）：管理云空间（云盘/云存储）中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题（docx、sheet、bitable、file、folder、wiki）；也负责把本地 Word/Markdown/Excel/CSV/PPTX 以及 Base 快照（.base）导入为飞书在线云文档（docx、sheet、bitable、slides）。当用户需要上传或下载文件、整理云空间（云盘/云存储）目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格/Base/幻灯片 时使用。\"云空间\"、\"云盘\"和\"云存储\"是同一概念，用户说\"云盘\"、\"云存储\"、\"网盘\"、\"我的空间\"时均路由到本 skill。当用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是资源类型、URL 路径模式和 token，而不是域名。" +description: "飞书云空间（云盘/云存储）：管理文件、文件夹、评论和权限，并将本地 Word/Markdown/Excel/CSV/PPTX/Base 快照导入为飞书在线文档、表格、多维表格或幻灯片。当用户需要上传/下载文件、搜索或整理云空间对象、查看元数据、修改标题、管理评论/权限/评论订阅，或处理 doubao.com 云空间资源 URL/token 时使用。不负责：文档正文编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 内容读写（走 lark-markdown）。" metadata: requires: bins: ["lark-cli"] @@ -14,361 +14,98 @@ metadata: > **术语说明：** 飞书云空间也常被称为"云盘"或"云存储"，三者指的是同一个产品，是飞书官方的云端文件存储与管理中心。 -> **导入分流规则：** 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。 +## 关键规则速览 + +- Wiki 链接里的 `/wiki/` 不是底层文件 token；优先用 `drive +inspect` 解包，完整规则见 [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md)。 +- 本地文件导入为在线文档统一走 `drive +import`：目标是 Base / 多维表格时用 `--type bitable`（`.xlsx` / `.csv` / `.base`，`.xls` 不支持）；目标是电子表格时用 `--type sheet`（`.xlsx` / `.xls` / `.csv`）；Office / Markdown / HTML / TXT -> `--type docx`，PPTX -> `--type slides`。 +- 原生 `.md` 文件内容读写、patch、diff 走 [`lark-markdown`](../lark-markdown/SKILL.md)；把 Markdown 转成在线 docx 才走 `drive +import --type docx`。 +- 评论默认只查未解决评论；review / 审阅场景优先局部评论。评论细节见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。 +- 权限申请、安全标签、搜索等用户个人资源场景优先 `--as user`；bot 只能处理自己可见或已授权的资源。 ## 快速决策 -- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--mine`，实为 owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。 -- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。 +- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（`--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag。 +- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`；`.xls` 不能直接导入为 bitable，需先转 `.xlsx` 或改导入为 sheet。 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。 +- 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。 - 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。 - 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。 -- 用户要比较原生 `.md` 文件的**历史版本差异**，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。 -- 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。 -- 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。 -- 用户要在云空间（云盘/云存储）里新建文件夹，优先使用 `lark-cli drive +create-folder`。 -- 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 `lark-cli drive +upload --wiki-token `；不要误切到 `wiki` 域命令。 -- `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。 - -#### 处理流程 - -**推荐方式：使用 `drive +inspect` 自动解包** - -```bash -lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX' -``` - -返回结果包含 `type`（底层文档类型）、`token`（真实 file_token）、`title`、`url` 等字段，直接用于后续操作。 - -**手动方式：使用 `wiki.spaces.get_node` 查询节点信息** - -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 --api-version v2` 自动处理 | `docs +fetch --api-version v2` 支持直接传入 URL | -| 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；`docx` 支持文本定位或 block_id，`sheet` 使用 `!`，`slides` 使用 `!`，且都支持最终解析到对应类型的 wiki URL；Drive file 不支持局部评论 | -| 添加全文评论 | `file_token` | 不传 `--block-id` 时，`drive +add-comment` 默认创建全文评论；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc`/`docx`/`file` 的 wiki URL | -| 下载文件 | `file_token` | 从文件 URL 中直接提取 | -| 上传文件 | `folder_token` / `wiki_node_token` | 目标位置的 token | -| 列出文档评论 | `file_token` | 同添加评论 | - -### 评论能力边界（关键！） - -- `drive +add-comment` 支持两种模式。 -- 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc`/`docx`/`file` 的 wiki URL。 -- 局部评论：传 `--block-id` 时启用；`docx` 支持文本定位或 block id，`sheet` 支持 `!`，`slides` 支持 `!`，wiki URL 解析到这些类型时也支持对应局部评论。Drive file 本次只支持全文评论，不支持局部评论。 -- Drive file 评论仅支持白名单扩展名：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件暂不支持，CLI 会直接报错提示当前还不支持这种类型的评论。 -- 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`。 - -- 评论写入内容（添加评论、回复评论、编辑回复）里的文本不能直接出现 `<`、`>`；提交前必须先转义：`<` -> `<`，`>` -> `>`。 -- 使用 `drive +add-comment` 时，shortcut 会对 `type=text` 的文本元素自动做上述转义兜底；如果直接调用 `drive file.comments create_v2`、`drive file.comment.replys create`、`drive file.comment.replys update`，则需要在请求里自行传入已转义的内容。 -- 如果 wiki 解析后不是 `doc`/`docx`/`file`/`sheet`/`slides`，不要用 `+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` 默认必须传 `is_solved:false`，即仅查询未解决评论。即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确提到要包含已解决评论，仍然按默认口径查询未解决评论。仅当用户明确要求包含已解决评论时，才可省略 `is_solved` 参数。 - -**正确示例：** - -```bash -# 默认查询：仅未解决评论（推荐） -lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}' +- 用户要比较原生 `.md` 文件的历史版本差异，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。 +- 用户要查看、下载、回滚或删除文件的历史版本，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；自动化场景优先 `--as bot`。 +- 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。 +- 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下，仍然使用 `lark-cli drive +upload --wiki-token `；不要误切到 `wiki` 域命令。 +- 用户要修改标题，可用 `drive files patch` 传 `new_title`，支持 docx、sheet、bitable、file、wiki、folder 类型。 -# 查询所有评论（用户未明确要求包含已解决评论） -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"}' -``` - -**错误示例：** - -```bash -# 不推荐：用户未明确要求但查询所有评论 -lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}' -``` - -- 查询文档评论时，使用 `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` 拉全后，再做全量回复数 / 总互动数统计。 - -### 评论业务特性与引导（关键！） - -#### Review 场景评论落点 -- 默认策略是“能局部就局部”：用户说 review、审阅、检查文档、标注问题、给修改建议、逐条评论时，优先创建局部评论。 -- 多个独立问题应分别创建多条局部评论；不要为了省调用次数把 review 发现的问题合并到全文评论。 -- 只有在目标类型支持全文评论，且出现以下任一情况时，才退回全文评论：用户明确要求全文/总体评论、评论内容确实是文档级总结、目标类型不支持局部评论，或无法稳定定位到具体位置；否则应说明限制并请求用户提供可定位位置。 -- 具体参数、定位方式和不同文档类型的约束见 [`drive +add-comment` 行为说明](references/lark-drive-add-comment.md#行为说明)。 - -#### 评论排序引导 -- 一个文档通常有多个评论，评论按 `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](../../skills/lark-drive/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/slides） | - -#### `permission.public.patch` 错误码引导 - -调用 `lark-cli drive permission.public patch` 更新文档公开权限失败时，如果返回以下错误码，按表格给用户明确下一步。不要把这些错误简单归类为缺少 scope；它们通常表示租户、对外分享或文档密级策略拦截。 - -| 错误码 | 含义 | 给用户的引导 | -|--------|------------------------|--------------| -| `91009` | 对外分享被租户安全策略管控，当前用户无法开启 | 提示用户：对外分享能力被租户安全策略统一管控，无法通过 API 或当前用户直接开启；需要联系租户管理员调整组织级对外分享策略。 | -| `91010` | 文档对外分享未打开 | 提示用户：当前文档尚未打开对外分享，请先在文档权限设置中打开对外分享，再重试 `permission.public.patch`。 | -| `91011` | 对外分享被文档密级管控 | 提示用户：对外分享被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 | -| `91012` | 权限设置被文档密级管控 | 提示用户：该权限设置被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 | - -当用户最初提供的是文档 URL，遇到 `91011` 或 `91012` 时直接把该 URL 原样返回给用户作为操作入口；如果上下文只有 token，需要先尽量通过已有上下文、搜索结果或元数据恢复目标文档 URL，再给出可点击的文档 URL。 - -### 授权当前应用访问文档 - -当需要将文档权限授予**当前应用（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":"","type":""}' \ - --data '{"member_type":"openid","member_id":"","perm":"view","type":"user"}' -``` - -> **注意**：此方式仅适用于需要授权给**当前应用**的场景。授权给其他用户时，直接使用对方的 open_id 即可，无需调用 bot info 接口。 - -`` 可选值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`、`slides`。 +| 场景 | 身份建议 | +|------|----------| +| 搜索用户可见资源、申请权限、查看/更新安全标签 | 使用 `--as user`；这些 shortcut 是 user-only 或强依赖用户可见范围 | +| 用户个人云空间、用户拥有的文档/文件夹 | 默认 `--as user` | +| bot 自己创建的资源、已授权给 bot 的资源、自动化版本操作 | 可用 `--as bot`；版本命令自动化场景优先 bot | +| bot 因资源不可见失败 | 不要反复重试；提示用户切 `--as user`，或先把资源授权给当前应用 | ## Shortcuts（推荐优先使用） Shortcut 是对常用操作的高级封装（`lark-cli drive + [flags]`）。有 Shortcut 的操作优先使用。 -| Shortcut | 说明 | -|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [`+search`](references/lark-drive-search.md) | Search Lark docs, Wiki, and spreadsheet files with flat filter flags. Natural-language-friendly: `--edited-since`, `--mine`, `--doc-types`, etc. | -| [`+upload`](references/lark-drive-upload.md) | Upload a local file to a Drive folder or wiki node | -| [`+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 | -| [`+status`](references/lark-drive-status.md) | Compare a local directory with a Drive folder by exact SHA-256 hash by default, or use `--quick` for a best-effort modified-time diff that skips remote downloads; reports `new_local` / `new_remote` / `modified` / `unchanged` plus `detection=exact` or `detection=quick`. Duplicate remote `rel_path` conflicts fail fast with `error.type=duplicate_remote_path` and list every conflicting entry; do not proceed as if one was chosen. `--local-dir` 必须是 cwd 内的相对路径，越界路径 CLI 会直接拒绝；目标在 cwd 外时引导用户切换 agent 工作目录，不要私自 `cd` 绕过。 | -| [`+pull`](references/lark-drive-pull.md) | File-level Drive → local mirror. Duplicate remote `rel_path` conflicts fail by default; for duplicate files, `rename` downloads all copies with stable hashed suffixes, while `newest` / `oldest` pick one. `--if-exists` supports `overwrite` / `smart` / `skip` (`smart` is a best-effort modified-time incremental mode for repeat syncs). `--delete-local` requires `--yes`, only removes regular files, and is skipped after item failures. `--local-dir` must stay inside cwd. | -| `+sync` | Two-way local ↔ Drive sync. Reuses `+status` diff buckets, pulls `new_remote`, pushes `new_local`, and resolves `modified` via `--on-conflict=remote-wins|local-wins|keep-both|ask`. `--quick` enables best-effort modified-time diffing (timestamp mismatches can still trigger real pull/push actions), `--on-duplicate-remote` supports `fail|newest|oldest`, and the command is intentionally non-destructive (no delete on either side). | -| [`+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 comment to doc/docx/file/sheet/slides, also supports wiki URL resolving to doc/docx/file/sheet/slides; file targets support selected extensions and full comments only | -| [`+export`](references/lark-drive-export.md) | Export a doc/docx/sheet/bitable/slides to a local file with limited polling; supports `--file-name` for local naming | -| [`+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, slides) | -| [`+version-history`](references/lark-drive-version-history.md) | List historical versions of a file with only_tag=true and cursor-based pagination | -| [`+version-get`](references/lark-drive-version-get.md) | Download a specific historical version of a file | -| [`+version-revert`](references/lark-drive-version-revert.md) | Revert a file to a specific historical version | -| [`+version-delete`](references/lark-drive-version-delete.md) | Delete a specific historical version of a file | -| [`+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 | -| [`+push`](references/lark-drive-push.md) | File-level local → Drive mirror. Duplicate remote `rel_path` conflicts fail by default; `newest` / `oldest` only apply to duplicate files when you explicitly want to target one remote file. `--if-exists` supports `skip` / `smart` / `overwrite` (`smart` skips files whose remote `modified_time` is already up to date, but falls through to the same overwrite path when the remote is older, so it inherits overwrite's rollout caveat). `--delete-remote` requires `--yes`. `--local-dir` must stay inside cwd. | -| [`+task_result`](references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations | -| [`+inspect`](references/lark-drive-inspect.md) | Inspect a Lark document URL to get its type, title, and canonical token; auto-unwraps wiki URLs to the underlying document | -| [`+apply-permission`](references/lark-drive-apply-permission.md) | Apply to the document owner for view/edit access (user-only; 5/day per document) | -| [`+secure-label-list`](references/lark-drive-secure-label.md) | List secure labels available to the current user | -| [`+secure-label-update`](references/lark-drive-secure-label.md) | Update a Drive file/document secure label; downgrade approval errors require opening the document UI | - -## API Resources - -```bash -lark-cli schema drive.. # 调用 API 前必须先查看参数结构 -lark-cli drive [flags] # 调用 API -``` - -> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。 - -### files - - - `copy` — 复制文件 - - `create_folder` — 新建文件夹 - - `list` — 获取文件夹下的清单 - - `patch` — 修改文件标题 - -### file.comments +| Shortcut | 说明 | +|----------|------| +| [`+search`](references/lark-drive-search.md) | 搜索飞书文档、Wiki、表格和云空间对象，支持 `--edited-since`、`--mine`、`--doc-types` 等扁平筛选 | +| [`+upload`](references/lark-drive-upload.md) | 上传本地文件到 Drive 文件夹或 wiki 节点 | +| [`+create-folder`](references/lark-drive-create-folder.md) | 在 Drive 中创建文件夹，支持 bot 创建后自动授权当前用户 | +| [`+download`](references/lark-drive-download.md) | 下载 Drive 文件到本地 | +| [`+status`](references/lark-drive-status.md) | 比较本地目录与 Drive 文件夹，默认精确 SHA-256，也支持 `--quick` 快速模式 | +| [`+pull`](references/lark-drive-pull.md) | 单向同步 Drive 文件夹到本地目录 | +| `+sync` | 双向同步本地目录与 Drive 文件夹；默认非破坏性，不删除任一侧文件 | +| [`+push`](references/lark-drive-push.md) | 单向同步本地目录到 Drive 文件夹；删除远端需显式 `--delete-remote --yes` | +| [`+create-shortcut`](references/lark-drive-create-shortcut.md) | 在其他文件夹中创建指向已有 Drive 文件的快捷方式 | +| [`+add-comment`](references/lark-drive-add-comment.md) | 给 doc/docx/file/sheet/slides 添加全文或局部评论，支持可解析到这些类型的 wiki URL | +| [`+export`](references/lark-drive-export.md) | 导出 doc/docx/sheet/bitable/slides 到本地文件 | +| [`+export-download`](references/lark-drive-export-download.md) | 根据导出任务返回的 file_token 下载导出文件 | +| [`+import`](references/lark-drive-import.md) | 将本地文件导入为在线 docx、sheet、bitable 或 slides | +| [`+version-history`](references/lark-drive-version-history.md) | 查看文件历史版本列表 | +| [`+version-get`](references/lark-drive-version-get.md) | 下载指定历史版本 | +| [`+version-revert`](references/lark-drive-version-revert.md) | 回滚到指定历史版本 | +| [`+version-delete`](references/lark-drive-version-delete.md) | 删除指定历史版本 | +| [`+move`](references/lark-drive-move.md) | 移动 Drive 文件或文件夹 | +| [`+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 | +| [`+apply-permission`](references/lark-drive-apply-permission.md) | 向文档 owner 申请 view/edit 权限，仅支持 user 身份 | +| [`+secure-label-list`](references/lark-drive-secure-label.md) | 列出当前用户可用的密级标签 | +| [`+secure-label-update`](references/lark-drive-secure-label.md) | 更新 Drive 文件或文档密级标签；降级审批类错误需打开文档 UI 处理 | - - `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` — 查询用户、应用对指定事件的订阅状态 +- 直接文档 URL（如 `/docx/`、`/doc/`、`/sheets/`、`/drive/folder/`）通常可从路径直接取得对应 token。 +- Wiki URL（`/wiki/`）必须先解析到底层 `obj_type` 和 `obj_token`，再决定后续调用哪个域。 +- `drive +inspect` 是跨类型 URL 检视的首选入口；当它输出 `type` 和 `token` 后，后续命令使用该 canonical token。 +- 原生 API 调用前先运行 `lark-cli schema drive..` 查看 `--params` / `--data` 结构；不要猜字段。 -### file.statistics +## 原生 API 快速索引 - - `get` — 获取文件统计信息 +- 评论订阅事件：`drive user.subscription`、`drive user.subscription_status`、`drive user.remove_subscription`。 +- 公开权限设置：`drive permission.public get|patch`；错误码和处理建议见 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。 +- 协作者权限：`drive permission.members create|auth|transfer_owner`；授权当前应用访问文档见权限 guide，转移 owner 必须单独确认。 +- 元数据、统计、访问记录：`drive metas batch_query`、`drive file.statistics get`、`drive file.view_records list`。 +- 评论列表、解决状态、回复：`drive file.comments list|batch_query|patch`、`drive file.comment.replys *`；统计口径见评论 guide。 -### file.view_records +## 评论与权限 - - `list` — 获取文档的访问者记录 +- 添加评论优先使用 [`drive +add-comment`](references/lark-drive-add-comment.md)；查询、统计、回复限制和 reaction 规则见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md) 与 [`lark-drive-reactions.md`](references/lark-drive-reactions.md)。 +- 权限申请优先使用 [`drive +apply-permission`](references/lark-drive-apply-permission.md)；公开权限错误码、授权当前应用访问文档等规则见 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。 -### file.comment.reply.reactions +## 不在本 skill 范围 - - `update_reaction` — 添加/删除 reaction +- 文档正文读取、改写、追加、替换、图片/附件插入：切到 [`lark-doc`](../lark-doc/SKILL.md)。 +- 电子表格单元格、工作表、筛选、公式等表内操作：切到 [`lark-sheets`](../lark-sheets/SKILL.md)。 +- Base 表、字段、记录、视图、表单、仪表盘、工作流等表内操作：切到 [`lark-base`](../lark-base/SKILL.md)。 +- 知识空间、Wiki 节点、空间成员管理：切到 [`lark-wiki`](../lark-wiki/SKILL.md)。 +- Drive 原生 Markdown 文件的创建、读取、patch、overwrite、diff：切到 [`lark-markdown`](../lark-markdown/SKILL.md)。 -## 权限表 +## 参考 -| 方法 | 所需 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` | -| `permission.public.get` | `docs:permission.setting:read` | -| `permission.public.patch` | `docs:permission.setting:write_only` | -| `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` | +- [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md) — Wiki token / obj_token / obj_type 路由规则 +- [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md) — 评论查询、统计、回复和 review 落点规则 +- [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md) — 权限错误码和应用授权规则 diff --git a/skills/lark-drive/references/lark-drive-comments-guide.md b/skills/lark-drive/references/lark-drive-comments-guide.md new file mode 100644 index 000000000..eafe16fd3 --- /dev/null +++ b/skills/lark-drive/references/lark-drive-comments-guide.md @@ -0,0 +1,66 @@ +# drive comments guide + +> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 入口、身份路由和 Wiki token 解包规则；再阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证与全局参数。 + +## 创建评论 + +- 添加评论优先使用 `drive +add-comment`。 +- 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL、白名单扩展名普通文件，以及最终解析为这些类型的 Wiki URL。 +- 局部评论：传 `--block-id` 时启用；支持 `docx`、`sheet`、`slides`，以及最终解析为这些类型的 Wiki URL。docx block ID 可通过 `docs +fetch --api-version v2 --detail with-ids` 获取；sheet 使用 `!`；slides 使用 `!`。 +- 如果 Wiki URL 解包后不是 `doc` / `docx` / `file` / `sheet` / `slides`，不要使用 `+add-comment`。 +- Drive 普通文件评论仅支持平台允许的文件类型，常见后缀包括 `.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`；普通文件只支持全文评论。 +- `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。 +- 如果直接调用原生评论 V2 API，先执行 `lark-cli schema drive.file.comments.create_v2` 并优先参考 [`lark-drive-add-comment.md`](lark-drive-add-comment.md)。全文评论省略 `anchor`；doc/docx 局部评论传 `anchor.block_id`；sheet 评论使用 `anchor.block_id` + `sheet_col` + `sheet_row`；slides 评论使用 `anchor.block_id` + `slide_block_type`。 + +## Review 场景 + +- 代码、文案、方案 review 场景优先创建局部评论。 +- 不同问题尽量拆成多条局部评论，便于逐条解决和追踪。 +- Drive 普通文件不支持局部锚点，只能创建全文评论。 + +## 内容与转义 + +- 评论内容使用 `reply_elements` 表达，不要把纯 Markdown 当作结构化评论正文。 +- `drive +add-comment` 会处理常见文本转义；直接调原生 API 时需要自行转义 `<` 和 `>`，避免被平台当作标签片段。 +- 需要在评论中表达代码或 JSON 时，优先作为普通文本元素传入，不要猜测不在 schema 里的富文本字段。 + +## 查询与统计 + +- `drive file.comments list` 默认必须传 `is_solved:false`，即仅查询未解决评论。 +- 即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确要求包含已解决评论，仍按未解决评论查询。 +- 只有用户明确要求包含已解决评论时，才省略 `is_solved`。 + +```bash +# 默认查询：仅未解决评论 +lark-cli drive file.comments list --params '{"file_token":"","file_type":"docx","is_solved":false}' + +# 用户明确要求包含已解决评论时 +lark-cli drive file.comments list --params '{"file_token":"","file_type":"docx"}' +``` + +- `items` 是评论卡片列表，不是平铺的互动消息列表。 +- 创建第一条评论时会同时创建该卡片里的第一条 reply；真正承载正文的是 `item.reply_list.replies`。 +- 统计“评论数”或“评论卡片数”：统计 `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` 的评论无法添加回复。 +- 用户要回复某条评论但该评论不能回复时，只提示限制原因；不要自动替用户寻找其他可回复评论。 + +## 批量查询与 reaction + +- `drive file.comments batch_query` 只用于已知评论 ID 后的批量查询，需要传入具体 comment ID 列表。 +- 遍历、统计、获取最新/最早评论等场景使用 `drive file.comments list`。 +- reaction（表情、点赞、谁点了什么、添加/删除表情）场景先阅读 [`lark-drive-reactions.md`](lark-drive-reactions.md)。 diff --git a/skills/lark-drive/references/lark-drive-permission-guide.md b/skills/lark-drive/references/lark-drive-permission-guide.md new file mode 100644 index 000000000..64aa3fcb2 --- /dev/null +++ b/skills/lark-drive/references/lark-drive-permission-guide.md @@ -0,0 +1,49 @@ +# drive permission guide + +> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 入口、身份路由和 Wiki token 解包规则；再阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证与全局参数。 + +## 权限申请 + +- 向文档 owner 申请 view / edit 权限时，优先使用 `drive +apply-permission`。 +- `drive +apply-permission` 仅支持 user 身份；不要用 bot 反复重试用户个人资源。 +- 如果用户只给 token，先尽量用 `drive +inspect` 或上下文恢复 URL / 类型，再申请权限。 + +## 公开权限错误码 + +调用 `drive.permission.public.patch` 修改公开权限时，常见业务错误码按下表处理： + +| 错误码 | 处理建议 | +|--------|----------| +| `91009` | 当前文件已设置更高安全等级或受组织策略限制，无法开放到目标范围；提示用户在文档 UI 或安全设置中处理 | +| `91010` | 文件 owner 或管理员设置不允许修改公开权限；需要 owner / 管理员调整策略 | +| `91011` | 当前身份没有修改公开权限的权限；切换到有权限的 user，或让 owner 授权 | +| `91012` | 目标公开范围不符合当前租户策略；不要继续扩大权限，提示用户按组织策略处理 | + +如果错误信息与上表不一致，以接口返回的 `msg` / `error` 为准，并给出下一步可执行动作。 + +## 授权当前应用访问文档 + +当需要把文档权限授予**当前应用（bot）自身**时，先获取当前 bot 的 `open_id`，再授权给该 `open_id`： + +```bash +# 1. 获取当前应用的 open_id +lark-cli api GET /open-apis/bot/v3/info --as bot + +# 2. 授权当前应用访问文档 +lark-cli drive permission.members create \ + --params '{"token":"","type":""}' \ + --data '{"member_type":"openid","member_id":"","perm":"view","type":"user"}' +``` + +说明： + +- 此方式只适用于授权给当前应用自身。 +- 授权给其他用户时，直接使用对方的 `open_id`，不要调用 bot info。 +- 不要转移 owner，除非用户明确要求且已说明影响。 +- `` 常见值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`、`slides`。 + +## 身份判断 + +- 用户个人云空间、用户拥有的文档、公开权限申请、密级标签等场景优先 `--as user`。 +- bot 创建或已授权给 bot 的资源可使用 `--as bot`。 +- bot 因资源不可见失败时，说明资源可见性问题；建议切换 user 身份或先给 bot 授权，不要盲目重试。 diff --git a/skills/lark-drive/references/lark-drive-reactions.md b/skills/lark-drive/references/lark-drive-reactions.md index fd2d4cde6..457fefbe7 100644 --- a/skills/lark-drive/references/lark-drive-reactions.md +++ b/skills/lark-drive/references/lark-drive-reactions.md @@ -1,6 +1,6 @@ # drive reactions -> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 评论卡片模型、评论数/回复数统计口径、`file_token` / `file_type` 规则；再阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 +> **前置条件：** 先阅读 [`../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) 了解认证、全局参数和安全规则。 处理文档评论 / 回复上的 reaction（点赞、表情、各表情数量、谁点了什么、添加/删除表情）。这个场景不常见，但规则比较集中：查询时只有在用户明确需要 reaction 信息时才带 `need_reaction=true`；写入时统一使用 `drive file.comment.reply.reactions update_reaction`，操作对象始终是 `reply_id`。 diff --git a/skills/lark-markdown/SKILL.md b/skills/lark-markdown/SKILL.md index 881d1e4fe..5b53cc028 100644 --- a/skills/lark-markdown/SKILL.md +++ b/skills/lark-markdown/SKILL.md @@ -1,7 +1,7 @@ --- name: lark-markdown version: 1.2.0 -description: "飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。" +description: "飞书 Markdown：查看、创建、上传、编辑和比较 Drive 原生 Markdown 文件。当用户需要创建或编辑 `.md` 文件、读取、修改、局部 patch 或比较差异时使用。不负责：把 Markdown 导入成飞书在线文档 docx（走 lark-drive 的 drive +import --type docx）、文件搜索/权限/评论/移动/删除等云空间管理操作（走 lark-drive）。" metadata: requires: bins: ["lark-cli"] @@ -23,6 +23,13 @@ metadata: - 用户要把本地 Markdown **导入成在线新版文档（docx）**，不要用本 skill，改用 [`lark-drive`](../lark-drive/SKILL.md) 的 `lark-cli drive +import --type docx` - 用户要对 Markdown 文件做**rename / move / delete / 搜索 / 权限 / 评论**等云空间（云盘/云存储）操作，不要留在本 skill，切到 [`lark-drive`](../lark-drive/SKILL.md) +## 身份策略 + +- 所有 markdown shortcut 同时支持 `--as user` 和 `--as bot` +- 访问用户个人云空间或用户拥有的文件时，优先使用 `--as user` +- CI / 自动化场景、bot 自己创建或已被授权访问的 Markdown 文件，可使用 `--as bot` +- 如果 bot 因看不到用户资源而失败，不要反复重试；提示用户改用 `--as user` 或先给 bot 授权 + ## 核心边界 - 本 skill 处理的是 **Drive 中作为普通文件存储的 Markdown**，不是 docx 文档 @@ -34,7 +41,7 @@ metadata: - `markdown +patch` 的内部语义是：**先完整下载 Markdown，再本地替换，再整文件覆盖上传** - `markdown +patch` 不是服务端原子 patch；它是 CLI 侧编排出来的局部更新能力 - `markdown +patch` 当前只支持**单组** `--pattern` / `--content` -- `markdown +patch` 替换后的最终内容**不能为空**；如果替换后整篇 Markdown 变成空字符串，CLI 会直接报错，不会上传空文件 +- `markdown +patch` 替换后的最终内容**不能为空**；Drive 不支持 0 字节 Markdown，且空结果通常代表误清空，CLI 会直接报错，不会上传空文件 - `--file` 只接受本地 `.md` 文件路径 ## Shortcuts（推荐优先使用） @@ -43,11 +50,11 @@ Shortcut 是对常用操作的高级封装（`lark-cli markdown + [flags]` | Shortcut | 说明 | |----------|------| -| [`+create`](references/lark-markdown-create.md) | Create a Markdown file in Drive | -| [`+diff`](references/lark-markdown-diff.md) | Compare two remote Markdown versions, or compare remote Markdown against a local file | -| [`+fetch`](references/lark-markdown-fetch.md) | Fetch a Markdown file from Drive | -| [`+patch`](references/lark-markdown-patch.md) | Patch a Markdown file in Drive via fetch-local-replace-overwrite | -| [`+overwrite`](references/lark-markdown-overwrite.md) | Overwrite an existing Markdown file in Drive | +| [`+create`](references/lark-markdown-create.md) | 在 Drive 中创建原生 Markdown 文件 | +| [`+diff`](references/lark-markdown-diff.md) | 比较两个远端 Markdown 历史版本，或比较远端 Markdown 与本地文件 | +| [`+fetch`](references/lark-markdown-fetch.md) | 读取 Drive 中的原生 Markdown 文件 | +| [`+patch`](references/lark-markdown-patch.md) | 通过下载、替换、覆盖上传的方式局部更新 Markdown 文件 | +| [`+overwrite`](references/lark-markdown-overwrite.md) | 覆盖更新 Drive 中已有的 Markdown 文件 | ## 参考 diff --git a/skills/lark-markdown/references/lark-markdown-patch.md b/skills/lark-markdown/references/lark-markdown-patch.md index 5a618cc5d..1d522a243 100644 --- a/skills/lark-markdown/references/lark-markdown-patch.md +++ b/skills/lark-markdown/references/lark-markdown-patch.md @@ -63,9 +63,42 @@ lark-cli markdown +patch \ - `--content` 必须显式传入，但允许为空字符串 - 未加 `--regex` 时，行为等价于对整份 Markdown 文本执行 `strings.ReplaceAll` - 加了 `--regex` 时，行为等价于对整份 Markdown 文本执行 RE2 全量替换；`--content` 里的 `$1`、`${name}` 会按 Go regexp replacement template 解释，字面 `$` 请写成 `$$` -- 替换后的最终 Markdown 不能为空；如果 patch 结果是空字符串，CLI 会直接报错，不会上传空文件 +- 替换后的最终 Markdown 不能为空；Drive 不支持 0 字节 Markdown，且空结果通常代表误清空，CLI 会直接报错，不会上传空文件 - `0` 命中时命令仍然成功返回，但不会上传新版本 +## GOOD / BAD：正则转义 + +`--pattern` 默认是字面量，不需要正则转义。只有传 `--regex` 时，`--pattern` 才按 Go RE2 正则解释。 + +```bash +# GOOD：默认字面量模式，括号和点号按普通文本匹配 +lark-cli markdown +patch \ + --file-token boxcnxxxx \ + --pattern 'TODO(v1.2)' \ + --content 'DONE(v1.2)' + +# BAD：开启 --regex 后，未转义的 . 会匹配任意字符，括号会变成分组 +lark-cli markdown +patch \ + --file-token boxcnxxxx \ + --regex \ + --pattern 'TODO(v1.2)' \ + --content 'DONE' + +# GOOD：开启 --regex 后，按 RE2 规则转义字面括号和点号 +lark-cli markdown +patch \ + --file-token boxcnxxxx \ + --regex \ + --pattern 'TODO\\(v1\\.2\\)' \ + --content 'DONE' + +# GOOD：replacement 里需要字面 $ 时写成 $$ +lark-cli markdown +patch \ + --file-token boxcnxxxx \ + --regex \ + --pattern 'price: (\\d+)' \ + --content 'price: $$1' +``` + ## 实现边界 - 该命令的内部语义是：**download -> local replace -> overwrite upload** diff --git a/skills/lark-shared/references/lark-wiki-token-routing.md b/skills/lark-shared/references/lark-wiki-token-routing.md new file mode 100644 index 000000000..7a66c6161 --- /dev/null +++ b/skills/lark-shared/references/lark-wiki-token-routing.md @@ -0,0 +1,48 @@ +# Wiki token routing + +> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解认证、全局参数、身份选择和错误处理。 + +Wiki 链接里的 `/wiki/` 是知识库节点 token，不是底层文档、表格、Base、幻灯片或文件 token。处理 Wiki URL 时先解包，再按底层对象类型路由到对应 skill 或 API。 + +## 推荐入口 + +优先使用 `drive +inspect` 自动识别 URL 类型并解包 Wiki 节点： + +```bash +lark-cli drive +inspect --url 'https://example.feishu.cn/wiki/' +``` + +返回里的 `type`、`token`、`title`、`url` 是后续操作的 canonical 信息。后续命令使用返回的 canonical token，不要继续把 Wiki 节点 token 当作文件 token 传入。 + +## 手动解包 + +当 shortcut 不满足需求时，用 Wiki 节点接口查询底层对象： + +```bash +lark-cli wiki spaces get_node --params '{"token":""}' +``` + +从返回结果中读取： + +- `node.obj_type`：底层对象类型 +- `node.obj_token`：底层对象 token +- `node.space_id`：知识空间 ID +- `node.title`：节点标题 + +## 路由表 + +| `obj_type` | 后续处理 | +|------------|----------| +| `docx` / `doc` | 文档正文读取和编辑走 `lark-doc`；评论、权限、导出、文件元数据走 `lark-drive` | +| `sheet` | 单元格、工作表、导出等表格操作走 `lark-sheets`；评论、权限、文件元数据走 `lark-drive` | +| `bitable` | 表、字段、记录、视图、表单、仪表盘、工作流走 `lark-base`；评论、权限、文件元数据走 `lark-drive` | +| `slides` | 幻灯片内容编辑走 `lark-slides`；导出、评论、权限、文件元数据走 `lark-drive` | +| `file` | 普通文件上传、下载、移动、删除、权限、评论走 `lark-drive` | +| `mindnote` | 按当前 CLI 支持能力优先走 `lark-drive`；缺口再评估原生 OpenAPI | + +## 规则 + +- 不要把 Wiki 节点 token 直接当作 `doc_token`、`file_token`、`spreadsheet_token`、`app_token` 或 `presentation_token`。 +- Wiki 节点、空间目录、成员管理等知识库结构操作保留 Wiki 节点 token，走 `lark-wiki`。 +- 内容、评论、权限、导出等底层对象操作使用解包后的 `obj_token`。 +- 如果用户只给 Wiki URL，先解析类型；不要凭标题、路径或上下文猜底层对象类型。