Sheet

⚠️ 强制前置条件：本文档共 370 行，指令说明和约束分散在各部分。必须先读到末行「全文完」，再执行任何其他操作；即使已找到当前任务所需的指令，也不得提前停止。未见该标记时，下一步必须继续调用 Read，在读完之前不得调用 Bash、--help 或任何其他工具。读取工具能一次取全文就一次取全，被截断则调整偏移量（offset）续读。本技能所有文档末行均有该标记。

⚠️ 平台差异：SystemPrompt 里若出现 Computer OS: Windows，在阅读完本 SKILL后，无论后续是否执行lark-cli操作都必须先完整 Read references/ref-windows-compat.md，查看在 windows 平台上执行命令所必须要注意的问题，否则会出现大面积报错。

表格全场景处理技能（sheet）

本技能适用两种运行环境：云电脑，本地电脑，根据下述顺序判定。

1. SystemPrompt 中的 Computer OS 字段：值为 Windows 或 Mac 判为本地电脑；值为其他判为云电脑。
2. SystemPrompt 未包含 Computer OS 字段时：包裹的内容中出现 Runtime: local_pc，则运行环境为本地电脑；出现 Runtime: cloud_vm，则运行环境为云电脑。

本技能涉及两种表格载体：

• 本地表格文件：.xlsx、.xls、.csv 等表格文件，可能存储于云电脑或本地电脑上。
• 飞书表格 / Lark Sheets：可理解为在线版 Excel，通常通过 URL 提供，常见域名包括 larkoffice.com、doubao.com，结构为 域名/sheets/TOKEN，不要因为域名不是飞书就断定不是飞书表格。

本技能支持两种运行引擎：

• Excel 引擎，通过 Python pandas / openpyxl 和 scripts/ 来对 .xlsx / .xls / .csv 等表格文件进行操作。
• 飞书引擎，通过 lark-cli sheets 操作表格：
  • 对飞书表格进行操作，详见「三」。
  • 用本地 Canvas 模式操作表格文件，详见「Canvas 模式」。

云电脑

运行引擎

对输入的 .xlsx / .xls / .csv 等本地表格文件附件的编辑，走Excel 引擎。对飞书表格的编辑走飞书引擎。

Must-CLI场景：交付物涉及透视表 / 图表 / 单元格图片 / 迷你图任一能力时，需要走飞书引擎以充分发挥原生对象的效果，有附件时可通过 +workbook-import 导入表格文件，无附件时通过 +workbook-create 创建表格，之后用 lark-cli sheets 编辑。

交付契约

云电脑上无论新建、编辑场景，默认都必须交付经过检查的飞书在线表格，方便在线预览、协作编辑。哪怕用户说“做个 Excel”“整理成表格”“给我个表”“原表格/原文件”，由于在云端运行，也只能交付飞书表格。

通过Excel 引擎得到的结果，需要调用 lark-cli sheets +workbook-import 将本地 Excel 文件（.xlsx）导入为飞书在线表格，获得 URL 再交付。

例外：如果用户明确禁止使用飞书表格/Sheets CLI，或者只要无格式 .csv，则交付本地表格文件。

在通过交付工具将经过检查的飞书表格交付用户之前，必须执行scripts/lark_sheet_selfcheck.py "<url>" 对飞书表格进行检查，然后核对检查结果并修复。不要同时交付本地 Excel 文件。

默认执行路径

1. inspect_workbook.py 预检，同时从题面原文提取检查清单（要产出的 sheet 名 / 文件名、必须包含的数据项 / 交易 / 指标）
2. 选择引擎处理
3. （仅在使用 Excel 引擎时）产物可打开且必交项齐全后导入在线表，导入失败重试一次仍不成，降级改交本地文件。
4. 产物检查，在交付前必须按检查清单进行产物诊断，修复出现的问题，但不可进入反复修复循环，解决不了或非确定性问题时记录到交付说明给用户，不要求停止交付。
5. 调用交付工具交付经检查的产物

本地电脑

运行引擎

与云电脑的引擎选择类似，唯一例外：如果要编辑的本地 .xlsx / .xls / .csv 等表格文件被用户通过豆包客户端"Canvas 模式"打开（详见「Canvas 模式」），编辑时必须使用 飞书引擎，通过 lark-cli sheets 操作，以提供可回滚、编辑状态实时可见的最佳体验。

注意：使用Excel 引擎编辑文件时，由于 Python 直接改本地文件不可回滚，因此动手前必须先创建副本，编辑一律落在副本上、原文件不动。

交付契约

本地电脑新建场景下，默认交付飞书表格，除非用户明确要求交付本地表格文件，或禁止使用飞书表格。

编辑场景交付物形态与编辑对象一致，编辑飞书表格就交付飞书表格，编辑本地 Excel 文件就交付本地 Excel 文件，除非用户明确提出了本地/在线表格要求。

最后根据用户需要，通过交付工具将飞书表格 URL 或本地文件路径交付用户。注意：交付本地文件给用户时，禁止擅自拼接本地文件的token当成在线链接提供给用户，应直接交付本地文件路径。

本地电脑暂不强制执行 lark_sheet_selfcheck.py（脚本在本地打开模式下的兼容性待验证）

Canvas 模式

用户可以在豆包客户端通过一个 canvas 打开 .xlsx / .xls / .csv 等表格文件或在线飞书表格，实现人机协作。此时系统会通过 <system-reminder> 注入下列与打开文件相关的信息，即使用户关闭了 canvas，该信息也会保留，但 file_status 会更新。注意 没有被打开过的本地文件或飞书表格不带这些字段。

Canvas 模式打开一个本地文件时，文件会被解码为底层产物放入工作目录，其解码后的路径被 token 唯一标识，豆包客户端（canvas）通过实时渲染底层产物，让用户实时感受到你对此产物的任何变更，一切变更均发生于工作目录中的底层产物，不改变用户本地文件，仅当用户要求保存时才会打包成同类型文件覆盖用户提供的真实本地路径。交付产物时，不要将修改写回用户真实本地文件，交付用户提供的原文件路径即可，并提醒用户自行保存。

权威经验

• 用户要求进行文件级操作（如复制、移动、重命名等）时本 skill 指令不再适合，建议使用 bash(linux/mac)、PowerShell(windows) 类指令进行操作，注意此时应该操作的是用户的真实文件，不得操作底层产物。
• 用户未明确要求的情况下，禁止输出任何与"工作目录"、"底层产物"相关的内容，也禁止向用户解释底层原理。
• 在Canvas 模式下：
  • 若 lark-cli 长期出现超时问题，应当考虑当前 canvas 可能被关闭，不要继续使用 lark-cli 指令。file_status 为 "close" 时，lark-cli 一定会执行失败，此时可用 Python 处理。文件从未被打开（不带 token）时同理。
  • 编辑的本地文件只能由用户自行保存，禁止通过 lark-cli 导出。

0、方法与规范类 References（按动作触发，先读再动手）

文件在 references/ 下；短名的完整文件名 = lark-sheets-<短名>.md，guide-* / ref-* / template-* 直接用全名。 按对象操作（读写 / 透视 / 图表 / 筛选 / 排序…）该读哪份，见「三」的「场景 → 命令速查」表的「动手前读」列，本表不重复列。

⏬ 未完——继续调整 offset 续读，直到末行「全文完」标记。

一、开工前

产物载体：按上方对应运行环境的「交付契约」判定。用户点名了产物文件名时，新建 / 导入产生的工作簿标题与交付附件名沿用该文件名（工作簿标题去扩展名；交付附件名保留完整文件名含扩展名），避免改写成自拟标题（用户已有的在线表不因此改名）；附件名中的 / 替换为 -。本地转在线直接 +workbook-import --file ./x.xlsx；在线编辑完成后直接使用在线表 URL 交付，未闭合的诊断项在交付说明中列出即可。

Must-CLI 对象风险：交付物涉及透视表 / 图表 / 单元格图片 / 迷你图任一能力时，"云电脑"推荐先 +workbook-import（有附件；目标是并入已有工作簿时不走 import，见速查表追加行）或 +workbook-create（无附件），之后用 lark-cli sheets 就地做；"本地电脑"推荐在 Canvas 模式下，使用 lark-cli 指令操作本地文件。若改用“本地 Python 生成 .xlsx → 导入”，导入后透视表可能变死表、单元格图可能变浮动图、图表可能变静态图。命令按「三」的速查表选。速查表没列的子选项（中位数汇总 / 计算字段 / 重复行标签 / 面积图 / 胜负迷你图等均原生支持）先查对应 reference 再动手，避免凭"没列"判不支持而绕路。

workspace 建议：中间文件优先放 workspace 相对路径，避免 /tmp 带来的 cwd 和 @file 相对路径问题。

附件读取：下载后验字节数与魔数，失败先重试（curl 加 -L）再用 +workbook-import 兜底；原件未读入前不要凭记忆重建"同款"表或脑补数据。兜底用尽仍读不出（损坏 / 扫描件）时，已提取的照常填、读不出的留空并在交付说明写明缺口，不用常识 / 检索 / 其它文件顶替附件内本该有的事实数据。

Excel 引擎核心动作（走本地 .xlsx 路径时优先做；诊断脚本不替代完成主体产物）： ① 聚合前剔除汇总行：出现「合计 / 总计 / 小计 / 累计」这类与明细口径不同的行时，先从明细中排除再做统计，否则重复计数（inspect_workbook.py 的 special_rows 可定位）； ② 交付前记录确定性风险：产物打不开、导入失败、题面点名 sheet / 文件名缺失、真实公式错误、base 明显被整体覆盖时，优先修复；修不完则在交付说明中列出。诊断中的 WARN、样式指纹、硬编码嫌疑也只记录在交付说明，不要求循环修复。仅当交付物被限定为本地 xlsx（用户明确禁止使用飞书表格）时，图表可用 openpyxl 原生 chart 对象绑定数据区，交付前可确认 ws._charts 非空；其余情况图表推荐按在线对象做。

二、场景路由与交付建议

场景路由

交付建议

交付前逐条核对：把 query 拆成显式要求清单（点名 N 项就核 N 项），清单含产出项（sheet 名与数量、指标 / 列、图表、文件名）与题面给定的参数取值、计算口径；可机械核对的（数量 / 位置 / 表头逐字串 / 图表张数 / 原列保留）回读产物断言相等，缺口在交付说明逐项声明，不只报成功示例。其余编辑纪律见「三」的编辑准则，飞书任务动手前过一遍。

三、飞书表格操作引擎（lark-cli）

术语约定

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

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

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

下列准则横切所有飞书表格任务，动手前先过一遍——被索引直接路由进某个工具参考时也一律生效；展开与边界见括注的 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"，指不到位置的要么补做，要么把该句删掉改成"未完成 + 原因"。

9. 拆成可验证 checklist：落地前把指令拆成"独立可验证子要点"，优先逐点 assert 或抽样回读（多维排序每维一点、多目标每目标一点、范围类核起 / 末 / 边界；样式类子项也算——标色 / 标红可回读着色单元格数或规则数）；验证中发现的已知问题（算错 / 取不到数的格）在交付说明逐个列出，避免只报成功示例。

10. 全量处理前置断言条数：翻译 / 打标 / 批量公式等逐条任务，建议先把预期条数写入脚本再 assert actual == expected；断言不过时优先补齐。机制上补不了时（预算将尽 / 能力缺失）先落地可打开的主体产物（数据与结构），未完成项在交付说明声明。

11. 批量替换 / 标注 / 删除建议残留复查：逐个旧值执行「搜索 → 替换 → 再搜索」循环，尽量让每个旧值剩余命中数归零（单次替换有数量上限，大表尾部常有残留）；回读采样覆盖前部 / 中段 / 表尾，不只抽前几行。

12. 新增内容要能被看懂：新增列给可区分含义的表头（不与原列同名）；题面 / 模板指定的 sheet 名 / 标题 / 备注 / 图例文案逐字照搬，不缩写、不润色、不省略修饰成分与双语形式；数值沿用原列显示格式（整数 / 千分位 / 百分比 / 日期）；日期列转换先扫全列锁定月 / 日位（如 9/3/24：出现过 >12 的位置是日），逐格凭感觉解析必月日颠倒；图表必须含标题、坐标轴标签与图例；长文本列自动换行并给足列宽。单位 / 口径 / 来源等元信息另置（标题下副标题行，或并进字段名如 营收（万元）），不得占用已有表头格或数据格。

13. 表外数据要交代依据：填入表内 / 附件 / 用户输入都取不到的外部数据（标准值、行情、法规参数等）时，交付说明写清取值依据、单位口径与不确定项；来自常识推算就写明"推算、未经核验"，不得伪造来源出处。

14. 缺失值不编造：源数据 / 附件内本应存在的事实数据查不到或无法确定时一律留空 + 备注（“暂未发布 / 未知 / 待核实”），不用推算值 / 估算值充数（表外参数按上条）；原表已示范缺失值写法就照抄该约定。

实操展开（读取路径、原生工具优先级、脚本配合、易漏陷阱）见下方「执行要点」节。端到端工作流：了解结构（优先 scripts/lark_inspect_workbook.py / +workbook-info）→ 读数据 → 理解语义 → 原生工具优先 → 写入 → 回读验证。

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

若本次读取被截断在本表中段：下列能力都原生存在， 详细用法（flag、payload 形状、易错点）在本表后半部分与其后的「执行要点」「公共 flag」章节：

+styles-put 美化收尾（样式 / 边框 / 合并 / 行高列宽 / 冻结 一次交付）· +chart-create 原生图表 · +pivot-create 透视表 · +filter-create 筛选 · +cond-format-create 条件格式 · +range-sort 排序 · +dim-insert 插入行列 · +cells-search / +cells-replace 查找替换 · +workbook-import 本地文件转在线表

要用其中任一能力而对应行未读到时，用文件读取工具的偏移参数（offset / 起始行）把后半段再读一次， 取全对应行再动手。不要因为没读到展开就判定命令不存在，更不要改用本地脚本绕路—— 本地生成的透视表 / 图表导入后会退化成死表、静态图。

把高频意图映射到真实存在的 shortcut / flag（agent 常从 Excel / Google Sheets / OpenAPI 误迁移命令名）。选定命令后先读「动手前读」列指向的 reference 再动手——命令名对得上不代表用法对。

⏬ 未完——继续调整 offset 续读，直到末行「全文完」标记。

⚠️ 动手前的触发式必读（按动作判定，不看主场景）：本次操作只要涉及样式 / 美化（底色 / 边框 / 字号 / 对齐 / 数字格式 / 汇总行 / 配色 / 列宽行高），动手前先读 lark-sheets-visual-standards；只要要写飞书公式，动手前先读 lark-sheets-formula-translation（飞书函数与 Excel 有差异，凭直觉迁移易错），写完后可读 lark-sheets-formula-verify 并执行 +formula-verify 做一次诊断。哪怕主任务是"建表 / 展开数据 / 录入"，只要动作里含美化或写公式就适用——别因"这不算专门的美化 / 公式任务"而跳过。 ⚠️ 两种图片别选错：图若绑定某条记录、要随行排序 / 筛选 / 增删（凭证 / 证件照 / 每行配图，话里带「对应 / 每行 / 这列」等绑定词）→ 单元格图片 +cells-set-image；只是自由摆放的装饰（logo / 水印 / 封面）→ 浮动图片 +float-image-create。别因「浮动图更好控制 / 更熟」默认选浮动图。 ⚠️ 纯文本还是数值语义（看数据本质，不看当下用途）：金额 / 百分比 / 比率 / 计数 / 日期等本质是量值的数据 → 一律数值写入，常规二维表用 +table-put（dtypes 声明类型 + formats 设展示格式），版式装不下（多级 / 合并表头的宽表 leaderboard 等）改用 +cells-set 传数字（百分比传小数 0.4）+ number_format，照样显示 40% 且数值无损。只有编号 / 身份证 / 单据号这类本质是标识符、要字面保真的才用 +csv-put 平铺。几个常见借口都不成立——"只是 leaderboard / 报表展示不用算""版式复杂""样式以后再刷、先铺文本"都不是把百分比写成 "40%" 字符串灌 +csv-put 的理由（展示不改变它是数值；类型不能后补，落成文本就回不来）。判据与操作展开见 lark-sheets-write-cells「数字还是文本」。 ⚠️ 要新建子表 / 整表美化 → 别默认「+csv-put 写值再事后刷样式」：+table-put / +workbook-create 的 --styles 能在写数据的同一步带全套样式（区域底色 / 边框 / 列宽 / 行高 / 合并），且 +table-put 的 payload 里若 sheet 名不在工作簿中会自动新建子表——纯文本表要新建子表 + 美化时同样走这里（--styles 与列是否 typed 无关），比「+csv-put 写值 + 多次 +cells-batch-set-style / +*-resize 刷样式」少好几次调用（冻结行列等 sheet 级属性仍需 +dim-freeze 单独一步）。存量表事后美化则一次 +styles-put 交付（同一份 --styles 词汇）。 ⚠️ 定位 flag：+cells-get / +cells-set / +csv-get 用 --range；+csv-put 规范用 --start-cell（单个左上角锚点格），也接受 --range 别名（区间自动取左上角），二者择一即可。--range 只写 A1:B2 纯区间——不接受 OpenAPI 的 sheetId!A1:B2 前缀写法，子表定位必须单独传 --sheet-id / --sheet-name（从 OpenAPI 迁移习惯最易踩）。 ⚠️ 读取附加信息一律走 +cells-get --include …，没有 --with-styles 这类 flag；看合并单元格用 +sheet-info 的 merged_cells，不要在 +cells-get 里找 merge flag。

💡 高频写命令签名（照抄改参即可；各命令 --help 的 Tips 段有同款示例）：

lark-cli sheets +cells-set --url <U> --sheet-name S1 --range A1:B1 --cells '[[{"value":"名称"},{"formula":"=SUM(B2:B9)"}]]'  # --cells 恒为二维数组 [[…]]，单格也是 [[{…}]]
lark-cli sheets +cells-set-style --url <U> --sheet-name S1 --range A1:D1 --font-weight bold --background-color "#F0F0F0" --horizontal-alignment center
lark-cli sheets +styles-put --url <U> --styles - <<'JSON'
{"styles":[{"name":"S1","cell_styles":[{"range":"A1:D1","font_weight":"bold","background_color":"#F0F0F0"}],"col_sizes":[{"range":"A:D","type":"pixel","size":120}],"freeze":{"rows":1}}]}
JSON
lark-cli sheets +batch-update --url <U> --dry-run --operations - <<'JSON'   # high-risk：先 --dry-run 给用户看，同意后原样重发并追加 --yes
[{"shortcut":"+cells-set","input":{"sheet_name":"S1","range":"A1","cells":[[{"value":"x"}]]}}]
JSON
lark-cli sheets +dim-freeze --url <U> --sheet-name S1 --rows 1 --cols 2  # 一次给全；冻结是整份状态覆盖，没写的轴即为不冻结
lark-cli sheets +dim-insert --url <U> --sheet-name S1 --position 3 --count 2 --inherit-style before  # 行/列由 --position 决定：数字=行、字母=列，无 --dimension
lark-cli sheets +cols-resize --url <U> --sheet-name S1 --range A:C --width 120  # 像素；分列不同宽用 --widths '{"A":80,"C:E":120}'
lark-cli sheets +sheet-copy --url <U> --sheet-name 源表名 --title 副本名  # --sheet-name=源表、--title=新表名

执行要点（读取 / 原生工具 / 陷阱）

读取：按需求选路径（细则见 lark-sheets-read-data）

"补齐 / 填空"类只探前 10 行就写会漏写表尾——先按 lark-sheets-read-data 确认真实数据末行（准则 3）。

用脚本配合 CLI 时

• 只读 stdout：CLI 数据走 stdout、诊断走 stderr；解析 JSON 别 2>&1（警告混入会解析失败），用管道或单独重定向 stdout。
• 读表理解优先用 scripts/lark_*.py（若可用）：lark_inspect_workbook.py / lark_detect_subtables.py / lark_profile_table.py 是只读脚本，用来把在线表格整理成结构摘要。可选增强，不是必经步骤——scripts/ 只随仓库版 skill 分发，二进制内嵌版没有这些文件；本地不存在时直接用 CLI 等价路径（对照表见 lark-sheets-read-data：+workbook-info / +sheet-info / 小窗口 +csv-get）。它们不替代写入类 shortcut；确认目标区域后，写入仍按对应 reference 执行。
• 喂 CLI 的 CSV / JSON 用 UTF-8 无 BOM；临时文件不要落进用户项目目录——宿主若声明过 workspace 落点纪律（如禁用 /tmp）就照它放，没有则用系统临时目录。
• 命令失败先读 stderr 再调整，别原样重发。
• 回写纯单元格值：值(样式)注记剥离规则见准则 2（SoT）；补充：残留引号一并剥离；排序优先 +range-sort 原生工具，别"读出本地排完再整列写回"。

易漏陷阱

• +dim-insert 不继承行高：只继承值 / 公式 / 边框，新行回落默认高度截断长文本；插行填长文本前读相邻行 row_height，用 +batch-update 合 +rows-resize 补齐。
• 公式容错：日期 / 查找 / 数值转换公式用 IFERROR 包裹；写完读结果列首末各 5 行查 #VALUE! / #REF! / #DIV/0!，必要时再跑 +formula-verify 定位问题；同一方案试错上限 3 次。
• 循环引用：聚合公式引用范围不能含目标 cell 自身或其传递依赖。
• 隐藏行列：+csv-get 默认含隐藏行列；设 --skip-hidden=true 只看可见，返回的真实行号可能跳空。禁止按返回数组下标推导行号，必须使用 annotated_csv 的 [row=N] 或 row_indices。
• 跨 sheet 对象：图表 / 条件格式 / 透视表 / 浮动图片可能分布在多个子表，操作前先 +workbook-info 掌握全局。
• 断定"命令不支持某场景"前必须实调一次拿到真实报错：不得仅凭 --help 输出或推测就降级绕路——工具描述与实现可能不一致，报错才是事实。
• NLP 任务分批：语义理解 / 翻译 / 改写 / 分类等用 NLP 处理（代码只做分批 / 行号映射 / 写回）；数据量大必须分批（通常 30 行 / 批），每批处理完即时写回，单批生成通常 ≤ 300 行，多批用 +batch-update。

公共 flag 速查

各 reference 的 shortcut 标题下用一行徽章标注支持的公共 / 系统 flag（如 _公共四件套 · 系统：--dry-run_；_公共：URL/token（无 sheet 定位）…_ 表示只接 URL/token）。type / 必填 / 描述在本段统一声明：

公共 flag（定位资源）

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

1. spreadsheet 定位（必填）：--url（解析 /sheets/、/spreadsheets/、/wiki/ 三种链接；wiki 链接自动定位背后的电子表格）与 --spreadsheet-token（裸 token）二选一。例外：+workbook-create / +workbook-import 产出还不存在的表，不接受任何定位 flag。
2. sheet 定位（公共四件套 shortcut 必填）：--sheet-id 与 --sheet-name 二选一。
   • ⚠️ 不确定 sheet 名时禁止猜 Sheet1：除非对话或上下文已出现具体值，第一步先 +workbook-info 拿 sheets[].sheet_id/title 再选——中文表的子表常叫"数据"/"工作表 1"/业务名，猜名大概率撞 sheet not found。
   • ⚠️ --range 里的 Sheet1! 前缀不能替代 sheet 定位：仍必须传 --sheet-id / --sheet-name。
   • ⚠️ A1 引用含 ! 时整段用单引号包裹（--range 'Sheet1!A1:B2'，挡 bash history expansion；别用 set +H，sh/dash 下非法）。sheet 名含 -/空格需内层再包单引号时用 ''' 转义：--source ''''Sales-2025'''!A1:D100'。
   • 例外：徽章标 _公共：URL/token（无 sheet 定位）…_ 的 shortcut（+workbook-info / +workbook-export / +batch-update / +styles-put / +dropdown-update|delete / +cells-batch-clear / +sheet-create）不接受 sheet 定位。+pivot-create 用 --target-sheet-id/name（XOR，可都不传）。

# 统一调用范式：两组定位缺一不可（占位符别原样填；表名先 +workbook-info 查）
lark-cli sheets +csv-get --url "https://.../sheets/shtXXX" --sheet-name "<真实表名>" --range "A1:F30"

系统 flag

⚠️ high-risk-write 命令清单（exit 10 强确认门禁）：+batch-update、+cells-clear、+cells-batch-clear、+sheet-delete、+dim-delete、+dropdown-delete，以及各对象删除 +chart-delete / +pivot-delete / +cond-format-delete / +filter-delete / +filter-view-delete / +sparkline-delete / +float-image-delete。

审批协议：先 --dry-run 预览、向用户展示将执行的操作与影响范围，获得用户明确同意后再在原命令追加 --yes 执行。未经用户同意不得带 --yes，也不得在 exit 10 后静默补 --yes 重试——那等于禁用门禁。

Agent 使用提示：写复合 JSON flag 前对结构不确定时，先 --print-schema --flag-name <name>（深层字段用点分路径切片）再构造 payload；图表直接 +chart-create --print-example <type> 拿最小可用模板改参。reference 的 ## Schemas 段只给一层结构。

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

• JSON 类入参分三类：复合 JSON = 深层嵌套对象（--print-schema 可查）；简单 JSON = 一二维标量数组；非 JSON 文本 = 原样文本（如 CSV）。--print-schema 只对复合 JSON flag 有效。
• envelope：所有 shortcut 返回统一外层 {ok, identity, data, ...}；写操作不会自动回读，校验自行调用 +*-list / +*-get / +cells-get。

复合 JSON / 大入参：优先 stdin

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

⏬ 未完——继续调整 offset 续读，直到末行「全文完」标记。

推荐写法：payload 写到用户项目目录之外的临时文件（落点同上：宿主声明过禁用 /tmp 就放 workspace 内相对路径，否则系统临时目录），再用 stdin 喂进去：

# TMPFILE 指向 payload 文件（落点按上文纪律选：workspace 内相对路径，或系统临时目录）
lark-cli sheets +cells-set --url "..." --sheet-name "Sheet1" --range "A1:B2" --cells - < "$TMPFILE"
lark-cli sheets +batch-update --url "..." --dry-run --operations - <<'JSON'   # high-risk：先 --dry-run，用户同意后再追加 --yes 重发
[{"shortcut":"+cells-set","input":{...}}]
JSON

• stdin 每次调用只能给一个 flag：+table-put 同时传 --sheets 与 --styles 两个大 JSON 时，一个走 -、另一个走 @./styles.json（@file 只接受 cwd 下相对路径，绝对路径会被拒；正解是 stdin，别 cd、别把临时文件写进用户项目目录）。
• 参数含特殊字符时用单引号包裹即可，不要 set +H（sh/dash 下非法直接报错）；参数本身含单引号或 payload 大时走 stdin。
• 非 POSIX shell（PowerShell / cmd.exe）适配：本 skill 全部 bash 代码块（heredoc <<'JSON'、单引号转义 '''）只适用于 bash / zsh，动手前先判断当前 shell，非 POSIX 环境按下表改写，不要试错式改引号——@file（cwd 相对路径）是全平台无引号问题的兜底形态：

四、References 与脚本总览

引擎无关 / Excel 引擎 reference 的触发条件见开头「0、方法与规范类 References」表。

飞书引擎 reference：按对象操作该读哪份，见「三」的「场景 → 命令速查」表的「动手前读」列；方法与规范类见开头「0、方法与规范类 References」表。完整文件清单以 references/ 目录为准。

脚本（scripts/）按引擎分别标注：飞书引擎用 lark_inspect_workbook.py（在线表格结构预检）、lark_detect_subtables.py（候选子表块识别）、lark_profile_table.py（表头 / 数据范围 / 字段类型画像）、lark_chart_layout_check.py（图表重叠 / 遮挡内容 / 越界交付检查）、sheets_df.py（DataFrame → --sheets typed payload，含 df_to_sheet）；Excel 引擎用 inspect_workbook.py（结构预检）、preview_excel_rows.py（多行表头预览）、formula_verify.py（公式重算与诊断）、format_range.py（批量样式/条件格式）、_excel_utils.py / lo_runtime.py（内部工具）。

===== 全文完（共 370 行）=====