lark-drive

drive (v1)

CRITICAL — Before starting, you MUST first use the Read tool to read ../lark-shared/SKILL.md, which contains authentication and permission handling

Core Concepts

Document Types and Tokens

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。

Document URL Formats and Token Handling

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

Special Handling for Wiki Links (Critical!)

Knowledge base links (/wiki/TOKEN) may actually be different types of documents such as cloud documents, spreadsheets, bitables, etc.You cannot directly assume that the token in the URL is the file_token, you must first query the actual type and real token.

Processing Flow

Use wiki.spaces.get_node to query node information

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(for subsequent operations)
- node.title: Document title

According to obj_type use the corresponding API

obj_type	Description	API Used
`docx`	New cloud document	`drive file.comments.`、`docx.`
`doc`	Legacy cloud document	`drive file.comments.*`
`sheet`	Spreadsheet	`sheets.*`
`bitable`	Bitable	`bitable.*`
`slides`	Slides	`drive.*`
`file`	File	`drive.*`
`mindnote`	Mind map	`drive.*`

Query Example

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

Example return result:

{
  "node": {
    "obj_type": "docx",
    "obj_token": "xxxx",
    "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 (直接使用)

Common Operation Token Requirements

Operation	Required Token	Description
Read document content	`file_token` / automatically handled via `docs +fetch` automatically handle	`docs +fetch` supports passing URLs directly
Add local comment (text-selection 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 ultimately resolve to `docx` wiki URLs
Add full-text comment	`file_token`	When not passing `--selection-with-ellipsis` / `--block-id` ,`drive +add-comment` creates a full-text comment by default; supports `docx`, legacy `doc` URLs, as well as those that ultimately resolve to `doc`/`docx` wiki URLs
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 a comment

Comment capability boundaries (critical!)

drive +add-comment supports two modes.
Full-text comments: when --selection-with-ellipsis / --block-id is not passed, this is enabled by default; you can also explicitly pass --full-comment; supports docx, legacy doc URLs, as well as those that ultimately resolve to doc/docx wiki URLs.
Local comments: when --selection-with-ellipsis or --block-id is passed, this is enabled; only supports docx, as well as those that ultimately resolve to docx wiki URLs.
drive +add-comment 's --content requires passing reply_elements JSON array string, for example --content '[{"type":"text","text":"正文"}]'。
If after wiki resolution it is not doc/docx, do not use +add-comment。
If you need to call the comment V2 protocol more directly at a lower level, use the native API instead: first execute lark-cli schema drive.file.comments.create_v2, then execute lark-cli drive file.comments create_v2 .... Full-text comments omit anchor, local comments pass anchor.block_id。

Comment query and counting semantics (critical!)

When querying document comments, use drive file.comments list。
drive file.comments list returned by items should be understood as a list of "comment cards"; each item corresponds to one comment card seen in the user interface, rather than a flat list of interaction messages.
Semantically, on the server side, when the first comment is created, the first reply in that card is created at the same time; therefore what actually carries the body text is each item.reply_list.replies, where the first reply is, from the user's perspective, the "comment itself" in this card.
When the user wants to count the "number of comments" or "number of comment cards", just count the length of items ; for a full count, add up the lengths of items returned across all comment pages.
When the user wants to count the "number of replies", from the user's perspective the first comment in each comment card should be excluded; the counting basis is the sum of the lengths of all item.reply_list.replies minus the length of items .
When the user wants to count the "total number of interactions", just count the sum of the lengths of all item.reply_list.replies ; this basis includes the first comment in each comment card.
If a certain item.has_more=true, it means there are more replies under this comment card that are not included in the current response; in this case you need to continue calling drive file.comment.replys list to fetch them all, then calculate the full reply count / total interaction count.

Comment business characteristics and guidance (critical!)

Comment sorting guidance

A document usually has multiple comments, and comments are sorted by create_time(creation time).
Important: only when the user explicitly mentions "latest comment", "last comment", or "earliest comment" do you need to sort by create_time :
- You must first fetch all comments (handle pagination and fetch all data), and you cannot sort after fetching only one page
- "Latest comment" / "last comment": sort by create_time in descending order, and take the first one
- "Earliest comment": sort by create_time Sort in ascending order and take the first item
If the user only says "the first comment", directly use drive file.comments list the first item returned; no additional sorting is needed.

Comment reply restrictions

Before adding a comment reply, first check whether the following restrictions exist
Full-text comments do not support replies：is_whole=true comments (full-text comments) cannot have replies added. When encountering such comments, prompt the user with "Full-text comments do not support replies".
Resolved comments do not support replies：is_solved=true comments cannot have replies added. When encountering such comments, prompt the user with "This comment has been resolved and cannot be replied to".
Note: When the user wants to reply to a comment but the comment cannot be replied to due to the above restrictions, just prompt that it cannot be replied to,do not automatically help the user find other comments that can be replied to, to avoid not meeting user expectations.

Choosing between batch query and list query

Use drive file.comments batch_query isafter the comment ID is knownfor batch query, and a specific list of comment IDs needs to be passed in.
Use drive file.comments list to retrieve the comment list by pagination, suitable for counting the total number of comments, iterating through all comments, or getting "the latest/last N comments", etc.

Typical errors and solutions

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

Shortcuts (recommended to use first)

Shortcut is a high-level wrapper for common operations (lark-cli drive +<verb> [flags]). For operations that have a Shortcut, use it first.

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

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

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

files

copy — Copy file

file.comments

batch_query — Batch get comments
create_v2 — Add full-text/partial (selected text) comment
list — Get document comments by pagination
patch — Resolve/restore comment

file.comment.replys

create —
delete — Delete reply
list — Get reply
update — Update reply

permission.members

auth —
create — Add collaborator permission
transfer_owner —

metas

batch_query — Get document metadata

user

remove_subscription — Unsubscribe from user- and app-dimension events
subscription — Subscribe to user- and app-dimension events (this release opens the comment-added event)
subscription_status — Query the subscription status of users and apps for specified events

Permission table

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`