lark-drive

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），或查询当前用户可用的密级标签，直接读取 references/lark-drive-secure-label.md；这是 Drive 文件治理能力。
• 用户要检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移，或要“权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 references/lark-drive-workflow.md，再按其中 Workflow Registry 进入 permission_governance workflow。
• 用户要查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置，优先使用 lark-cli drive +permission-get-setting；它只读取目标自身设置，不递归审计文件夹子文档权限。裸 token 必须显式传 --type。
• 用户要按特定主题、关键词或内容线索跨容器查找资料，并统一收集到 Drive 文件夹或 Wiki 节点，必须先阅读 references/lark-drive-workflow.md，再按其中 Workflow Registry 进入 topic_move_collector workflow。该 workflow 负责搜索召回、内容验证、相关性分类、移动计划、写前确认和结果验证；禁止直接从 drive +search 或 drive +move 开始。
• 用户要整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 references/lark-drive-workflow.md，再按其中 Workflow Registry 进入 knowledge_organize workflow。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
• 按主题跨范围查找并集中归档，进入 topic_move_collector；对已知文件夹、文档库或知识库做目录盘点和结构重组，进入 knowledge_organize；只移动一个已明确资源时仍使用原子移动命令。
• 用户要搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象，优先使用 lark-cli drive +search；按标题定位和处理重复候选时遵循 references/lark-drive-search.md。自然语言里"最近我编辑过的"、"我创建的"（→ --created-by-me，原始创建者语义）、"我负责/owner 的"（→ --mine，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
• 用户要对文档评论做任何操作（添加评论、列表 / 批量查询、回复、获取 / 更新 / 删除回复、解决 / 恢复、reaction），按下方 Shortcuts 表选择对应的 drive +<verb> 评论命令，执行前先阅读该命令的 ref。按评论定位文档正文位置见 references/lark-drive-comment-location.md。
• 用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，仍按资源类型、URL 路径和 token 路由到本 skill；不要因为域名不是飞书而回退到 WebFetch。
• 用户要把本地 .xlsx / .csv / .base 导入成 Base / 多维表格 / bitable，第一步必须使用 lark-cli drive +import --type bitable。
• 用户要把本地 .md / .docx / .doc / .txt / .html 导入成在线文档，使用 lark-cli drive +import --type docx。
• 用户要把本地 .pptx 导入成飞书幻灯片，使用 lark-cli drive +import --type slides；当前 PPTX 导入上限是 500MB。
• 批量执行 drive +import 且目标是同一个位置（同一 --folder-token、默认根目录，或同一 --target-token）时，必须串行执行；不要并发导入到同一位置，服务端可能返回并发冲突错误。
• 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新原生 .md 文件（不是导入成 docx），切到 lark-markdown。
• 用户要比较原生 .md 文件的历史版本差异，或比较远端 Markdown 与本地草稿，切到 lark-markdown 的 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。
• 用户要查看或下载文件内容，或者查看文件可用预览格式并获取 PDF / HTML / 文本 / 图片等转换预览产物，使用 lark-cli drive +preview。+preview 和 +download 都支持 --file-token / --url / --wiki-token 三选一（Wiki 会解析到底层 file）；但两者只处理 Drive 文件，若目标是 docx/sheet/bitable/slides 等在线文档，改用 drive +export。
• 用户要获取某个文件的封面图，优先使用 lark-cli drive +cover；先 --list-only 看规格，再选 --spec 下载。
• 用户要导出云文档时，优先使用 lark-cli drive +export --url '<文档 URL>' --file-extension <格式>；详细参数、Wiki token 和错误码处理见 references/lark-drive-export.md。
• 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 lark-cli drive +upload --wiki-token <wiki_token>；不要误切到 wiki 域命令。
• lark-base 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 lark-base。
• 用户给的是 wiki URL / token，且后续还没明确底层资源类型时，先用 lark-cli drive +inspect 解包；+inspect 失败后不要自动切到别的写接口继续尝试，先按错误提示处理权限、scope 或链接问题。
• drive +inspect / drive +upload 遇到 not found、permission denied、missing scope 时，默认停止重试；只有 rate limit 或临时网络错误才适合有限重试。