lark-sheets

⚙️ Cowork / Claude Desktop 执行环境说明（自动注入）

本技能依赖本地 lark-cli（@larksuite/cli，可用 command -v lark-cli 定位）及其 ~/.lark-cli 登录态（应用密钥存于 macOS keychain）。

在 Cowork 中运行任何 lark-cli 命令时，必须在本地 macOS 上执行（使用 Desktop Commander 的 start_process / interact_with_process，或其它本地 shell 工具），不要用隔离的 Linux 沙箱 mcp__workspace__bash——沙箱里没有 lark-cli、也读不到 keychain。 执行前确保 npm 全局 bin 目录（npm prefix -g 输出目录下的 bin）在 PATH 中。

（在 Claude Code 中可忽略本说明，lark-cli 在本机 shell 直接可用。）

sheets

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

术语约定

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

标准用语	同义 / 口语（均指同一对象）	说明
工作表（sheet）	子表、tab、标签页	spreadsheet 内的单张表；sheet_id 是其稳定标识
电子表格（spreadsheet）	工作簿、表格	顶层容器；由 --url 或 --spreadsheet-token 定位
reference_id	id	表内对象的稳定标识，即各对象主键 flag 接受的值（见下表）。⚠️ 与 lark-sheets-float-image 的 --image-uri（图片上传句柄）不是一回事，后者不属于 reference_id

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

对象	主键 flag	对象	主键 flag
工作表 sheet	--sheet-id	条件格式规则	--rule-id
图表 chart	--chart-id	筛选视图	--view-id
透视表 pivot	--pivot-table-id	迷你图（按组）	--group-id
浮动图片	--float-image-id

飞书表格编辑准则（动手前必守，所有编辑类任务一律生效）

下列准则横切所有飞书表格任务，动手前先过一遍——即使你是被索引直接路由进某个工具参考也一律生效。每条只给一句话纲要，展开与边界见括注的 reference。

1. 最小改动：除任务要改的单元格 / 列外，原表其它单元格、行列结构、Sheet 名、合并区、格式 1:1 保持；中间结果放原数据右侧或新建空白 Sheet，禁止删 / 改名 / 隐藏 / 移动已存在 Sheet；改写类任务精确圈定行列，不该转的原值 1:1 保留。
2. 真实写回 + 回读校验：交付必须是对在线表格的真实写入，写完用 +csv-get / +cells-get / +<对象>-list 回读确认实际生效——写操作返回 ok 只代表请求被接受、不代表结果符合预期；写公式后查错误码、筛选 / 排序后核对前几行、删除 / 清空后确认已空。禁止只在文本里声称"已完成"。
3. 读全再写：批量填充 / 补齐 / 修正类任务先确认真实数据末行再写，只探前 N 行会漏写表尾（确定末行流程见 lark-sheets-read-data）。
4. 公式优先于硬编码：能用公式表达的计算（总计 / 占比 / 增长率 / 提取 / 查找）一律写公式而非静态值；凡可由表内其它单元格推导的派生值默认就用公式，即使用户没说"联动 / 自动更新"；写任何飞书公式前先读 lark-sheets-formula-translation，而且只要公式真实写入表格，收尾默认就要继续跑 lark-sheets-formula-verify 的 +formula-verify，直到 status='success'。
5. 续写 / 扩展继承样式：续写、补齐、复制区块、新增行列时禁止只读值只写值，必须连带 cell_styles + border_styles + 合并 + 行高一起继承（清单见 lark-sheets-write-cells，四边框最易漏）。
6. 多步写入合并 +batch-update：多个连续写入、或同一工具对多区域重复调用，合并为单次原子 +batch-update（语义见 lark-sheets-batch-update）。
7. 分组汇总用透视表："按 X 统计 Y / 分组汇总 / 各类数量金额"用 +pivot-{create|update|delete}，禁止用 SUMIF / 本地脚本拼一张假透视表。
8. 拆成可验证 checklist：落地前把指令拆成所有"独立可验证子要点"，逐点 assert 全过才交付（多维排序每维一点、多目标每目标一点、范围类核起 / 末 / 边界）；只做第一个要点属违规。
9. 全量处理前置断言条数：翻译 / 打标 / 批量公式落地等逐条任务，先把预期条数硬编码再 assert actual == expected，禁止输出"已完成前 N 条，剩余继续"的半成品。