lark-sheets
飞书电子表格:创建和操作电子表格。支持创建表格、创建/复制/删除/更新工作表、读写单元格、追加行数据、查找内容、导出文件。当用户需要创建电子表格、管理工作表、批量读写数据、在已知表格中查找内容、导出或下载表格时使用。若用户是想按名称或关键词搜索云空间里的表格文件,请改用 lark-drive 的 drive +search 先定位资源。
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- lark-sheets
- version
- 1.2.0
- metadata
- { "cliHelp": "lark-cli sheets --help", "requires": { "bins": [ "lark-cli" ] } }
- description
- 飞书电子表格:创建和操作电子表格。支持创建表格、创建/复制/删除/更新工作表、读写单元格、追加行数据、查找内容、导出文件。当用户需要创建电子表格、管理工作表、批量读写数据、在已知表格中查找内容、导出或下载表格时使用。若用户是想按名称或关键词搜索云空间里的表格文件,请改用 lark-drive 的 drive +search 先定位资源。
02 资源文件 10
- 参考文档references/lark-sheets-cell-data.md5.3 KB
- 参考文档references/lark-sheets-cell-images.md1.8 KB
- 参考文档references/lark-sheets-cell-style-and-merge.md3.6 KB
- 参考文档references/lark-sheets-dropdown.md3.7 KB
- 参考文档references/lark-sheets-filter-views.md5.6 KB
- 参考文档references/lark-sheets-float-images.md3.4 KB
- 参考文档references/lark-sheets-formula.md3.5 KB
- 参考文档references/lark-sheets-row-column-management.md4.7 KB
- 参考文档references/lark-sheets-sheet-management.md5.0 KB
- 参考文档references/lark-sheets-spreadsheet-management.md4.2 KB
03 SKILL.md 正文
sheets (v3)
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md,其中包含认证、权限处理
快速决策
- 已知 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使用对应的 APIobj_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 — 创建筛选
- 用于首次创建筛选
- ⚠️ range 必须覆盖所有需要筛选的列(如 B1:E200)
- 如果已有筛选存在,再用 create 会覆盖整个筛选
-
update — 更新筛选
- 用于在已有筛选上添加/更新指定列的条件
- 只需指定 col 和 condition,不需要 range
-
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"} |
| 邮箱 | "邮箱字符串" |
"user@example.com" |
| 公式 | {"type":"formula","text":"=公式"} |
{"type":"formula","text":"=SUM(A1:A10)"} |
| @人 | {"type":"mention","text":"标识","textType":"email|openId|unionId","notify":false} |
{"type":"mention","text":"user@example.com","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。
限制:
- 公式支持 IMPORTRANGE 跨表引用(最多 5 层嵌套、每个工作表最多 100 个引用)
- @人仅支持同租户用户,单次最多 50 人
- 下拉列表需先配置下拉选项,否则
multipleValue写入会变成纯文本。配置方法见references/lark-sheets-dropdown.md#set-dropdown。值中的字符串不能包含逗号
Shortcuts(推荐优先使用)
Shortcut 是对常用操作的高级封装(lark-cli sheets +<verb> [flags])。有 Shortcut 的操作优先使用。
Spreadsheet Management
对应参考文档:spreadsheet-management
| Shortcut | 说明 |
|---|---|
+create |
Create a spreadsheet (optional header row and initial data) |
+info |
View spreadsheet metadata and sheet information |
+export |
Export a spreadsheet (async task polling + optional download) |
Sheet Management
对应参考文档:sheet-management
| Shortcut | 说明 |
|---|---|
+create-sheet |
Create a sheet in an existing spreadsheet |
+copy-sheet |
Copy a sheet within a spreadsheet |
+delete-sheet |
Delete a sheet from a spreadsheet |
+update-sheet |
Update sheet title, position, visibility, freeze, or protection |
Cell Data
对应参考文档:cell-data
| Shortcut | 说明 |
|---|---|
+read |
Read spreadsheet cell values |
+write |
Write to spreadsheet cells (overwrite mode) |
+append |
Append rows to a spreadsheet |
+find |
Find cells in a spreadsheet |
+replace |
Find and replace cell values |
Cell Style And Merge
对应参考文档:cell-style-and-merge
| Shortcut | 说明 |
|---|---|
+set-style |
Set cell style for a range |
+batch-set-style |
Batch set cell styles for multiple ranges |
+merge-cells |
Merge cells in a spreadsheet |
+unmerge-cells |
Unmerge (split) cells in a spreadsheet |
Cell Images
对应参考文档:cell-images
| Shortcut | 说明 |
|---|---|
+write-image |
Write an image into a spreadsheet cell |
Row Column Management
对应参考文档:row-column-management
| Shortcut | 说明 |
|---|---|
+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 |
Filter Views
对应参考文档:filter-views
| Shortcut | 说明 |
|---|---|
+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 |
Dropdown
对应参考文档:dropdown
| Shortcut | 说明 |
|---|---|
+set-dropdown |
设置下拉列表(multipleValue 写入的前置步骤) |
+update-dropdown |
更新下拉列表选项 |
+get-dropdown |
查询下拉列表配置 |
+delete-dropdown |
删除下拉列表 |
Float Images
对应参考文档:float-images
| Shortcut | 说明 |
|---|---|
+media-upload |
上传本地图片素材,返回 file_token(供 +create-float-image 使用;>20MB 自动分片) |
+create-float-image |
创建浮动图片 |
+update-float-image |
更新浮动图片属性 |
+get-float-image |
获取浮动图片 |
+list-float-images |
查询所有浮动图片 |
+delete-float-image |
删除浮动图片 |
Formula
对应参考文档:formula
浮动图片相关的读接口只返回元数据(含
float_image_token),不包含图片字节。要读取图片内容,用 token 调lark-cli docs +media-preview --token "<float_image_token>" --output ./image.png。
API Resources
lark-cli schema sheets.<resource>.<method> # 调用 API 前必须先查看参数结构
lark-cli sheets <resource> <method> [flags] # 调用 API
重要:使用原生 API 时,必须先运行
schema查看--data/--params参数结构,不要猜测字段格式。
spreadsheets
create— 创建电子表格get— 获取电子表格信息patch— 修改电子表格属性
spreadsheet.sheet.filters
create— 创建筛选delete— 删除筛选get— 获取筛选update— 更新筛选
spreadsheet.sheets
find— 查找单元格
spreadsheet.sheet.float_images
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 |
04 同仓库更多 Skills
seedance-prompt-en
Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.
onepage-pdf
Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.
native-feel-cross-platform-desktop
Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.
gstack
Router for the gstack skill suite. (gstack)
fireworks-tech-graph
Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.
dbs-video-extract
接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。