lark-drive

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 重建正文；导出/导入只用于本地文件转换或离线产物。

快速决策

• 用户要把已有 Wiki 节点移出知识库，放到 Drive 文件夹或“我的空间”根目录：切到 lark-wiki，使用 lark-cli wiki +move-to-drive；不要把 Wiki token 直接交给 drive +move。这是会改变文档归属和权限继承的写操作，执行前确认源节点与目标位置。
• 用户要复制文档 / 创建副本 到云盘或者文件夹时：已提供可直接使用的 URL 或 token，按 references/lark-drive-copy.md 使用 lark-cli drive +copy；仅提供标题时，先按 references/lark-drive-search.md 使用 drive +search 唯一定位源资源，再按 copy reference 复制。如果是要复制文档 / 创建副本到知识库，使用 wiki +node-copy（见 lark-wiki-node-copy.md）。
• 用户要识别飞书 / doubao 云空间 URL 的类型和 token时，可以先按 URL 路径形态做轻量判断；当路径已明确指向 docx / sheet / bitable / slides / file / folder 等资源时，可直接提取对应 token/type。传入 wiki URL、需要识别标题或 canonical URL、URL/token 有歧义，或后续操作依赖底层真实资源时，再使用 lark-cli drive +inspect --url '<url>' 进行识别；具体用法、失败处理和边界见 references/lark-drive-inspect.md。
• 高风险写操作（删除、公开权限修改、owner 转移、版本删除/回滚、批量移动/覆盖/同步）必须同时满足三个条件才执行：目标已解析为该操作可直接使用的执行对象，执行细节已明确到可直接调用命令（例如删除的 file-token/type、公开权限修改的共享范围、owner 转移的目标 owner、版本删除/回滚的 version id、移动/覆盖/同步的目标位置和冲突策略），且用户在本轮明确确认执行这些具体目标和执行细节。用户只说“删除没用的文件”“开放/共享给大家”“改成开放”“覆盖/移动这些”只表示目标状态；先只读发现并列出候选、权限档位或执行方案，停止等待用户确认。
• 用户要检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移，或要”权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 references/lark-drive-workflow.md，再按其中 Workflow Registry 进入 permission_governance workflow。
• 用户明确要移除单个云文档协作者权限时，使用 lark-cli drive +member-remove；先阅读 references/lark-drive-member-remove.md。这是高风险写操作，真实执行必须确认准确的资源、成员 ID/type 和 wiki 权限范围，并显式传 --yes。
• 用户要为指定飞书文档设置 / 修改密级标签（secure label），或查询当前用户可用的密级标签，直接读取 ；这是 Drive 文件治理能力。

修改标题

• 用户要重命名 / 改标题 / 改文件名，使用 lark-cli drive +update-title，用法见 references/lark-drive-update-title.md。

核心概念

文档类型与 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	不能直接当底层 file_token；优先用 drive +inspect 解包获取 obj_token
/sheets/	https://example.larksuite.com/sheets/shtcnxxxxxxxxx	file_token	URL 路径中的 token 直接作为 file_token 使用
/page/	https://example.feishu.cn/page/pagcnxxxxxxxx/	apps token	URL 路径中的 token 直接使用，资源类型为 apps
/drive/folder/	https://example.larksuite.com/drive/folder/fldcnxxxx	folder_token	URL 路径中的 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_type	file_type 参数错误	根据 obj_type 传入正确的 file_type（docx/doc/sheet/slides/bitable/apps）
232140101 / 232140100 / 233523001（常见于 drive +import 的 job_error_msg）	同一位置下存在并发导入 / 创建操作	批量导入到同一文件夹、根目录或同一 --target-token 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突

权限能力入口

• 用户要管理 Drive 文档/文件协作者、公开权限、授权当前应用访问文档，或处理 permission.public.patch 的 91009 / 91010 / 91011 / 91012 错误时，先读 lark-drive-permission-guide.md。
• 用户要查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置，使用 +permission-get-setting；如果要递归审计文件夹下子文档权限，再进入 permission_governance workflow。
• 用户只是没有访问权限并希望向 owner 申请访问，优先使用 +apply-permission。
• 普通 scope、身份或登录问题仍按 lark-shared 处理；不要把租户安全策略、对外分享、密级拦截简单归类为缺 scope。

不在本 skill 范围

• 文档正文读取、总结、创建、编辑、图片/附件插入或下载：使用 lark-doc。
• 电子表格单元格、筛选、公式、样式等表内操作：使用 lark-sheets。
• Base / 多维表格内部的表、字段、记录、视图、仪表盘等操作：使用 lark-base。
• 知识空间、Wiki 节点层级、空间成员管理：使用 lark-wiki；上传本地文件到 wiki 节点仍用 drive +upload --wiki-token。
• 原生 Markdown 文件读取、写入、patch、diff：使用 lark-markdown；把 Markdown 导入成在线 docx 才用 drive +import --type docx。

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 与确认后删除远端。

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

• copy — 复制文件；优先使用 drive +copy
• create_folder — 新建文件夹
• list — 获取文件夹下的清单；使用前阅读 references/lark-drive-files-list.md
• patch — 修改文件标题；优先使用 drive +update-title shortcut

permission.members

• auth —
• create — 增加协作者权限
• transfer_owner —

metas

• batch_query — 获取文档元数据

user

• remove_subscription — 取消订阅用户、应用维度事件
• subscription — 订阅用户、应用维度事件（本次开放评论添加事件）
• subscription_status — 查询用户、应用对指定事件的订阅状态

file.statistics

• get — 获取文件统计信息
  • 获取 docx / 文件统计信息时，建议优先使用 typed flags：lark-cli drive file.statistics get --file-token <token> --file-type <type> --format json；--params JSON 也支持，适合批量拼装或 raw 参数场景。

file.view_records

• list — 获取文档的访问者记录
  • 查看 docx 最近访问记录、返回 open_id、最多 N 条时，建议优先使用 typed flags：lark-cli drive file.view_records list --file-token <docx_token> --file-type docx --page-size <N> --viewer-id-type open_id --format json；--params JSON 也支持，适合批量拼装、分页续跑或 raw 参数场景。

file.comment.reply.reactions

• update_reaction — 添加/删除 reaction；优先使用 drive +react-reply

quota_details

• get — 获取当前用户的容量信息，包含各业务使用量、租户配额是否超限、用户配额、所在部门配额
  • 仅支持 --as user，不要使用默认的 bot 身份
  • quota_detail_id 传当前用户的 user_id