@amaster.ai/pi-lark 0.1.13 → 0.1.15

package/skills/lark-sheets/references/lark-sheets-legacy-command-migration.md

@@ -0,0 +1,152 @@
+# Lark Sheet 旧命令迁移指南
+
+## 适用场景
+
+调用 `sheets` 旧命令（`+create`、`+read`、`+write`、`+create-sheet`、`+media-upload` 等 42 个）时收到
+`unknown subcommand`，或手上的脚本 / skill 早于表格命令重构。本文给出全部旧命令的替代命令，以及
+**不只是改名**的那些差异（flag 名、单元格 payload 写法、响应字段路径）。
+
+这些旧命令在重构后曾以别名形式保留了一段时间，线上使用量降到 5% 以下后整体删除。它们不再存在，
+也没有 deprecation 提示——直接报 `unknown subcommand`。
+
+## 一、命令名对照表
+
+### 工作簿
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+create` | `+workbook-create` |
+| `+info` | `+workbook-info` |
+| `+export` | `+workbook-export` |
+
+### 子表
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+create-sheet` | `+sheet-create` |
+| `+copy-sheet` | `+sheet-copy` |
+| `+delete-sheet` | `+sheet-delete` |
+| `+update-sheet` | 按意图拆开：`+sheet-rename` / `+sheet-move` / `+sheet-hide` / `+sheet-unhide` / `+dim-freeze` |
+
+### 单元格数据
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+read` | `+cells-get`（只要纯值 / CSV 用 `+csv-get`，整表用 `+table-get`） |
+| `+write` | `+cells-set` |
+| `+append` | `+table-put --sheets '{"sheets":[{…,"mode":"append"}]}'`（追加到已有数据下方；顶层必须是 `{"sheets":[…]}` 信封，裸数组会被拒绝）；若已知目标行号，`+cells-set` 写该区域即可 |
+| `+find` | `+cells-search` |
+| `+replace` | `+cells-replace` |
+
+### 样式 / 合并 / 单元格图片
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+set-style` | `+cells-set-style` |
+| `+batch-set-style` | `+cells-batch-set-style` |
+| `+merge-cells` | `+cells-merge` |
+| `+unmerge-cells` | `+cells-unmerge` |
+| `+write-image` | `+cells-set-image` |
+
+### 行列
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+add-dimension` | `+dim-insert` |
+| `+insert-dimension` | `+dim-insert` |
+| `+move-dimension` | `+dim-move` |
+| `+delete-dimension` | `+dim-delete` |
+| `+update-dimension` | 按意图拆开：`+rows-resize` / `+cols-resize` / `+dim-hide` / `+dim-unhide` / `+dim-group` / `+dim-ungroup` / `+dim-freeze` |
+
+### 筛选视图
+
+条件（condition）不再是独立对象，已折叠进视图自身的 flag。
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+create-filter-view` | `+filter-view-create` |
+| `+update-filter-view` | `+filter-view-update` |
+| `+list-filter-views` | `+filter-view-list` |
+| `+get-filter-view` | `+filter-view-list` |
+| `+delete-filter-view` | `+filter-view-delete` |
+| `+create-filter-view-condition` | `+filter-view-update` |
+| `+update-filter-view-condition` | `+filter-view-update` |
+| `+delete-filter-view-condition` | `+filter-view-update` |
+| `+list-filter-view-conditions` | `+filter-view-list` |
+| `+get-filter-view-condition` | `+filter-view-list` |
+
+### 下拉列表
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+set-dropdown` | `+dropdown-set` |
+| `+update-dropdown` | `+dropdown-update` |
+| `+get-dropdown` | `+dropdown-get` |
+| `+delete-dropdown` | `+dropdown-delete` |
+
+### 浮动图片
+
+单独的上传步骤已折叠进创建命令：`+float-image-create` 直接收本地 `--image` 路径。
+
+| 旧命令 | 替代 |
+| --- | --- |
+| `+media-upload` | `+float-image-create`（嵌入单元格内的图片用 `+cells-set-image`） |
+| `+create-float-image` | `+float-image-create` |
+| `+update-float-image` | `+float-image-update` |
+| `+delete-float-image` | `+float-image-delete` |
+| `+get-float-image` | `+float-image-list` |
+| `+list-float-images` | `+float-image-list` |
+
+## 二、只改命令名会踩的坑
+
+### 1. 单元格 payload 词汇变了
+
+旧命令的 `--values` 里，公式写成 `{"type":"formula","text":"=SUM(C2:C5)"}`。这类带 `type` / `text`
+的写法会被 `+cells-set` **直接拒绝**：
+
+```text
+--cells[0][0].type is not a cell field — the value type is inferred from the JSON value;
+control display format via cell_styles.number_format
+```
+
+新写法把字段直接放在 cell 对象上（`{"formula":"=SUM(C2:C5)"}`）：
+
+```bash
+lark-cli sheets +cells-set --range C6 --cells '[[{"formula":"=SUM(C2:C5)"}]]'
+```
+
+内容字段只能选一个：`value` / `formula` / `rich_text` / `multiple_values`；`cell_styles`、`border_styles`、
+`note`、`data_validation` 可与内容字段自由叠加。纯标量（`"文本"`、`123`）也可直接放在格位上。
+完整字段用 `+cells-set --print-schema --flag-name cells` 查看。
+
+`--values` 在 `+cells-set` 上仍作为 `--cells` 的别名被接受，所以**只有携带旧对象写法的调用才会失败**。
+
+### 2. 响应字段路径变了
+
+| 命令 | 取值路径 |
+| --- | --- |
+| `+workbook-create` | spreadsheet token 在 `data.spreadsheet.spreadsheet_token` |
+| `+workbook-info` | 子表列表在 `data.sheets[]`（旧 `+info` 是 `data.sheets.sheets[]`）；**不再回显** spreadsheet token |
+| `+cells-get` | 值在 `data.ranges[].cells[][].value` |
+| `+cells-search` | `data.total_matches`、`data.matches[].address` |
+| `+sheet-create` / `+sheet-copy` | 新子表 id 在 `data.sheet_id` |
+| `+sheet-rename` / `+sheet-hide` | **只返回 `data.revision`**，要确认结果需回读 `+workbook-info`（`sheet_name`、`is_hidden`） |
+| `+dim-freeze` | `data.frozen_rows`、`data.frozen_columns` |
+
+### 3. `+update-sheet` 的一次调用要拆成多次
+
+旧命令在一次调用里同时设置标题、隐藏态和冻结行列；新命令按意图拆开，需要分别调用
+`+sheet-rename`、`+sheet-hide` / `+sheet-unhide`、`+dim-freeze`。
+
+注意 `+dim-freeze` 是**整份冻结状态覆盖**：`--rows` 与 `--cols` 一起表达完整状态，没写的那个轴会变成未冻结。
+
+### 4. 底层接口换了
+
+子表增删改查从 `sheets/v2/spreadsheets/{token}/sheets_batch_update` 换成了
+`sheet_ai/v2/spreadsheets/{token}/tools/invoke_write`（`modify_workbook_structure`）。
+只有直接断言过 HTTP 请求体的调用方需要关心这条。
+
+## 三、找不到对应命令时
+
+`lark-cli sheets --help` 列出全部当前命令；单个命令的 flag 与示例用 `lark-cli sheets <命令> --help`。
+按任务选命令的决策表见 [SKILL.md](../SKILL.md)。

package/skills/lark-sheets/references/lark-sheets-read-data.md

@@ -24,13 +24,13 @@
 | 快速查看纯值数据、批量处理 | `+csv-get` | 对话上下文 | 返回 CSV 文本（每行带 `[row=N]` 前缀）；大表请按 `--range` 行窗口分批读（截断时看 `has_more`） |
 | 按列类型结构化读出（喂 DataFrame / round-trip 回 `+table-put`） | `+table-get` | 对话上下文 | 返回 typed 协议（`columns:[列名]` + `data` + `dtypes`/`formats` + `range`），输出形状对齐 pandas split；可一行 `pd.DataFrame(sheet["data"], columns=sheet["columns"]).astype(sheet["dtypes"])` 还原 DataFrame，或直接 round-trip 回 `+table-put`。不带 `--range` 时读**完整 used range**（跨过表中部空行 / 空列），每个子表回传读取范围 `range`；被 `max_chars` 裁掉时**该子表**带 `truncated: true` 与 `truncation_warning`，预算耗尽导致后续整表未读时**顶层**也带同组字段，`--output-path` 落盘模式另看 stdout 回执的 `complete` / `truncated`——**先看截断字段再用数据；三层都没报也不等于逻辑读全**，仍要用返回数据实际行数、关键末行与源数据交叉核对（详见下文）。注意这与下文 `current_region` "遇表中部空行截断"不矛盾：`+table-get` 读的是子表物理 used range（飞书记录的已用矩形，含中间空行），`current_region` 是从锚点连通扩展、遇整行空行就断 |
 | 查看公式、样式、批注、数据验证 | `+cells-get` | 对话上下文 | 返回单元格完整信息，token 开销较大 |
-| 查看某区域的下拉框（数据验证）选项 | `+dropdown-get` | 对话上下文 | 返回该 A1 范围已配置的下拉列表选项 |
+| 查看某区域的下拉框（数据验证）配置 | `+dropdown-get` | 对话上下文 | 返回该 A1 范围的下拉选项、多选开关和胶囊配色 |
 
 **选择原则**：
 - 只看值或做数据处理 → `+csv-get`；大表分批读取，避免一次拉全表撑爆上下文
 - 要按列类型结构化读出（喂 DataFrame / round-trip 回 `+table-put`）→ `+table-get`
 - 需要公式/样式/批注 → `+cells-get`
-- 只想知道某区域下拉框有哪些选项 → `+dropdown-get`
+- 查看某区域下拉框的选项、多选开关或胶囊配色 → `+dropdown-get`
 
 ## 读表理解脚本（Agent 优先入口）
 

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

@@ -80,9 +80,12 @@
 
 ### 6. 图表展示
 
-- 遵循用户指令选择图表类型，或匹配用户意图（饼图/环形图 → 占比，折线图 → 趋势）。
-- 包含必要元素：标题、坐标轴标题、多系列图例；数据标签按需（关键点 / 末值标注即可，不必每个数据点都加）。
-- 调整至合适大小，避免数据和标签过多堆叠。
+- 遵循用户指令选择图表类型，或匹配用户意图（饼图 → 占比，折线图 → 趋势）。
+- 包含必要元素：标题、坐标轴标题、多系列图例；普通基础图先按开启数值标签运行尺寸建议器并默认展示，密集时依次采用建议尺寸、稀疏标签、Top-N 或拆图；目标线等常量系列不显示逐点重复标签。
+- Y 轴显示范围默认交给图表引擎，不按数据源单列的最小值 / 最大值主动设限；组合图先比较系列单位和量级，把会被压扁的系列放到右轴。
+- 饼图默认将图例放在底部；尺寸建议器保持相对固定的饼区，主要按最长标签增加两侧留白。类别过多或数值高度偏斜时优先 Top-N 或条形图，避免靠无限加宽解决。
+- 创建前运行 `scripts/lark_chart_size_advisor.py`，使用其 `create_flags`；若提示仅放大无法解决，则改用条形图、Top-N 或拆图。创建后运行 `scripts/lark_chart_quality_check.py`。
+- 优先继承原表配色，同一指标跨图保持同色；组合图使用同色系柱形和高对比折线，辅助系列使用中性色。分类色过多时优先精简数据，不依靠更多相近颜色区分。
 - **图表放置防重叠**：新增图表前须计算放置区域，避免与已有图表重叠。具体步骤：
   1. 调用 `+chart-list` 获取当前工作表所有已有图表的 `position`（锚点单元格：`col` 是列字母如 "A"/"B"、`row` 是 1-based 行号；以 `+chart-list` 实际返回字段为准）、`offset`（锚点内偏移：`row_offset`、`col_offset`，单位像素）以及 `size`（`width`、`height`，单位像素）。
   2. 获取工作表的行高和列宽信息（像素）。

package/skills/lark-sheets/references/lark-sheets-write-cells.md

@@ -193,14 +193,38 @@ Step 2: `+styles-put` — 对 A2:A100 声明统一的 fill + border 样式
 
 两个 flag **必须传一个、且只能传一个**——同时传或都不传，CLI 会立刻报错。`--source-range` 用 A1 + sheet 前缀写法（如 `'Sheet1'!T1:T3`，sheet 名按 A1 标准单引号包裹），可以指同 sheet 也可以指其它 sheet（如 `'Refs'!A1:A10`）。
 
-### 配色：默认即上色，三种意图三条线
+### 多选下拉：验证规则与选中值是两层数据
 
-下拉**默认带胶囊高亮**——什么 flag 都不传时，所有选项按内置 10 色色板循环上色，跟 UI 手动配下拉的默认行为对齐。三种意图：
+`+dropdown-set --multiple` 只把目标单元格的验证规则设为“允许多选”，**不会写入当前选中值**。后续用 `+cells-set` 填充多选结果时，必须把每个选项写成 `multiple_values` 数组项；不要把多个选项用逗号拼成一个普通 `value`，否则整串会被当成单值并触发数据验证失败。
+
+```bash
+# 先创建允许多选的下拉规则
+lark-cli sheets +dropdown-set \
+  --spreadsheet-token shtXXX --sheet-id "$SID" \
+  --range "E2:E15" \
+  --options '["A","B","C","D"]' \
+  --multiple
+
+# 再向 E6 写入 3 个选中值
+lark-cli sheets +cells-set \
+  --spreadsheet-token shtXXX --sheet-id "$SID" \
+  --range "E6" \
+  --cells '[[{"multiple_values":[{"value":"A"},{"value":"B"},{"value":"C"}]}]]'
+```
+
+### 配色：新建默认用内置色板，更新保留已有配色
+
+下拉**默认带胶囊高亮**——新建时不传 `--highlight` / `--colors`，所有选项按内置 10 色色板循环上色，跟 UI 手动配下拉的默认行为对齐。只有用户明确指定自定义颜色，或选项具有清晰的语义配色（如状态、风险、优先级，且颜色有助于理解）时才传 `--colors`。
+
+下拉胶囊文字默认是黑色。自定义颜色时应使用**浅色、低饱和度背景**，避免鲜艳或偏深的色值影响可读性。
+
+`+dropdown-update` 会重写整条验证规则。若用户没有要求重置已有配色，先用 `+dropdown-get` 回读，并把现有 `highlight_colors` 作为 `--colors` 传回；省略会按内置色板重建。
 
 | 想要的效果 | 怎么传 |
 |---|---|
-| 默认色板循环上色 | 都不传 `--highlight` / `--colors` |
-| 按选项指定具体颜色 | 只传 `--colors '["#hex",...]'`（不需要再传 `--highlight`） |
+| 新建时使用默认色板 | 都不传 `--highlight` / `--colors` |
+| 更新时保留已有配色 | 先 `+dropdown-get` 回读，再将 `highlight_colors` 作为 `--colors` 传回 |
+| 用户明确要求或选项有语义配色 | 只传浅色、低饱和度的 `--colors '["#hex",...]'`（不需要再传 `--highlight`） |
 | 纯白下拉、不要高亮 | 传 `--highlight=false`（注意 `=false` 不能省，单写 `--highlight` 在 cobra 里等价于 true） |
 
 `--colors` 长度**可以短于**选项数（list 模式短于 `--options` 长度，listFromRange 模式短于 `--source-range` 的单元格数），未指定的选项按内置色板循环补色；但**不能长于**——CLI 在 Validate 阶段就会拦截，错误形如 `--colors length (4) must not exceed dropdown source size (3)`。
@@ -211,36 +235,35 @@ Step 2: `+styles-put` — 对 A2:A100 声明统一的 fill + border 样式
 
 **`--options` 模式 — 默认色板（最常见）**：
 
-```
+```bash
 lark-cli sheets +dropdown-set \
   --url https://... --sheet-id <id> \
   --range A2:A100 \
   --options '["待开始","进行中","已完成","已取消"]'
 ```
 
-**`--options` 模式 — 指定颜色**（4 个选项配 3 个颜色，第 4 个按色板补）：
+**用户明确要求语义配色时**：
 
-```
+```bash
 lark-cli sheets +dropdown-set \
   --url https://... --sheet-id <id> \
   --range A2:A100 \
-  --options '["待开始","进行中","已完成","已取消"]' \
-  --colors '["#bff7d9","#FFE699","#bacefd"]'
+  --options '["待开始","进行中","已完成"]' \
+  --colors '["#E8F3FF","#FFF3D6","#E8F8E8"]'
 ```
 
 **`--source-range` 模式**（先在 `'Sheet1'!T1:T3` 维护「男/女/保密」三行，再让 `B2:B21` 引用它）：
 
-```
+```bash
 lark-cli sheets +dropdown-set \
   --url https://... --sheet-id <id> \
   --range B2:B21 \
-  --source-range ''\''Sheet1'\''!T1:T3' \
-  --colors '["#cce8ff","#ffd6e7","#e6e6e6"]'
+  --source-range ''\''Sheet1'\''!T1:T3'
 ```
 
 **纯白下拉**（明确告诉用户"不要彩色"时才用）：
 
-```
+```bash
 lark-cli sheets +dropdown-set \
   --url https://... --sheet-id <id> \
   --range A2:A100 \
@@ -252,7 +275,7 @@ lark-cli sheets +dropdown-set \
 >
 > ⚠️ **`--ranges` 类批量 flag 的 sheet 前缀必须「裸写」**——`+cells-batch-clear` / `+dropdown-update` / `+dropdown-delete` 的 `--ranges` 解析器不接受引号：表名含点或空格（如 `2025.9`、`一月份`）也直接写 `2025.9!A1`，写成 `'2025.9'!A1` 会被当成表名一部分、报 `sheet not found`。**但 `--source-range`、透视表 `--source`、`--range` 走 A1 标准**：sheet 名带单引号（如 `'Sheet1'!A1:B2`）是标准写法、裸写也接受，回读统一返回带引号形式——别把 `--ranges` 的裸写要求套到这些 flag 上。
 
-`+dropdown-update`（多 range 批量更新）的所有 flag 语义与 `+dropdown-set` 完全一致；只是目标 `--ranges` 由单值变成 JSON 数组（每项带 sheet 前缀），同一份选项 + 配色应用到所有 range。
+`+dropdown-update`（多 range 批量更新）的目标 `--ranges` 是 JSON 数组（每项带 sheet 前缀），同一份选项 + 配色应用到所有 range。它会替换完整验证规则；需要保留现有配色时，按上文先回读并透传 `--colors`。
 
 ## Shortcuts
 
@@ -274,7 +297,7 @@ _公共四件套 · 系统：`--dry-run`_
 | Flag | Type | 必填 | 说明 |
 | --- | --- | --- | --- |
 | `--range` | string | xor | 写入区域（A1 格式）。与 `--writes` 二选一（单区域用 --range+--cells，多区域用 --writes） |
-| `--cells` | string + File + Stdin（复合 JSON） | xor | JSON：2D 数组 `[[{cell},...],...]`，维度与 `--range` 完全一致；每个 cell 可含 `value` / `formula` / `cell_styles` / `note` / `rich_text`（含 `type="embed-image"` 单元格嵌图）等，完整字段跑 `--print-schema` |
+| `--cells` | string + File + Stdin（复合 JSON） | xor | JSON：2D 数组 `[[{cell},...],...]`，维度与 `--range` 完全一致；每个 cell 可含 `value` / `formula` / `multiple_values` / `cell_styles` / `note` / `rich_text`（含 `type="embed-image"` 单元格嵌图）等。向启用多选的下拉单元格写入选中值时，必须用 `multiple_values:[{"value":...}]`，不要把多个选项用逗号拼成一个 `value`；完整字段跑 `--print-schema` |
 | `--writes` | string + File + Stdin（复合 JSON） | xor | 多区域写入 JSON 数组（最多 100 项），每项 `{sheet_name\|sheet_id, range, cells}`——**sheet 定位必须写在每项里**（与 +batch-update 子操作、+styles-put 项同惯例，不认顶层 --sheet-name），cells 结构同 `--cells`（二维数组，可逐格带 cell_styles/border_styles）。整批展开为**单次批量提交**（fail-fast，失败后先回读再补发），支持跨 sheet；典型场景：批量修复散布多处的公式、跨表同构写入——不要为此拼 +batch-update 的 --operations。与 `--range`+`--cells` 二选一；范围级统一样式不在此做，写完接 +styles-put |
 | `--allow-overwrite` | bool | optional | 允许覆盖非空 cell（默认 true）；设为 false 时遇非空 cell 报错 |
 | `--max-cells` | int | optional | 防爆，默认 50000（隐藏 flag：不在 `--help` 列出，但可正常传入） |
@@ -318,8 +341,8 @@ _公共四件套 · 系统：`--dry-run`_
 | --- | --- | --- | --- |
 | `--range` | string | required | 目标范围（A1 格式，如 `A2:A100`） |
 | `--options` | string + File + Stdin（复合 JSON） | xor | 下拉选项 JSON 数组，例如 `["opt1","opt2"]`。服务端不限制选项数量，也不限制单个选项长度；含逗号的选项可以接受（写入时会自动转义）。大量选项建议改用 `--source-range`。 |
-| `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉胶囊背景色，RGB hex 数组（如 `["#1FB6C1","#F006C2"]`）。长度可短不可长——超长 Validate 拦截（`--colors length (N) must not exceed dropdown source size (M)`），未指定项按内置 10 色色板循环补色。**单独传即生效**；`--highlight=false` 时被忽略。 |
-| `--multiple` | bool | optional | 启用多选；默认 `false` |
+| `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉胶囊背景色，RGB hex 数组。新建时默认不要传：省略即使用内置 10 色色板；仅在用户明确要求或选项有清晰语义配色时传。胶囊文字默认黑色，应选浅色、低饱和度背景。长度可短不可长——超长 Validate 拦截（`--colors length (N) must not exceed dropdown source size (M)`），未指定项按内置色板循环补色。单独传即生效；`--highlight=false` 时被忽略。 |
+| `--multiple` | bool | optional | 启用多选；默认 `false`。本 flag 只设置验证规则，不会写入选中值；后续用 `+cells-set` 写值时必须传 `multiple_values` 数组，不要传逗号拼接的 `value` |
 | `--highlight` | bool | optional | 下拉胶囊背景色高亮开关。**不传 = 开**（按内置 10 色色板循环上色）；`--highlight=false` 关闭得到纯白下拉。配色用 `--colors` 覆盖。 |
 | `--source-range` | string | xor | listFromRange 模式的下拉源 range，A1 表示法 + sheet 前缀（如 `'Sheet1'!T1:T3`）。映射到 server `data_validation.range`，搭配 server `data_validation.type='listFromRange'` 自动生效。跟 `--options` 二选一：传 `--options` 走 inline 列表（type=list），传本 flag 走 range 引用（type=listFromRange）。`--colors` 长度规则不变（≤ 源 range 单元格数），`--highlight` / `--multiple` 行为相同。当 `--highlight` 开启且 source 覆盖单元格数超过 2000 时，服务端会将该下拉判为 option-error（这是不支持的组合）；CLI 会在返回结果的 `data.warnings` 中给出 warning。如需取消，传 `--highlight=false`。 |