docs(sheets): sync lark-sheets skill spec from upstream

Refine reference docs and flag-defs descriptions from upstream sheet-skill-spec (--depth wording for +dim-group / +dim-ungroup, plus assorted reference clarifications). Description-only; no CLI behavior or flag surface change.
2026-07-12 04:14:04 +08:00 · 2026-05-23 13:45:44 +08:00
parent 2f5c625ac7
commit b85311c873
13 changed files with 44 additions and 47 deletions
--- a/shortcuts/sheets/data/flag-defs.json
+++ b/shortcuts/sheets/data/flag-defs.json
@@ -975,7 +975,7 @@
        "kind": "own",
        "type": "int",
        "required": "optional",
-        "desc": "Nesting level (used by `+dim-group`); default 1",
+        "desc": "Nesting level for grouping; default 1",
        "default": "1"
      },
      {
@@ -1060,7 +1060,7 @@
        "kind": "own",
        "type": "int",
        "required": "optional",
-        "desc": "Nesting level (used by `+dim-group`); default 1",
+        "desc": "Group nesting level to ungroup; default 1 (outermost)",
        "default": "1"
      },
      {
--- a/skills/lark-sheets/SKILL.md
+++ b/skills/lark-sheets/SKILL.md
@@ -63,7 +63,7 @@ metadata:
 | --- | --- | --- | --- |
 | `--dry-run` | bool | 否 | 零副作用：仅打印请求路径与参数模板，不发起调用；多步操作会输出每个子操作的请求模板 |
 | `--yes` | bool | 是（仅 `high-risk-write`） | 二次确认；不带时退出码 10。详见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 高风险审批协议 |
-| `--print-schema` | bool | 否 | 本地打印复合 JSON flag 的 JSON Schema 并退出，不发起任何调用、不需要其它 required flag。与 `--flag-name <name>` 搭配指定要查哪个 flag；省略 `--flag-name` 时列出该 shortcut 所有可查询的 flag。仅在 shortcut 含复合 JSON flag 时有效。 |
+| `--print-schema` | bool | 否 | 本地打印复合 JSON flag 的 JSON Schema 并退出，不发起任何调用、不需要其它 required flag。与 `--flag-name <name>` 搭配指定要查哪个 flag；省略 `--flag-name` 时列出该 shortcut 所有可查询的 flag。**仅在 shortcut 含复合 JSON flag 时有效**——判断方法：该 shortcut 的 Flags 表里出现类型标注为「复合 JSON」的 flag（如 `--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys` / `--options`）即支持；纯标量 flag 的 shortcut 不支持。 |
 | `--flag-name` | string | 否 | 配合 `--print-schema` 使用，指定要打印 JSON Schema 的 flag 名（不带 `--` 前缀，如 `cells` / `properties` / `operations`）。 |

 **Agent 使用提示**：写复合 JSON flag（`--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys` 等）时，如果对结构不确定，先跑 `lark-cli sheets <shortcut> --print-schema --flag-name <name>` 把完整 JSON Schema 读出来再构造 payload，比靠 reference 的速查表更精确，也避免因为字段拼写或缺失被服务端拒绝。reference 的 `## Schemas` 段只给一层结构，深层只能靠 `--print-schema` 或 `## Examples` 的真实示例。
--- a/skills/lark-sheets/references/lark-sheets-chart.md
+++ b/skills/lark-sheets/references/lark-sheets-chart.md
@@ -20,9 +20,9 @@
 | 用户说 | 图表类型 | 备注 |
 |--------|---------|------|
 | "占比"、"比例"、"各XX占多少" | 饼图（pie） | 单维度占比首选 |
-| "对比"、"各XX的YY" | 柱状图（bar） | 多类别数值对比 |
+| "对比"、"各XX的YY" | 柱形图（column，纵向） | 多类别数值对比；横向条形用 `bar` |
 | "趋势"、"变化"、"走势" | 折线图（line） | 时间序列首选 |
-| "堆积"、"组成构成" | 堆积柱状图（bar + stack） | 多系列累加 |
+| "堆积"、"组成构成" | 堆积柱形图（column + stack） | 多系列累加 |
 | "分布"、"相关性" | 散点图（scatter） | 两变量关系 |

 **多图表需求**：当用户同时提到多种分析（如"统计占比 + 对比数量"），必须创建多个图表，每个对应一种类型，不要只做一个。
@@ -30,7 +30,7 @@
 **`--properties` 结构锚点（构造前必读）**：`--properties` 顶层只有 `position` / `offset` / `size` / `snapshot` 四个字段，**没有**顶层 `data`，也没有再嵌一层 `properties`。图表数据配置全部挂在 `snapshot.data` 下——下文及示例里出现的 `refs` / `headerMode` / `dim1` / `dim2` / `nameRef` 一律指 `snapshot.data.refs` / `snapshot.data.headerMode` / `snapshot.data.dim1` / `snapshot.data.dim2`（及其下的 `serie.nameRef` / `series[].nameRef`）；样式 / 堆叠 / 数据标签等在 `snapshot.plotArea` 下。完整结构以 `lark-cli sheets +chart-create --print-schema --flag-name properties` 为准。

 **常见配置错误（必须注意）**：
- **图表类型选择错误**：用户说"堆积柱状图/百分比堆积"时，应在 `properties.snapshot.plotArea.plot.extra.stack` 中配置堆叠；百分比堆叠需在该 stack 下设置 `percentage: true`。用户说"占比/比例"时，优先考虑饼图或百分比堆积图
+- **图表类型选择错误**：用户说"堆积柱形图/百分比堆积"时，应在 `properties.snapshot.plotArea.plot.extra.stack` 中配置堆叠；百分比堆叠需在该 stack 下设置 `percentage: true`。用户说"占比/比例"时，优先考虑饼图或百分比堆积图。注意区分 `column`（柱形图，纵向）与 `bar`（条形图，横向）是两个不同的 type 取值，"对比/各 XX" 类纵向柱默认用 `column`
 - **数据标签缺失**：用户需要看到具体数值时，需配置 `properties.snapshot.plotArea.plot.labels`（数据标签）相关字段
 - **数据源范围与系列名来源要对齐**：
  - **默认情况（inline 模式）**：`refs` 范围**应包含表头行**（首行/首列即系列名），且范围要精确覆盖目标数据，不要多选或少选。
@@ -69,7 +69,7 @@
 ## ⚠️ chart 数据源引用 pivot 时必须排除总计行（高频致命错误）

 当 chart 要基于刚创建的 pivot 产物画图时，**禁止凭猜写 `refs`**。pivot 默认启用 `show_row_grand_total` / `show_col_grand_total`，产物最后一行/一列通常是"总计"。如果 `refs` 把总计行一并框进去：
- **柱状图**末尾会多一根天文数字柱子（=所有数据求和），把其他柱子压扁到看不见
+- **柱形图**末尾会多一根天文数字柱子（=所有数据求和），把其他柱子压扁到看不见
 - **饼图**会多一个"总计"扇区占 33%+，真实类别的比例完全失真

 **正确流程**：
@@ -78,8 +78,6 @@
 3. 识别并排除"总计"/"小计"行（通常最后一行；嵌套 pivot 还要排除中间层小计）
 4. `+chart-create create` 时 `snapshot.data.refs` 精确到数据行（如 pivot 占 A1:D9、总计在 row9 → chart 用 `A1:D8`）

-详细规则见 `lark-sheets-pivot-table` 第 5 节"pivot → chart 组合场景"。
-
 ## 图表位置选择（创建前必做）

 凭感觉挑列号/行号会被 API 拒（`position is out of sheet range`），浪费一轮调用。按以下四步走：
--- a/skills/lark-sheets/references/lark-sheets-core-operations.md
+++ b/skills/lark-sheets/references/lark-sheets-core-operations.md
@@ -57,7 +57,7 @@
   除此之外，每次读完还必须查三个字段——交叉表和扁平列表都用得到：
   - `actual_range`：本次实际返回的范围（请求超边界时自动裁剪）
   - `current_region`：连续数据矩形（Excel Ctrl+Shift+\*）；若末行 > 请求 range 末行说明数据还没读全
-   - `has_more`：因 `max_bytes` 被截断时为 `true`，按 `actual_range` 末行+1 分页续读，或改走路径 A
+   - `has_more`：返回体超过 `--max-chars` 被截断时为 `true`，按 `actual_range` 末行+1 分页续读，或改走路径 A

 **`current_region` 远大于可灌入上下文的量（如几百行）时**：切换到路径 A（分批 `+csv-get` 导出到本地 + 本地脚本处理），不要用路径 B 翻页硬塞到上下文。

@@ -251,15 +251,7 @@ print(df.head(10))                   # 必做：横向——确认表头行 +
 - 公式来自 Excel 或包含数组场景时，先读取 `lark-sheets-formula-translation` 完成改写，再生成公式。
 - 数组公式必须写成 `=ARRAYFORMULA(数组公式)` 语法。
 - 在公式字符串中，数据范围应使用飞书支持的语法，例如 `H:H`、`A2:B5`。禁止使用不符合飞书公式语法的写法，如 `H2:H`、`2:2` 等。
- 飞书表格不支持以下函数，禁止主动使用；当用户明确要求使用这些函数时，应拒绝并说明飞书不支持：
-  - CUBE 相关函数，如 `CUBEMEMBER`、`CUBESET`、`CUBEVALUE`、`CUBERANK`
-  - `GOOGLEFINANCE`、`GOOGLETRANSLATE` 等 Google 特有函数
-  - `FORECAST.ETS` 相关函数，如 `FORECAST.ETS`、`FORECAST.ETS.STAT`
-  - `INFO`、`RTD` 等系统信息相关函数
-  - `PIVOT`
-  - `AMORDEGRC`
-  - `PHONETIC`
-  - `DETECTLANGUAGE`
+- 飞书表格不支持部分 Excel / Google 专有函数（如 CUBE 系列、`GOOGLETRANSLATE`、`STOCKHISTORY`、`WEBSERVICE` 等），禁止主动使用；当用户明确要求使用这些函数时，应拒绝并说明飞书不支持。**完整的"飞书不支持函数"清单（含替代方案）见 `lark-sheets-formula-translation` 的「飞书不支持的函数」段——以那里为唯一权威清单。**

 ### 向下填充与绝对引用

--- a/skills/lark-sheets/references/lark-sheets-formula-translation.md
+++ b/skills/lark-sheets/references/lark-sheets-formula-translation.md
@@ -205,13 +205,18 @@ Excel：`{=A1:A10*B1:B10}`（Ctrl+Shift+Enter 输入）
 - 年份差：`=DATEDIF(A2,B2,"Y")`
 - 工作日差：`=NETWORKDAYS(A2,B2)`

-## 飞书不支持的 Excel 专有函数
+## 飞书不支持的函数

-以下函数在飞书里不存在，遇到时需要告知用户并提供替代方案：
+> 本段是"飞书不支持函数"的**唯一权威清单**（`lark-sheets-core-operations` 不再单列，统一指向这里）。以下函数在飞书里不存在或被禁用，禁止主动使用；用户明确要求时应拒绝并提供替代方案：

 - `STOCKHISTORY` — 实时股票数据，飞书无等价函数，需手动导入数据
 - `WEBSERVICE` — 外部 HTTP 请求，飞书无等价函数
- `CUBEVALUE`、`CUBEMEMBER`、`CUBESET` 等 — OLAP cube 函数，飞书不支持
+- CUBE 系列（`CUBEVALUE`、`CUBEMEMBER`、`CUBESET`、`CUBERANK` 等）— OLAP cube 函数，飞书不支持
+- `GOOGLEFINANCE`、`GOOGLETRANSLATE` 等 Google 特有函数 — 无等价函数
+- `FORECAST.ETS` 系列（`FORECAST.ETS`、`FORECAST.ETS.STAT` 等）— 飞书不支持
+- `INFO`、`RTD` — 系统信息 / 实时数据函数，飞书不支持
+- `PIVOT` — 用 `+pivot-{create|update|delete}` 透视表对象替代
+- `AMORDEGRC`、`PHONETIC`、`DETECTLANGUAGE` — 飞书不支持

 ## 代表性改写示例

--- a/skills/lark-sheets/references/lark-sheets-pivot-table.md
+++ b/skills/lark-sheets/references/lark-sheets-pivot-table.md
@@ -120,6 +120,11 @@ lark-cli sheets +pivot-list --url "..." --sheet-id "$SID"
 ### `+pivot-create`

 > 数据源 `--source` 必须从表头行开始；空行 / 汇总行会被当作数据参与聚合，需提前用 `+csv-get` 确认起止边界。`--source` 和 `--range` 是独立 flag（不要再放 `--properties`）；`rows` / `columns` / `values` 等数组字段走 `--properties`。
+>
+> **落点 flag 三选一的决策（避免冲突）**：
+> - **默认（推荐）**：`--target-sheet-id` / `--target-position` / `--range` 都不传 → 自动新建子表存放透视表产物。
+> - **放进指定的已有子表**：传 `--target-sheet-id <落点子表 id>` + 可选 `--target-position <子表内起点 cell，默认 A1>`。
+> - **`--range`** 只在不指定落点子表、想精确指定左上角 cell（映射到 `properties.range`）时用；与 `--target-position` 表达同一意图但落不同 wire 字段，**两者不要同时给**。一般用前两种即可，无需 `--range`。

 ```bash
 lark-cli sheets +pivot-create --url "..." --sheet-id "$SRC_SID" \
@@ -142,4 +147,4 @@ lark-cli sheets +pivot-delete --url "..." --pivot-table-id "$PID" --yes
 - `DryRun`：写操作输出"将要 POST/PATCH/DELETE 的 pivot 请求模板"+ 预估输出尺寸（行数 × 列数）。
 - `Execute`：写后调用 `+pivot-list --pivot-table-id <id>` 回读 + `+csv-get` 抽样读透视产物，envelope.meta.verification 给出实际输出尺寸 + 总计行位置。

-> ⚠️ pivot 输出包含总计 / 小计行；后续 chart 引用 pivot 时，`data_range` 必须排除这些行（见 `lark-sheets-chart` 决策段）。
+> ⚠️ pivot 输出包含总计 / 小计行；后续 chart 引用 pivot 时，`snapshot.data.refs` 必须排除这些行（见 `lark-sheets-chart` 的「⚠️ chart 数据源引用 pivot 时必须排除总计行」段）。
--- a/skills/lark-sheets/references/lark-sheets-range-operations.md
+++ b/skills/lark-sheets/references/lark-sheets-range-operations.md
@@ -262,6 +262,6 @@ lark-cli sheets +range-sort --url "..." --sheet-id "$SID" --range "A1:E100" --ha

 ### Validate / DryRun / Execute 约束

- `Validate`：XOR 公共四件套；`+cells-clear` 强制 `--yes` 或 `--dry-run`；`+range-*` 校验源 / 目标 range 在同一 spreadsheet；`+range-sort` 的 `--sort-keys` 必须合法 JSON 数组且 col 都在 `--range` 内；`+rows-resize` / `+cols-resize` 的 `--type` 必填，`--type pixel` 时 `--size` 必填、其它 type 时 `--size` 应省略；`+cols-resize.--type` 不接受 `auto`（只行高支持自适应）。
+- `Validate`：XOR 公共四件套；`+cells-clear` 强制 `--yes` 或 `--dry-run`；`+range-*` 校验源 / 目标 range 在同一 spreadsheet；`+range-sort` 的 `--sort-keys` 必须合法 JSON 数组且 col 都在 `--range` 内；`+rows-resize` / `+cols-resize` 的 `--type` 必填，`--type pixel` 时 `--size` 必填、其它 type 时 `--size` 会被忽略（传了无害）；`+cols-resize.--type` 不接受 `auto`（只行高支持自适应）。
 - `DryRun`：所有写操作输出"将要 PATCH 的 range + 受影响 cell 数估算"。
 - `Execute`：写后调用 `+cells-get --range <影响范围>` 抽样回读对比，envelope.meta.verification 沉淀对比结果。
--- a/skills/lark-sheets/references/lark-sheets-read-data.md
+++ b/skills/lark-sheets/references/lark-sheets-read-data.md
@@ -21,10 +21,12 @@
 |---------|----------------|---------|------|
 | 快速查看纯值数据、批量处理 | `+csv-get` | 对话上下文 | 返回 CSV 文本；大表请按 `--range` 行窗口分批读（单次返回量由 `--max-chars` 自动兜底，截断时看 `has_more`） |
 | 查看公式、样式、批注、数据验证 | `+cells-get` | 对话上下文 | 返回单元格完整信息，token 开销较大 |
+| 查看某区域的下拉框（数据验证）选项 | `+dropdown-get` | 对话上下文 | 返回该 A1 范围已配置的下拉列表选项 |

 **选择原则**：
 - 只看值或做数据处理 → `+csv-get`；大表分批读取，避免一次拉全表撑爆上下文
 - 需要公式/样式/批注 → `+cells-get`
+- 只想知道某区域下拉框有哪些选项 → `+dropdown-get`

 ⚠️ 超大数据请走"`+csv-get` 按 `--range` 行窗口（如 `A1:Z500` / `A501:Z1000` …）分批读到本地文件 + 本地脚本处理 + `+csv-put` 分批回写"。

--- a/skills/lark-sheets/references/lark-sheets-search-replace.md
+++ b/skills/lark-sheets/references/lark-sheets-search-replace.md
@@ -15,7 +15,7 @@
 | 操作需求 | 使用工具 | 说明 |
 |---------|---------|------|
 | 搜索/定位文本 | `+cells-search` | 返回匹配的单元格位置，支持正则、精确匹配等 |
-| 查找并替换文本 | `+cells-replace` | 批量替换文本，支持正则捕获组引用 |
+| 查找并替换文本 | `+cells-replace` | 批量替换文本；`--regex` 模式下 `--replacement` 可用 `$1`、`$2` 引用 `--find` 的捕获组 |

 **常见配置错误（必须注意）**：
 - **不要把操作动词当搜索词**：用户说"汇总金额"是一个操作动作（求和），不是要搜索"汇总金额"这个文本。只有当确实需要定位某个文本值的位置时才用 `+cells-search`
@@ -95,6 +95,10 @@ lark-cli sheets +cells-replace --url "https://example.feishu.cn/sheets/shtXXX" \
 # 确认后执行
 lark-cli sheets +cells-replace --url "https://example.feishu.cn/sheets/shtXXX" \
  --sheet-name "Sheet1" --find "v1" --replacement "v2"
+
+# 正则捕获组：把 "2026-03" 重排成 "03/2026"（$1/$2 引用 --find 的捕获组）
+lark-cli sheets +cells-replace --url "https://example.feishu.cn/sheets/shtXXX" \
+  --sheet-name "Sheet1" --regex --find "(\\d{4})-(\\d{2})" --replacement "$2/$1" --dry-run
 ```

 > `+cells-replace` 虽然 Risk = write，但范围大或正则错可能改一堆。**强烈推荐工作流**：先 `+cells-search` 看匹配数，再 `+cells-replace --dry-run` 预览，最后真正执行。
--- a/skills/lark-sheets/references/lark-sheets-sheet-structure.md
+++ b/skills/lark-sheets/references/lark-sheets-sheet-structure.md
@@ -129,7 +129,7 @@ _公共四件套 · 系统：`--dry-run`_
 | `--dimension` | string | required | 维度方向（行或列）（可选值：`row` / `column`） |
 | `--start` | int | required | 起始位置（0-based） |
 | `--end` | int | required | 结束位置（exclusive） |
-| `--depth` | int | optional | 嵌套层级（`+dim-group` 用），默认 1 |
+| `--depth` | int | optional | 嵌套分组的层级（创建到第几层），默认 1 |
 | `--group-state` | string | optional | 分组初始展开状态（可选值：`expand` / `fold`）（默认 `expand`） |

 ### `+dim-ungroup`
@@ -141,7 +141,7 @@ _公共四件套 · 系统：`--dry-run`_
 | `--dimension` | string | required | 维度方向（行或列）（可选值：`row` / `column`） |
 | `--start` | int | required | 起始位置（0-based） |
 | `--end` | int | required | 结束位置（exclusive） |
-| `--depth` | int | optional | 嵌套层级（`+dim-group` 用），默认 1 |
+| `--depth` | int | optional | 要取消的分组层级，默认 1（最外层） |

 ### `+dim-move`

@@ -205,6 +205,6 @@ lark-cli sheets +dim-freeze --url "..." --sheet-id "$SID" --dimension row --coun

 ### Validate / DryRun / Execute 约束

- `Validate`：XOR 公共四件套；`--start ≤ --end`；`+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`。
+- `Validate`：XOR 公共四件套；`--start ≤ --end`；`+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 的 dimension 区间 + 目标参数"。
 - `Execute`：写后自动调用 `+sheet-info --include row_heights,col_widths,hidden_rows,hidden_cols,groups,frozen` 回读对比，envelope.meta.verification 给出受影响的范围。
--- a/skills/lark-sheets/references/lark-sheets-sparkline.md
+++ b/skills/lark-sheets/references/lark-sheets-sparkline.md
@@ -82,8 +82,7 @@ _创建/更新/部分删除的迷你图属性_

 > **何时需要先 `+sparkline-list`：**
 > - `+sparkline-update`：**总是**需要——拿到组内每一项的 `sparkline_id`，回填到 `properties.sparklines[i]`，server 用它做映射。
-> - `+sparkline-delete` 删单个 / 部分项：需要——同样要把 `sparkline_id` 填进 `properties.sparklines[i]`。
-> - `+sparkline-delete` 删整组：**不需要** `sparkline_id`，只要 `--group-id`。
+> - `+sparkline-delete`：**不需要** `sparkline_id`——CLI 仅支持按 `--group-id` 整组删除（该 shortcut 没有 `--properties`）。

 ### `+sparkline-list`

@@ -131,19 +130,11 @@ lark-cli sheets +sparkline-update --url "..." --sheet-id "$SID" --group-id "grpA

 ### `+sparkline-delete`

-> 两种模式：
-> - **删整组**：不传 `--properties`，仅 `--group-id`。删完后该 group 整个清掉。
-> - **删单个 / 部分项**：传 `--properties '{"sparklines":[{"sparkline_id":"..."},...]}'`，每项必须含 `sparkline_id`；删指定项后组内为空会自动清理 group。
->
-> 强制 `--yes` 或 `--dry-run`；先 `--dry-run` 确认要删的目标。
+> 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
-
-# 删组内指定项（先 +sparkline-list 拿到 sparkline_id）
-lark-cli sheets +sparkline-delete --url "..." --sheet-id "$SID" --group-id "grpA" \
-  --properties '{"sparklines":[{"sparkline_id":"sl_1"}]}' --yes
 ```

 ### Validate / DryRun / Execute 约束
@@ -151,8 +142,8 @@ lark-cli sheets +sparkline-delete --url "..." --sheet-id "$SID" --group-id "grpA
 - `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`**：不传 `--properties` = 删整组（合法路径，不需要 sparkline_id）；传 `properties.sparklines` 时每项必须含 `sparkline_id`（server contract；CLI 本地暂未预检 delete 的 partial-item 分支，缺 id 会到 server 端才被拒）。
-  - `--properties` 顶层只接 `config`（同组共享样式）和 `sparklines`（迷你图项数组）；`+sparkline-create` 要求每个 `sparklines[i]` 含 `position` 与 `source`（或 `source_range`，二选一）。
+  - **`+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>` 回读，envelope.meta.verification 给出 `config` / `sparklines` 字段级对比。
--- a/skills/lark-sheets/references/lark-sheets-visual-standards.md
+++ b/skills/lark-sheets/references/lark-sheets-visual-standards.md
@@ -17,7 +17,7 @@
 2. **对齐方式**：文本列左对齐、数值 / 货币 / 百分比列右对齐、日期 / 分类列居中；垂直方向统一居中
 3. **数值格式**：每列统一小数位 + 千分位（用 `number_format`）；金额列统一货币符号；同一列内**禁止**出现 0 位 / 1 位 / 2 位小数混杂
 4. **边框**：覆盖范围按上方「美化范围必须覆盖所有用户语义目标」规则（含汇总 / 总计 / 表尾说明行），内外框线清晰
-5. **列宽 + 行高 + 自动换行**：详细规则见 `lark-sheets-range-operations` 的「写入后列宽自适应」章节（按最长字符数扩列宽 / 长文本设置 `wrap=true` + 调高行高 / 长数字设置 `number_format` 防科学计数法）
+5. **列宽 + 行高 + 自动换行**：详细规则见 `lark-sheets-range-operations` 的「写入后列宽自适应」章节（按最长字符数扩列宽 / 长文本设置 `cell_styles.word_wrap="auto-wrap"` + 调高行高 / 长数字设置 `number_format` 防科学计数法）

 **差异化标注场景**：用户要求"重复行 / 异常值 / 重要项视觉区分"时，标注列 / 行必须设置与普通数据**显著不同**的 `cell_styles`（背景色 + 加粗 + 字体色至少改一项），不能与普通数据格式完全一致。

@@ -135,7 +135,7 @@
 - 若倒数两行背景色不同（如 #FFFFFF 与 #F3F4F6），新行按奇偶延续，不要固定一个色
 - `border_styles` 最易遗漏（四边都要复制），否则新行会缺框线

-> 具体采样调用与工作流见 `lark-sheets-read-data` 的「格式采样工作流（新增行时继承原有格式）」章节。
+> 具体采样调用（用 `+cells-get` 读源行 `cell_styles` + `border_styles`、`+sheet-info` 读行高合并）见 `lark-sheets-write-cells` 的「新增列 / 新增行的样式继承」章节。

 #### 2B. 基于模板区域的修改（copy 保留所有格式）

--- a/skills/lark-sheets/references/lark-sheets-write-cells.md
+++ b/skills/lark-sheets/references/lark-sheets-write-cells.md
@@ -109,7 +109,7 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl
 - **语义信号**（二选一）：用户 prompt 含"合计/汇总/总计/统计/各科平均分/最下面加一行算…/底部总计"等意图词；或上下文明确是"表尾追加一行做聚合"
 - **结构信号**：新行全行都在做聚合（含 `=SUM/AVERAGE/COUNT/MAX/MIN/SUBTOTAL(...)`，支持 IFERROR 包裹），**不是**单个 cell 算个参考值或每行都算的派生列

-满足上述时，**不要在本 skill 里猜样式**，直接去读 `lark-sheets-visual-standards` 的"汇总行规范"章节，按那里的规则配齐 `font.bold / horizontal_alignment / background_color / border_styles`。
+满足上述时，**不要在本 skill 里猜样式**，直接去读 `lark-sheets-visual-standards` 的「场景一 → 1A. 添加汇总行 / 表头行」章节，按那里的样式要点配齐 `font.bold / horizontal_alignment / background_color / border_styles`。

 反例（**不是**汇总行，禁止自动加粗）：
 - 用户说"在 H5 帮我算个 AVERAGE 参考"→ 单 cell 计算
@@ -132,7 +132,7 @@ Step 2: 再用 `+cells-set` 单独写具体 value/formula（不再传样式，
  `+cells-set` — range="C11:F11", cells=[[{formula: "=AVERAGE(C2:C10)"}, {formula: "=AVERAGE(D2:D10)"}, ...]]
 ```

-⚠️ **Step 1 `cell_styles` 禁止留空**：只铺 border、不铺 `cell_styles`，等于新行从格式上"裸奔"——没字体、没对齐、没背景色。如果新行是汇总行，这意味着 bold 丢失，用户感受"没做样式"。Step 1 的 `cell_styles` 要么继承源区块（`+cells-get` 读相邻已有行样式后复用），要么按汇总行规范（见 `lark-sheets-visual-standards`）配齐。
+⚠️ **Step 1 `cell_styles` 禁止留空**：只铺 border、不铺 `cell_styles`，等于新行从格式上"裸奔"——没字体、没对齐、没背景色。如果新行是汇总行，这意味着 bold 丢失，用户感受"没做样式"。Step 1 的 `cell_styles` 要么继承源区块（`+cells-get` 读相邻已有行样式后复用），要么按汇总行样式要点（见 `lark-sheets-visual-standards` 的「场景一 → 1A. 添加汇总行 / 表头行」）配齐。

 **做法 B：一次写入但每个 cell 都显式带样式**

@@ -295,9 +295,9 @@ _列表选项_
 示例：

 ```bash
-# 纯值（数组形态）
+# 纯值（数组形态）；默认即覆盖非空 cell，无需显式传 --allow-overwrite
 lark-cli sheets +cells-set --url "https://example.feishu.cn/sheets/shtXXX" \
-  --sheet-name "Sheet1" --range "A1:B2" --allow-overwrite \
+  --sheet-name "Sheet1" --range "A1:B2" \
  --cells '[[{"value":"name"},{"value":"score"}],[{"value":"alice"},{"value":95}]]'

 # 富 cell（公式 + 样式，cells 是二维矩阵每元素一个 cell schema）