lark-drive

drive (v1)

术语说明： 飞书云空间也常被称为"云盘"、"云存储"、"网盘"或"我的空间"，这些说法通常指的是同一个产品，是飞书官方的云端文件存储与管理中心。

导入分流规则： 如果用户要把本地 Excel / CSV / .base 快照导入成 Base / 多维表格 / bitable，必须优先使用 lark_drive_import(type="bitable")。不要先切到 lark-base；lark-base 只负责导入完成后的表内操作。

副本分流规则： 如果用户要复制在线文档、创建文档副本、把文档复制到另一个文件夹，必须使用 lark_invoke(tool_name="lark_drive_files_copy", ...)。不要用 lark_drive_export 下载后再 lark_drive_import 上传，也不要用 lark_docs_fetch + lark_docs_create 重建正文；导出/导入只用于本地文件转换或离线产物。

快速决策

• 用户要复制文档 / 创建副本 / 另存为副本时，使用 lark_invoke(tool_name="lark_drive_files_copy", ...)。先用 lark_discover(query="drive.files.copy") 确认参数；如果来源是 wiki URL/token，先用 lark_drive_inspect() 获取底层 token 和 type，不要把 wiki token 直接当 file_token。params.file_token 传源文档 token，data.folder_token 传目标文件夹 token，data.name 传副本名称，data.type 传源文件类型（如 docx / sheet / bitable / slides）。示例：lark_invoke(tool_name="lark_drive_files_copy", args={params: {"file_token":"<DOC_TOKEN>"}, data: {"folder_token":"<FOLDER_TOKEN>","name":"<COPY_NAME>","type":"docx"}})。如返回需要确认，向用户确认后在调用里加 _confirm=true 重试。
• 用户要识别飞书 / doubao 云空间 URL 的类型和 token时，可以先按 URL 路径形态做轻量判断；当路径已明确指向 docx / sheet / bitable / slides / file / folder 等资源时，可直接提取对应 token/type。传入 wiki URL、需要识别标题或 canonical URL、URL/token 有歧义，或后续操作依赖底层真实资源时，再使用 lark_drive_inspect(url="<url>") 进行识别；具体用法、失败处理和边界见 lark_get_skill(domain="drive", section="inspect")。
• 高风险写操作（删除、公开权限修改、owner 转移、版本删除/回滚、批量移动/覆盖/同步）必须同时满足三个条件才执行：目标已解析为该操作可直接使用的执行对象，执行细节已明确到可直接调用命令（例如删除的 file-token/type、公开权限修改的共享范围、owner 转移的目标 owner、版本删除/回滚的 version id、移动/覆盖/同步的目标位置和冲突策略），且用户在本轮明确确认执行这些具体目标和执行细节。用户只说"删除没用的文件""开放/共享给大家""改成开放""覆盖/移动这些"只表示目标状态；先只读发现并列出候选、权限档位或执行方案，停止等待用户确认。
• 用户要检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移，或要"权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner"，必须先调用 lark_get_skill(domain="drive", section="workflow")，再按其中 Workflow Registry 进入 permission_governance workflow（lark_get_skill(domain="drive", section="workflow-permission-governance")）。
• 用户要整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库，或要"盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案"，必须先调用 lark_get_skill(domain="drive", section="workflow")，再按其中 Workflow Registry 进入 knowledge_organize workflow（lark_get_skill(domain="drive", section="workflow-knowledge-organize")）。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
• 用户要搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象，优先使用 lark_drive_search()。自然语言里"最近我编辑过的"、"我创建的"（→ created_by_me=true，原始创建者语义）、"我负责/owner 的"（→ mine=true，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平参数，避免手写嵌套 JSON。
• 用户要获取文档评论列表时，优先使用 lark_drive_list_comments(url="<url>")，不要优先手写 lark_invoke(tool_name="lark_drive_file_comments_list", ...)；具体使用方式先调用 lark_get_skill(domain="drive", section="list-comments")。
• 用户要根据文档评论定位正文位置，例如 根据评论 review 文档、根据评论内容回看文档、区分多处相同引用文本时，对于 docx 类型（file_type=docx）的文档支持通过 lark_drive_list_comments(need_relation=true) 返回评论位置，其他类型会静默忽略该参数；具体用法需要先调用 lark_get_skill(domain="drive", section="comment-location") 了解。
• 用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，仍按资源类型、URL 路径和 token 路由到本 skill；不要因为域名不是飞书而回退到 WebFetch。
• 用户要把本地 .xlsx / .csv / .base 导入成 Base / 多维表格 / bitable，第一步必须使用 lark_drive_import(type="bitable")。
• 用户要把本地 .md / .docx / .doc / .txt / .html 导入成在线文档，使用 lark_drive_import(type="docx")。
• 用户要把本地 .pptx 导入成飞书幻灯片，使用 lark_drive_import(type="slides")；当前 PPTX 导入上限是 500MB。
• 批量执行 lark_drive_import 且目标是同一个位置（同一 folder_token、默认根目录，或同一 target_token）时，必须串行执行；不要并发导入到同一位置，服务端可能返回并发冲突错误。
• 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新原生 .md 文件（不是导入成 docx），切到 lark_get_skill(domain="markdown")。
• 用户要比较原生 .md 文件的历史版本差异，或比较远端 Markdown 与本地草稿，切到 lark_get_skill(domain="markdown") 的 lark_markdown_diff；需要版本号时先用 lark_drive_version_history()。
• 用户要查看、下载、回滚或删除文件的历史版本，使用 lark_drive_version_history()、lark_drive_version_get()、lark_drive_version_revert()、lark_drive_version_delete()；这组工具同时支持 user identity 和 bot identity。
• 用户要把本地 .xlsx / .xls / .csv 导入成电子表格，使用 lark_drive_import(type="sheet")。
• 用户要在云空间（云盘/云存储）里新建文件夹，优先使用 lark_drive_create_folder()。
• 用户要查看某个文件有哪些可下载预览格式，或想下载 PDF / HTML / 文本 / 图片等预览产物，使用 lark_drive_preview()。
• 用户要获取某个文件的封面图，优先使用 lark_drive_cover()；先 list_only=true 看规格，再选 spec 下载。
• 用户要导出云文档时，优先使用 lark_drive_export(url="<文档 URL>", file_extension="<格式>")；详细参数、Wiki token 和错误码处理见 lark_get_skill(domain="drive", section="export")。
• 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 lark_drive_upload(wiki_token="<wiki_token>")；不要误切到 wiki 域命令。
• lark-base 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在"本地文件 -> Base"这一步提前切到 lark-base。
• 用户给的是 wiki URL / token，且后续还没明确底层资源类型时，先用 lark_drive_inspect() 解包；lark_drive_inspect() 失败后不要自动切到别的写接口继续尝试，先按错误提示处理权限、scope 或链接问题。
• lark_drive_inspect() / lark_drive_upload() 遇到 not found、permission denied、missing scope 时，默认停止重试；只有 rate limit 或临时网络错误才适合有限重试。