> ## Documentation Index > Fetch the complete documentation index at: https://docs.newenergycoder.club/llms.txt > Use this file to discover all available pages before exploring further. # lark-drive > 飞书云空间：管理云空间中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题（docx、sheet、bitable、file、folder、wiki）；也负责把本地 Word/Markdown/Excel/… | 项目 | 内容 | | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 来源 | [skills/lark-drive/SKILL.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/SKILL.md) | | 分类 | 飞书/Lark 办公套件 | | 安装 | 克隆 [Skill 分支](https://github.com/new-energy-coder-club/new_energy_coder_club/tree/Skill) 后，将 `skills/lark-drive/` 目录复制到 `~/.claude/skills/`（Claude Code）、`~/.trae/skills/`（Trae IDE）或 `~/.qclaw/skills/`（QClaw/OpenClaw），详见 [Skill 安装方式](/community/skill-branch) | # drive (v1) **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-shared/SKILL.md)，其中包含认证、权限处理** > **导入分流规则：** 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。 ## 快速决策 * 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"、"最近一周我打开过的 xxx"、"某人创建的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。老的 `docs +search` 进入维护期、后续会下线，不要新增对它的依赖。 * 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。 * 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。 * 用户要在 Drive 里上传、创建、读取、覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-markdown/SKILL.md)。 * 用户要把本地 `.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。 #### 处理流程 1. **使用 `wiki.spaces.get_node` 查询节点信息** ```bash theme={null} 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 theme={null} # 查询 wiki 节点 lark-cli wiki spaces get_node --params '{"token":"wiki_token"}' ``` 返回结果示例： ```json theme={null} { "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` 支持直接传入 URL | | 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；`docx` 支持文本定位或 block\_id，`slides` 仅支持 block\_id，且都支持最终解析到对应类型的 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":"正文"}]'`。 * `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`/`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 theme={null} # 默认查询：仅未解决评论（推荐） 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 theme={null} # 不推荐：用户未明确要求但查询所有评论 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](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/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） | ### 授权当前应用访问文档 当需要将文档权限授予**当前应用（bot）自身**时，先通过 bot info 接口获取应用的 open\_id，再调用权限接口授权： ```bash theme={null} # 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`。 ## Shortcuts（推荐优先使用） Shortcut 是对常用操作的高级封装（`lark-cli drive + [flags]`）。有 Shortcut 的操作优先使用。 | Shortcut | 说明 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`+search`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-search.md) | Search Lark docs, Wiki, and spreadsheet files with flat filter flags (preferred over `docs +search`). Natural-language-friendly: `--edited-since`, `--mine`, `--doc-types`, etc. | | [`+upload`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-upload.md) | Upload a local file to a Drive folder or wiki node | | [`+create-folder`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-create-folder.md) | Create a Drive folder, optionally under a parent folder, with bot auto-grant support | | [`+download`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-download.md) | Download a file from Drive to local | | [`+status`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-status.md) | Compare a local directory with a Drive folder by SHA-256 content hash; reports `new_local` / `new_remote` / `modified` / `unchanged` (read-only diff primitive for sync workflows). 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`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-pull.md) | One-way **file-level** mirror of a Drive folder onto a local directory (Drive → local). Duplicate remote `rel_path` conflicts fail by default before writing; for duplicate files only, `--on-duplicate-remote rename` downloads all copies with stable hashed suffixes, while `newest` / `oldest` explicitly choose one. Supports `--if-exists` (overwrite/skip) and `--delete-local` for orphan cleanup; the destructive `--delete-local` requires `--yes` and only unlinks regular files — empty local directories left behind by remote folder deletes are NOT pruned. Item-level failures exit non-zero (`error.type=partial_failure`) and skip the `--delete-local` pass to avoid half-synced state. `--local-dir` is bounded to cwd by CLI path validation; tell the user to switch the agent's working directory if the target is outside cwd. | | [`+create-shortcut`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-create-shortcut.md) | Create a shortcut to an existing Drive file in another folder | | [`+add-comment`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-add-comment.md) | Add a comment to doc/docx/sheet/slides, also supports wiki URL resolving to doc/docx/sheet/slides | | [`+export`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-export.md) | Export a doc/docx/sheet/bitable to a local file with limited polling; supports `--file-name` for local naming | | [`+export-download`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-export-download.md) | Download an exported file by file\_token | | [`+import`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-import.md) | Import a local file to Drive as a cloud document (docx, sheet, bitable) | | [`+move`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-move.md) | Move a file or folder to another location in Drive | | [`+delete`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-delete.md) | Delete a Drive file or folder with limited polling for folder deletes | | [`+push`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-push.md) | Mirror a local directory onto a Drive folder (local → Drive). Duplicate remote `rel_path` conflicts fail by default before upload / overwrite / delete; use `--on-duplicate-remote newest\|oldest` only when the conflict is duplicate files and you explicitly want to target one existing remote file. Supports `--if-exists` (overwrite/skip) and `--delete-remote` for one-way mirror sync; the destructive `--delete-remote` requires `--yes`. `--local-dir` is bounded to cwd by CLI path validation; tell the user to switch the agent's working directory if the source is outside cwd. | | [`+task_result`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations | | [`+apply-permission`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-drive/references/lark-drive-apply-permission.md) | Apply to the document owner for view/edit access (user-only; 5/day per document) | ## API Resources ```bash theme={null} lark-cli schema drive.. # 调用 API 前必须先查看参数结构 lark-cli drive [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` |