Agent Skills
› fanfan-de/anybox
› lark-drive
lark-drive
GitHub管理飞书云空间文件与文件夹，支持上传下载、创建、移动删除、元数据查看、评论及权限管理。负责将本地Office/Base文件导入为在线文档，处理Wiki链接Token解析，修改文件标题及版本历史管理。
Trigger Scenarios
用户需要上传或下载文件
整理云空间目录结构
查看文件详情或元数据
管理文档评论或权限
修改文件标题
订阅评论变更事件
将本地文件导入为新版文档或表格
Install
npx skills add fanfan-de/anybox --skill lark-drive -g -y
SKILL.md
Frontmatter
{
"name": "lark-drive",
"version": "1.0.0",
"metadata": {
"cliHelp": "lark-cli drive --help",
"requires": {
"bins": [
"lark-cli"
]
}
},
"description": "飞书云空间：管理云空间中的文件和文件夹。上传和下载文件、创建文件夹、复制\/移动\/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题（docx、sheet、bitable、file、folder、wiki）；也负责把本地 Word\/Markdown\/Excel\/CSV 以及 Base 快照（.base）导入为飞书在线云文档（docx、sheet、bitable）。当用户需要上传或下载文件、整理云空间目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格\/Base 时使用。"
}
drive (v1)
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理
导入分流规则： 如果用户要把本地 Excel / CSV /
.base快照导入成 Base / 多维表格 / bitable，必须优先使用lark-cli drive +import --type bitable。不要先切到lark-base；lark-base只负责导入完成后的表内操作。
快速决策
- 用户要搜文档 / Wiki / 电子表格 / 多维表格 / 云空间对象，优先使用
lark-cli drive +search。自然语言里"最近我编辑过的"、"我创建的"、"最近一周我打开过的 xxx"、"某人创建的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。老的docs +search进入维护期、后续会下线，不要新增对它的依赖。 - 用户要把本地
.xlsx/.csv/.base导入成 Base / 多维表格 / bitable，第一步必须使用lark-cli drive +import --type bitable。 - 用户要把本地
.md/.docx/.doc/.txt/.html导入成在线文档，使用lark-cli drive +import --type docx。 - 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新原生
.md文件（不是导入成 docx），切到lark-markdown。 - 用户要查看、下载、回滚或删除文件的历史版本，使用
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 处理
| 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 |
⚠️ 不能直接使用，需要先查询获取真实的 obj_token |
/sheets/ |
https://example.larksuite.com/sheets/shtcnxxxxxxxxx |
file_token |
URL 路径中的 token 直接作为 file_token 使用 |
/drive/folder/ |
https://example.larksuite.com/drive/folder/fldcnxxxx |
folder_token |
URL 路径中的 token 作为文件夹 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 查询节点信息
-
使用
wiki.spaces.get_node查询节点信息lark-cli wiki spaces get_node --params '{"token":"wiki_token"}' -
从返回结果中提取关键信息
node.obj_type：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）node.obj_token：真实的文档 token（用于后续操作）node.title：文档标题
-
根据
obj_type使用对应的 APIobj_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 需求
| 操作 | 需要的 Token | 说明 |
|---|---|---|
| 读取文档内容 | file_token / 通过 docs +fetch --api-version v2 自动处理 |
docs +fetch --api-version v2 支持直接传入 URL |
| 添加局部评论（划词评论） | file_token |
传 --block-id 时，drive +add-comment 会创建局部评论；docx 支持文本定位或 block_id，slides 仅支持 block_id，且都支持最终解析到对应类型的 wiki URL |
| 添加全文评论 | file_token |
不传 --block-id 时，drive +add-comment 默认创建全文评论；支持 docx、旧版 doc URL，以及最终解析为 doc/docx 的 wiki URL |
| 下载文件 | file_token |
从文件 URL 中直接提取 |
| 上传文件 | folder_token / wiki_node_token |
目标位置的 token |
| 列出文档评论 | file_token |
同添加评论 |
评论能力边界（关键！）
-
drive +add-comment支持两种模式。 -
全文评论：未传
--block-id时默认启用，也可显式传--full-comment；支持docx、旧版docURL，以及最终解析为doc/docx的 wiki URL。 -
局部评论：传
--block-id时启用；仅支持docx，以及最终解析为docx的 wiki URL。block ID 可通过docs +fetch --api-version v2 --detail with-ids获取。 -
drive +add-comment的--content需要传reply_elementsJSON 数组字符串，例如--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/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拉全后，再做全量回复数 / 总互动数统计。
评论业务特性与引导（关键！）
评论排序引导
- 一个文档通常有多个评论，评论按
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 了解如何使用。
典型错误与解决方案
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
not exist |
使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 obj_token |
permission denied |
没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
invalid file_type |
file_type 参数错误 | 根据 obj_type 传入正确的 file_type（docx/doc/sheet/slides） |
permission.public.patch 错误码引导
调用 lark-cli drive permission.public patch 更新文档公开权限失败时，如果返回以下错误码，按表格给用户明确下一步。不要把这些错误简单归类为缺少 scope；它们通常表示租户、对外分享或文档密级策略拦截。
| 错误码 | 含义 | 给用户的引导 |
|---|---|---|
91009 |
对外分享被租户安全策略管控，当前用户无法开启 | 提示用户：对外分享能力被租户安全策略统一管控，无法通过 API 或当前用户直接开启；需要联系租户管理员调整组织级对外分享策略。 |
91010 |
文档对外分享未打开 | 提示用户：当前文档尚未打开对外分享，请先在文档权限设置中打开对外分享，再重试 permission.public.patch。 |
91011 |
对外分享被文档密级管控 | 提示用户：对外分享被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
91012 |
权限设置被文档密级管控 | 提示用户：该权限设置被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
当用户最初提供的是文档 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 的操作优先使用。
| Shortcut | 说明 |
|---|---|
+search |
Search Lark docs, Wiki, and spreadsheet files with flat filter flags (preferred over docs +search). Natural-language-friendly: --edited-since, --mine, --doc-types, etc. |
+upload |
Upload a local file to a Drive folder or wiki node |
+create-folder |
Create a Drive folder, optionally under a parent folder, with bot auto-grant support |
+download |
Download a file from Drive to local |
+status |
Compare a local directory with a Drive folder by exact SHA-256 hash by default, or use --quick for a best-effort modified-time diff that skips remote downloads; reports new_local / new_remote / modified / unchanged plus detection=exact or detection=quick. Duplicate remote rel_path conflicts fail fast with error.type=duplicate_remote_path and list every conflicting entry; do not proceed as if one was chosen. --local-dir 必须是 cwd 内的相对路径，越界路径 CLI 会直接拒绝；目标在 cwd 外时引导用户切换 agent 工作目录，不要私自 cd 绕过。 |
+pull |
File-level Drive → local mirror. Duplicate remote rel_path conflicts fail by default; for duplicate files, rename downloads all copies with stable hashed suffixes, while newest / oldest pick one. --if-exists supports overwrite / smart / skip (smart is a best-effort modified-time incremental mode for repeat syncs). --delete-local requires --yes, only removes regular files, and is skipped after item failures. --local-dir must stay inside cwd. |
+sync |
Two-way local ↔ Drive sync. Reuses +status diff buckets, pulls new_remote, pushes new_local, and resolves modified via `--on-conflict=remote-wins |
+create-shortcut |
Create a shortcut to an existing Drive file in another folder |
+add-comment |
Add a comment to doc/docx/sheet/slides, also supports wiki URL resolving to doc/docx/sheet/slides |
+export |
Export a doc/docx/sheet/bitable to a local file with limited polling; supports --file-name for local naming |
+export-download |
Download an exported file by file_token |
+import |
Import a local file to Drive as a cloud document (docx, sheet, bitable) |
+version-history |
List historical versions of a file with only_tag=true and cursor-based pagination |
+version-get |
Download a specific historical version of a file |
+version-revert |
Revert a file to a specific historical version |
+version-delete |
Delete a specific historical version of a file |
+move |
Move a file or folder to another location in Drive |
+delete |
Delete a Drive file or folder with limited polling for folder deletes |
+push |
File-level local → Drive mirror. Duplicate remote rel_path conflicts fail by default; newest / oldest only apply to duplicate files when you explicitly want to target one remote file. --if-exists supports skip / smart / overwrite (smart skips files whose remote modified_time is already up to date, but falls through to the same overwrite path when the remote is older, so it inherits overwrite's rollout caveat). --delete-remote requires --yes. --local-dir must stay inside cwd. |
+task_result |
Poll async task result for import, export, move, or delete operations |
+inspect |
Inspect a Lark document URL to get its type, title, and canonical token; auto-unwraps wiki URLs to the underlying document |
+apply-permission |
Apply to the document owner for view/edit access (user-only; 5/day per document) |
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
权限表
| 方法 | 所需 scope |
|---|---|
files.copy |
docs:document:copy |
files.create_folder |
space:folder:create |
files.list |
space:document:retrieve |
files.patch |
docx:document:write_only |
file.comments.batch_query |
docs:document.comment:read |
file.comments.create_v2 |
docs:document.comment:create |
file.comments.list |
docs:document.comment:read |
file.comments.patch |
docs:document.comment:update |
file.comment.replys.create |
docs:document.comment:create |
file.comment.replys.delete |
docs:document.comment:delete |
file.comment.replys.list |
docs:document.comment:read |
file.comment.replys.update |
docs:document.comment:update |
permission.members.auth |
docs:permission.member:auth |
permission.members.create |
docs:permission.member:create |
permission.members.transfer_owner |
docs:permission.member:transfer |
permission.public.get |
docs:permission.setting:read |
permission.public.patch |
docs:permission.setting:write_only |
metas.batch_query |
drive:drive.metadata:readonly |
user.remove_subscription |
docs:event:subscribe |
user.subscription |
docs:event:subscribe |
user.subscription_status |
docs:event:subscribe |
file.statistics.get |
drive:drive.metadata:readonly |
file.view_records.list |
drive:file:view_record:readonly |
file.comment.reply.reactions.update_reaction |
docs:document.comment:create |
Version History
- 08dc189 Current 2026-07-05 18:58
