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!)
The knowledge base link (/wiki/TOKEN) may point to different types of documents behind it, such as cloud documents, spreadsheets, bitables, etc.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_nodeto query node informationlark-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
-
Based on
obj_type, use the corresponding APIobj_type Description API Used docxNew version cloud document drive file.comments.*、docx.*docOld version cloud document drive file.comments.*sheetSpreadsheet sheets.*bitableBitable bitable.*slidesSlides drive.*fileFile drive.*mindnoteMind map drive.*
Query Example
# 查询 wiki 节点
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
Example return 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 +updatecan create a new blank board
Scenario 1: Document content and board token have already been obtained via docs +fetch
If the user has already retrieved the document content via docs +fetch , and the document already contains a board (the returned markdown contains the <whiteboard token="xxx"/> tag), please guide the user to:
- Record the board token
- Check
../lark-whiteboard/SKILL.mdto learn how to edit board content
Scenario 2: A board was just 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 according to 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
--markdownRepeat multiple whiteboard tags in Step 2: Record the token from the response docs +updateAfter success, read the response fielddata.board_tokensdata.board_tokensis the token list of the newly created whiteboards; for subsequent edits, directly use the tokens here Step 3: Guide editing- Record the token of the whiteboard that needs to be edited
- View
../lark-whiteboard/SKILL.mdto learn how to edit whiteboard content
Notes
- Existing whiteboard content cannot be directly edited through lark-doc's
docs +updateDirect editing - Editing a whiteboard requires using the dedicated
../lark-whiteboard/SKILL.md
Document visualization suggestions
💡 When writing documents, when you need to express relatively complex timing, architectural hierarchy, logical relationships, data flows, etc., it is recommended to use whiteboards to draw visual diagrams to significantly improve the readability of the document.
Please refer to
../lark-whiteboard/SKILL.mdto learn how to draw whiteboard content.
Quick decision
- When the user says "look at the images/attachments/materials in the document" or "preview the materials", prioritize using
lark-cli docs +media-preview。 - When the user explicitly says "download the materials", then use
lark-cli docs +media-download。 - If the target is clearly a whiteboard / whiteboard / whiteboard thumbnail, only use
lark-cli docs +media-download --type whiteboard, do not use+media-preview。 - When the user says "find a spreadsheet", "search spreadsheets by name", "find reports", or "recently opened spreadsheets", first use
lark-cli docs +searchfor resource discovery. docs +searchdoes not only search documents / Wiki; the results will directly returnSHEETand other cloud space objects.- After obtaining the spreadsheet URL / token, switch to
lark-sheetsfor operations such as reading, filtering, and writing within the object. - When the user says "add a comment to the document", "view comments", "reply to comments", "add an emoji / reaction to a comment", or "delete a comment emoji / reaction",do not stay in
lark-doc, directly switch tolark-driveto handle it.
Whiteboard requirement discovery (proactive identification)
Users rarely proactively mention "whiteboard". When creating documents, you should proactively identify content suitable for visualization and present it with a whiteboard.
🔴 Key requirements (must be followed)
Creating a blank whiteboard ≠ completing the task. After creating a blank whiteboard,you must continue to use the lark-whiteboard skill to fill in actual content。
Semantics and whiteboard type mapping
When creating/editing a document, if the document topic involves the following semantics, you shouldproactivelycreate a whiteboard without the user specifying it:
| Semantics | Whiteboard type | Reference guide |
|---|---|---|
| Architecture/layering/technical solution | Architecture diagram | lark-whiteboard-cli/scenes/architecture.md |
| Process/approval/deployment/business flow | Flowchart | lark-whiteboard-cli/scenes/flowchart.md |
| Organization/hierarchy/reporting relationship | Organizational chart | lark-whiteboard-cli/scenes/organization.md |
| Timeline/milestones/version planning | Milestone chart | lark-whiteboard-cli/scenes/milestone.md |
| Causality/retrospective/root cause analysis | Fishbone diagram | lark-whiteboard-cli/scenes/fishbone.md |
| Solution comparison/technology selection | Comparison chart | lark-whiteboard-cli/scenes/comparison.md |
| Loop/Flywheel/Closed loop | Flywheel diagram | lark-whiteboard-cli/scenes/flywheel.md |
| Hierarchy proportion/Capability model | Pyramid diagram | lark-whiteboard-cli/scenes/pyramid.md |
| Module dependency/Call relationship | Architecture diagram | lark-whiteboard-cli/scenes/architecture.md |
| Classification organization/Knowledge system | Mind map | lark-whiteboard-cli/scenes/mermaid.md |
| Data distribution/Proportion | Pie chart | lark-whiteboard-cli/scenes/mermaid.md |
Before creating a whiteboard, be sure to first read lark-whiteboard-cli and lark-whiteboard these two Skills to understand the whiteboard creation process.
Complete execution process (must be fully executed)
- Create a blank whiteboard placeholder: For creation scenarios use
docs +create, for editing scenarios usedocs +updateto insert a blank whiteboard - Get whiteboard token: From the
docs +updateresponse'sdata.board_tokensget the whiteboard token list - Fill whiteboard content: Switch to
lark-whiteboard-clito create whiteboard content and fill it into the whiteboard - Verify completion: Confirm that all whiteboards have actual content, not blank
Not applicable: Plain text records (logs/memos), data-intensive content (use tables), user explicitly wants text only.
⚠️ Warning: If only a blank whiteboard is created without filling in content, the task will be considered incomplete!
Additional notes
docs +search In addition to searching documents / Wiki, it also serves as a resource discovery entry point for "first locate the cloud space object, then switch back to the corresponding business skill to operate"; when the user verbally says "table / report", also prioritize starting from here.
Shortcuts (recommended to use first)
Shortcut is a high-level encapsulation of common operations (lark-cli docs +<verb> [flags]). For operations with a Shortcut, prioritize using it.
| 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. |
+mention-link |
Backlink creation: Convert text_run URL to mention_doc so that Lark correlation diagrams recognize it. Since lark-cli's markdown conversion always generates text_run, this method must be used to create backlinks. |