lark-drive

软件研发 Agent 与技能管理 61 文件 中英

飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移

飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本、飞书文档密级标签（secure labels）和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。

说明语言：中英混合

来源larksuitecli ↗　查看原文件 ↗版权归原作者，请遵循原仓库许可
安装
npx skills add https://github.com/larksuite/cli --skill lark-drive

需要已安装 skills CLI。也可以直接从源仓库 clone。

在星云中查看 ↗
SKILL.md 原文

name: lark-drive version: 1.0.0 description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本、飞书文档密级标签（secure labels）和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。" metadata: requires: bins: ["lark-cli"] cliHelp: "lark-cli drive --help" ---

drive (v1)

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理

术语说明： 飞书云空间也常被称为"云盘"、"云存储"、"网盘"或"我的空间"，这些说法通常指的是同一个产品，是飞书官方的云端文件存储与管理中心。
导入分流规则： 如果用户要把本地 Excel / CSV / .base 快照导入成 Base / 多维表格 / bitable，必须优先使用 lark-cli drive +import --type bitable。不要先切到 lark-base；lark-base 只负责导入完成后的表内操作。
副本分流规则： 如果用户要复制在线文档、创建文档副本、把文档复制到另一个文件夹，必须使用 lark-cli drive +copy。不要用 drive +export 下载后再 drive +import 上传，也不要用 docs +fetch + docs +create 重建正文；导出/导入只用于本地文件转换或离线产物。

快速决策

修改标题

核心概念

文档类型与 Token

飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的 file_token。

文档 URL 格式与 Token 处理

URL 格式示例Token 类型处理方式
/docx/https://example.larksuite.com/docx/doxcnxxxxxxxxxfile_tokenURL 路径中的 token 直接作为 file_token 使用
/doc/https://example.larksuite.com/doc/doccnxxxxxxxxxfile_tokenURL 路径中的 token 直接作为 file_token 使用
/wiki/https://example.larksuite.com/wiki/wikcnxxxxxxxxxwiki_token不能直接当底层 file_token；优先用 drive +inspect 解包获取 obj_token
/sheets/https://example.larksuite.com/sheets/shtcnxxxxxxxxxfile_tokenURL 路径中的 token 直接作为 file_token 使用
/page/https://example.feishu.cn/page/pagcnxxxxxxxx/apps tokenURL 路径中的 token 直接使用，资源类型为 apps
/drive/folder/https://example.larksuite.com/drive/folder/fldcnxxxxfolder_tokenURL 路径中的 token 作为文件夹 token 使用

Wiki 链接特殊处理

lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'

知识库链接背后可能是 docx、sheet、bitable、slides、file 等不同对象。后续要做评论、下载、导出或内容读取时，优先用 drive +inspect 拿到 type、token、title、url；完整手动解析和跨 skill 路由见共享文档 lark-wiki-token-routing.md。不要只根据 /wiki/<token> 猜底层类型。

常见操作 Token 需求

操作需要的 Token说明
读取文档内容file_token / 通过 docs +fetch 自动处理docs +fetch 支持直接传入 URL
下载文件file_token从文件 URL 中直接提取
上传文件folder_token / wiki_node_token目标位置的 token

典型错误与解决方案

错误信息原因解决方案
not exist使用了错误的 token检查 token 类型，wiki 链接必须先查询获取 obj_token
permission denied没有相关操作权限引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限
invalid file_typefile_type 参数错误根据 obj_type 传入正确的 file_type（docx/doc/sheet/slides/bitable/apps）
232140101 / 232140100 / 233523001（常见于 drive +import 的 job_error_msg）同一位置下存在并发导入 / 创建操作批量导入到同一文件夹、根目录或同一 --target-token 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突

权限能力入口

不在本 skill 范围

Shortcuts（推荐优先使用）

Shortcut 是对常用操作的高级封装（lark-cli drive +<verb> [flags]）。有 Shortcut 的操作优先使用。

Shortcut说明
+search搜索文档、Wiki、表格、文件夹等云空间对象；支持 --edited-since、--created-by-me、--mine、--doc-types 等扁平 flag；区分 original creator 与 owner 语义。
+upload上传本地文件到 Drive 文件夹或 wiki 节点；修改/重写/更新已有文件时优先覆盖上传，而不是直接上传一个新文件。
+create-folder新建 Drive 文件夹，支持父文件夹与 bot 创建后自动授权。
+download下载 Drive 文件到本地。
+preview查看或下载文件内容，或者查看文件可用预览格式并获取 PDF / HTML / 文本 / 图片等转换预览产物。
+cover查看或下载文件封面图规格。
+status比较本地目录与 Drive 文件夹差异；默认按 SHA-256 精确比较，--quick 使用修改时间近似比较。
+pull从 Drive 拉取文件到本地目录，支持重复远端路径处理和增量模式。
+sync双向同步本地目录与 Drive 文件夹：拉取 new_remote、推送 new_local，modified 按 `--on-conflict=remote-wins\local-wins\keep-both\ask 处理；--quick 用修改时间近似比较；--on-duplicate-remote 支持 fail / newest / oldest；只同步 type=file`，跳过在线文档和 shortcut，且不会删除两端多余文件。
+push将本地目录推送到 Drive 文件夹，支持 skip / smart / overwrite 与确认后删除远端。
+create-shortcut在另一个文件夹里创建现有 Drive 文件的快捷方式。
+copy复制资源到目标文件夹；如果要复制到知识库，使用 wiki +node-copy；
+add-comment给 doc/docx/file/sheet/slides/base(bitable) 添加全文/局部评论；不支持妙搭 apps。
+list-comments分页获取评论列表。
+batch-query-comments按评论 ID 批量获取评论。
+resolve-comment把评论标记为已解决（is_solved=true）。
+restore-comment恢复/重新打开已解决评论（is_solved=false）。
+add-reply给已有评论添加回复。
+list-replies分页获取某条评论下的回复。
+update-reply整体替换某条回复的内容。
+delete-reply删除评论下的某条回复（高风险，需 --yes）。
+react-reply给回复加/删表情回应。
+export将 doc/docx/sheet/bitable/slides 导出为本地文件。
+export-download根据导出产物的 file_token 下载文件。
+import将本地文件导入为飞书在线文档、表格、多维表格或幻灯片。
+version-history查看文件历史版本。
+version-get下载指定历史版本。
+version-revert回滚到指定历史版本。
+version-delete删除指定历史版本。
+move移动 Drive 文件或文件夹；Wiki 层级移动走 lark-wiki。
+update-title重命名文件、文件夹、在线文档或知识库。
+delete删除 Drive 文件或文件夹，文件夹删除会轮询异步任务。
+task_result查询 import/export/move/delete 等异步任务结果。
+inspect检视 URL 的类型、标题和 canonical token；wiki URL 会自动解包到底层文档。
+apply-permission以 user 身份向文档 owner 申请访问权限。
+member-add添加一个或最多 10 个 Drive 文档、文件、文件夹或 wiki 节点协作者/授权成员；封装 Drive permission member create/batch_create，真实写入需要 --yes。
+member-list查询 Drive 文档、文件、文件夹或 wiki 节点的协作者/授权成员列表。
+member-remove移除一个 Drive 文档、文件、文件夹或 wiki 节点协作者；封装 Drive permission member delete，真实写入需要 --yes。
+permission-get-setting查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置；支持 URL 或裸 token + --type；不递归读取文件夹子文档权限。
+secure-label-list列出当前用户可用的密级标签。
+secure-label-update更新 Drive 文件或文档的密级标签。

API Resources

lark-cli schema drive.<resource>.<method>   # 调用 API 前必须先查看参数结构
lark-cli drive <resource> <method> [flags] # 调用 API
重要：使用原生 API 时，必须先运行 schema 查看 --data / --params 参数结构，不要猜测字段格式。 高频原生命令： 读取 Drive 文件夹清单时使用 drive files list，使用前先读 references/lark-drive-files-list.md，按模板通过 --params 传参并手动处理分页；不要把 --page-all 输出直接交给 JSON 解析脚本。

files

permission.members

metas

user

file.statistics

file.view_records

file.comment.reply.reactions

quota_details

同类技能
agent-browseragentcoreask-mattbrowser-actbrowser-act-skill-forgebrowser-usechief-of-staffclaude-handoff
本页内容来自开源项目 larksuite， 版权归原作者所有。
本站仅作技能索引与分享，所有 Skill 版权归其原作者所有。