lark-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

docs (v1)

CRITICAL — 开始前 MUST 先用 Read 工具读取
../lark-shared/SKILL.md
，其中包含认证、权限处理

CRITICAL — MUST use the Read tool to read
../lark-shared/SKILL.md
before starting, which contains authentication and permission handling

核心概念

Core Concepts

文档类型与 Token

Document Types and Tokens

飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的

file_token

。

In the Lark 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

文档 URL 格式与 Token 处理

URL Formats and Token Handling

URL 格式	示例	Token 类型	处理方式
`/docx/`	`https://example.larksuite.com/docx/doxcnxxxxxxxxx`	`file_token`	URL 路径中的 token 直接作为 `file_token` 使用
`/doc/`	`https://example.larksuite.com/doc/doccnxxxxxxxxx`	`file_token`	URL 路径中的 token 直接作为 `file_token` 使用
`/wiki/`	`https://example.larksuite.com/wiki/wikcnxxxxxxxxx`	`wiki_token`	⚠️ 不能直接使用，需要先查询获取真实的 `obj_token`
`/sheets/`	`https://example.larksuite.com/sheets/shtcnxxxxxxxxx`	`file_token`	URL 路径中的 token 直接作为 `file_token` 使用
`/drive/folder/`	`https://example.larksuite.com/drive/folder/fldcnxxxx`	`folder_token`	URL 路径中的 token 作为文件夹 token 使用

URL Format	Example	Token Type	Handling Method
`/docx/`	`https://example.larksuite.com/docx/doxcnxxxxxxxxx`	`file_token`	Use the token in the URL path directly as the `file_token`
`/doc/`	`https://example.larksuite.com/doc/doccnxxxxxxxxx`	`file_token`	Use the token in the URL path directly as the `file_token`
`/wiki/`	`https://example.larksuite.com/wiki/wikcnxxxxxxxxx`	`wiki_token`	⚠️ Cannot be used directly, you need to query to obtain the real `obj_token` first
`/sheets/`	`https://example.larksuite.com/sheets/shtcnxxxxxxxxx`	`file_token`	Use the token in the URL path directly as the `file_token`
`/drive/folder/`	`https://example.larksuite.com/drive/folder/fldcnxxxx`	`folder_token`	Use the token in the URL path as the folder token

Wiki 链接特殊处理（关键！）

Special Handling of Wiki Links (Critical!)

知识库链接（

/wiki/TOKEN

）背后可能是云文档、电子表格、多维表格等不同类型的文档。不能直接假设 URL 中的 token 就是 file_token，必须先查询实际类型和真实 token。

Knowledge base links (

/wiki/TOKEN

) may correspond to different document types such as cloud documents, spreadsheets, base tables, etc. Do not assume that the token in the URL is the file_token directly; you must first query the actual type and real token.

处理流程

Processing Flow

使用
wiki.spaces.get_node
查询节点信息

bash

lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

从返回结果中提取关键信息
- ```
node.obj_type
```
  ：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）
- ```
node.obj_token
```
  ：真实的文档 token（用于后续操作）
- ```
node.title
```
  ：文档标题

根据
obj_type
使用对应的 API

obj_type	说明	使用的 API
`docx`	新版云文档	`drive file.comments.` 、 `docx.`
`doc`	旧版云文档	`drive file.comments.*`
`sheet`	电子表格	`sheets.*`
`bitable`	多维表格	`bitable.*`
`slides`	幻灯片	`drive.*`
`file`	文件	`drive.*`
`mindnote`	思维导图	`drive.*`

Use
wiki.spaces.get_node
to query node information

bash

lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

Extract key information from the returned results
- ```
node.obj_type
```
  : Document type (docx/doc/sheet/bitable/slides/file/mindnote)
- ```
node.obj_token
```
  : Real document token (used for subsequent operations)
- ```
node.title
```
  : Document title

Use the corresponding API based on
obj_type

obj_type	Description	API to Use
`docx`	New version cloud document	`drive file.comments.` , `docx.`
`doc`	Old version cloud document	`drive file.comments.*`
`sheet`	Spreadsheet	`sheets.*`
`bitable`	Base table	`bitable.*`
`slides`	Slides	`drive.*`
`file`	File	`drive.*`
`mindnote`	Mind map	`drive.*`

查询示例

Query Example

bash

undefined

bash

undefined

查询 wiki 节点

Query wiki node

lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'


返回结果示例：
```json
{
   "node": {
      "obj_type": "docx",
      "obj_token": "xxxx",
      "title": "标题",
      "node_type": "origin",
      "space_id": "12345678910"
   }
}

lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'


Return result example:
```json
{
   "node": {
      "obj_type": "docx",
      "obj_token": "xxxx",
      "title": "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 (直接使用)

Wiki Space
└── Wiki Node
    ├── obj_type: docx (New version document)
    │   └── obj_token (Real document token)
    ├── obj_type: doc (Old version document)
    │   └── obj_token (Real document token)
    ├── obj_type: sheet (Spreadsheet)
    │   └── obj_token (Real document token)
    ├── obj_type: bitable (Base table)
    │   └── obj_token (Real document token)
    └── obj_type: file/slides/mindnote
        └── obj_token (Real document token)

Drive Folder
└── File (File/Document)
    └── file_token (Use directly)

重要说明：画板编辑

Important Note: Whiteboard Editing

⚠️ lark-doc skill 不能直接编辑已有画板内容，但
docs +update
可以新建空白画板

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

场景 1：已通过 docs +fetch 获取到文档内容和画板 token

Scenario 1: Obtained document content and whiteboard token via docs +fetch

如果用户已经通过

docs +fetch

拉取了文档内容，并且文档中已有画板（返回的 markdown 中包含

<whiteboard token="xxx"/>

标签），请引导用户：

记录画板的 token
查看
```
../lark-whiteboard/SKILL.md
```
了解如何编辑画板内容

If the user has pulled the document content via

docs +fetch

and the document already contains a whiteboard (the returned markdown includes the

<whiteboard token="xxx"/>

tag), guide the user to:

Record the whiteboard token
Check
```
../lark-whiteboard/SKILL.md
```
to learn how to edit whiteboard content

场景 2：刚创建画板，需要编辑

Scenario 2: Just created a whiteboard and need to edit it

如果用户刚通过

docs +update

创建了空白画板，需要编辑时： 步骤 1：按空白画板语法创建

在

--markdown

中直接传

<whiteboard type="blank"></whiteboard>

需要多个空白画板时，在同一个
```
--markdown
```
里重复多个 whiteboard 标签 步骤 2：从响应中记录 token
```
docs +update
```
成功后，读取响应字段
```
data.board_tokens
```
```
data.board_tokens
```
是新建画板的 token 列表，后续编辑直接使用这里的 token 步骤 3：引导编辑
记录需要编辑的画板 token
查看
```
../lark-whiteboard/SKILL.md
```
了解如何编辑画板内容

If the user just created a blank whiteboard via

docs +update

and needs to edit it: Step 1: Create using blank whiteboard syntax

Directly pass

<whiteboard type="blank"></whiteboard>

--markdown

When multiple blank whiteboards are needed, repeat multiple whiteboard tags in the same
```
--markdown
```
Step 2: Record the token from the response
After
```
docs +update
```
succeeds, read the response field
```
data.board_tokens
```
```
data.board_tokens
```
is a list of tokens for the newly created whiteboards; use these tokens directly for subsequent editing Step 3: Guide to editing
Record the token of the whiteboard to be edited
Check
```
../lark-whiteboard/SKILL.md
```
to learn how to edit whiteboard content

注意事项

Notes

已有画板内容无法通过 lark-doc 的
```
docs +update
```
直接编辑
编辑画板需要使用专门的
```
../lark-whiteboard/SKILL.md
```

Existing whiteboard content cannot be directly edited via lark-doc's
```
docs +update
```
Specialized
```
../lark-whiteboard/SKILL.md
```
is required for editing whiteboards

快速决策

Quick Decision

用户说“找一个表格”“按名称搜电子表格”“找报表”“最近打开的表格”，先用
```
lark-cli docs +search
```
做资源发现。
```
docs +search
```
不是只搜文档 / Wiki；结果里会直接返回
```
SHEET
```
等云空间对象。
拿到 spreadsheet URL / token 后，再切到
```
lark-sheets
```
做对象内部读取、筛选、写入等操作。

When users say "find a spreadsheet", "search for 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 cloud space objects such as
```
SHEET
```
.
After obtaining the spreadsheet URL/token, switch to
```
lark-sheets
```
for operations such as internal reading, filtering, and writing.

补充说明

Supplementary Notes

docs +search

除了搜索文档 / Wiki，也承担“先定位云空间对象，再切回对应业务 skill 操作”的资源发现入口角色；当用户口头说“表格 / 报表”时，也优先从这里开始。

In addition to searching documents/Wiki,

docs +search

also serves as a resource discovery entry for "locating cloud space objects first, then switching back to the corresponding business skill for operations"; when users verbally mention "spreadsheets/reports", start here first.

Shortcuts（推荐优先使用）

Shortcuts (Recommended for Priority Use)

Shortcut 是对常用操作的高级封装（

lark-cli docs +<verb> [flags]

）。有 Shortcut 的操作优先使用。

Shortcut	说明
`+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.

Shortcuts are advanced encapsulations of common operations (

lark-cli docs +<verb> [flags]

). Prioritize using operations with Shortcuts.

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.