AGENT SKILL

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

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。

处理流程

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

    lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
    
  2. 从返回结果中提取关键信息

    • node.obj_type:文档类型(docx/doc/sheet/bitable/slides/file/mindnote)
    • node.obj_token:真实的文档 token(用于后续操作)
    • node.title:文档标题
  3. 根据 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 (直接使用)

操作流程(重要):

  1. create — 创建筛选

    • 用于首次创建筛选
    • ⚠️ range 必须覆盖所有需要筛选的列(如 B1:E200)
    • 如果已有筛选存在,再用 create 会覆盖整个筛选
  2. update — 更新筛选

    • 用于在已有筛选上添加/更新指定列的条件
    • 只需指定 col 和 condition,不需要 range
  3. delete — 删除筛选

  4. 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 再 create
  • Excess 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

shengdabai
shengdabai/Tony-Claude-Code-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.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

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.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

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.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

gstack

Router for the gstack skill suite. (gstack)

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

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.

★ 3
shengdabai
shengdabai/Tony-Claude-Code-Skills

dbs-video-extract

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

★ 3