drive (v1)

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

Terminology Note: Feishu Cloud Space is also commonly referred to as "Cloud Drive" or "Cloud Storage." These three terms refer to the same product, which is the official Feishu cloud-based file storage and management center.

Import Routing Rules: If a user wants to import a local Excel / CSV / .base snapshot into Base / Bitable, you must prioritize using lark-cli drive +import --type bitable. Do not switch to lark-base first; lark-base is only responsible for operations within the table after the import is complete.

Quick Decision Making

• If a user wants to organize Cloud Drive / folders / document libraries / knowledge bases / personal document libraries, or wants to "inventory the directory structure, identify unarchived/temporary/duplicate/empty directories, or generate an organization plan," you must first read references/lark-drive-workflow-knowledge-organize.md. By default, only generate a plan; creating directories, moving resources, and requesting permissions must be confirmed separately.
• If a user wants to search for documents / Wiki / spreadsheets / Bitable / Cloud Space (Cloud Drive/Cloud Storage) objects, prioritize using lark-cli drive +search. In natural language, requests like "recently edited by me," "created by me" (→ --mine, which is owner semantics), "xxx I opened in the last week," or "docx owned by someone" map directly to flat flags, avoiding manual nested JSON.
• If a user wants to locate content based on document comments, for example, reviewing a document based on comments, revisiting a document based on comment content, or distinguishing between multiple identical cited texts, docx type (file_type=docx) documents support returning comment locations via need_relation=true. Other types do not currently support this. You must first read references/lark-drive-comment-location.md to understand specific usage.
• If a user wants to import a local .xlsx / .csv / .base into Base / Bitable, the first step must be using lark-cli drive +import --type bitable.
• If a user wants to import a local .md / .docx / .doc / .txt / .html into an online document, use lark-cli drive +import --type docx.
• If a user wants to import a local .pptx into Feishu Slides, use lark-cli drive +import --type slides; the current PPTX import limit is 500MB.
• If a user wants to upload, create, read, partially patch, or overwrite update native .md files (not imported as docx) in Drive, switch to lark-markdown.
• If a user wants to compare historical version differences of native .md files, or compare remote Markdown with a local draft, switch to lark-cli markdown +diff in lark-markdown; when a version number is needed, use drive +version-history first.
• If a user wants to view, download, roll back, or delete historical versions of files, use drive +version-history, drive +version-get, drive +version-revert, and drive +version-delete; this set of commands supports both --as user and --as bot. For automation scenarios, prioritize --as bot.
• If a user wants to import a local .xlsx / .xls / .csv into a spreadsheet, use lark-cli drive +import --type sheet.
• If a user wants to create a new folder in Cloud Space (Cloud Drive/Cloud Storage), prioritize using lark-cli drive +create-folder.
• If a user wants to see which downloadable preview formats are available for a file, or wants to download PDF / HTML / text / image preview artifacts, use lark-cli drive +preview.
• If a user wants to get the cover image of a file, prioritize using lark-cli drive +cover; use --list-only first to check specifications, then select --spec to download.
• If a user wants to upload a local file to a specific wiki node in a knowledge base / document library, still use lark-cli drive +upload --wiki-token <wiki_token>; do not mistakenly switch to wiki domain commands.
• If the user provides a wiki URL / token and the underlying resource type is not yet clear, use lark-cli drive +inspect to unpack it first; if +inspect fails, do not automatically switch to other write interfaces to continue trying. Handle permissions, scope, or link issues according to the error prompt first.
• If drive +inspect / drive +upload encounters not found, permission denied, or missing scope, stop retrying by default; only rate limit or temporary network errors are suitable for limited retries.

Modifying Titles

• Use the drive files patch command. You can modify the title via the new_title field. This supports docx, sheet, bitable, file, wiki, and folder types.

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

Wiki Link Special Handling (Critical!)

Behind a knowledge base link (/wiki/TOKEN) could be a cloud document, spreadsheet, Bitable, or other document type. Do not assume the token in the URL is the file_token. You must query the actual type and real token first.

Processing Flow

Recommended Method: Use drive +inspect for automatic unpacking

lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'

The returned result contains type (underlying document type), token (real file_token), title, url, etc., which can be used directly for subsequent operations.

Manual Method: Use wiki.spaces.get_node to query node information

1. Use wiki.spaces.get_node to query node information

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

2. 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

3. Use the corresponding API based on obj_type

   obj_type	Description	API Used
   docx	New Cloud Doc	drive file.comments.*, docx.*
   doc	Old Cloud Doc	drive file.comments.*
   sheet	Spreadsheet	sheets.*
   bitable	Bitable	bitable.*
   slides	Slides	drive.*
   file	File	drive.*
   mindnote	Mindnote	drive.*

Query Example

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

Returned result example:

{
  "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 Doc)
    │   └── obj_token (Real document token)
    ├── obj_type: doc (Old Doc)
    │   └── obj_token (Real document token)
    ├── obj_type: sheet (Spreadsheet)
    │   └── obj_token (Real document token)
    ├── obj_type: bitable (Bitable)
    │   └── obj_token (Real document token)
    └── obj_type: file/slides/mindnote
        └── obj_token (Real document token)

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

Common Operation Token Requirements

Comment Capability Boundaries (Critical!)

• drive +add-comment supports two modes.

• Full-text comment: Enabled by default when --block-id is not passed, or can be explicitly passed via --full-comment; supports docx, old doc URL, Drive files with whitelisted extensions, and wiki URLs that resolve to doc/docx/file.

• Partial comment: Enabled when --block-id is passed; docx supports text positioning or block id, sheet supports <sheetId>!<cell>, slides supports <slide-block-type>!<xml-id>, and wiki URLs that resolve to these types also support corresponding partial comments. Drive file only supports full-text comments, not partial comments.

• Drive file comments only support whitelisted extensions: .md, .txt, .json, .csv, .go, .js, .py, .pptx, .png, .jpg, .jpeg, .zip, .mp3, .mp4. Ordinary files not in the whitelist, such as .pdf, .docx, .xlsx, are not currently supported. The CLI will report an error indicating that this type of comment is not supported.

• For Review / Proofreading / Checking / Pointing out issues one by one, prioritize using partial comments. Do not combine multiple locatable issues into one full-text comment. See drive +add-comment behavior description for specific parameters and positioning methods.

• The --content for drive +add-comment requires a reply_elements JSON array string, for example --content '[{"type":"text","text":"Body"}]'.

• slides comments require explicitly passing --block-id <slide-block-type>!<xml-id>; the CLI will split this and write it into anchor.block_id and anchor.slide_block_type. <xml-id> is the element id in the PPT XML protocol; --selection-with-ellipsis and --full-comment are not supported.

• Text content written in comments (adding comments, replying to comments, editing replies) cannot directly contain < or >; they must be escaped before submission: < -> <, > -> >.

• When using drive +add-comment, the shortcut automatically performs the above escaping for type=text elements. If calling drive file.comments create_v2, drive file.comment.replys create, or drive file.comment.replys update directly, you must pass the escaped content in the request yourself.

• If the wiki resolution is not doc/docx/file/sheet/slides, do not use +add-comment.

• If you need to call the comment V2 protocol directly at a lower level, use the native API: first execute lark-cli schema drive.file.comments.create_v2, then execute lark-cli drive file.comments create_v2 .... Omit anchor for full-text comments, and pass anchor.block_id for partial comments.

Comment Query and Statistics (Critical!)

Mandatory Rule: drive file.comments list must pass is_solved:false by default, meaning only query unresolved comments. Even if the user says "all comments" or "list all comments," as long as they do not explicitly mention including resolved comments, still query unresolved comments by default. Only omit the is_solved parameter when the user explicitly requests to include resolved comments.

Correct Example:

# Default query: unresolved comments only (Recommended)
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}'

# Query all comments (User did not explicitly request resolved comments)
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}'

# Include resolved comments (Requires explicit user request)
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}'

Incorrect Example:

# Not recommended: Querying all comments when the user did not explicitly request it
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}'

• When querying document comments, use drive file.comments list.
• The items returned by drive file.comments list should be understood as a list of "comment cards." Each item corresponds to a comment card seen in the user interface, not a flattened list of interactive messages.
• In server semantics, creating the first comment also creates the first reply in that card. Therefore, the actual body content is in each item.reply_list.replies, where the first reply is the "comment itself" from the user's perspective.
• When a user wants to count "number of comments" or "number of comment cards," simply count the length of items. For a full count, accumulate the length of items returned across all paginated results.
• When a user wants to count "number of replies," from the user's perspective, exclude the first comment in each card. The counting logic is the sum of the lengths of all item.reply_list.replies minus the length of items.
• When a user wants to count "total interactions," count the sum of the lengths of all item.reply_list.replies; this metric includes the first comment in each card.
• If an item.has_more=true, it means there are more replies under that comment card not included in the current return. In this case, continue calling drive file.comment.replys list to pull the full list before performing full reply count / total interaction count statistics.

Comment Business Characteristics and Guidance (Critical!)

Review Scenario Comment Placement

• The default strategy is "partial if possible": When a user says review, check document, mark issues, give modification suggestions, or comment line by line, prioritize creating partial comments.
• Multiple independent issues should have multiple partial comments created separately; do not merge issues found during review into a full-text comment to save on call counts.
• Only revert to a full-text comment if the target type supports full-text comments AND one of the following occurs: the user explicitly requests a full/overall comment, the comment content is indeed a document-level summary, the target type does not support partial comments, or it is impossible to stably locate the specific position. Otherwise, explain the limitation and request the user to provide a locatable position.
• See drive +add-comment behavior description for specific parameters, positioning methods, and constraints for different document types.

Comment Sorting Guidance

• A document usually has multiple comments, sorted by create_time.
• Important: Only sort by create_time when the user explicitly mentions "latest comment," "last comment," or "earliest comment":
  • Must fetch all comments first (handle pagination to pull all data); do not sort after fetching only one page.
  • "Latest comment" / "Last comment": Sort by create_time descending, take the first one.
  • "Earliest comment": Sort by create_time ascending, take the first one.
• If the user just says "first comment," use the first one returned by drive file.comments list directly; no extra sorting is needed.

Comment Reply Restrictions

• Check for the following restrictions before adding a comment reply.
• Full-text comments do not support replies: Comments with is_whole=true cannot have replies added. If you encounter such a comment, inform the user that "Full-text comments do not support replies."
• Resolved comments do not support replies: Comments with is_solved=true cannot have replies added. If you encounter such a comment, inform the user that "This comment has been resolved and cannot be replied to."
• Note: When a user wants to reply to a comment that cannot be replied to due to the above restrictions, only inform them that it cannot be replied to. Do not automatically find other comments for the user to reply to, to avoid violating user expectations.

Batch Query vs. List Query

• Use drive file.comments batch_query for batch queries after the comment IDs are known; it requires passing a specific list of comment IDs.
• Use drive file.comments list for paginated retrieval of comment lists, suitable for counting total comments, traversing all comments, or scenarios like getting the "latest/last N comments."

Comment Positioning Fields

• When you need to locate the document content based on a comment (e.g., reviewing a document based on comments, distinguishing between multiple identical cited texts, mapping comment points to docs +fetch blocks), first confirm the target is file_type=docx, then read Comment Positioning Field Description. Other document types do not currently support returning positioning fields.

Reaction / Emoji Scenarios

• When encountering questions related to reactions on comments/replies (emojis, counts of each emoji, who clicked what, adding/deleting emojis), read lark-drive-reactions.md first to understand how to use them.

Typical Errors and Solutions

permission.public.patch Error Code Guidance

When updating public document permissions via lark-cli drive permission.public patch fails, if the following error codes are returned, guide the user according to the table. Do not simply classify these errors as missing scope; they usually indicate interception by tenant, external sharing, or document security level policies.

When the user initially provides a document URL and encounters 91011 or 91012, return that URL to the user as an entry point for the operation. If the context only has a token, try to restore the target document URL using existing context, search results, or metadata before providing the clickable document URL.

Authorizing the Current Application to Access Documents

When you need to grant document permissions to the current application (bot) itself, first obtain the application's open_id via the bot info interface, then call the permission interface to authorize:

# 1. Get the current application's open_id
lark-cli api GET /open-apis/bot/v3/info --as bot
# Get bot.open_id from the return value

# 2. Authorize the current application to access the document
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"}'

Note: This method is only applicable to scenarios where you need to authorize the current application. When authorizing other users, use their open_id directly; there is no need to call the bot info interface.

<resource_type> optional values: doc, docx, sheet, bitable, file, folder, wiki, slides.

Shortcuts (Recommended to use first)

Shortcuts are high-level encapsulations of common operations (lark-cli drive +<verb> [flags]). Prioritize using operations that have Shortcuts.