docs (v2)

⚠️ API Version: This skill uses the v2 API. All docs +create --api-version v2, docs +fetch --api-version v2, and docs +update --api-version v2 commands must include the --api-version v2 flag.

# Common examples
lark-cli docs +fetch  --api-version v2 --doc "Document URL or token"
lark-cli docs +create --api-version v2 --content '<title>Title</title><p>Content</p>'
lark-cli docs +update --api-version v2 --doc "Document URL or token" --command append --content '<p>Content</p>'

Prerequisites, Must read before performing operations

CRITICAL, Before performing any operation, you MUST use the Read tool to read the following files. No exceptions:

1. ../lark-shared/SKILL.md, Authentication, permission handling, global parameters (common to all operations)
2. Reading documents (docs +fetch --api-version v2) → Must read lark-doc-fetch.md (--scope / --detail selection, partial reading strategy, <fragment> / <excerpt> output structure)
3. Creating or editing document content → Must read lark-doc-xml.md (XML syntax rules; only switch to lark-doc-md.md if the user explicitly requests Markdown); read lark-doc-create-workflow.md when creating from scratch; read lark-doc-update-workflow.md when editing existing documents.

Failure to read the above files before performing operations will lead to incorrect parameter selection, formatting errors, or substandard styling.

Format Selection Rules (Global):

• Creation / Import Scenarios (docs +create, or full-paragraph writes via docs +update --command append/overwrite): Both XML and Markdown are acceptable. If the user provides a local .md file or explicitly says "import Markdown," use Markdown directly. Otherwise, default to XML (which supports rich blocks like callouts, grids, checkboxes, etc.).
• Precision Editing Scenarios (partial refinement commands for docs +update such as str_replace, block_insert_after, block_replace, block_delete, block_move_after): Prioritize XML (--doc-format xml, which is the default). XML provides stable expression of block structures and styles, making partial refinement more controllable. Do not switch to Markdown just because it is simpler.

Quick Decision Making

• When a user needs a "direct link / anchor link to a specific block": Return Base Document URL#block_id. If you only have the document URL and no block_id, first use docs +fetch --detail with-ids to retrieve the target block ID.
• Example:
  • Known document URL = https://xxx.feishu.cn/docx/doxcn123
  • Known block_id = blkcn456
  • Should return https://xxx.feishu.cn/docx/doxcn123#blkcn456
• When a user needs to create, copy, or move resource blocks (whiteboards, spreadsheets, bitables, etc.) within a document, you must first read the "III. Resource Blocks" section of lark-doc-xml.md.
• When writing documents, prioritize planning important information (core processes, architecture, comparisons, risks, roadmaps, key metrics, causal relationships) as whiteboards rather than using only text or tables.
• New whiteboards must be isolated to a SubAgent: Simple diagrams should be inserted directly by the SubAgent as <whiteboard type="svg">Full SVG</whiteboard> without reading lark-whiteboard. Complex diagrams should be initialized by the main Agent as <whiteboard type="blank"></whiteboard>, then trigger a SubAgent to read lark-whiteboard for writing.
• If the user says "look at the images/attachments/materials in the document" or "preview materials" → Use lark-cli docs +media-preview.
• If the user explicitly says "download materials" → Use lark-cli docs +media-download.
• If the target is a whiteboard/whiteboard thumbnail → Must use lark-cli docs +media-download --type whiteboard (do not use +media-preview).
• After obtaining a spreadsheet URL/token → Switch to lark-sheets for internal object operations.
• If the user says "add a comment to the document," "view comments," "reply to a comment," or "add/delete an emoji reaction to a comment" → Switch to lark-drive to handle it.
• When embedded <sheet>, <bitable>, or <cite file-type="sheets|bitable"> tags appear in document content → You must proactively extract the token and switch to the corresponding skill to drill down and read the internal data. Do not simply present the tag itself.

Shortcuts (Recommended)

Shortcuts are advanced wrappers for common operations (lark-cli docs +<verb> [flags]). Prioritize using operations that have shortcuts.