lark-sheets

name: lark-sheets version: 3.0.0 description: "飞书电子表格：创建和操作电子表格。支持创建表格、管理工作表与行列结构（增删/合并/调整尺寸/隐藏/冻结）、读写单元格（值/公式/样式/批注/单元格图片）、查找替换、多操作原子批量更新，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象的创建与维护。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）、金融/财务建模（DCF、三张表、预算、Sensitivity 等）等任务时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。" metadata: requires: bins: ["lark-cli"] siblings: ["lark-shared"] cliHelp: "lark-cli sheets --help"

sheets

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理。

术语约定

下列词在本 skill 各文档中可能交替出现，但指同一对象；解析用户口语时按此映射，不要当成不同概念：

每类对象用各自的主键 flag 定位（命名不统一，按此表对照，不要凭直觉拼）：

场景 → 命令速查（拿不准命令名先查这里，别按直觉拼）

把高频意图映射到真实存在的 shortcut / flag。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移命令名或 flag，先对照本表，避免一次必然失败的试错。完整 shortcut 见各工具参考。

⚠️ 两种图片别选错：图若绑定某条记录、要随行排序 / 筛选 / 增删（凭证 / 证件照 / 每行配图，话里带「对应 / 每行 / 这列」等绑定词）→ 单元格图片 +cells-set-image；只是自由摆放的装饰（logo / 水印 / 封面）→ 浮动图片 +float-image-create。别因「浮动图更好控制 / 更熟」默认选浮动图。 ⚠️ 纯文本还是数值语义：要写的列里有数字 / 金额 / 百分比 / 日期 / 计数 → +table-put（写入已有表；外层 {"sheets":[...]} 包裹、列 pandas dtype 用 dtypes、展示格式用 formats，保留排序 / 求和 / 图表 / 透视能力；目标表还不存在就用 +workbook-create --sheets，同 typed 协议、一步建表 + 写入，别先建空表再 +table-put）；只有纯文本才用 +csv-put。两者写完显示可以完全相同，但 +csv-put 落的是文本、不能参与计算——别把数值在本地拼成带 $ / % 的字符串再走 +csv-put。 ⚠️ 定位 flag：+cells-get / +cells-set / +csv-get 用 --range；+csv-put 规范用 --start-cell（单个左上角锚点格），也接受 --range 别名（区间自动取左上角），二者择一即可。 ⚠️ 读取附加信息一律走 +cells-get --include …，没有 --with-styles 这类 flag；看合并单元格用 +sheet-info 的 merged_cells，不要在 +cells-get 里找 merge flag。

References

本 skill 的 reference 分两组：先读通用方法与规范（横切所有任务的工作流、铁律、样式、公式规则，不含具体 shortcut），它们规定了"怎么做对"；再按操作对象进入工具参考查具体 shortcut 与调用细节。编辑类任务务必先过一遍通用方法与规范，其中的铁律对所有工具参考一律生效。

通用方法与规范（先读，横切所有任务，不含具体 shortcut）

按对象的工具参考（含 shortcut）

公共 flag 速查

各 reference 的每个 shortcut 标题下用一行徽章标注该 shortcut 支持的公共 / 系统 flag，例如：

• _公共四件套 · 系统：--dry-run_ — URL/token + sheet 定位（两组各必给一个，详见下方「公共 flag」），加 --dry-run
• _公共：URL/token（无 sheet 定位） · 系统：--yes、--dry-run_ — 只接 URL/token，常见于 +batch-update 等不强制 sheet 定位的 shortcut

徽章里只列名字。type / 必填 / 描述都在本段统一声明：

公共 flag（定位资源）

公共四件套 = --url / --spreadsheet-token / --sheet-id / --sheet-name，分成两组 XOR，每组都必须给且只能给一个（XOR = 二选一必填，不是"可选"）：

1. spreadsheet 定位（必填）：--url 与 --spreadsheet-token 二选一，必须给其中之一。两个都不给 → 校验报错 specify at least one of --url or --spreadsheet-token；两个都给 → 互斥冲突。
   • --url 解析 /sheets/、/spreadsheets/ 与 /wiki/ 三种链接（从路径里抽出 token；也可以直接把裸 token 传给 --spreadsheet-token）。其它形态的链接不会被解析成表格 token。
   • /wiki/ 知识库链接可直接传 --url：会自动定位到链接背后的电子表格；若该链接背后不是电子表格（而是文档 / 多维表格等），则报错。
   • 例外：+workbook-create（新建表 + 可选写入数据）与 +workbook-import（把本地文件导入为新表）都产出一张还不存在的表格，不接受任何 spreadsheet / sheet 定位 flag——+workbook-create 只有 --title / --folder-token / --values / --styles / --sheets，+workbook-import 只有 --file（必填）/ --folder-token / --name。
2. sheet 定位（公共四件套 shortcut 必填）：--sheet-id 与 --sheet-name 二选一，必须给其中之一。两个都不给 → 校验报错 specify at least one of --sheet-id or --sheet-name。
   • ⚠️ 不确定 sheet 名时禁止直接猜 Sheet1：除非用户对话明确说出 sheet 名 / id，或上下文（之前的工具调用 / URL 锚点 ?sheet=xxx）已经出现过具体值，否则第一步先调 +workbook-info --url "..."（或 --spreadsheet-token）拿 sheets[].sheet_id / sheets[].title 列表再选。中文环境下子表常叫"数据" / "Sheet"（无数字）/ "工作表 1" / 业务名，猜 Sheet1 大概率撞 sheet not found，比先查多耗一次失败调用 + 重试。
   • ⚠️ --range 里的 Sheet1! 前缀不能替代 sheet 定位：即使写了 --range 'Sheet1!A1:B2'，仍必须额外传 --sheet-id 或 --sheet-name，否则照样报上面的错。
   • ⚠️ A1 reference 含 !（--source / --range / --ranges）：整段用单引号包裹，如 --range 'Sheet1!A1:B2'——单引号能挡住 bash 的 history expansion（! 被拦成 event not found；双引号挡不住；别改用 set +H，原因见下方「复合 JSON / 大入参」）。sheet 名含特殊字符（- / 空格 / 非 ASCII）需在内部按 A1 标准再包一层单引号时，用 '\'' 转义保持外层单引号，如 --source ''\''Sales-2025'\''!A1:D100'。
   • 例外：徽章标为 _公共：URL/token（无 sheet 定位）…_ 的 shortcut（如 +workbook-info / +workbook-export / +batch-update / +dropdown-update|delete / +cells-batch-set-style / +cells-batch-clear / +sheet-create）不接受也不需要 sheet 定位，只给一组 spreadsheet 定位即可。+pivot-create 用 --target-sheet-id / --target-sheet-name（XOR，可都不传，落点细节见 lark-sheets-pivot-table）。

统一调用范式（公共四件套 shortcut 的所有示例都遵循此形状，两组定位缺一不可）：

lark-cli sheets <shortcut> <workbook 定位> <sheet 定位> <其它 flag>
#   workbook 定位：--url "..."        或 --spreadsheet-token "..."           （二选一，必给）
#   sheet 定位：    --sheet-id "$SID"  或 --sheet-name "<真实表名>"            （二选一，必给；占位符不要原样填）
# 例：lark-cli sheets +csv-get --url "https://.../sheets/shtXXX" --sheet-name "<真实表名>" --range "A1:F30"
# 注意：真实表名不要直接填 "Sheet1"——大多数表的子表不叫这个；先 +workbook-info 拿 sheets[].title 再代入。

系统 flag

Agent 使用提示：写复合 JSON flag（--cells / --properties / --operations / --border-styles / --sort-keys / --options 等）时，如果对结构不确定，先跑 lark-cli sheets <shortcut> --print-schema --flag-name <name> 把完整 JSON Schema 读出来再构造 payload，比靠 reference 的速查表更精确，也避免因为字段拼写或缺失被服务端拒绝。reference 的 ## Schemas 段只给一层结构，深层只能靠 --print-schema 或 ## Examples 的真实示例。

flag 内容类型与输出约定（术语速记）

• flag 表里 JSON 类入参标三类：复合 JSON = 深层嵌套对象（用 --print-schema 取完整结构）；简单 JSON = 一维 / 二维标量数组（如 ["sheet1!A1:B2",...] / [["alice",95]]，结构简单无需 print-schema）；非 JSON 文本 = 原样文本（如 CSV）。--print-schema 只对复合 JSON flag 有效（同一 shortcut 的简单 JSON flag 如 --colors 不在此列）。
• envelope：所有 shortcut 返回统一外层结构 {ok, identity, data, ...}。正文里 envelope.data 指业务数据层（如 +csv-get 的 annotated_csv）；写操作不会自动回读，如需校验请自行调用对应的 +*-list / +*-get / +cells-get。

复合 JSON / 大入参：优先 stdin

flag 帮助里标注支持 Stdin 的入参，当 payload 较大、含换行 / 引号等特殊字符，或已经落在某个文件里时，优先用 stdin（-）传入，避免命令行超长与 shell 转义问题。

推荐写法：payload 写到用户项目目录之外的临时文件（放系统临时目录，避免污染项目），再用 stdin 喂进去：

# TMPFILE 指向系统临时目录下的 payload 文件（脚本里用 tempfile.gettempdir() / os.tmpdir() 等取临时目录）
lark-cli sheets +cells-set --url "..." --sheet-name "Sheet1" --range "A1:B2" --cells - < "$TMPFILE"

参数含特殊字符（! / 引号 / 空格 / 非 ASCII）时，用单引号包裹该参数即可，不要起手 set +H 之类的 shell 开关来防转义。 set +H（关 bash history expansion）在 sh / dash 下是非法选项（set: Illegal option -H）、会让整条命令直接失败；而单引号挡得住 ! 的 history expansion（否则报 event not found），对 bash 与 sh / dash 一致安全。参数本身含单引号、或 payload 较大时，按上文走 stdin。

@file 接绝对路径会被拒，且被拒后不要照报错提示做。 @file 出于安全只接受 cwd 下的相对路径，传 cwd 之外的绝对路径会被拒。此时报错会建议"先 cd 到目标目录，或改用相对路径"——两条都不要照做：cd 过去、或把临时文件写进用户项目目录，都会污染工作目录。正解是改用 stdin（--<flag> - < 文件）。