drive (v1)

CRITICAL — You MUST use the Read tool to access
../lark-shared/SKILL.md
first, 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`	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

Special Handling for Wiki Links (Critical!)

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

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

# Query wiki node
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 (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 Requirements for Common Operations

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
```
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!)

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

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

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
```
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

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 (Recommended for Priority Use)

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>   # 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 file

file.comments

```
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
```
— Create reply
```
delete
```
— Delete reply
```
list
```
— Get replies
```
update
```
— Update reply

permission.members

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

metas

```
batch_query
```
— Get document metadata

user

```
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

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`

lark-drive

NPX Install

Tags

SKILL.md Content (Chinese)

drive (v1)

Core Concepts

Document Types and Tokens

Document URL Formats and Token Handling

Special Handling for Wiki Links (Critical!)

Processing Flow

Query Example

Resource Relationships

Token Requirements for Common Operations

Comment Capability Boundaries (Critical!)

Comment Query and Statistical Caliber (Critical!)

Comment Business Features and Guidance (Critical!)

Comment Sorting Guidance

Comment Reply Restrictions

Selection Between Batch Query and List Query

Typical Errors and Solutions

Shortcuts (Recommended for Priority Use)

API Resources

files

file.comments

file.comment.replys

permission.members

metas

user

Permission Table