lark-doc

docs (v2)

Identity: Document operations use --as user by default. Execute lark-cli auth login before first use.

CRITICAL, API Version: This skill uses the v2 API. You must explicitly pass --api-version v2 when executing docs +create, docs +fetch, and docs +update.

# 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, Read before performing operations

CRITICAL, Before performing any corresponding operation, you MUST use the Read tool to read the following files. All are required:

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; switch to lark-doc-md.md only when 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 result in incorrect parameter selection, formatting errors, or substandard styling.

Format Selection Rules (Global):

• Creation / Import Scenarios (docs +create, or full-segment writing 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 callouts, grids, checkboxes, and other rich blocks).
• Precision Editing Scenarios (local 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 reliably expresses block structures and styles, making local 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 Document Base URL#block_id. If you only have the document URL and no block_id, first use docs +fetch --detail with-ids to obtain 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 are inserted directly by the SubAgent as <whiteboard type="svg">Full SVG</whiteboard> without reading lark-whiteboard; complex diagrams require the main Agent to first create a <whiteboard type="blank"></whiteboard> and then launch a SubAgent to read lark-whiteboard for writing.
• When a user says "look at the images/attachments/materials in the document" or "preview materials" → Use lark-cli docs +media-preview.
• When a user explicitly says "download materials" → Use lark-cli docs +media-download.
• If the target is a whiteboard/whiteboard thumbnail → You 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 object-level operations.
• When a 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.

Out of Scope

• Document comment management → lark-drive
• Data operations for spreadsheets or Base → lark-sheets / lark-base
• Cloud storage file upload, download, and permission management → lark-drive