lark-drive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

drive (v1)

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

CRITICAL — You MUST use the Read tool to access
../lark-shared/SKILL.md
first, which contains authentication and permission handling

核心概念

Core Concepts

文档类型与 Token

Document Types and Tokens

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

file_token

。

In the Feishu Open Platform, different types of documents have different URL formats and token handling methods. When performing document operations (such as adding comments, downloading files, etc.), you must first obtain the correct

file_token

文档 URL 格式与 Token 处理

Document URL Formats and Token Handling

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 使用

URL Format	Example	Token Type	Handling Method
`/docx/`	`https://example.larksuite.com/docx/doxcnxxxxxxxxx`	`file_token`	Use the token in the URL path directly as `file_token`
`/doc/`	`https://example.larksuite.com/doc/doccnxxxxxxxxx`	`file_token`	Use the token in the URL path directly as `file_token`
`/wiki/`	`https://example.larksuite.com/wiki/wikcnxxxxxxxxx`	`wiki_token`	⚠️ Cannot be used directly, you need to query to get the real `obj_token`
`/sheets/`	`https://example.larksuite.com/sheets/shtcnxxxxxxxxx`	`file_token`	Use the token in the URL path directly as `file_token`
`/drive/folder/`	`https://example.larksuite.com/drive/folder/fldcnxxxx`	`folder_token`	Use the token in the URL path as the folder token

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

Special Handling for Wiki Links (Critical!)

知识库链接（

/wiki/TOKEN

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

A knowledge base link (

/wiki/TOKEN

) may correspond to different types of documents such as cloud documents, spreadsheets, base tables, etc. Do not assume that the token in the URL is the file_token; you must first query the actual type and real token.

处理流程

Processing Flow

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

bash

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
使用对应的 API

obj_type	说明	使用的 API
`docx`	新版云文档	`drive file.comments.` 、 `docx.`
`doc`	旧版云文档	`drive file.comments.*`
`sheet`	电子表格	`sheets.*`
`bitable`	多维表格	`bitable.*`
`slides`	幻灯片	`drive.*`
`file`	文件	`drive.*`
`mindnote`	思维导图	`drive.*`

Query node information using
wiki.spaces.get_node

bash

lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

Extract key information from the returned result
- ```
node.obj_type
```
  : Document type (docx/doc/sheet/bitable/slides/file/mindnote)
- ```
node.obj_token
```
  : Real document token (used for subsequent operations)
- ```
node.title
```
  : Document title

Use the corresponding API based on
obj_type

obj_type	Description	API to Use
`docx`	New version cloud document	`drive file.comments.` 、 `docx.`
`doc`	Old version cloud document	`drive file.comments.*`
`sheet`	Spreadsheet	`sheets.*`
`bitable`	Base table	`bitable.*`
`slides`	Slides	`drive.*`
`file`	File	`drive.*`
`mindnote`	Mind map	`drive.*`

查询示例

Query Example

bash

undefined

bash

undefined

查询 wiki 节点

Query wiki node

lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'


返回结果示例：
```json
{
  "node": {
    "obj_type": "docx",
    "obj_token": "xxxx",
    "title": "标题",
    "node_type": "origin",
    "space_id": "12345678910"
  }
}

lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'


Sample return result:
```json
{
  "node": {
    "obj_type": "docx",
    "obj_token": "xxxx",
    "title": "Title",
    "node_type": "origin",
    "space_id": "12345678910"
  }
}

资源关系

Resource Relationships

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 (直接使用)

Wiki Space
└── Wiki Node
    ├── obj_type: docx (New version document)
    │   └── obj_token (Real document token)
    ├── obj_type: doc (Old version document)
    │   └── obj_token (Real document token)
    ├── obj_type: sheet (Spreadsheet)
    │   └── obj_token (Real document token)
    ├── obj_type: bitable (Base table)
    │   └── obj_token (Real document token)
    └── obj_type: file/slides/mindnote
        └── obj_token (Real document token)

Drive Folder
└── File (File/Document)
    └── file_token (Use directly)

常见操作 Token 需求

Token Requirements for Common Operations

操作	需要的 Token	说明
读取文档内容	`file_token` / 通过 `docs +fetch` 自动处理	`docs +fetch` 支持直接传入 URL
添加局部评论（划词评论）	`file_token`	传 `--selection-with-ellipsis` 或 `--block-id` 时， `drive +add-comment` 会创建局部评论；仅支持 `docx` ，以及最终解析为 `docx` 的 wiki URL
添加全文评论	`file_token`	不传 `--selection-with-ellipsis` / `--block-id` 时， `drive +add-comment` 默认创建全文评论；支持 `docx` 、旧版 `doc` URL，以及最终解析为 `doc` / `docx` 的 wiki URL
下载文件	`file_token`	从文件 URL 中直接提取
上传文件	`folder_token` / `wiki_node_token`	目标位置的 token
列出文档评论	`file_token`	同添加评论

Operation	Required Token	Description
Read document content	`file_token` / Auto-handled via `docs +fetch`	`docs +fetch` supports direct URL input
Add local comment (selected text comment)	`file_token`	When passing `--selection-with-ellipsis` or `--block-id` , `drive +add-comment` will create a local comment; only supports `docx` and wiki URLs that resolve to `docx`
Add full-document comment	`file_token`	When not passing `--selection-with-ellipsis` / `--block-id` , `drive +add-comment` defaults to creating a full-document comment; supports `docx` , old version `doc` URLs, and wiki URLs that resolve to `doc` / `docx`
Download file	`file_token`	Extract directly from the file URL
Upload file	`folder_token` / `wiki_node_token`	Token of the target location
List document comments	`file_token`	Same as adding comments

评论能力边界（关键！）

Comment Capability Boundaries (Critical!)

```
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 +add-comment
```
supports two modes.
Full-document comment: Enabled by default when
```
--selection-with-ellipsis
```
/
```
--block-id
```
is not passed, or can be explicitly enabled by passing
```
--full-comment
```
; supports
```
docx
```
, old version
```
doc
```
URLs, and wiki URLs that resolve to
```
doc
```
/
```
docx
```
.
Local comment: Enabled when
```
--selection-with-ellipsis
```
or
```
--block-id
```
is passed; only supports
```
docx
```
and wiki URLs that resolve to
```
docx
```
.

The

--content

parameter of

drive +add-comment

requires a JSON array string of

reply_elements

, e.g.,

--content '[{"type":"text","text":"Content"}]'

Do not use
```
+add-comment
```
if the wiki resolves to a type other than
```
doc
```
/
```
docx
```
.
If you need to directly call the comment V2 protocol at a lower level, use the native API: first run
```
lark-cli schema drive.file.comments.create_v2
```
, then run
```
lark-cli drive file.comments create_v2 ...
```
. Omit
```
anchor
```
for full-document comments, and pass
```
anchor.block_id
```
for local comments.

评论查询与统计口径（关键！）

Comment Query and Statistical Caliber (Critical!)

查询文档评论时，使用
```
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
```
拉全后，再做全量回复数 / 总互动数统计。

Use
```
drive file.comments list
```
to query document comments.
The
```
items
```
returned by
```
drive file.comments list
```
should be understood as a list of "comment cards", where each
```
item
```
corresponds to a comment card seen in the user interface, not a flat list of interactive messages.
In server-side semantics, when the first comment is created, the first reply in the card is also created; therefore, the actual content is carried in
```
item.reply_list.replies
```
, where the first reply is the "comment itself" in the user's view.
When users want to count the "number of comments" or "number of comment cards", count the length of
```
items
```
; for full statistics, sum the lengths of
```
items
```
returned from all comment pages.
When users want to count the "number of replies", exclude the first comment in each comment card from the user's perspective; the statistical caliber is the total length of all
```
item.reply_list.replies
```
minus the length of
```
items
```
.
When users want to count the "total number of interactions", count the total length of all
```
item.reply_list.replies
```
; this caliber includes the first comment in each comment card.
If
```
item.has_more=true
```
for a certain item, it means there are more replies under this comment card not included in the current return; in this case, you need to continue calling
```
drive file.comment.replys list
```
to pull all data before conducting full reply count / total interaction count statistics.

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

Comment Business Features and Guidance (Critical!)

评论排序引导

Comment Sorting Guidance

一个文档通常有多个评论，评论按
```
create_time
```
（创建时间）排序。
重要：只有当用户明确提到"最新评论"、"最后评论"、"最早评论"时，才需要根据
```
create_time
```
进行排序：
- 必须先获取所有评论（处理分页拉完所有数据），不能只获取一页就排序
- "最新评论" / "最后评论"：按
```
create_time
```
  降序排列，取第一条
- "最早评论"：按
```
create_time
```
  升序排列，取第一条
如果用户只说"第一条评论"，直接使用
```
drive file.comments list
```
返回的第一条即可，不需要额外排序。

A document usually has multiple comments, sorted by
```
create_time
```
(creation time).
Important: Only when the user explicitly mentions "latest comment", "last comment", or "earliest comment" should you sort by
```
create_time
```
:
- Must first obtain all comments (handle pagination to pull all data), do not sort after only getting one page
- "Latest comment" / "Last comment": Sort in descending order by
```
create_time
```
  , take the first one
- "Earliest comment": Sort in ascending order by
```
create_time
```
  , take the first one
If the user only says "first comment", directly use the first one returned by
```
drive file.comments list
```
, no additional sorting is needed.

评论回复限制

Comment Reply Restrictions

添加评论回复前先检查是否存在以下限制
全文评论不支持回复：
```
is_whole=true
```
的评论（全文评论）无法添加回复，遇到此类评论应提示用户"全文评论不支持回复"。
已解决评论不支持回复：
```
is_solved=true
```
的评论无法添加回复，遇到此类评论应提示用户"该评论已被解决，无法回复"。
注意：当用户要回复某条评论但该评论因上述限制不能回复时，只提示不能回复即可，不要自动帮用户找其他可以回复的评论，避免不符合用户预期。

Check for the following restrictions before adding a comment reply
Full-document comments do not support replies: Comments with
```
is_whole=true
```
(full-document comments) cannot have replies added. Prompt the user with "Full-document comments do not support replies" when encountering such comments.
Resolved comments do not support replies: Comments with
```
is_solved=true
```
cannot have replies added. Prompt the user with "This comment has been resolved and cannot be replied to" when encountering such comments.
Note: When the user wants to reply to a comment but it cannot be replied to due to the above restrictions, only prompt that it cannot be replied to, do not automatically find other commentable comments for the user to avoid inconsistent expectations.

批量查询与列表查询的选择

Selection Between Batch Query and List Query

使用
```
drive file.comments batch_query
```
是已知评论 ID 后的批量查询，需要传入具体的评论 ID 列表。
使用
```
drive file.comments list
```
用于分页获取评论列表，适合统计评论总数、遍历所有评论，或获取"最新/最后 N 条评论"等场景。

```
drive file.comments batch_query
```
is for batch query after knowing the comment IDs, requiring a specific list of comment IDs to be passed.
```
drive file.comments list
```
is used to obtain comment lists in pages, suitable for scenarios such as counting the total number of comments, traversing all comments, or obtaining "latest/last N comments".

典型错误与解决方案

Typical Errors and Solutions

错误信息	原因	解决方案
`not exist`	使用了错误的 token	检查 token 类型，wiki 链接必须先查询获取 `obj_token`
`permission denied`	没有相关操作权限	引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限
`invalid file_type`	file_type 参数错误	根据 `obj_type` 传入正确的 file_type（docx/doc/sheet）

Error Message	Cause	Solution
`not exist`	Used an incorrect token	Check the token type; wiki links must first be queried to obtain `obj_token`
`permission denied`	No relevant operation permissions	Guide the user to check if the current identity has the corresponding operation permissions for the document/file; if needed, grant the corresponding permissions
`invalid file_type`	Incorrect file_type parameter	Pass the correct file_type according to `obj_type` (docx/doc/sheet)

Shortcuts（推荐优先使用）

Shortcuts (Recommended for Priority Use)

Shortcut 是对常用操作的高级封装（

lark-cli drive +<verb> [flags]

）。有 Shortcut 的操作优先使用。

Shortcut	说明
`+upload`	Upload a local file to Drive
`+download`	Download a file from Drive to local
`+add-comment`	Add a full-document comment, or a local comment to selected docx text (also supports wiki URL resolving to doc/docx)

Shortcuts are advanced encapsulations of common operations (

lark-cli drive +<verb> [flags]

). Use shortcuts first for operations that have them.

Shortcut	Description
`+upload`	Upload a local file to Drive
`+download`	Download a file from Drive to local
`+add-comment`	Add a full-document comment, or a local comment to selected docx text (also supports wiki URL resolving to doc/docx)

API Resources

bash

lark-cli schema drive.<resource>.<method>   # 调用 API 前必须先查看参数结构
lark-cli drive <resource> <method> [flags] # 调用 API

重要：使用原生 API 时，必须先运行
schema
查看
--data
/
--params
参数结构，不要猜测字段格式。

bash

lark-cli schema drive.<resource>.<method>   # Must check the parameter structure before calling the API
lark-cli drive <resource> <method> [flags] # Call the API

Important: When using the native API, you must first run
schema
to check the
--data
/
--params
parameter structure, do not guess the field format.

files

```
copy
```
— 复制文件

```
copy
```
— Copy file

file.comments

```
batch_query
```
— 批量获取评论
- ```
create_v2
```
  — 添加全文/局部（划词）评论
- ```
list
```
  — 分页获取文档评论
- ```
patch
```
  — 解决/恢复评论

```
batch_query
```
— Batch get comments
- ```
create_v2
```
  — Add full-document/local (selected text) comment
- ```
list
```
  — Paginate to get document comments
- ```
patch
```
  — Resolve/restore comment

file.comment.replys

```
create
```
—
- ```
delete
```
  — 删除回复
- ```
list
```
  — 获取回复
- ```
update
```
  — 更新回复

```
create
```
— Create reply
- ```
delete
```
  — Delete reply
- ```
list
```
  — Get replies
- ```
update
```
  — Update reply

permission.members

```
auth
```
—
- ```
create
```
  — 增加协作者权限
- ```
transfer_owner
```
  —

```
auth
```
— Authenticate permission member
- ```
create
```
  — Add collaborator permission
- ```
transfer_owner
```
  — Transfer owner

metas

```
batch_query
```
— 获取文档元数据

```
batch_query
```
— Get document metadata

user

```
remove_subscription
```
— 取消订阅用户、应用维度事件
- ```
subscription
```
  — 订阅用户、应用维度事件（本次开放评论添加事件）
- ```
subscription_status
```
  — 查询用户、应用对指定事件的订阅状态

```
remove_subscription
```
— Unsubscribe from user or application-level events
- ```
subscription
```
  — Subscribe to user or application-level events (comment addition event is open this time)
- ```
subscription_status
```
  — Query the subscription status of user or application to specified events

权限表

Permission Table

方法	所需 scope
`files.copy`	`docs:document:copy`
`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`
`metas.batch_query`	`drive:drive.metadata:readonly`
`user.remove_subscription`	`docs:event:subscribe`
`user.subscription`	`docs:event:subscribe`
`user.subscription_status`	`docs:event:subscribe`

Method	Required scope
`files.copy`	`docs:document:copy`
`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`
`metas.batch_query`	`drive:drive.metadata:readonly`
`user.remove_subscription`	`docs:event:subscribe`
`user.subscription`	`docs:event:subscribe`
`user.subscription_status`	`docs:event:subscribe`