Lark Drive

drive (v1)

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

核心概念

文档类型与 Token

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

文档 URL 格式与 Token 处理

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

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

处理流程

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

查询示例

# 查询 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 支持两种模式。
• 全文评论：未传 --selection-with-ellipsis / --block-id 时默认启用，也可显式传 --full-comment；支持 docx、旧版 doc URL，以及最终解析为 doc/docx 的 wiki URL。
• 局部评论：传 --selection-with-ellipsis 或 --block-id 时启用；仅支持 docx，以及最终解析为 docx 的 wiki URL。
• drive +add-comment 的 --content 需要传 reply_elements JSON 数组字符串，例如 --content '[{"type":"text","text":"正文"}]'。
• 如果 wiki 解析后不是 doc/docx，不要用 +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。
• 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 拉全后，再做全量回复数 / 总互动数统计。

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

评论排序引导

• 一个文档通常有多个评论，评论按 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 条评论"等场景。

典型错误与解决方案

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 — 复制文件

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 — 查询用户、应用对指定事件的订阅状态

权限表

drive +add-comment

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

给文档添加评论。底层统一走 /open-apis/drive/v1/files/:file_token/new_comments（create_v2）接口；未指定位置时省略 anchor 创建全文评论，指定 --selection-with-ellipsis 或 --block-id 时传入 anchor.block_id 创建局部评论。支持直接传 docx URL/token、旧版 doc URL（仅全文评论），也支持传最终可解析为 doc/docx 的 wiki URL。

命令

# 默认：未指定位置时添加全文评论
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
  --content '[{"type":"text","text":"请补充发布说明"}]'

# 也可以显式指定为全文评论；旧版 doc URL 仅支持全文评论
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/doc/<DOC_ID>" \
  --full-comment \
  --content '[{"type":"text","text":"请补充旧版文档的背景信息"}]'

# wiki 链接也可以，shortcut 会先解析到真实 doc/docx token
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
  --content '[{"type":"text","text":"这里需要一段全文评论"}]'

# 给 docx 文档里匹配到的文字添加局部评论
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
  --selection-with-ellipsis "流程" \
  --content '[{"type":"text","text":"请补充流程说明"}]'

# wiki 链接也支持局部评论，但解析结果必须是 docx
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
  --selection-with-ellipsis "流程" \
  --content '[{"type":"text","text":"请补充更细的开发步骤"}]'

# 组合文本、@用户、链接元素
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
  --selection-with-ellipsis "流程" \
  --content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 处理，参考 "},{"type":"link","text":"https://example.com"}]'

# 已知 block_id 时可跳过 MCP 直接创建局部评论
lark-cli drive +add-comment \
  --doc "<DOCX_TOKEN>" \
  --block-id "<BLOCK_ID>" \
  --content '[{"type":"text","text":"评论内容"}]'

# 如果需要更底层的原生 API，也可以直接调用 V2 协议
lark-cli schema drive.file.comments.create_v2

lark-cli drive file.comments create_v2 \
  --params '{"file_token":"<DOC_TOKEN>"}' \
  --data '{"file_type":"docx","reply_elements":[{"type":"text","text":"全文评论内容"}]}'

# 预览底层调用链
lark-cli drive +add-comment \
  --doc "https://example.larksuite.com/docx/<DOC_ID>" \
  --selection-with-ellipsis "流程" \
  --content '[{"type":"text","text":"请补充流程说明"}]' \
  --dry-run

参数

行为说明

• 无需预先获取文档内容：使用 --selection-with-ellipsis 时，shortcut 内部会自动调用 locate-doc 定位目标文本，不需要先调用 docs +fetch 获取文档。
• 未传 --selection-with-ellipsis / --block-id 时，shortcut 默认创建全文评论；也可以显式传 --full-comment。
• 全文评论支持 docx、旧版 doc URL，以及最终可解析为 doc/docx 的 wiki URL。
• 传 --selection-with-ellipsis 或 --block-id 时，shortcut 创建局部评论（划词评论）；该模式仅支持 docx，以及最终可解析为 docx 的 wiki URL。
• --content 接收结构化评论元素数组；type 支持 text、mention_user、link。为便于书写，mention_user / link 元素可以直接把用户 ID 或链接地址放在 text 字段中，shortcut 会转换成 OpenAPI 所需字段。
• 局部评论走 locate-doc 时，内部固定使用 limit=10。
• 当 locate-doc 命中多处时，shortcut 会中止并提示用户继续收窄 --selection-with-ellipsis，不支持手动指定匹配序号。
• 写入评论前会自动生成符合 OpenAPI 定义的请求体：
• 统一接口：POST /new_comments
• 统一字段：file_type + reply_elements
• 全文评论：省略 anchor
• 局部评论：传入 anchor.block_id
• --dry-run 仅预览调用链和请求体，不会实际写入。
• 如果需要更底层的控制，仍可改用 lark-cli schema drive.file.comments.create_v2 + lark-cli drive file.comments create_v2。

[!CAUTION]

这是写入操作 —— 执行前必须确认用户意图。

参考

• lark-drive -- 云空间全部命令
• lark-shared -- 认证和全局参数

drive +download

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

从飞书云空间下载文件到本地。

命令

# 下载到指定路径
lark-cli drive +download --file-token boxbc_xxx --output ./report.pdf

# 只提供 token，默认保存为当前目录下同名文件
lark-cli drive +download --file-token boxbc_xxx

URL 解析

从飞书文件 URL 提取 token：

https://xxx.feishu.cn/drive/file/boxbc_xxx
                                  ^^^^^^^^^
                                  file_token

参考

• lark-drive -- 云空间全部命令
• lark-shared -- 认证和全局参数

drive +upload

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

上传本地文件到飞书云空间。

命令

# 推荐：使用 shortcut 一步上传
lark-cli drive +upload --file ./report.pdf --folder-token fldbc_xxx

# 自定义上传后的文件名
lark-cli drive +upload --file ./report.pdf --name "季度总结.pdf"

# 生成可用临时下载链接的上传方式（素材上传，适用于后续用 curl 下载）
# 注意：需要可写 docx 文档 ID（用于挂载素材 block），且文件最大 20MB
lark-cli drive +upload --as-media --doc docx_xxx --file ./report.pdf

# 取出 tmp_download_url 后可直接 curl 下载
curl -L -o report.pdf "<TMP_DOWNLOAD_URL>"

# 原生命令（高级/分片上传）：预上传 + 完成上传
lark-cli drive files upload_prepare --data '{
  "file_name": "report.pdf",
  "parent_type": "explorer",
  "parent_node": "fldbc_xxx",
  "size": 1048576
}'
lark-cli drive files upload_finish --data '{
  "upload_id": "<UPLOAD_ID>",
  "block_num": 1
}'

# 查看完整参数定义
lark-cli schema drive.files.upload_prepare

[!IMPORTANT]

如果文件是以应用身份（bot）上传的，agent 在上传成功后应默认继续使用 bot 身份，为当前可用的 user 身份添加该文件的 full_access（管理员）权限。推荐流程：

1. 先用 lark-cli contact +get-user 获取当前用户信息，并从返回结果中读取该用户的 open_id

2. 再切回 bot 身份，使用这个 open_id 给该用户授权该文件的 full_access（管理员）权限

>

如果 lark-cli contact +get-user 无法执行，或者本地没有可用的 user 身份、拿不到当前用户的 open_id，则应视为“本地没有可用的 user 身份”，明确说明因此未完成授权。

>

回复上传结果时，除 file_token 外，还必须明确告知用户授权结果：

- 如果授权成功：直接说明当前 user 已获得该文件的管理员权限

- 如果本地没有可用的 user 身份：明确说明因此未完成授权

- 如果授权失败：明确说明文件已上传成功，但授权失败，并透出失败原因；同时提示用户可以稍后重试授权，或继续使用应用身份（bot）处理该文件

>

如果授权未完成，应继续给出后续引导：用户可以稍后重试授权，也可以继续使用应用身份（bot）处理该文件；如果希望后续改由自己管理，也可将文件 owner 转移给该用户。

>

仍然不要擅自执行 owner 转移。 如果用户需要把 owner 转给自己，必须单独确认。

参数（预上传 --data JSON body）：

[!CAUTION]

这是写入操作 —— 执行前必须确认用户意图。

参考

• lark-drive -- 云空间全部命令
• lark-shared -- 认证和全局参数