@yandy0725/pi-lark 0.1.0

package/skills/lark-sheets/references/lark-sheets-sheet-structure.md

@@ -0,0 +1,212 @@
+# Lark Sheet Sheet Structure
+
+## 结构性操作影响面预检（插入 / 删除行列前必做）
+
+插入 / 删除行列、隐藏 / 取消隐藏、冻结、行列分组都会让原表的引用关系发生偏移。**操作前必须**先打印以下三类信息，并评估操作是否会让它们失效；否则禁止执行：
+
+1. **当前合并单元格范围**（来自 `+sheet-info` 的 `merged_cells`）：插入行 / 列时，跨过插入位置的合并区域可能扩张或断裂；删除行 / 列时合并区域可能直接消失。
+2. **现有公式的引用范围**（用 `+cells-get` 抽样附近行 + 跨表引用 + 透视表 / 图表 / 条件格式 / 筛选器的数据源 range）：插入 / 删除会导致 `=SUM(B4:B13)` 这种相对引用偏移；如果操作发生在引用范围内部，可能产生 `#REF!`。
+3. **数据验证（下拉列表）规则的应用范围**：列表来源是某个区域时，区域被部分删除会让规则失效。
+
+不可逆的影响必须先在回复中告知用户，得到确认再执行。
+
+## 使用场景
+
+读写。管理子表结构与布局。本 reference 覆盖 9 个 shortcut（按用途分两类）：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看子表布局 | `+sheet-info` | 获取行高、列宽、隐藏行列、行列分组、合并单元格等信息 |
+| 变更子表结构 | `+dim-{insert|delete|hide|unhide|freeze|group|ungroup|move}` | 插入/删除/隐藏/取消隐藏/冻结/分组/移动行列 |
+
+注意：
+
+- 当表格存在合并单元格时，应结合返回的 `merged_cells` 判断表头、分组标题和区域语义
+- 不要把合并区域中非左上角的空白单元格理解为"无内容"；通常应将左上角单元格的内容视为整个合并区域的语义内容
+- 插入用 `+dim-insert`：`--position`（插入位置；行用 1-based 行号如 `3`，列用字母如 `C`，新行/列插在此位置**之前**）+ `--count`（插入数量，>0）。新行/列样式继承用 `--inherit-style`（`before`/`after`/`none`）
+- 例如"在第 20 行后新增 116 行"：`--position 21 --count 116`（"第 20 行后"即 1-based 行号 21）
+
+**区间表达统一为 A1 风格**：所有涉及"一段连续行/列"的 shortcut 都用同一套 A1 闭区间字符串语法，**不存在 inclusive / exclusive / 0-based / 1-based 跨命令差异**：
+
+| 命令 | 用什么 flag 表达区间 / 位置 | 例子 |
+| --- | --- | --- |
+| `+dim-insert` | `--position` + `--count` | `--position 3 --count 5`（在第 3 行前插 5 行）/ `--position C --count 2`（在 C 列前插 2 列） |
+| `+dim-delete` / `+dim-hide` / `+dim-unhide` / `+dim-group` / `+dim-ungroup` / `+rows-resize` / `+cols-resize` | `--range` | `"3:7"`（第 3-7 行，闭区间）/ `"C:F"`（C-F 列，闭区间）/ `"5"` 或 `"C"`（单行/列） |
+| `+dim-move` | `--source-range`（源区间）+ `--target`（目标位置） | `--source-range "3:7" --target 12`（把第 3-7 行移到第 12 行前）/ `--source-range "C:F" --target H` |
+
+行用 1-based 数字、列用字母——跟 Excel / 飞书 UI 看到的行号、列字母完全一致。
+
+**常见配置错误（必须注意）**：
+- **插入列直接用字母**：`+dim-insert` 的 `--position` 在列场景直接传字母（如 `C`），不要把列字母换算成 0-based 索引
+- **插入后引用偏移**：插入行/列后，原有数据的行号 / 列字母会发生偏移。如果插入后还需要对原有区域执行写入操作，必须重新计算偏移后的位置
+- **删除行列前先确认范围**：删除操作不可逆，执行前应确认 `--range` 精确无误。可先用 `+csv-get` 读取目标区域验证内容
+- **"在 D 列左侧新增一列"的正确写法**：`--position D --count 1`（新列插在 D 列之前）；要继承左侧列样式加 `--inherit-style before`
+- **`+dim-move` 同维度约束**：`--source-range` 是行区间时 `--target` 必须是行号（数字），是列区间时 `--target` 必须是列字母——不可一行一列混用
+- **插入列后必须检查多行表头合并区域**：很多表格有 2-3 行的合并表头。插入列后，原有的合并区域不会自动扩展到新列。必须先用 `+sheet-info --include merges` 读取合并区域，插入后将跨越插入位置的合并区域重新设置（用 `+cells-{merge|unmerge}`），否则新列的表头会是空的、格式不连续
+- **公式写入范围跳过表头行**：写入公式时从数据行开始（不是第 1 行）。先确认表头占几行（可能 1-3 行），公式的起始行 = 表头行数 + 1
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+sheet-info` | read | 工作表 |
+| `+dim-insert` | write | 工作表 |
+| `+dim-delete` | high-risk-write | 工作表 |
+| `+dim-hide` | write | 工作表 |
+| `+dim-unhide` | write | 工作表 |
+| `+dim-freeze` | write | 工作表 |
+| `+dim-group` | write | 工作表 |
+| `+dim-ungroup` | write | 工作表 |
+| `+dim-move` | write | 工作表 |
+
+## Flags
+
+### `+sheet-info`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--include` | string_slice | optional | 要返回的结构信息类别，逗号分隔多个（可选值：`merges` / `row_heights` / `col_widths` / `hidden_rows` / `hidden_cols` / `groups` / `frozen`） |
+| `--range` | string | optional | 限定只返回该 A1 范围的结构信息；省略时返回整表 |
+
+### `+dim-insert`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--inherit-style` | string | optional | 新行/列样式继承策略 enum：`before`（继承前一行/列）/ `after`（继承后一行/列）/ `none`（默认）（可选值：`before` / `after` / `none`） |
+| `--position` | string | required | 插入位置（在此行/列**之前**插入）：行用 1-based 行号如 `3`；列用字母如 `C` |
+| `--count` | int | required | 插入数量（>0） |
+
+### `+dim-delete`
+
+_公共四件套 · 系统：`--yes`、`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--range` | string | required | 要删除的行/列闭区间；行用 1-based 数字如 `3:7` 或单行 `5`，列用字母如 `C:F` 或单列 `C` |
+
+### `+dim-hide`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--range` | string | required | 要隐藏的行/列闭区间；行如 `3:7`，列如 `C:F` |
+
+### `+dim-unhide`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--range` | string | required | 要取消隐藏的行/列闭区间；行如 `3:7`，列如 `C:F` |
+
+### `+dim-freeze`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--dimension` | string | required | 维度方向（行或列）（可选值：`row` / `column`） |
+| `--count` | int | required | 冻结前 N 行/列；传 0 解除冻结 |
+
+### `+dim-group`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--depth` | int | optional | 嵌套分组的层级（创建到第几层），默认 1 |
+| `--group-state` | string | optional | 分组初始展开状态（可选值：`expand` / `fold`）（默认 `expand`） |
+| `--range` | string | required | 要创建分组的行/列闭区间；行如 `3:7`，列如 `C:F` |
+
+### `+dim-ungroup`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--depth` | int | optional | 要取消的分组层级，默认 1（最外层） |
+| `--range` | string | required | 要取消分组的行/列闭区间；行如 `3:7`，列如 `C:F` |
+
+### `+dim-move`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--source-range` | string | required | 要移动的源行/列闭区间；行如 `3:7`，列如 `C:F` |
+| `--target` | string | required | 目标位置（移到此行/列**之前**）：行用 1-based 行号如 `12`，列用字母如 `H`。必须与 `--source-range` 同维度（行/列） |
+
+## Examples
+
+公共四件套：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（XOR）。
+
+### `+sheet-info`
+
+输出契约：返回子表的行高 / 列宽 / 隐藏 / 合并 / 分组等布局元信息。
+
+### `+dim-insert`
+
+```bash
+# 在第 10 行前插 3 行，继承上方样式
+lark-cli sheets +dim-insert --url "https://example.feishu.cn/sheets/shtXXX" \
+  --sheet-id "$SID" --position 10 --count 3 --inherit-style before
+
+# 在 C 列前插 2 列
+lark-cli sheets +dim-insert --url "..." --sheet-id "$SID" --position C --count 2
+```
+
+### `+dim-delete`
+
+```bash
+# 删除第 5-7 行
+lark-cli sheets +dim-delete --url "..." --sheet-id "$SID" --range "5:7" --yes
+
+# 删除 D-F 列
+lark-cli sheets +dim-delete --url "..." --sheet-id "$SID" --range "D:F" --yes
+```
+
+### `+dim-hide` / `+dim-unhide`
+
+```bash
+lark-cli sheets +dim-hide   --url "..." --sheet-id "$SID" --range "5:7"
+lark-cli sheets +dim-unhide --url "..." --sheet-id "$SID" --range "5:7"
+lark-cli sheets +dim-hide   --url "..." --sheet-id "$SID" --range "C:F"
+```
+
+### `+dim-move`
+
+```bash
+# 把第 3-7 行移到第 12 行前
+lark-cli sheets +dim-move --url "..." --sheet-id "$SID" --source-range "3:7" --target 12
+
+# 把 C-F 列移到 H 列前
+lark-cli sheets +dim-move --url "..." --sheet-id "$SID" --source-range "C:F" --target H
+```
+
+### `+rows-resize` / `+cols-resize`
+
+> ⚠️ 这两条 shortcut 来自 `lark-sheets-range-operations` 的 `+rows-resize / +cols-resize` tool（分组在"工作表"是为了发现性）。详细参数和示例在 `lark-sheets-range-operations.md`。
+>
+> 行 vs 列底层 schema 有差异：`+rows-resize.--type` 支持 `pixel` / `standard` / `auto`，`+cols-resize.--type` 只支持 `pixel` / `standard`（列宽不支持自动适应）。
+
+### `+dim-freeze`
+
+```bash
+# 冻结前 1 行（--count 传 0 解除冻结）
+lark-cli sheets +dim-freeze --url "..." --sheet-id "$SID" --dimension row --count 1
+```
+
+### `+dim-group` / `+dim-ungroup`（大纲）
+
+> 仅当用户明确说"行分组 / 列分组 / 大纲 / outline"时触发；按字段做数据分组用 `+pivot-create`。
+
+### Validate / DryRun / Execute 约束
+
+- `Validate`：XOR 公共四件套；`--range` / `--source-range` 必须是合法 A1 闭区间（行用数字、列用字母，不可混用）；`+dim-insert` 的 `--count` > 0；`+dim-move` 的 `--target` 必须与 `--source-range` 同维度（行 vs 列）；`+dim-delete` 强制 `--yes` 或 `--dry-run`；`+rows-resize` / `+cols-resize` 的 `--type` 必填，`--type pixel` 时 `--size` 必填、其它 type 时 `--size` 会被忽略（传了无害）；`+rows-resize` / `+cols-resize` 的行 vs 列 `--type` 差异详见 `lark-sheets-range-operations.md`。
+- `DryRun`：写操作输出"将要 PATCH 的目标范围 + 目标参数"。
+- `Execute`：写后不自动回读；如需确认，自行调用 `+sheet-info --include row_heights,col_widths,hidden_rows,hidden_cols,groups,frozen` 查看受影响的范围。

package/skills/lark-sheets/references/lark-sheets-sparkline.md

@@ -0,0 +1,149 @@
+# Lark Sheet Sparkline
+
+## 真对象硬约束
+
+当用户要求"迷你图 / 趋势线 / 单元格内图表"时，**必须**通过 `+sparkline-{create|update|delete}` 创建真实的迷你图对象。**禁止**用文本字符（如 `▁▂▃▅▇`）拼接在单元格里、或用 `SPARKLINE()` 公式函数（已禁用）代替。判断标准：交付后 `+sparkline-list` 必须能返回该对象。
+
+## 使用场景
+
+读写迷你图对象。本 reference 覆盖 4 个 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看已有迷你图 | `+sparkline-list` | 获取迷你图的类型、数据源和样式配置 |
+| 创建/更新/删除迷你图 | `+sparkline-{create|update|delete}` | 对迷你图执行写入操作 |
+
+典型工作流：先读取现有迷你图了解配置 → 执行创建/更新/删除 → **必须再次读取验证结果**。
+
+**常见配置错误（必须注意）**：
+- **数据源范围要精确**：迷你图的数据源范围必须与实际数据行列精确对应，范围偏移会导致图形展示错误
+- **不要与 SPARKLINE() 公式混淆**：飞书表格的 `SPARKLINE()` 公式函数已被禁用，迷你图只能通过 `+sparkline-{create|update|delete}` 的对象方式创建
+- **创建后必须验证**：调用 `+sparkline-list` 确认迷你图配置正确
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+sparkline-list` | read | 对象 |
+| `+sparkline-create` | write | 对象 |
+| `+sparkline-update` | write | 对象 |
+| `+sparkline-delete` | high-risk-write | 对象 |
+
+## Flags
+
+### `+sparkline-list`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--group-id` | string | optional | 按 group_id 过滤 |
+
+### `+sparkline-create`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--properties` | string + File + Stdin（复合 JSON） | required | JSON：`{config（共享样式配置）, sparklines（迷你图数组）}`；完整字段结构跑 `--print-schema` |
+
+### `+sparkline-update`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--group-id` | string | required | 目标组 id |
+| `--properties` | string + File + Stdin（复合 JSON） | required | JSON：`{config, sparklines}`；先 `+sparkline-list --group-id <id>` 回读再 patch；完整字段结构跑 `--print-schema` |
+
+### `+sparkline-delete`
+
+_公共四件套 · 系统：`--yes`、`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--group-id` | string | required | 目标组 id |
+
+## Schemas
+
+> 复合 JSON flag 字段速查（只列顶层 + 一层嵌套）。深层结构看下方 `## Examples`，或用 `--print-schema` 读完整 JSON Schema（用法见 SKILL.md「公共 flag 速查」与「Agent 使用提示」）。
+
+### `+sparkline-create` `--properties` / `+sparkline-update` `--properties`
+
+_创建/更新/部分删除的迷你图属性_
+
+**顶层字段**：
+- `config` (object?) — 迷你图样式配置, 相同 groupId 的迷你图共享相同的样式 { theme_type?: enum, non_num_show_as?: enum, empty_show_as?: enum, contain_hidden_cells?: boolean, series_color?: string, …共 13 项 }
+- `sparklines` (array<object>?) — 迷你图项列表 each: { sparkline_id?: string, position?: object, source?: string, source_range?: object }
+
+## Examples
+
+公共四件套：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（XOR）。迷你图用 **两层 id** 管理——`group_id` 选组（一组同形态的迷你图共享类型 / 样式 / 数据源映射），`sparkline_id` 在组内选具体某一项。注意：不等同于已禁用的 `SPARKLINE()` 公式函数。
+
+> **何时需要先 `+sparkline-list`：**
+> - `+sparkline-update`：**总是**需要——拿到组内每一项的 `sparkline_id`，回填到 `properties.sparklines[i]`，server 用它做映射。
+> - `+sparkline-delete`：**不需要** `sparkline_id`——CLI 仅支持按 `--group-id` 整组删除（该 shortcut 没有 `--properties`）。
+
+### `+sparkline-list`
+
+```bash
+# 列出整张子表的所有迷你图组
+lark-cli sheets +sparkline-list --url "..." --sheet-id "$SID"
+
+# 钉到单组：返回该组每一项的 sparkline_id（update / partial-delete 必需）
+lark-cli sheets +sparkline-list --url "..." --sheet-id "$SID" --group-id "grpA"
+```
+
+### `+sparkline-create`
+
+> `--properties` 顶层只有 `config`（同组共享样式，如 `line_width` / `points` / `extremum_max` / `extremum_min`）和 `sparklines`（迷你图项数组）两个字段。`sparklines[i]` 每项必须含 `position`（落点 cell，`row` + `col`）+ `source`（数据 A1 范围，与 `source_range` 二选一）；create 时 `sparkline_id` 可省略，由系统生成。
+
+```bash
+lark-cli sheets +sparkline-create --url "..." --sheet-id "$SID" --properties @sparkline.json
+```
+
+`sparkline.json` 示例（在 F 列嵌入两行折线迷你图，数据分别来自 A2:E2 和 A3:E3）：
+
+```jsonc
+{
+  "config": { "line_width": 2 },
+  "sparklines": [
+    {"position": {"row": 1, "col": "F"}, "source": "'Sheet1'!A2:E2"},
+    {"position": {"row": 2, "col": "F"}, "source": "'Sheet1'!A3:E3"}
+  ]
+}
+```
+
+### `+sparkline-update`
+
+> 两步式：先 `+sparkline-list --group-id <id>` 拿当前组的 `sparkline_id` 列表，再构造 `properties.sparklines[]`——**每项必须带 `sparkline_id`**。只改样式可只传 `properties.config`（不带 `sparklines`，整组样式覆盖式更新）。
+
+```bash
+# 假设 +sparkline-list 已返回 group_id=grpA，组内 sparkline_id=sl_1 / sl_2
+lark-cli sheets +sparkline-update --url "..." --sheet-id "$SID" --group-id "grpA" --properties '{
+  "sparklines": [
+    {"sparkline_id":"sl_1","source":"'Sheet1'!A2:A20"},
+    {"sparkline_id":"sl_2","source":"'Sheet1'!B2:B20"}
+  ]
+}'
+```
+
+### `+sparkline-delete`
+
+> CLI 仅支持**整组删除**：传 `--group-id` 删掉该组全部迷你图。该 shortcut **没有** `--properties`，无法只删组内单项（需求上要"留一部分"时，改用 `+sparkline-update` 重写该组的 `sparklines` 列表，而不是 delete）。强制 `--yes` 或 `--dry-run`；先 `--dry-run` 确认要删的目标组。
+
+```bash
+# 删整组
+lark-cli sheets +sparkline-delete --url "..." --sheet-id "$SID" --group-id "grpA" --yes
+```
+
+### Validate / DryRun / Execute 约束
+
+- `Validate`：
+  - XOR 公共四件套；`+sparkline-{update,delete}` 必须 `--group-id`。
+  - **`+sparkline-update`**：当 `properties.sparklines` 非空时，每一项必须含 `sparkline_id`（CLI 预检，错误信息会指回 `+sparkline-list`，避免命中服务端的不可读拒绝）；只传 `properties.config`（config-only update）合法、不触发 sparkline_id 检查。
+  - **`+sparkline-delete`**：只接 `--group-id`（整组删除），**没有** `--properties`，无法删组内单项。
+  - `--properties`（仅 `+sparkline-create` / `+sparkline-update`）顶层只接 `config`（同组共享样式）和 `sparklines`（迷你图项数组）；`+sparkline-create` 要求每个 `sparklines[i]` 含 `position` 与 `source`（或 `source_range`，二选一）。
+  - `+sparkline-delete` 强制 `--yes` 或 `--dry-run`。
+- `DryRun`：写操作输出"将要 POST/PATCH/DELETE 的 sparkline group 请求模板"。
+- `Execute`：写后不自动回读；如需确认，自行调用 `+sparkline-list --group-id <id>` 查看 `config` / `sparklines`。

package/skills/lark-sheets/references/lark-sheets-visual-standards.md

@@ -0,0 +1,205 @@
+# 飞书表格样式与配色规范
+
+> **本文定位**：飞书表格"正确视觉输出"的取值标准与美化决策流——配色、表头、对齐、数值格式、斑马纹、列宽行高、图表展示，以及新增 / 继承 / 美化已有区域三类场景的做法。
+> **边界**：本文只讲"样式长什么样、怎么决策"；**怎么调用工具写入样式**（`cell_styles` / `border_styles` 字段、合并、resize 等参数）见 `lark-sheets-write-cells` / `lark-sheets-range-operations` / `lark-sheets-batch-update`。**条件格式**（高亮 / 标红 / 数据条 / 色阶）见 `lark-sheets-conditional-format`。本文不含 shortcut，铁律见 `lark-sheets-core-operations`。
+
+## 最高优先级原则
+
+- **用户指令优先**：用户明确提出的格式要求（如"使用红色背景"）具有最高权重，即使与通用审美冲突。
+- **继承原表风格**：编辑前先采样原文件视觉特征（色系、边框、对齐、数字格式），新增内容必须与之对齐。严禁对已有风格的文件强行施加通用标准化格式。
+- **扩展而非覆盖**：新增行列或追加数据时，目标是"扩展原模板"——继承邻近区域的表头风格、条纹节奏、边框层级、对齐方式、数字格式和列宽/行高策略。
+- **美化只动样式属性，不动数据**：对**已有区域**做美化时，**只能**修改 `font` / `fill` / `border` / `alignment` / `number_format` 这 5 类样式属性。**禁止**改动原始单元格的 `value` / `formula`、合并区域、行列结构、Sheet 名称。如果美化需求需要改变数据布局（例如"汇总行加进表里"），必须把"加汇总行"和"美化"拆成两步，前者属于编辑动作、需另行得到用户授权。
+- **不可见视觉属性也属保护对象**：原表的**合并范围、对齐方式（H-Align/V-Align）、行高列宽、数字格式**是用户能感知但不一定会明示的视觉属性。即使用户没说"保留这些"，**禁止**因写入新内容而修改它们；写公式 / 写值 / 写新列时只传 `value` / `formula`，不要重置 `alignment` / `number_format` 等字段为默认值（重置等同于改动）。**例外**：用户明示要修改这些属性时（如"调整对齐 / 合并 / 列宽"）才能动。
+- **美化范围必须覆盖所有用户语义目标**：用户说"给表格加边框 / 美化整个表"时，范围 = 实际数据区域**含所有数据行**（含汇总行、总计行、表尾备注行），不能停在"看起来主体内容结束"的地方。落地前先用 `current_region` + 末尾 5~10 行核对真实末行（同 `lark-sheets-read-data` 的「确定数据范围的正确流程」），再设置美化范围。范围漏掉用户提到的目标行 / 列**直接判失败**。
+
+## 美化任务 5 维度 checklist（用户说"美化 / 整理 / 让表更清晰 / 适合打印"时必做）
+
+当用户用"美化 / 整理表格 / 让表清晰 / 适合打印 / 调整样式"等口语表达**主动美化需求**时，**必须**遍历以下 5 个维度逐一落地，**只动一处就交付**（如只加边框）属于违规：
+
+1. **表头格式区分**：表头行加粗 + 背景色填充（与数据行有色差）+ 居中对齐；多行表头时全部行同步处理
+2. **对齐方式**：文本列左对齐、数值 / 货币 / 百分比列右对齐、日期 / 分类列居中；垂直方向统一居中
+3. **数值格式**：每列统一小数位 + 千分位（用 `number_format`）；金额列统一货币符号；同一列内**禁止**出现 0 位 / 1 位 / 2 位小数混杂
+4. **边框**：覆盖范围按上方「美化范围必须覆盖所有用户语义目标」规则（含汇总 / 总计 / 表尾说明行），内外框线清晰
+5. **列宽 + 行高 + 自动换行**：详细规则见 `lark-sheets-range-operations` 的「写入后列宽自适应」章节（按最长字符数扩列宽 / 长文本设置 `cell_styles.word_wrap="auto-wrap"` + 调高行高 / 长数字设置 `number_format` 防科学计数法）
+
+**差异化标注场景**：用户要求"重复行 / 异常值 / 重要项视觉区分"时，标注列 / 行必须设置与普通数据**显著不同**的 `cell_styles`（背景色 + 加粗 + 字体色至少改一项），不能与普通数据格式完全一致。
+
+**显式要求边框 / 表头 / 对齐时同样按上面标准落地**（不必等用户说"美化"）：① 用户说"给某矩形区域加边框"必须**整个矩形含表头行、数据行、汇总行全部加内外框**，落地后核起 / 末行、末列三边界（反例：要求加边框的区域实际无任何边框）；② **新建表头前先确认哪一行才是表头**——别把已有的第一行数据误当表头刷成蓝底白字，真正该加的表头列也要建出来（反例：把第一行数据误设成了表头样式）；③ 新增 / 编辑区域的字号必须与原表一致，禁止 13 号与 14 号、10 号与 11 号混杂（反例：新列字号与原表不一致）。
+
+## 通用样式规范
+
+> 以下取值标准都在「最高优先级原则」的**继承原表风格 / 扩展而非覆盖**前提下生效：凡涉及"沿用原表"的条目，遵循该原则即可，本节不再逐条复述。
+
+### 1. 表头样式
+
+- 表头/汇总行须与数据区域有明确视觉区分。
+- 使用低饱和度背景色搭配字体颜色（如深蓝 + 白字，浅蓝 + 黑字），文字加粗、水平居中。
+- 表头覆盖多列时使用合并单元格。
+
+### 2. 数据区域样式
+
+- 减少垂直线条，优先使用水平浅灰细线。
+- **对齐方式**：文本左对齐，数值/货币/百分比右对齐，日期或分类居中，所有内容垂直居中。
+- 次要信息（备注、次要日期等）使用缩小字号或浅灰色。
+- **Zebra Stripes**：数据行 > 10 行时可使用交替背景色引导视线。
+  - 设置前先清理原区域背景色为白色（#FFFFFF），再设置斑马纹色，避免新旧混杂。
+  - 优先直接设置单元格背景色，而非条件格式（除非用户要求）。
+  - 推荐配色：奇数行 #FFFFFF，偶数行 #F3F4F6 或 #EBF1F8。
+
+### 3. 数值格式
+
+- 百分比使用 `%` 符号，适当注明单位和货币符号（¥、$）。
+- 大于 1000 的数字使用千分位符，保留一致的小数位数（1–2 位）。
+- 涉及数据检索的须注明数据来源。
+- 可使用数据条/色阶/条件格式增强可视化。
+
+### 4. 整体结构
+
+- 长表/宽表考虑冻结行列，方便滚动查看。
+- **长文本处理**：启用自动换行，行高合理调整以确保阅读舒适，添加适当垂直留白，目标是清晰、专业、不拥挤的布局。
+- 保持表格简洁，合理分组（可用合并单元格展示分组），在适当位置添加合计或汇总行。
+- **区域分隔**：多阶段或多类别时，使用柔和背景色块进行逻辑分区，而非简单边框。
+- **增删行列的样式规则**：
+  - 新增整列继承同组列的表头样式、列宽、对齐和数字格式；新增整行继承同层级数据行或汇总行风格，避免写成表头风格。追加列时需判断是否应加入已有合并单元格（常见于顶部标题行）。
+  - 若追加位置紧邻汇总行、说明区或空白分隔区，先判断真实数据区域边界再操作，避免破坏原有结构。
+  - **Zebra Stripes 维护**：插入或删除行后若影响后续行奇偶性，须从受影响行往后重建条纹（先清理再重设）。少量增删用局部重建，大量变动用全局清理+统一重建。
+  - 具体采样与复制流程见下方「场景二：从已有区域继承美化」。
+- **列宽调整**（飞书 `+rows-resize / +cols-resize` 按 pixel 传值）：
+  - 禁止硬编码固定列宽，须根据该列实际内容长度估算像素。
+  - 经验估算：中文每字约 15-18px，英文/数字每字约 7-9px，外加 10-16px padding。
+  - 上下限建议 80~400px；超上限启用自动换行（`word_wrap: auto-wrap`）+ 调整行高，而非无限加宽。
+  - 合并单元格不参与列宽计算，避免撑宽单列。
+  - 复制自原文件的列优先沿用原列宽，不重新计算覆盖。
+
+### 5. 配色
+
+- 优先沿用原表色板与明暗层级（见「继承原表风格」），新增区域不凭空换色，确保视觉连续。
+- 背景填充选择柔和色（如浅蓝 `#DDEBF7`），区分颜色时优先同一主题色不同深浅，避免超过 3 种主题色。
+
+### 6. 图表展示
+
+- 遵循用户指令选择图表类型，或匹配用户意图（饼图/环形图 → 占比，折线图 → 趋势）。
+- 包含必要元素：标题、图例、数据标签、坐标轴标题。
+- 调整至合适大小，避免数据和标签过多堆叠。
+- **图表放置防重叠**：新增图表前须计算放置区域，避免与已有图表重叠。具体步骤：
+  1. 调用 `+chart-list` 获取当前工作表所有已有图表的 `position`（锚点单元格：`row` 行索引、`col` 列索引如 "A"/"B"）、`offset`（锚点内偏移：`row_offset`、`col_offset`，单位像素）以及 `size`（`width`、`height`，单位像素）。
+  2. 获取工作表的行高和列宽信息（像素）。
+  3. 根据每个图表的锚点 `position.row`/`position.col` + 偏移 `offset.row_offset`/`offset.col_offset` + 尺寸 `size.width`/`size.height`，结合行高列宽，计算出每个已有图表覆盖的像素矩形区域 `(x_min, y_min, x_max, y_max)`。
+  4. 为新图表选定大小后，候选放置位置应避开所有已有矩形区域；若存在重叠则向下或向右偏移，直至找到无冲突位置。
+  5. 若工作表已无足够空间，优先向下方空白区域放置，保持图表间至少 1 行或 1 列的间距。
+
+> 飞书表格中颜色需带 `#` 前缀（如 `#0070C0`），与 openpyxl 的无前缀写法不同。
+> 具体工具调用参数格式，请读取对应工具 skill（`lark-sheets-write-cells`、`lark-sheets-conditional-format`、`lark-sheets-range-operations` 等）。
+
+---
+
+## 场景化操作指南
+
+### 场景一：新增独立样式
+
+> 适用情况：在表格中创建全新的、具有独立视觉特征的区域，如汇总行、新表头、独立数据表等。
+
+#### 1A. 添加汇总行 / 表头行
+
+**决策流程：**
+1. 先用 `+cells-get` 读取目标位置上方的数据区域，确认数据边界和已有样式（背景色、字体大小等）
+2. 如果需要新增空行，先用 `+dim-{insert|delete|hide|unhide|freeze|group|ungroup}` 插入行
+3. 用 `+cells-set` 写入汇总公式 + 特殊样式（背景色区分 + 加粗 + 边框）
+4. 如果汇总行标题需要跨列显示，追加 `+cells-{merge|unmerge}` 合并标题区域
+
+**样式要点：**
+- 汇总行使用比数据区域更深的同色系背景（如数据区 #EBF1F8 → 汇总行 #D6E4F0 或 #4472C4 + 白字）
+- 必须加粗，水平对齐方式与数据列一致（数值列右对齐，文本列左对齐）
+- 上方加一条较粗的边框线，与数据区域形成视觉分隔
+
+#### 1B. 添加独立数据表/独立区域
+
+**决策流程：**
+
+1. 新建 sheet，或用 `+cells-get` 或 `+workbook-info` 确认已有表格的占用范围，找到空闲区域
+2. 用 `+cells-get` 采样已有表格的表头样式（背景色、字体大小、字重、对齐方式）和数据区域样式
+3. 新表头复用已有表头的配色和字体参数（保持风格统一），但内容和列宽可独立
+4. 新数据区域复用已有数据区域的对齐规则、边框风格、数字格式
+5. 用 `+cells-set` 一次性写入新表头 + 数据
+
+**样式要点：**
+- 必须复用：背景色色系、字体大小、字重、边框风格
+- 可以独立：列宽、行高、具体数字格式（根据新数据的类型调整）
+- 新旧表格之间至少留 1~2 行空白作为视觉分隔
+
+### 场景二：从已有区域继承美化
+
+> 适用情况：新增的行/列/区域与已有内容性质相同（数据类型、层级一致），需要无缝衔接已有格式。
+
+#### 2A. 继续补充行/列（数据性质与已有内容一致）
+
+**核心规则**：采样紧邻 2 行 → 判断并延续 Zebra Stripes 奇偶性 → 按 write-cells 的继承清单带齐样式写入。
+
+**斑马纹延续要点**（本节只管"奇偶判断"这一标准，"带哪些样式字段写入"的机制见下方指针）：
+
+- 至少读 2 行（末行 + 倒数第二行）才能判断是否有斑马纹交替色
+- 若倒数两行背景色不同（如 #FFFFFF 与 #F3F4F6），新行按奇偶延续，不要固定一个色
+
+> 具体继承哪些字段、怎么采样与写入（`+cells-get` 读源行 `cell_styles` + `border_styles`、`+sheet-info --include row_heights,merges` 读行高合并、带齐 6 类样式写入）见 `lark-sheets-write-cells` 的「新增列 / 新增行的样式继承」章节——`border_styles` 四边最易遗漏，以那里为准。
+
+#### 2B. 基于模板区域的修改（copy 保留所有格式）
+
+**核心思路：三步分层法**
+
+```
+Step 1 — 格式铺开：`+batch-update` + `+range-copy`（或 `+range-fill`）
+  └── 将模板行/区域的 **全部格式**（样式、边框、数字格式、数据验证等）复制到目标区域
+  └── 推荐用 `+range-copy --paste-type formats`（仅复制格式，目标值/公式保留），即"格式刷"
+  └── 若需连带公式平移填充（如公式列结构一致），改用 `+range-fill --series-type copy` 或 `+range-copy --paste-type all`
+
+Step 2 — 内容覆写：`+batch-update` + `+cells-set`（仅传 value/formula，不传任何样式）
+  └── 将每行的实际数据写入，cell_styles 全部省略，因为格式已在 Step 1 中就位
+
+Step 3 — 微调收尾：`+batch-update` + `+rows-resize / +cols-resize` / `+cells-{merge|unmerge}` 等
+  └── 调整行高列宽、处理合并单元格、扩展条件格式范围等边缘情况
+```
+
+**关键注意事项：**
+- Step 1 用 `+range-copy --paste-type formats` 时只铺格式、不动值/公式，Step 2 再用 `+cells-set` 写值即可（`+cells-set` 默认覆盖，无需额外 flag）；若 Step 1 用 `--paste-type all` 连带复制了值/公式，Step 2 写入同样会覆盖（默认行为）
+- `+range-fill --series-type auto`（或 `linear`/`date`）会自动递增数字序列（1→2→3）和日期序列，`+range-fill --series-type copy` 则原样复制值但公式引用会自动平移
+- 如果模板区域存在合并单元格，copy/fill 不会复制合并状态，必须在 Step 3 中用 `+cells-{merge|unmerge}` 补全
+- 如果模板区域有条件格式，需要在 Step 3 中通过 `+cond-format-update` 扩展 ranges
+
+**场景：纯"格式刷"（用户说"把 A 列样式应用到 B 列"、"格式复制过去"、"只刷格式不改数据"）**
+
+单步即可，无需三步分层：调用 `+range-copy --paste-type formats`，`--source-range` 为样式来源、`--target-range` 为目标起点。参数细节见 `lark-sheets-range-operations`。
+
+### 场景三：已有区域格式美化
+
+> 适用情况：对已存在数据的区域进行格式美化（不改变数据内容），重点处理表头、汇总行等特殊行的识别与格式设置，需特别注意合并单元格的安全操作。
+
+#### 整体操作流程
+
+```
+1. 探查阶段
+   ├── `+workbook-info` → 获取子表列表、行列数、冻结位置
+   ├── `+sheet-info --include merges` → 获取合并区域
+   ├── `+cells-get`（前几行 + 末尾几行，`--include style`）→ 采样表头/数据区/汇总行样式
+   └── 分析结果 → 建立区域地图（表头行号、数据起止行号、汇总行号、合并区域列表）
+
+2. 规划阶段
+   ├── 判断表头行：通常第 1 行或前 2 行，特征为加粗/背景色/合并/居中
+   ├── 判断汇总行：通常最后 1~2 行，特征为加粗/SUM/AVERAGE 公式/更深背景色
+   ├── 判断合并区域：从 `+cells-get` 返回中识别（多个单元格同值且样式相同通常暗示合并）
+   └── 制定美化方案：按区域分别设置样式
+
+3. 执行阶段（按顺序）
+   ├── 先处理合并单元格（如需取消合并再重新合并，必须先 unmerge 再 merge）
+   ├── 设置表头样式
+   ├── 设置数据区域样式
+   ├── 设置汇总行样式
+   └── 调整列宽行高
+```
+
+#### 美化中的合并单元格要点
+
+- 编辑前先识别已有合并区域（见探查阶段），避免破坏原有语义分区。
+- 美化表头/分组标题时，若需修改合并区域的范围或样式，遵循"先 `unmerge` → 修改 → 再 `merge`"顺序。
+- 合并区域样式只写左上角，不要对合并内的其他单元格重复写入样式。
+
+> 合并单元格完整的安全操作规则（含数据保护、样式占位等 5 条）见 `lark-sheets-range-operations` 的 `+cells-{merge|unmerge}` 章节。