lark-sheets

sheets

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

术语约定

同一对象的交替说法，按此映射解析用户口语：工作表（sheet）= 子表 / tab / 标签页（sheet_id 是稳定标识）；电子表格（spreadsheet）= 工作簿 / 表格（顶层容器，由 --url 或 --spreadsheet-token 定位）；reference_id = 表内对象的稳定标识，即各对象主键 flag 接受的值（与 --image-uri 图片上传句柄不是一回事）。

每类对象用各自的主键 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（用户明示要求的除外，确认影响后执行，见 lark-sheets-workbook）；改写类任务精确圈定行列，不该转的原值 1:1 保留；补齐类只写空单元格，已有值（哪怕看着可疑）一律不动，最多在交付说明备注。原表数值列的显示格式（小数位 / 千分位 / 是否科学计数法）同属不可改动项；仅当原值已被压成科学计数法或丢小数位时补 number_format 恢复可读，底层值不动。新增的计算列 / 汇总行（均值、占比、金额）必须显式设 number_format——公式默认吐出的多位小数（3.64507772）会被判为格式不合格，按语义定位数（比率两位小数、占比百分比、金额千分位）并与原表同列风格对齐。
2. 真实写回 + 回读校验：交付必须是对在线表格的真实写入，写完用 +csv-get / +cells-get / +<对象>-list 回读确认生效（顺带确认无截断 / 溢出 / 科学计数法）——返回 ok 只代表请求被接受，不代表结果符合预期。回读值可能带「值(样式)」注记（如 49.6(V-Align: bottom)），据此回写前先剥离注记只留纯值；写公式后用 +cells-get --include formula 核对真实落格（仅看显示值不能证明联动）；筛选 / 排序后核对前几行，删除后确认已空。不要只在文本里声称"已完成"。
3. 读全再写：批量填充 / 补齐 / 修正类任务先确认真实数据末行再写，只探前 N 行会漏写表尾（确定末行流程见 lark-sheets-read-data）。
4. 公式优先于硬编码：凡可由表内其它单元格推导的值（总计 / 占比 / 增长率 / 提取 / 查找）一律写公式，即使用户没说"联动 / 自动更新"——本地算好再静默写进单元格，交付的是改输入不重算的死表。提取类产出同行源列的连续原文片段（逐字保真、不跨列取材，一格含多个片段要全列出）；语义判断类（无固定分隔符 / 模式可循）公式表达不了，逐行写静态值，别用固定偏移 / 通用正则硬套。输入列可能为空时公式先判空返回空（空格按 0 参与算术产出无错误码的错值，IFERROR 拦不住）。写聚合公式（SUM / COUNTIF / AVERAGE 等）前先确认区间的起止两端：起点跳过表头行、终点覆盖真实末行——漏掉末行或把表头算进计数是最常见的错值来源，且结果看着合理、不报错；写完抽查区间首尾两格确认落在数据内。写飞书公式前读 lark-sheets-formula-translation，落表后用 +formula-verify 诊断。试错 3 次仍失败可降级静态值，交付说明写明「静态值 + 失败原因 + 不随源数据更新」。
5. 续写 / 扩展继承样式：续写、补齐、复制区块、新增行列时禁止只读值只写值——原表的字体 / 字号 / 颜色、四边框、对齐、底色（含奇偶行交替）、行高列宽、合并都要一并延续到新区域，判分与验收都按"新区域与相邻原始区域视觉一致"来看。
   • 新增行 / 列优先用 +dim-insert --inherit-style before（或 after），样式由原生继承，比"往空白区直接写值再补刷样式"可靠得多（后者最易整片丢失交替底色与边框）。它只选继承哪一侧，不是插入方向。行高是例外，不随样式继承：插行填长文本前读相邻行 row_height，补 +rows-resize（可与插入链合批）。
   • 已经写进空白区、或要对齐非相邻区域时，先 +cells-get --include style 读原区样式，再随值一起写回（清单见 lark-sheets-write-cells，四边框最易漏）。
   • 新增列后把原跨列合并的标题扩展到新末列；插入行复制邻近行的合并分段，按分组合并前逐组核对边界行号，错界会吞掉组名。
6. 多步写入分流：美化收尾（样式 / 合并 / 行高列宽 / 冻结的任意组合）→ 一次 +styles-put 声明式规格交付（见 lark-sheets-styles-put）；同一个写操作打多个区域 → 用该命令自身的复数形态（--ranges / map 入参）；只有跨类型、有顺序依赖的操作链（如插列 → 写表头 → 回填数据）才用 +batch-update（high-risk-write：按下方审批协议先获用户同意再带 --yes；失败处置语义见 lark-sheets-batch-update）。
7. 分组汇总优先用透视表：参考速查表「分组汇总 / 透视」行；SUMIF / 本地脚本拼假透视表可能丢失原生透视能力，作为风险记录。
8. 回复里声称的每一项，产物里都要能指到位置：交付说明 / 回复正文写了"已生成趋势分析报告""图中对比了两个资产""覆盖 11 种格式"，就必须在产物中真实存在对应的 sheet / 图表对象 / 文字段落，并能说出它在哪张表第几行。文字描述不能替代产物——判分只认产物里能被读到的内容，回复里的描述一概不计分。交付前逐条对照自己写的每句"已完成 X"，指不到位置的要么补做，要么把该句删掉改成"未完成 + 原因"。