SuperAPI AI Directory

lark-doc

General & other

View repository

Updated 10-16 08:33

About this skill

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!)

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

  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. Based on obj_type , use the corresponding API

    obj_type Description API Used
    docx New version cloud document drive file.comments.*、docx.*
    doc Old version cloud document 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 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 +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 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:

  1. Record the board token
  2. Check ../lark-whiteboard/SKILL.md to 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 --markdown Repeat multiple whiteboard tags in 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; 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.md to learn how to edit whiteboard content

Notes

  • Existing whiteboard content cannot be directly edited through lark-doc's docs +update Direct 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.md to 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 +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 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 to lark-drive to 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)

  1. Create a blank whiteboard placeholder: For creation scenarios use docs +create, for editing scenarios use docs +update to insert a blank whiteboard
  2. Get whiteboard token: From the docs +update response's data.board_tokens get the whiteboard token list
  3. Fill whiteboard content: Switch to lark-whiteboard-cli to create whiteboard content and fill it into the whiteboard
  4. 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.