lark-sheets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sheets (v3)

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

重要提示 — 开始前必须先用 Read 工具读取
../lark-shared/SKILL.md
，其中包含认证、权限处理相关内容

快速决策

按标题或关键词找云空间里的表格文件，先用
```
lark-cli docs +search
```
。
```
docs +search
```
会直接返回
```
SHEET
```
结果，不要把它误解成只能搜文档 / Wiki。
已知 spreadsheet URL / token 后，再进入
```
sheets +info
```
、
```
sheets +read
```
、
```
sheets +find
```
等对象内部操作。

按标题或关键词找云空间里的表格文件，先用
```
lark-cli docs +search
```
。
```
docs +search
```
会直接返回
```
SHEET
```
结果，不要把它误解成只能搜文档 / Wiki。
已知 spreadsheet URL / token 后，再进入
```
sheets +info
```
、
```
sheets +read
```
、
```
sheets +find
```
等对象内部操作。

核心概念

文档类型与 Token

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

file_token

。

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

file_token

。

文档 URL 格式与 Token 处理

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 格式	示例	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 使用

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

知识库链接（

/wiki/TOKEN

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

知识库链接（

/wiki/TOKEN

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

处理流程

使用
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.*`

使用
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.*`

查询示例

bash

undefined

bash

undefined

查询 wiki 节点

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"}'


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

资源关系

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 (直接使用)

操作流程（重要）：

create — 创建筛选
- 用于首次创建筛选
- ⚠️ range 必须覆盖所有需要筛选的列（如 B1:E200）
- 如果已有筛选存在，再用 create 会覆盖整个筛选
update — 更新筛选
- 用于在已有筛选上添加/更新指定列的条件
- 只需指定 col 和 condition，不需要 range
delete — 删除筛选
get — 获取筛选状态

多列筛选示例：

创建媒体名称(B列)和情感分析(E列)的双重筛选：

bash

undefined

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 (直接使用)

操作流程（重要）：

create — 创建筛选
- 用于首次创建筛选
- ⚠️ range 必须覆盖所有需要筛选的列（如 B1:E200）
- 如果已有筛选存在，再用 create 会覆盖整个筛选
update — 更新筛选
- 用于在已有筛选上添加/更新指定列的条件
- 只需指定 col 和 condition，不需要 range
delete — 删除筛选
get — 获取筛选状态

多列筛选示例：

创建媒体名称(B列)和情感分析(E列)的双重筛选：

bash

undefined

1. 删除现有筛选（如有）

lark-cli sheets spreadsheet.sheet.filters delete
--params '{"spreadsheet_token":"<spreadsheet_token>","sheet_id":"<sheet_id>"}'

2. 创建第一个筛选，range 覆盖所有要筛选的列

lark-cli sheets spreadsheet.sheet.filters create
--params '{"spreadsheet_token":"<spreadsheet_token>","sheet_id":"<sheet_id>"}'
--data '{"col":"B","condition":{"expected":["xx"],"filter_type":"multiValue"},"range":"<sheet_id>!B1:E200"}'

3. 添加第二个筛选条件

lark-cli sheets spreadsheet.sheet.filters update
--params '{"spreadsheet_token":"<spreadsheet_token>","sheet_id":"<sheet_id>"}'
--data '{"col":"E","condition":{"expected":["xx"],"filter_type":"multiValue"}}'


**常见错误：**
- `Wrong Filter Value`：筛选已存在，需要先 delete 再 create
- `Excess Limit`：update 时重复添加同一列条件


**常见错误：**
- `Wrong Filter Value`：筛选已存在，需要先 delete 再 create
- `Excess Limit`：update 时重复添加同一列条件

Shortcuts（推荐优先使用）

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

lark-cli sheets +<verb> [flags]

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

Shortcut	说明
`+info`	View spreadsheet and sheet information
`+read`	Read spreadsheet cell values
`+write`	Write to spreadsheet cells (overwrite mode)
`+append`	Append rows to a spreadsheet
`+find`	Find cells in a spreadsheet
`+create`	Create a spreadsheet (optional header row and initial data)
`+export`	Export a spreadsheet (async task polling + optional download)

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

lark-cli sheets +<verb> [flags]

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

Shortcut	说明
`+info`	查看电子表格和工作表信息
`+read`	读取电子表格单元格值
`+write`	写入电子表格单元格（覆盖模式）
`+append`	向电子表格追加行数据
`+find`	在电子表格中查找单元格
`+create`	创建电子表格（可选表头行和初始数据）
`+export`	导出电子表格（异步任务轮询 + 可选下载）

API Resources

bash

lark-cli schema sheets.<resource>.<method>   # 调用 API 前必须先查看参数结构
lark-cli sheets <resource> <method> [flags] # 调用 API

重要：使用原生 API 时，必须先运行
schema
查看
--data
/
--params
参数结构，不要猜测字段格式。

bash

lark-cli schema sheets.<resource>.<method>   # 调用 API 前必须先查看参数结构
lark-cli sheets <resource> <method> [flags] # 调用 API

重要：使用原生 API 时，必须先运行
schema
查看
--data
/
--params
参数结构，不要猜测字段格式。

spreadsheets

```
create
```
— 创建电子表格
- ```
get
```
  — 获取电子表格信息
- ```
patch
```
  — 修改电子表格属性

```
create
```
— 创建电子表格
- ```
get
```
  — 获取电子表格信息
- ```
patch
```
  — 修改电子表格属性

spreadsheet.sheet.filters

```
create
```
— 创建筛选
- ```
delete
```
  — 删除筛选
- ```
get
```
  — 获取筛选
- ```
update
```
  — 更新筛选

```
create
```
— 创建筛选
- ```
delete
```
  — 删除筛选
- ```
get
```
  — 获取筛选
- ```
update
```
  — 更新筛选

spreadsheet.sheets

```
find
```
— 查找单元格

```
find
```
— 查找单元格

权限表

方法	所需 scope
`spreadsheets.create`	`sheets:spreadsheet:create`
`spreadsheets.get`	`sheets:spreadsheet.meta:read`
`spreadsheets.patch`	`sheets:spreadsheet.meta:write_only`
`spreadsheet.sheet.filters.create`	`sheets:spreadsheet:write_only`
`spreadsheet.sheet.filters.delete`	`sheets:spreadsheet:write_only`
`spreadsheet.sheet.filters.get`	`sheets:spreadsheet:read`
`spreadsheet.sheet.filters.update`	`sheets:spreadsheet:write_only`
`spreadsheet.sheets.find`	`sheets:spreadsheet:read`

方法	所需 scope
`spreadsheets.create`	`sheets:spreadsheet:create`
`spreadsheets.get`	`sheets:spreadsheet.meta:read`
`spreadsheets.patch`	`sheets:spreadsheet.meta:write_only`
`spreadsheet.sheet.filters.create`	`sheets:spreadsheet:write_only`
`spreadsheet.sheet.filters.delete`	`sheets:spreadsheet:write_only`
`spreadsheet.sheet.filters.get`	`sheets:spreadsheet:read`
`spreadsheet.sheet.filters.update`	`sheets:spreadsheet:write_only`
`spreadsheet.sheets.find`	`sheets:spreadsheet:read`