飞书电子表格:创建和操作电子表格。创建表格并写入表头和数据、读取和写入单元格、追加行数据、在已知电子表格中查找单元格内容、导出表格文件。当用户需要创建电子表格、批量读写数据、在已知表格中查找内容、导出或下载表格时使用。若用户是想按名称或关键词搜索云空间里的表格文件,请改用 lark-doc 的 docs +search 先定位资源。
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md,其中包含认证、权限处理
lark-cli docs +search。docs +search 会直接返回 SHEET 结果,不要把它误解成只能搜文档 / Wiki。sheets +info、sheets +read、sheets +find 等对象内部操作。飞书开放平台中,不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作(如添加评论、下载文件等)时,必须先获取正确的 file_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/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.* |
# 查询 wiki 节点
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 — 创建筛选
update — 更新筛选
delete — 删除筛选
get — 获取筛选状态
多列筛选示例:
创建媒体名称(B列)和情感分析(E列)的双重筛选:
# 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 再 createExcess Limit:update 时重复添加同一列条件接受二维数组的 shortcut(+write/+append 的 --values、+create 的 --data)中,每个单元格值支持以下类型。公式、带文本链接、@人、@文档、下拉列表必须使用对象格式,直接传字符串会被当作纯文本存储。
| 类型 | 写入格式 | 示例 |
|---|---|---|
| 字符串 | "文本" | "hello" |
| 数字 | 数字 | 123、3.14 |
| 日期 | 数字(自 1899-12-30 起的天数,需先设单元格日期格式) | 42101 |
| 链接(纯 URL) | "URL 字符串" | "https://example.com" |
| 链接(带文本) | {"type":"url","text":"显示文本","link":"URL"} | {"type":"url","text":"飞书","link":"https://www.feishu.cn"} |
| 邮箱 | "邮箱字符串" | "[email protected]" |
| 公式 | {"type":"formula","text":"=公式"} | {"type":"formula","text":"=SUM(A1:A10)"} |
| @人 | {"type":"mention","text":"标识","textType":"email|openId|unionId","notify":false} | {"type":"mention","text":"[email protected]","textType":"email","notify":false}(notify 可选,默认 false;仅在用户明确要求通知时设为 true) |
| @文档 | {"type":"mention","textType":"fileToken","text":"token","objType":"类型"} | {"type":"mention","textType":"fileToken","text":"shtXXX","objType":"sheet"} |
| 下拉列表 | {"type":"multipleValue","values":[值1,值2]} | {"type":"multipleValue","values":["选项A","选项B"]} |
写入公式示例:
# ✅ 正确:使用对象格式
lark-cli sheets +write --url "URL" --sheet-id "sheetId" --range "C6" \
--values '[[{"type":"formula","text":"=SUM(C2:C5)"}]]'
# ❌ 错误:直接传字符串,会被存为纯文本
lark-cli sheets +write --url "URL" --sheet-id "sheetId" --range "C6" \
--values '[["=SUM(C2:C5)"]]'
公式语法参考:涉及 ARRAYFORMULA、原生数组函数、MAP/LAMBDA、日期差、Excel 公式改写等飞书特有规则时,先阅读
references/lark-sheets-formula.md。
限制:
multipleValue 写入会变成纯文本。配置方法见 references/lark-sheets-set-dropdown.md。值中的字符串不能包含逗号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) |
+write-image | Write an image into a spreadsheet cell |
+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) |
+merge-cells | Merge cells in a spreadsheet |
+unmerge-cells | Unmerge (split) cells in a spreadsheet |
+replace | Find and replace cell values |
+set-style | Set cell style for a range |
+batch-set-style | Batch set cell styles for multiple ranges |
+add-dimension | Add rows or columns at the end of a sheet |
+insert-dimension | Insert rows or columns at a specified position |
+update-dimension | Update row or column properties (visibility, size) |
+move-dimension | Move rows or columns to a new position |
+delete-dimension | Delete rows or columns |
+create-filter-view | Create a filter view |
+update-filter-view | Update a filter view |
+list-filter-views | List all filter views in a sheet |
+get-filter-view | Get a filter view by ID |
+delete-filter-view | Delete a filter view |
+create-filter-view-condition | Create a filter condition on a filter view |
+update-filter-view-condition | Update a filter condition |
+list-filter-view-conditions | List all filter conditions of a filter view |
+get-filter-view-condition | Get a filter condition by column |
+delete-filter-view-condition | Delete a filter condition |
| Shortcut | 说明 |
|---|---|
+set-dropdown | 设置下拉列表(multipleValue 写入的前置步骤) |
+update-dropdown | 更新下拉列表选项 |
+get-dropdown | 查询下拉列表配置 |
+delete-dropdown | 删除下拉列表 |
| Shortcut | 说明 |
|---|---|
+media-upload | 上传本地图片素材,返回 file_token(供 +create-float-image 使用;>20MB 自动分片) |
+create-float-image | 创建浮动图片 |
+update-float-image | 更新浮动图片属性 |
+get-float-image | 获取浮动图片 |
+list-float-images | 查询所有浮动图片 |
+delete-float-image | 删除浮动图片 |
浮动图片相关的读接口只返回元数据(含
float_image_token),不包含图片字节。要读取图片内容,用 token 调lark-cli docs +media-preview --token "<float_image_token>" --output ./image.png。
lark-cli schema sheets.<resource>.<method> # 调用 API 前必须先查看参数结构
lark-cli sheets <resource> <method> [flags] # 调用 API
重要:使用原生 API 时,必须先运行
schema查看--data/--params参数结构,不要猜测字段格式。
create — 创建电子表格get — 获取电子表格信息patch — 修改电子表格属性create — 创建筛选delete — 删除筛选get — 获取筛选update — 更新筛选find — 查找单元格create — 创建浮动图片patch — 更新浮动图片get — 获取浮动图片query — 查询所有浮动图片delete — 删除浮动图片| 方法 | 所需 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 |
spreadsheet.sheet.float_images.create | sheets:spreadsheet:write_only |
spreadsheet.sheet.float_images.patch | sheets:spreadsheet:write_only |
spreadsheet.sheet.float_images.get | sheets:spreadsheet:read |
spreadsheet.sheet.float_images.query | sheets:spreadsheet:read |
spreadsheet.sheet.float_images.delete | sheets:spreadsheet:write_only |