Lark Sheets

sheets (v3)

CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../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 处理

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

查询示例

# 查询 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 时重复添加同一列条件

Shortcuts（推荐优先使用）

Shortcut 是对常用操作的高级封装（lark-cli sheets +<verb> [flags]）。有 Shortcut 的操作优先使用。

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 — 查找单元格

权限表

sheets +append（追加行）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

本 skill 对应 shortcut：lark-cli sheets +append。

• --values 必须是二维数组 JSON
• 内置尺寸校验：最多 5000 行、每行最多 100 列
• --range 可以是 <sheetId> 或 <sheetId>!A1:D10
• 若已传 --sheet-id，--range 也可写 A1:D10 或 C2

[!CAUTION]

这是写入操作 —— 执行前必须确认用户意图。可以先用 --dry-run 预览。

命令

# 追加一行（6 列示例）
lark-cli sheets +append --spreadsheet-token "shtxxxxxxxx" \
  --range "<sheetId>!A1" \
  --values '[["华东一仓","2026-03",125000,98000,168000,"41.7%"]]'

# 配合 --sheet-id，可直接写相对范围
lark-cli sheets +append --spreadsheet-token "shtxxxxxxxx" \
  --sheet-id "<sheetId>" --range "A1" \
  --values '[["A","B"]]'

# 仅预览参数（不发请求）
lark-cli sheets +append --spreadsheet-token "shtxxxxxxxx" --range "<sheetId>!A1" \
  --values '[["A","B"]]' --dry-run

参数

输出

JSON，包含：

• table_range
• updated_range/updated_rows/updated_columns/updated_cells
• revision

参考

• lark-sheets-read — 追加后可 read 验证
• lark-shared — 认证和全局参数

sheets +create（创建表格）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

本 skill 对应 shortcut：lark-cli sheets +create。

特性：

• 一步创建表格并返回 URL
• 可选 --headers/--data 在创建后自动写入到第一个工作表的 A1 开始

[!CAUTION]

这是写入操作 —— 执行前必须确认用户意图。可以先用 --dry-run 预览。

[!IMPORTANT]

如果表格是以应用身份（bot）创建的，agent 在创建成功后应默认继续使用 bot 身份，为当前可用的 user 身份添加该表格的 full_access（管理员）权限。推荐流程：

1. 先用 lark-cli contact +get-user 获取当前用户信息，并从返回结果中读取该用户的 open_id

2. 再切回 bot 身份，使用这个 open_id 给该用户授权该表格的 full_access（管理员）权限

>

如果 lark-cli contact +get-user 无法执行，或者本地没有可用的 user 身份、拿不到当前用户的 open_id，则应视为“本地没有可用的 user 身份”，明确说明因此未完成授权。

>

回复创建结果时，除 spreadsheet_token / url 外，还必须明确告知用户授权结果：

- 如果授权成功：直接说明当前 user 已获得该表格的管理员权限

- 如果本地没有可用的 user 身份：明确说明因此未完成授权

- 如果授权失败：明确说明表格已创建成功，但授权失败，并透出失败原因；同时提示用户可以稍后重试授权，或继续使用应用身份（bot）处理该表格

>

如果授权未完成，应继续给出后续引导：用户可以稍后重试授权，也可以继续使用应用身份（bot）处理该表格；如果希望后续改由自己管理，也可将表格 owner 转移给该用户。

>

仍然不要擅自执行 owner 转移。 如果用户需要把 owner 转给自己，必须单独确认。

命令

# 最简单：只创建
lark-cli sheets +create --title "仓库管理营收报表"

# 创建并写入表头 + 初始数据
lark-cli sheets +create --title "仓库管理营收报表" \
  --headers '["仓库","统计月份","入库金额","出库金额","销售收入","毛利率"]' \
  --data '[["华东一仓","2026-03",125000,98000,168000,"41.7%"]]'

# 创建到指定文件夹（folder_token）
lark-cli sheets +create --title "测试表" --folder-token "fldbc_xxx"

# 仅预览参数（不发请求）
lark-cli sheets +create --title "测试表" --dry-run

参数

输出

JSON，包含：

• spreadsheet_token
• title
• url

参考

• lark-sheets-write — 后续覆盖写入
• lark-sheets-append — 后续追加写入
• lark-shared

sheets +export（导出表格）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

本 skill 对应 shortcut：lark-cli sheets +export。

特性：

• 创建导出任务并轮询完成（默认最多约 30 秒）
• 支持导出 xlsx 或 csv
• 若提供 --output-path，会直接下载并保存到本地；否则输出 file_token 供后续处理

命令

# 导出为 xlsx 并保存到本地
lark-cli sheets +export --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --file-extension xlsx --output-path "./report.xlsx"

# 导出为 csv（必须指定 sheet-id）
lark-cli sheets +export --spreadsheet-token "shtxxxxxxxx" \
  --file-extension csv --sheet-id "<sheetId>" --output-path "./report.csv"

# 不下载：只获取 file_token
lark-cli sheets +export --spreadsheet-token "shtxxxxxxxx" --file-extension xlsx

# 仅预览参数（不发请求）
lark-cli sheets +export --url "https://..." --file-extension xlsx --output-path "./report.xlsx" --dry-run

参数

输出

• 若提供 --output-path：输出 file_path/file_name/file_size
• 否则：输出 file_token/file_name/file_size

参考

• lark-sheets-info — 先获取 sheet_id
• lark-shared

sheets +find（查找单元格）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

边界说明： sheets +find 不是云空间搜索，只在一个已知 spreadsheet 内查找单元格内容。如果还不知道目标 spreadsheet 是哪一个，先用 `lark-doc` 的 docs +search 定位文件；docs +search 的结果里会直接返回 SHEET 类型，再回到 sheets +info / sheets +find。

本 skill 对应 shortcut：lark-cli sheets +find。

特性：

• --sheet-id 必填（建议先用 sheets +info 获取）
• --range 可写完整范围（如 <sheetId>!A1:D200）
• 若已传 --sheet-id，--range 也可直接写 A1:D200 或 C2
• 默认区分大小写；加 --ignore-case 可不区分大小写
• 可选 --search-by-regex 按正则匹配

命令

# 在指定范围查找（默认区分大小写）
lark-cli sheets +find --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --sheet-id "<sheetId>" --find "张三" --range "A1:H200"

# 不区分大小写
lark-cli sheets +find --spreadsheet-token "shtxxxxxxxx" \
  --sheet-id "<sheetId>" --find "仓库管理营收报表" --range "H1:H500" --ignore-case

# 正则查找
lark-cli sheets +find --spreadsheet-token "shtxxxxxxxx" \
  --sheet-id "<sheetId>" --find "仓库管理营收报表" --range "H1:H500" --search-by-regex

# 仅预览参数（不发请求）
lark-cli sheets +find --url "https://..." --sheet-id "<sheetId>" --find "xxx" --dry-run

参数

输出

JSON，包含：

• matched_cells
• matched_formula_cells
• rows_count

参考

• lark-sheets-info
• lark-shared

sheets +info（查看表格/工作表信息）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

本 skill 对应 shortcut：lark-cli sheets +info。

用于：

• 从表格 URL / token 获取 spreadsheet_token
• 列出工作表（sheet_id、标题、行列数等），便于后续 +read/+write/+find/+export 使用

命令

# 传 URL（支持用户粘贴时带空格/引号/反引号；支持 wiki URL）
lark-cli sheets +info --url "https://example.larksuite.com/sheets/shtxxxxxxxx"

# 传 spreadsheet_token
lark-cli sheets +info --spreadsheet-token "shtxxxxxxxx"

# 仅预览请求参数（不发请求）
lark-cli sheets +info --url "https://..." --dry-run

参数

输出

JSON，包含：

• spreadsheet_token：后续命令复用
• sheets[]：每个工作表的 sheet_id、title、row_count、column_count 等

参考

• lark-shared — 认证和全局参数

sheets +read（读取单元格）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

本 skill 对应 shortcut：lark-cli sheets +read。

内置能力：

• 支持 --url / --spreadsheet-token 二选一（URL 支持 wiki；支持粘贴时带空格/引号/反引号）
• 若已传 --sheet-id，--range 可写 A1:D10 或 C2
• 将单元格富文本 segment 数组拍平成纯文本，减少输出冗余
• 默认最多返回 200 行（超出会 truncated=true）

命令

# 读取指定范围（推荐）
lark-cli sheets +read --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --range "<sheetId>!A1:H20"

# 配合 --sheet-id，可直接写相对范围或单个单元格
lark-cli sheets +read --spreadsheet-token "shtxxxxxxxx" \
  --sheet-id "<sheetId>" --range "C2"

# 仅指定工作表（不含 A1:D10），读取整个工作表（仍会做 200 行截断）
lark-cli sheets +read --spreadsheet-token "shtxxxxxxxx" --range "<sheetId>"

# 不指定 range：读取 --sheet-id 对应工作表；再不指定则读取第一个工作表
lark-cli sheets +read --spreadsheet-token "shtxxxxxxxx" --sheet-id "<sheetId>"

# 控制值渲染方式
lark-cli sheets +read --url "https://..." --range "<sheetId>!A1:D10" --value-render-option Formula

# 仅预览参数（不发请求）
lark-cli sheets +read --url "https://..." --range "<sheetId>!A1:D10" --dry-run

参数

输出

JSON，包含：

• range：服务端实际读取的范围
• values：二维数组（已做富文本拍平）
• truncated/total_rows：当行数超过 200 时出现

参考

• lark-sheets-info — 先获取 sheet_id
• lark-shared — 认证和全局参数

sheets +write（写入单元格 / 覆盖写入）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

本 skill 对应 shortcut：lark-cli sheets +write。

• --values 必须是二维数组 JSON
• 内置尺寸校验：最多 5000 行、每行最多 100 列
• 若已传 --sheet-id，--range 可写 A1:D10 或 C2
• 若 --range 只给了 <sheetId> 或单个起始单元格，工具会按 --values 的尺寸自动展开为矩形范围

[!CAUTION]

这是写入操作 —— 执行前必须确认用户意图。可以先用 --dry-run 预览。

命令

# 覆盖写入一个矩形区域
lark-cli sheets +write --spreadsheet-token "shtxxxxxxxx" \
  --range "<sheetId>!A1:B2" \
  --values '[["name","age"],["alice",18]]'

# 已有 --sheet-id 时，可直接写相对范围
lark-cli sheets +write --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --sheet-id "<sheetId>" --range "C2" \
  --values '[["hello"]]'

# 只给 sheetId：会从 A1 开始，按 values 尺寸自动展开
lark-cli sheets +write --url "https://example.larksuite.com/sheets/shtxxxxxxxx" \
  --range "<sheetId>" \
  --values '[["hello","world"]]'

# 仅预览参数（不发请求）
lark-cli sheets +write --spreadsheet-token "shtxxxxxxxx" --range "<sheetId>!A1:B2" \
  --values '[["name","age"],["alice",18]]' --dry-run

参数

输出

JSON，包含：

• updated_range/updated_rows/updated_columns/updated_cells
• revision

参考

• lark-sheets-read — 写入前可先 read 验证范围
• lark-shared — 认证和全局参数