lark-drive

name: lark-drive version: 1.0.0 description: "飞书云空间（云盘/云存储）：管理云空间（云盘/云存储）中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题（docx、sheet、bitable、file、folder、wiki）；也负责把本地 Word/Markdown/Excel/CSV/PPTX 以及 Base 快照（.base）导入为飞书在线云文档（docx、sheet、bitable、slides）。当用户需要上传或下载文件、整理云空间（云盘/云存储）目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格/Base/幻灯片 时使用。"云空间"、"云盘"和"云存储"是同一概念，用户说"云盘"、"云存储"、"网盘"、"我的空间"时均路由到本 skill。当用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是资源类型、URL 路径模式和 token，而不是域名。" 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 只负责导入完成后的表内操作。

快速决策

• 用户要整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 references/lark-drive-workflow-knowledge-organize.md。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
• 用户要搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象，优先使用 lark-cli drive +search。自然语言里"最近我编辑过的"、"我创建的"（→ --mine，实为 owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
• 用户要把本地 .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 里上传、创建、读取、局部 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。
• 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 lark-cli drive +upload --wiki-token <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 处理

Wiki 链接特殊处理（关键！）

知识库链接（/wiki/TOKEN）背后可能是云文档、电子表格、多维表格等不同类型的文档。不能直接假设 URL 中的 token 就是 file_token，必须先查询实际类型和真实 token。

处理流程

推荐方式：使用 drive +inspect 自动解包

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

返回结果包含 type（底层文档类型）、token（真实 file_token）、title、url 等字段，直接用于后续操作。

手动方式：使用 wiki.spaces.get_node 查询节点信息

1. 使用 wiki.spaces.get_node 查询节点信息

   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.*

查询示例

# 查询 wiki 节点
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

返回结果示例：

{
  "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 需求

评论能力边界（关键！）

• drive +add-comment 支持两种模式。

• 全文评论：未传 --block-id 时默认启用，也可显式传 --full-comment；支持 docx、旧版 doc URL、白名单扩展名的 Drive file，以及最终解析为 doc/docx/file 的 wiki URL。

• 局部评论：传 --block-id 时启用；docx 支持文本定位或 block id，sheet 支持 <sheetId>!<cell>，slides 支持 <slide-block-type>!<xml-id>，wiki URL 解析到这些类型时也支持对应局部评论。Drive file 本次只支持全文评论，不支持局部评论。

• Drive file 评论仅支持白名单扩展名：.md、.txt、.json、.csv、.go、.js、.py、.pptx、.png、.jpg、.jpeg、.zip、.mp3、.mp4。.pdf、.docx、.xlsx 等未在白名单内的普通文件暂不支持，CLI 会直接报错提示当前还不支持这种类型的评论。

• Review / 审阅 / 校对 / 逐条指出问题场景优先使用局部评论，不要把多个可定位问题汇总成一条全文评论；具体参数和定位方式见 drive +add-comment 行为说明。

• drive +add-comment 的 --content 需要传 reply_elements JSON 数组字符串，例如 --content '[{"type":"text","text":"正文"}]'。

• slides 评论要求显式传 --block-id <slide-block-type>!<xml-id>；CLI 会将其拆分后写入 anchor.block_id 和 anchor.slide_block_type。其中 <xml-id> 是 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/file/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 参数。

正确示例：

# 默认查询：仅未解决评论（推荐）
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"}'

错误示例：

# 不推荐：用户未明确要求但查询所有评论
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 拉全后，再做全量回复数 / 总互动数统计。

评论业务特性与引导（关键！）

Review 场景评论落点

• 默认策略是“能局部就局部”：用户说 review、审阅、检查文档、标注问题、给修改建议、逐条评论时，优先创建局部评论。
• 多个独立问题应分别创建多条局部评论；不要为了省调用次数把 review 发现的问题合并到全文评论。
• 只有在目标类型支持全文评论，且出现以下任一情况时，才退回全文评论：用户明确要求全文/总体评论、评论内容确实是文档级总结、目标类型不支持局部评论，或无法稳定定位到具体位置；否则应说明限制并请求用户提供可定位位置。
• 具体参数、定位方式和不同文档类型的约束见 drive +add-comment 行为说明。

评论排序引导

• 一个文档通常有多个评论，评论按 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 了解如何使用。

典型错误与解决方案

permission.public.patch 错误码引导

调用 lark-cli drive permission.public patch 更新文档公开权限失败时，如果返回以下错误码，按表格给用户明确下一步。不要把这些错误简单归类为缺少 scope；它们通常表示租户、对外分享或文档密级策略拦截。

当用户最初提供的是文档 URL，遇到 91011 或 91012 时直接把该 URL 原样返回给用户作为操作入口；如果上下文只有 token，需要先尽量通过已有上下文、搜索结果或元数据恢复目标文档 URL，再给出可点击的文档 URL。

授权当前应用访问文档

当需要将文档权限授予当前应用（bot）自身时，先通过 bot info 接口获取应用的 open_id，再调用权限接口授权：

# 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":"<doc_token>","type":"<resource_type>"}' \
  --data '{"member_type":"openid","member_id":"<bot_open_id>","perm":"view","type":"user"}'

注意：此方式仅适用于需要授权给当前应用的场景。授权给其他用户时，直接使用对方的 open_id 即可，无需调用 bot info 接口。

<resource_type> 可选值：doc、docx、sheet、bitable、file、folder、wiki、slides。

Shortcuts（推荐优先使用）

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

API Resources

lark-cli schema drive.<resource>.<method>   # 调用 API 前必须先查看参数结构
lark-cli drive <resource> <method> [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

权限表