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

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	The token in the URL path is directly used as file_token use
/doc/	https://example.larksuite.com/doc/doccnxxxxxxxxx	file_token	The token in the URL path is directly used as 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 directly used as 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 be 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

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：The real document token(for subsequent operations)
   • node.title: document title

3. 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: whiteboard editing

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

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

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

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

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

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

• In --markdown directly pass <whiteboard type="blank"></whiteboard>
• When multiple blank whiteboards are needed, repeat multiple whiteboard tags in the same --markdown repeat multiple whiteboard tags in it 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 whiteboard; use the tokens here directly for subsequent edits Step 3: Guide editing
• Record the token of the whiteboard that needs editing
• See ../lark-whiteboard/SKILL.md to learn how to edit whiteboard content

Notes

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

Quick decision

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

Additional notes

docs +search In addition to searching documents / Wiki, it also serves as the resource discovery entry point for "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 here first.

Shortcuts (recommended for priority use)

Shortcut is a high-level wrapper for common operations (lark-cli docs +<verb> [flags]). For operations with a Shortcut, use it first.

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.