lark-doc

docs (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

On 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 used directly as the `file_token` use
`/doc/`	`https://example.larksuite.com/doc/doccnxxxxxxxxx`	`file_token`	The token in the URL path is used directly as the `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 used directly as the `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 point to different types of documents such as cloud docs, spreadsheets, or bitables.You cannot directly assume that the token in the URL is the file_token, you must first query the actual type and real token.

Handling Process

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：The 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 docs	`drive file.comments.`、`docx.`
`doc`	Old cloud docs	`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 returned 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 (直接使用)

Important Note: Board Editing

⚠️ The lark-doc skill cannot directly edit the content of an existing board, but docs +update can create a new blank board

Scenario 1: Document content and board token have already been obtained via docs +fetch

If the user has already fetched the document content via docs +fetch , and the document already has a board (the returned markdown contains the <whiteboard token="xxx"/> tag), please guide the user to:

Record the board token
View ../lark-whiteboard/SKILL.md to learn how to edit board content

Scenario 2: A board has just been created and needs to be edited

If the user has just created a blank board via docs +update and needs to edit it: Step 1: Create using blank whiteboard syntax

In --markdown directly pass <whiteboard type="blank"></whiteboard>
When multiple blank whiteboards are needed, in the same --markdown repeat multiple whiteboard tags Step 2: Record the token from the response
docs +update After success, read the response field data.board_tokens
data.board_tokens is the token list of the newly created whiteboards; subsequent edits use the tokens here directly Step 3: Guide editing
Record the tokens of the whiteboards that need editing
See ../lark-whiteboard/SKILL.md to learn how to edit whiteboard content

Notes

Existing whiteboard content cannot be edited directly via lark-doc's docs +update Edit directly
Editing a whiteboard requires the dedicated ../lark-whiteboard/SKILL.md

Quick decision

When the user says "find a table", "search spreadsheets by name", "find reports", "recently opened tables", first use lark-cli docs +search for resource discovery.
docs +search does not only search documents / Wiki; the results directly return SHEET and other cloud space objects.
After obtaining the spreadsheet URL / token, switch to lark-sheets to perform operations such as reading, filtering, and writing within the object.

Additional notes

docs +search In addition to searching documents / Wiki, it also serves as the resource discovery entry point of "first locate the cloud space object, then switch back to the corresponding business skill for operations"; when the user verbally says "table / report", also start from here first.

Shortcuts (recommended to use first)

A Shortcut is a high-level wrapper for common operations (lark-cli docs +<verb> [flags]). Operations with a Shortcut should be prioritized.

Shortcut	Description
`+search`	Search Lark docs, Wiki, and spreadsheet files (Search v2: doc_wiki/search)
`+create`	Create a Lark document
`+fetch`	Fetch Lark document content
`+update`	Update a Lark document
`+media-insert`	Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback)
`+media-download`	Download document media or whiteboard thumbnail (auto-detects extension)
`+whiteboard-update`	Update an existing whiteboard in lark document with whiteboard dsl. Such DSL input from stdin. refer to lark-whiteboard skill for more details.