| name | lark-sheets |
| version | 1.1.0 |
| description | 飞书电子表格：创建和操作电子表格。创建表格并写入表头和数据、读取和写入单元格、追加行数据、在已知电子表格中查找单元格内容、导出表格文件。当用户需要创建电子表格、批量读写数据、在已知表格中查找内容、导出或下载表格时使用。若用户是想按名称或关键词搜索云空间里的表格文件，请改用 lark-doc 的 docs +search 先定位资源。 |
| metadata | {"requires":{"bins":["lark-cli"]},"cliHelp":"lark-cli sheets --help"} |
sheets (v3)
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理
快速决策
- 按标题或关键词找云空间里的表格文件，先用
lark-cli docs +search。
docs +search 会直接返回 SHEET 结果，不要把它误解成只能搜文档 / Wiki。- 已知 spreadsheet URL / token 后，再进入
sheets +info、sheets +read、sheets +find 等对象内部操作。
核心概念
文档类型与 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 使用 |
Wiki 链接特殊处理（关键！）
知识库链接（/wiki/TOKEN）背后可能是云文档、电子表格、多维表格等不同类型的文档。不能直接假设 URL 中的 token 就是 file_token，必须先查询实际类型和真实 token。
处理流程
-
使用 wiki.spaces.get_node 查询节点信息
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.* |
查询示例
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
返回结果示例：
{
"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列)的双重筛选：
lark-cli sheets spreadsheet.sheet.filters delete \
--params '{"spreadsheet_token":"<spreadsheet_token>","sheet_id":"<sheet_id>"}'
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"}'
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 再 createExcess 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) |
API Resources
lark-cli schema sheets.<resource>.<method>
lark-cli sheets <resource> <method> [flags]
重要：使用原生 API 时，必须先运行 schema 查看 --data / --params 参数结构，不要猜测字段格式。
spreadsheets
create — 创建电子表格get — 获取电子表格信息patch — 修改电子表格属性
spreadsheet.sheet.filters
create — 创建筛选delete — 删除筛选get — 获取筛选update — 更新筛选
spreadsheet.sheets
权限表
| 方法 | 所需 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 |
