@amaster.ai/pi-lark 0.1.2-beta.73 → 0.1.2-beta.74

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

@@ -1,152 +0,0 @@
-# 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)。