lark-sheets

Name: lark-sheets
Author: larksuite

380kinstalls1.1kforks

How to install lark-sheets?

larksuite/cli/lark-sheets

$npx -y skills add larksuite/cli --skill lark-sheets

Installs into the current project.

Summary

飞书电子表格：创建和操作电子表格。支持创建表格、管理工作表与行列结构（增删/合并/调整尺寸/隐藏/冻结）、读写单元格（值/公式/样式/批注/单元格图片）、查找替换、多操作原子批量更新，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象的创建与维护。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）、金融/财务建模（DCF、三张表、预算、Sensitivity 等）等任务时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 dr

Files · 1

View on GitHub

SKILL.md

1	# sheets
2
3	CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理。
4
5	## 术语约定
6
7	下列词在本 skill 各文档中可能交替出现，但指同一对象；解析用户口语时按此映射，不要当成不同概念：
8
9	\| 标准用语 \| 同义 / 口语（均指同一对象） \| 说明 \|
10	\| --- \| --- \| --- \|
11	\| 工作表（sheet） \| 子表、tab、标签页 \| spreadsheet 内的单张表；`sheet_id` 是其稳定标识 \|
12	\| 电子表格（spreadsheet） \| 工作簿、表格 \| 顶层容器；由 `--url` 或 `--spreadsheet-token` 定位 \|
13	\| reference_id \| id \| 表内对象的稳定标识，即各对象主键 flag 接受的值（见下表）。⚠️ 与 `lark-sheets-float-image` 的 `--image-uri`（图片上传句柄）不是一回事，后者不属于 reference_id \|
14
15	每类对象用各自的主键 flag 定位（命名不统一，按此表对照，不要凭直觉拼）：
16
17	\| 对象 \| 主键 flag \| 对象 \| 主键 flag \|
18	\| --- \| --- \| --- \| --- \|
19	\| 工作表 sheet \| `--sheet-id` \| 条件格式规则 \| `--rule-id` \|
20	\| 图表 chart \| `--chart-id` \| 筛选视图 \| `--view-id` \|
21	\| 透视表 pivot \| `--pivot-table-id` \| 迷你图（按组） \| `--group-id` \|
22	\| 浮动图片 \| `--float-image-id` \| \| \|
23
24	## 飞书表格编辑准则（动手前必守，所有编辑类任务一律生效）
25
26	下列准则横切所有飞书表格任务，动手前先过一遍——即使你是被索引直接路由进某个工具参考也一律生效。每条只给一句话纲要，展开与边界见括注的 reference。
27
28	1. 最小改动：除任务要改的单元格 / 列外，原表其它单元格、行列结构、Sheet 名、合并区、格式 1:1 保持；中间结果放原数据右侧或新建空白 Sheet，禁止删 / 改名 / 隐藏 / 移动已存在 Sheet；改写类任务精确圈定行列，不该转的原值 1:1 保留。
29	2. 真实写回 + 回读校验：交付必须是对在线表格的真实写入，写完用 `+csv-get` / `+cells-get` / `+<对象>-list` 回读确认实际生效——写操作返回 `ok` 只代表请求被接受、不代表结果符合预期；写公式后查错误码、筛选 / 排序后核对前几行、删除 / 清空后确认已空。禁止只在文本里声称"已完成"。
30	3. 读全再写：批量填充 / 补齐 / 修正类任务先确认真实数据末行再写，只探前 N 行会漏写表尾（确定末行流程见 `lark-sheets-read-data`）。
31	4. 公式优先于硬编码：能用公式表达的计算（总计 / 占比 / 增长率 / 提取 / 查找）一律写公式而非静态值；凡可由表内其它单元格推导的派生值默认就用公式，即使用户没说"联动 / 自动更新"；写任何飞书公式前先读 `lark-sheets-formula-translation`，而且只要公式真实写入表格，收尾默认就要继续跑 `lark-sheets-formula-verify` 的 `+formula-verify`，直到 `status='success'`。
32	5. 续写 / 扩展继承样式：续写、补齐、复制区块、新增行列时禁止只读值只写值，必须连带 `cell_styles` + `border_styles` + 合并 + 行高一起继承（清单见 `lark-sheets-write-cells`，四边框最易漏）。
33	6. 多步写入合并 `+batch-update`：多个连续写入、或同一工具对多区域重复调用，合并为单次原子 `+batch-update`（语义见 `lark-sheets-batch-update`）。
34	7. 分组汇总用透视表："按 X 统计 Y / 分组汇总 / 各类数量金额"用 `+pivot-{create\|update\|delete}`，禁止用 SUMIF / 本地脚本拼一张假透视表。
35	8. 拆成可验证 checklist：落地前把指令拆成所有"独立可验证子要点"，逐点 `assert` 全过才交付（多维排序每维一点、多目标每目标一点、范围类核起 / 末 / 边界）；只做第一个要点属违规。
36	9. 全量处理前置断言条数：翻译 / 打标 / 批量公式落地等逐条任务，先把预期条数硬编码再 `assert actual == expected`，禁止输出"已完成前 N 条，剩余继续"的半成品。
37
38	> 上述准则的实操展开——读取路径、原生工具优先级、脚本配合、易漏陷阱——见下方「执行要点」节；端到端工作流为：了解结构（`+workbook-info`）→ 读数据 → 理解语义 → 原生工具优先 → 写入 → 回读验证。
39
40	## 场景 → 命令速查（拿不准命令名先查这里，别按直觉拼）
41
42	把高频意图映射到真实存在的 shortcut / flag。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移命令名或 flag，先对照本表，避免一次必然失败的试错。完整 shortcut 见各工具参考。选定命令后别急着写——先读「动手前读」列指向的 reference 再动手：命令名对得上不代表用法对，写入 / 清除 / 透视类尤其容易漏掉 reference 里的防错、类型与样式继承规则。
43
44	\| 你要做的事 \| ✅ 正确写法 \| 动手前读 \| ❌ 不存在（会被 cobra 拒） \|
45	\| --- \| --- \| --- \| --- \|
46	\| 读数据（纯值 / CSV） \| `+csv-get`（范围用 `--range`） \| `lark-sheets-read-data` \| `+get-range`、`+range-get`、`+cells-read` \|
47	\| 读值 + 公式 / 样式 / 批注 \| `+cells-get --include value,formula,style,comment,data_validation` \| `lark-sheets-read-data` \| `+get-cell`、`+cell-get`、`--with-styles`、`--with-merges`、`--include-merged-cells` \|
48	\| 写纯文本值（整块 CSV 平铺；列里没有需字面保真的数值 / 日期标签 / 编号——点分日期 `12.10`、编号 `001` 会被 csv-put 数值化，不算纯文本） \| `+csv-put`（定位用 `--start-cell`，单个左上角锚点格；也接受 `--range` 别名，区间自动取左上角） \| `lark-sheets-write-cells` \| 把含点分日期(`12.10`)/编号(`001`)的列裸灌 `+csv-put`——会被数值化（`12.10`→`12.1`、`001`→`1`，尾零/前导零丢失），改用 `+table-put` 声明 `dtypes:object` \|
49	\| 写带类型的数据到已有表（列里有数字 / 金额 / 百分比 / 日期 / 计数等本质是量值的数据——不看当下要不要排序 / 求和，量值一律走这里） \| `+table-put --sheets` 完整 payload `{"sheets":[{...}]}`（列名走 `columns`、二维数据走 `data`、列 pandas dtype 走 `dtypes`、列展示格式走 `formats`；来源不限 DataFrame——Counter / dict / list 同理；要同时美化加 `--styles` 一步带样式（区域底色 / 边框 / 列宽 / 行高 / 合并），不必事后再刷；payload 里不存在的 sheet 名会自动建子表，详见 write-cells） \| `lark-sheets-write-cells` \| 在本地把数字拼成 `"$1,234"` / `"30.5%"` 字符串再 `+csv-put`（会落成文本、丢失计算能力；常见借口见下方 ⚠️） \|
50	\| 新建电子表格并写带类型的数据（类型保真需求同上，但目标表还不存在） \| `+workbook-create --sheets`（协议与 `+table-put` 同构、一步建表 + typed 写入，无需先建空表再 `+table-put`；date / number 不丢；`--styles` 同样可在建表同一步带全套样式，详见 workbook） \| `lark-sheets-workbook` \| 用 `--values` 灌日期 / 数字（会落成文本、丢类型） \|
51	\| 写公式 / 富写入（样式 · 批注 · 图片 · 富文本），或需精确矩形定位的值 \| `+cells-set`（定位用 `--range`；批注 / 图片 / 富文本只能用它，公式也可；公式落表后继续 `+formula-verify` 收尾） \| `lark-sheets-write-cells` \| — \|
52	\| 插图：图片绑定到某条记录、随行走（凭证 / 证件照 / 商品图 / 头像 / 二维码 / 每行配图） \| `+cells-set-image`（单格 `--range`，嵌入单元格内） \| `lark-sheets-write-cells` \| — \|
53	\| 插图：自由摆放、不绑数据的装饰 / 标识（logo / 水印 / 封面大图 / banner） \| `+float-image-create`（浮动图片，自由定位 + 尺寸 + 层级） \| `lark-sheets-float-image` \| — \|
54	\| 查找 / 替换文本 \| `+cells-search`（找，关键字用 `--find`）、`+cells-replace`（替换） \| `lark-sheets-searc

People who liked this also viewed

6 picks

Type

lark-sheets

380kinstalls1.1kforks

View on GitHub

How to install lark-sheets?

larksuite/cli/lark-sheets

$npx -y skills add larksuite/cli --skill lark-sheets

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# sheets
2
3	CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理。
4
5	## 术语约定
6
7	下列词在本 skill 各文档中可能交替出现，但指同一对象；解析用户口语时按此映射，不要当成不同概念：
8
9	\| 标准用语 \| 同义 / 口语（均指同一对象） \| 说明 \|
10	\| --- \| --- \| --- \|
11	\| 工作表（sheet） \| 子表、tab、标签页 \| spreadsheet 内的单张表；`sheet_id` 是其稳定标识 \|
12	\| 电子表格（spreadsheet） \| 工作簿、表格 \| 顶层容器；由 `--url` 或 `--spreadsheet-token` 定位 \|
13	\| reference_id \| id \| 表内对象的稳定标识，即各对象主键 flag 接受的值（见下表）。⚠️ 与 `lark-sheets-float-image` 的 `--image-uri`（图片上传句柄）不是一回事，后者不属于 reference_id \|
14
15	每类对象用各自的主键 flag 定位（命名不统一，按此表对照，不要凭直觉拼）：
16
17	\| 对象 \| 主键 flag \| 对象 \| 主键 flag \|
18	\| --- \| --- \| --- \| --- \|
19	\| 工作表 sheet \| `--sheet-id` \| 条件格式规则 \| `--rule-id` \|
20	\| 图表 chart \| `--chart-id` \| 筛选视图 \| `--view-id` \|
21	\| 透视表 pivot \| `--pivot-table-id` \| 迷你图（按组） \| `--group-id` \|
22	\| 浮动图片 \| `--float-image-id` \| \| \|
23
24	## 飞书表格编辑准则（动手前必守，所有编辑类任务一律生效）
25
26	下列准则横切所有飞书表格任务，动手前先过一遍——即使你是被索引直接路由进某个工具参考也一律生效。每条只给一句话纲要，展开与边界见括注的 reference。
27
28	1. 最小改动：除任务要改的单元格 / 列外，原表其它单元格、行列结构、Sheet 名、合并区、格式 1:1 保持；中间结果放原数据右侧或新建空白 Sheet，禁止删 / 改名 / 隐藏 / 移动已存在 Sheet；改写类任务精确圈定行列，不该转的原值 1:1 保留。
29	2. 真实写回 + 回读校验：交付必须是对在线表格的真实写入，写完用 `+csv-get` / `+cells-get` / `+<对象>-list` 回读确认实际生效——写操作返回 `ok` 只代表请求被接受、不代表结果符合预期；写公式后查错误码、筛选 / 排序后核对前几行、删除 / 清空后确认已空。禁止只在文本里声称"已完成"。
30	3. 读全再写：批量填充 / 补齐 / 修正类任务先确认真实数据末行再写，只探前 N 行会漏写表尾（确定末行流程见 `lark-sheets-read-data`）。
31	4. 公式优先于硬编码：能用公式表达的计算（总计 / 占比 / 增长率 / 提取 / 查找）一律写公式而非静态值；凡可由表内其它单元格推导的派生值默认就用公式，即使用户没说"联动 / 自动更新"；写任何飞书公式前先读 `lark-sheets-formula-translation`，而且只要公式真实写入表格，收尾默认就要继续跑 `lark-sheets-formula-verify` 的 `+formula-verify`，直到 `status='success'`。
32	5. 续写 / 扩展继承样式：续写、补齐、复制区块、新增行列时禁止只读值只写值，必须连带 `cell_styles` + `border_styles` + 合并 + 行高一起继承（清单见 `lark-sheets-write-cells`，四边框最易漏）。
33	6. 多步写入合并 `+batch-update`：多个连续写入、或同一工具对多区域重复调用，合并为单次原子 `+batch-update`（语义见 `lark-sheets-batch-update`）。
34	7. 分组汇总用透视表："按 X 统计 Y / 分组汇总 / 各类数量金额"用 `+pivot-{create\|update\|delete}`，禁止用 SUMIF / 本地脚本拼一张假透视表。
35	8. 拆成可验证 checklist：落地前把指令拆成所有"独立可验证子要点"，逐点 `assert` 全过才交付（多维排序每维一点、多目标每目标一点、范围类核起 / 末 / 边界）；只做第一个要点属违规。
36	9. 全量处理前置断言条数：翻译 / 打标 / 批量公式落地等逐条任务，先把预期条数硬编码再 `assert actual == expected`，禁止输出"已完成前 N 条，剩余继续"的半成品。
37
38	> 上述准则的实操展开——读取路径、原生工具优先级、脚本配合、易漏陷阱——见下方「执行要点」节；端到端工作流为：了解结构（`+workbook-info`）→ 读数据 → 理解语义 → 原生工具优先 → 写入 → 回读验证。
39
40	## 场景 → 命令速查（拿不准命令名先查这里，别按直觉拼）
41
42	把高频意图映射到真实存在的 shortcut / flag。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移命令名或 flag，先对照本表，避免一次必然失败的试错。完整 shortcut 见各工具参考。选定命令后别急着写——先读「动手前读」列指向的 reference 再动手：命令名对得上不代表用法对，写入 / 清除 / 透视类尤其容易漏掉 reference 里的防错、类型与样式继承规则。
43
44	\| 你要做的事 \| ✅ 正确写法 \| 动手前读 \| ❌ 不存在（会被 cobra 拒） \|
45	\| --- \| --- \| --- \| --- \|
46	\| 读数据（纯值 / CSV） \| `+csv-get`（范围用 `--range`） \| `lark-sheets-read-data` \| `+get-range`、`+range-get`、`+cells-read` \|
47	\| 读值 + 公式 / 样式 / 批注 \| `+cells-get --include value,formula,style,comment,data_validation` \| `lark-sheets-read-data` \| `+get-cell`、`+cell-get`、`--with-styles`、`--with-merges`、`--include-merged-cells` \|
48	\| 写纯文本值（整块 CSV 平铺；列里没有需字面保真的数值 / 日期标签 / 编号——点分日期 `12.10`、编号 `001` 会被 csv-put 数值化，不算纯文本） \| `+csv-put`（定位用 `--start-cell`，单个左上角锚点格；也接受 `--range` 别名，区间自动取左上角） \| `lark-sheets-write-cells` \| 把含点分日期(`12.10`)/编号(`001`)的列裸灌 `+csv-put`——会被数值化（`12.10`→`12.1`、`001`→`1`，尾零/前导零丢失），改用 `+table-put` 声明 `dtypes:object` \|
49	\| 写带类型的数据到已有表（列里有数字 / 金额 / 百分比 / 日期 / 计数等本质是量值的数据——不看当下要不要排序 / 求和，量值一律走这里） \| `+table-put --sheets` 完整 payload `{"sheets":[{...}]}`（列名走 `columns`、二维数据走 `data`、列 pandas dtype 走 `dtypes`、列展示格式走 `formats`；来源不限 DataFrame——Counter / dict / list 同理；要同时美化加 `--styles` 一步带样式（区域底色 / 边框 / 列宽 / 行高 / 合并），不必事后再刷；payload 里不存在的 sheet 名会自动建子表，详见 write-cells） \| `lark-sheets-write-cells` \| 在本地把数字拼成 `"$1,234"` / `"30.5%"` 字符串再 `+csv-put`（会落成文本、丢失计算能力；常见借口见下方 ⚠️） \|
50	\| 新建电子表格并写带类型的数据（类型保真需求同上，但目标表还不存在） \| `+workbook-create --sheets`（协议与 `+table-put` 同构、一步建表 + typed 写入，无需先建空表再 `+table-put`；date / number 不丢；`--styles` 同样可在建表同一步带全套样式，详见 workbook） \| `lark-sheets-workbook` \| 用 `--values` 灌日期 / 数字（会落成文本、丢类型） \|
51	\| 写公式 / 富写入（样式 · 批注 · 图片 · 富文本），或需精确矩形定位的值 \| `+cells-set`（定位用 `--range`；批注 / 图片 / 富文本只能用它，公式也可；公式落表后继续 `+formula-verify` 收尾） \| `lark-sheets-write-cells` \| — \|
52	\| 插图：图片绑定到某条记录、随行走（凭证 / 证件照 / 商品图 / 头像 / 二维码 / 每行配图） \| `+cells-set-image`（单格 `--range`，嵌入单元格内） \| `lark-sheets-write-cells` \| — \|
53	\| 插图：自由摆放、不绑数据的装饰 / 标识（logo / 水印 / 封面大图 / banner） \| `+float-image-create`（浮动图片，自由定位 + 尺寸 + 层级） \| `lark-sheets-float-image` \| — \|
54	\| 查找 / 替换文本 \| `+cells-search`（找，关键字用 `--find`）、`+cells-replace`（替换） \| `lark-sheets-searc

People who liked this also viewed

6 picks

Type