@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.28c4f05 → 0.1.0-dev.4e64c13

package/shared/lark-cli/lark-sheets/references/lark-sheets-changeset.md

@@ -0,0 +1,105 @@
+# Lark Sheet Changeset
+
+## 使用场景
+
+读取两个版本之间的 **changeset（变更操作清单）**，用于**复核某次编辑（尤其是 AI 编辑）是否真实满足用户诉求**。
+
+典型场景：AI agent 对表格做了一批编辑后，想确认它"说做的"和"真正落到表格上的"是否一致——拉取编辑前版本到编辑后版本之间的 changeset，逐条核对 action 是否覆盖了用户要求的修改、有没有多改 / 漏改。
+
+## 版本（revision）语义
+
+- 这里的"版本"指表格的 **CS revision**（每次提交单调递增的修订号），不是文档历史里的命名版本。
+- `--start-revision` 是复核基线，即你认定的"编辑前"版本。
+- `--end-revision` 是"编辑后"版本；**省略时默认取最新 revision**，返回从 start 到最新的全部 changeset。
+- **版本差上限 20**：`end - start + 1 ≤ 20`，超出会被拒绝（服务端同样以 20 兜底）。复核大跨度变更时请分段拉取。
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+changeset-get` | read | 变更记录 |
+
+## Flags
+
+### `+changeset-get`
+
+_公共：URL/token（无 sheet 定位）_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--start-revision` | int | required | 起始版本（编辑前基线，>= 1） |
+| `--end-revision` | int | optional | 结束版本（省略取最新） |
+
+## 返回结构
+
+返回一个 JSON 对象，`changesets` 数组按版本顺序排列，每个元素是一次提交的**原始 action 列表**与元信息：
+
+```json
+{
+  "spreadsheet_token": "shtcnXXXX",
+  "latest_revision": 142,
+  "start_revision": 120,
+  "end_revision": 135,
+  "changesets": [
+    {
+      "revision": 121,
+      "create_time": "2026-06-12T10:00:00Z",
+      "actions": [
+        { "action": "setCellRange", "sheetId": "...", "value": { /* ... */ } }
+      ],
+      "is_self_edit": false,
+      "is_ai_edit": true
+    }
+  ]
+}
+```
+
+- 最外层 `latest_revision` 是**当前表格的最新版本号**（与查询区间无关），便于判断表格当前停在哪个版本、`--start-revision` 该取多少。
+- `actions` 是**未经语义渲染的原始操作对象**，按提交内的执行顺序排列。复核时逐条比对：每个 action 改了哪个 sheet、哪个区域、改成什么，是否对应用户的诉求。
+- `revision` / `create_time` 用于判断"这次改动属于哪个版本、什么时候做的"。
+- `is_self_edit` 表示该 changeset 是否由当前请求用户提交（committer 与请求用户相同），即"是不是我自己提交的编辑"。
+- `is_ai_edit` 表示该 changeset 是否由 AI 客户端提交（`member_id` 为 10 / 11）。复核时 `is_ai_edit=true` 即为 AI 写入的编辑（而非用户手动编辑），是核对 AI 是否完成诉求的主要对象。
+
+## 复核工作流（判断 AI 是否真实完成诉求）
+
+1. 记下 AI 开始编辑前的 revision（编辑前 `+workbook-info` 或上一次工具返回的 revision 即可作为 `--start-revision`）。
+2. AI 编辑完成后，跑 `+changeset-get --url <表格> --start-revision <编辑前版本>`（不传 end → 取到最新）。
+3. 遍历 `changesets[].actions`，核对：
+   - 用户要求的每一处修改是否都有对应 action；
+   - 有没有越权 / 多余的修改（动了用户没让动的 sheet / 区域）；
+   - action 的目标区域、值是否与诉求一致。
+4. 若版本跨度可能 > 20，分段拉取（如 `start..start+19`、`start+20..` …）。
+
+## 注意
+
+- `+changeset-get` 是**只读**操作，不改动表格。
+- 大跨度 / 大批量编辑的 changeset 可能体积较大；输出在传输层已 gzip。必要时缩小版本区间。
+- 该工具走只读 scope `sheets:spreadsheet:read`，需要对表格有查看权限。
+
+## Examples
+
+### `+changeset-get`
+
+公共：`--url` / `--spreadsheet-token`（二选一，无 sheet 定位）。changeset 是工作簿级历史，不接受 sheet 定位 flag。
+
+示例：
+
+```bash
+# 只传起始版本 → 返回从该版本到最新的全部 changeset（最常用：复核 AI 编辑前后的差异）
+lark-cli sheets +changeset-get --url "https://example.feishu.cn/sheets/shtXXX" --start-revision 120
+
+# 传起始 + 结束版本（版本差 end-start+1 ≤ 20）
+lark-cli sheets +changeset-get --spreadsheet-token shtXXX --start-revision 120 --end-revision 135
+```
+
+输出契约（envelope.data）：
+
+- `latest_revision` — 当前表格最新版本号（与查询区间无关）
+- `start_revision` / `end_revision` — 实际查询区间（省略 `--end-revision` 时 `end_revision` = 最新版本）
+- `changesets[]` — 按版本顺序排列；每项含 `revision` / `create_time` / `actions`（原始操作列表）/ `is_self_edit` / `is_ai_edit`
+
+### Validate / DryRun / Execute 约束
+
+- `Validate` 阶段只做 XOR 检查（`--url` / `--spreadsheet-token` 二选一）与版本上限校验（`--start-revision ≥ 1`，传了 `--end-revision` 时 `end ≥ start` 且 `end - start + 1 ≤ 20`）；**禁止**联网。
+- `DryRun` 输出请求模板，不实际拉取 changeset。
+- `Execute` 阶段才发起 changeset 查询；省略 `--end-revision` 时由服务端解析为最新 revision。

package/shared/lark-cli/lark-sheets/references/lark-sheets-chart.md

@@ -0,0 +1,45 @@
+# Lark Sheet Chart
+
+## 使用场景
+
+查看飞书表格中已有图表对象的配置。本 reference 覆盖 1 个只读 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看已有图表 | `+chart-list` | 获取图表的类型、数据源和样式配置 |
+
+> **跨 sheet 提示**：图表可能分布在多个子表；先 `+workbook-info` 掌握全局，再按子表 `+chart-list`。
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+chart-list` | read | 对象 |
+
+## Flags
+
+### `+chart-list`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--chart-id` | string | optional | 指定单个图表 reference_id 过滤 |
+
+## Examples
+
+公共四件套：`--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（前两者 XOR，后两者 XOR）。
+
+### `+chart-list`
+
+```bash
+lark-cli sheets +chart-list --url "https://example.feishu.cn/sheets/shtXXX" --sheet-id "$SID"
+```
+
+输出契约：返回按工作表分组的图表列表，每个图表含 `chart_id` / `position` / `details.snapshot` 等。
+
+### Validate / DryRun / Execute 约束
+
+- `Validate`：XOR 公共四件套。
+- `DryRun`：输出请求模板，零网络副作用。
+- `Execute`：发起图表列表查询。

package/shared/lark-cli/lark-sheets/references/lark-sheets-conditional-format.md

@@ -0,0 +1,42 @@
+# Lark Sheet Conditional Format
+
+## 使用场景
+
+查看飞书表格中已有条件格式规则的配置。本 reference 覆盖 1 个只读 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看已有条件格式 | `+cond-format-list` | 获取规则类型、范围和样式配置 |
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+cond-format-list` | read | 对象 |
+
+## Flags
+
+### `+cond-format-list`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--rule-id` | string | optional | 按规则 id 过滤 |
+
+## Examples
+
+公共四件套：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（XOR）。
+
+### `+cond-format-list`
+
+```bash
+# 列出当前 sheet 全部条件格式规则（含 rule_id、rule_type、范围与样式）
+lark-cli sheets +cond-format-list --url "..." --sheet-id "$SID"
+```
+
+### Validate / DryRun / Execute 约束
+
+- `Validate`：XOR 公共四件套。
+- `DryRun`：输出请求模板，零网络副作用。
+- `Execute`：发起条件格式列表查询。

package/shared/lark-cli/lark-sheets/references/lark-sheets-filter-view.md

@@ -0,0 +1,49 @@
+# Lark Sheet Filter View
+
+## 概念回顾
+
+筛选视图是 sheet 内的多份独立筛选配置，每个视图持有自己的 `range` 和 `rules`，由独立 `view_id`（10 位随机字符串）标识。一个 sheet 可有多个视图，视图的隐藏行仅在用户进入该视图时本地生效，不影响其他协作者，也不与该 sheet 上可能并存的筛选器（filter）互相影响。
+
+## 使用场景
+
+查看飞书表格中已有筛选视图对象的配置。本 reference 覆盖 1 个只读 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看已有筛选视图 | `+filter-view-list` | 获取 sheet 上所有视图（视图名、范围、规则） |
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+filter-view-list` | read | 对象 |
+
+## Flags
+
+### `+filter-view-list`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--view-id` | string | optional | 按筛选视图 reference_id 过滤（命中即只返回单个视图） |
+
+## Examples
+
+公共四件套：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（XOR）。`view_id` 是 10 位随机字符串，每个 sheet 可有多个视图。
+
+### `+filter-view-list`
+
+```bash
+# 列出某个 sheet 的全部筛选视图
+lark-cli sheets +filter-view-list --url "..." --sheet-id "$SID"
+
+# 按 view_id 精确定位
+lark-cli sheets +filter-view-list --url "..." --sheet-id "$SID" --view-id vAbcde1234
+```
+
+### Validate / DryRun / Execute 约束
+
+- `Validate`：XOR 公共四件套。
+- `DryRun`：输出请求模板，零网络副作用；`--sheet-name` 在 dry-run 输出里生成为 `<resolve:Sheet1>` 占位符。
+- `Execute`：发起筛选视图查询（返回各视图的 range + rules）。

package/shared/lark-cli/lark-sheets/references/lark-sheets-filter.md

@@ -0,0 +1,42 @@
+# Lark Sheet Filter
+
+## 使用场景
+
+查看飞书表格中已有筛选器（filter）对象的配置。本 reference 覆盖 1 个只读 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看已有筛选器 | `+filter-list` | 获取筛选器的范围、规则和条件配置 |
+
+> 每个工作表至多一个筛选器，`filter_id` 等于该工作表的 `sheet_id`。
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+filter-list` | read | 对象 |
+
+## Flags
+
+### `+filter-list`
+
+_公共四件套 · 系统：`--dry-run`_
+
+_仅含公共 / 系统 flag。_
+
+## Examples
+
+公共四件套：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（XOR）。`filter_id` 等同于 `sheet_id`（每个工作表至多一个筛选器）。
+
+### `+filter-list`
+
+```bash
+# 查看当前 sheet 的筛选器配置（filter_id 等于 sheet_id）
+lark-cli sheets +filter-list --url "..." --sheet-id "$SID"
+```
+
+### Validate / DryRun / Execute 约束
+
+- `Validate`：XOR 公共四件套。
+- `DryRun`：输出请求模板，零网络副作用。
+- `Execute`：发起筛选器查询（返回当前筛选条件 + 已过滤行数）。

package/shared/lark-cli/lark-sheets/references/lark-sheets-float-image.md

@@ -0,0 +1,43 @@
+# Lark Sheet Float Image
+
+## 使用场景
+
+查看飞书表格中已有**浮动图片**对象的配置（悬浮在单元格上方的图片，不属于单元格内容；与随行走的单元格内嵌图片不同）。本 reference 覆盖 1 个只读 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看已有浮动图片 | `+float-image-list` | 获取浮动图片的位置、大小和层级配置 |
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+float-image-list` | read | 对象 |
+
+## Flags
+
+### `+float-image-list`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--float-image-id` | string | optional | 按 id 过滤；省略时列工作表全部 |
+
+## Examples
+
+公共四件套：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（XOR）。浮动图片是 sheet 级对象。
+
+### `+float-image-list`
+
+```bash
+lark-cli sheets +float-image-list --url "..." --sheet-id "$SID"
+```
+
+返回每张浮动图片的 `image_token` / `position` / `size` / `z-index` 等。
+
+### Validate / DryRun / Execute 约束
+
+- `Validate`：XOR 公共四件套。
+- `DryRun`：输出请求模板，零网络副作用。
+- `Execute`：发起浮动图片列表查询。

package/shared/lark-cli/lark-sheets/references/lark-sheets-formula-verify.md

@@ -0,0 +1,64 @@
+# Lark Sheet Formula Verify（+formula-verify）
+
+> **本文定位**：飞书表格"公式是否真的零错误"的**只读**自检入口。`+formula-verify` 对指定子表（或整本工作簿）扫描公式与单元格值，一次调用聚合全表错误清单 + 编译失败清单 + 每类错误的定位与样本，让你快速核对一张表的公式健康度。它**不改动表格**。
+
+## 为什么需要自检
+
+飞书在线表格已经实时算好结果，但"算出来"和"算对了"是两件事。常见缺口：
+
+- 公式编译失败 → 单元格落成文本（写入类操作留下的 `formula_errors[]` 是**编译失败**信号）。
+- 公式编译成功但**运行时错误**：`#REF!` / `#DIV/0!` / `#VALUE!` / `#NAME?` / `#NULL!` / `#NUM!` / `#N/A`——这一类只看 `formula_errors[]` 看不到，必须扫单元格值。
+
+`+formula-verify` 把两路信号合并成一份统一 JSON：一次调用聚合全表错误清单 + 编译失败清单 + 每类错误的定位与样本，AI 一眼就能定位问题。
+
+## 调用契约
+
+最小调用形态：
+
+| 入参 | 含义 |
+|---|---|
+| `--url` / `--spreadsheet-token` | 表格定位（XOR 二选一，必填） |
+| `--sheet-id` / `--sheet-name` | 限定子表（mutually exclusive；省略则扫全部可见子表） |
+| `--range` | 限定 A1 范围；省略则用各 sheet 的 `current_region` |
+| `--max-locations` | 每类错误样本上限，默认 20 |
+| `--ai-only` | 只校验 AI 公式（`=AI(prompt, [range])`），跳过普通公式的 7 类 Excel 错误扫描。AI 公式是异步计算的：把这个 flag 配 `--range` 当写后的**第一次抽样检查**，不要用 `+cells-get` 轮询；抽样里没有明确的 failed / unsupported 状态时，可以在告知用户「计算仍在后台进行」的前提下继续交付，不必卡着等 pending 公式算完 |
+| `--exit-on-error` | `status='errors_found'` 时返回非 0 退出码（CI 网关用） |
+
+返回核心字段：
+
+- `status` ∈ `success` / `errors_found` / `partial`——**唯一可机读的健康度判据**。
+- `total_errors` / `total_formulas` / `scanned_cells`——本次扫描规模指标。
+- `has_more`——为 true 表示扫描被内部上限截断（详见后文「截断与续读」），未覆盖完整范围。
+- `error_summary[<错误类型>]`——每类错误的 `count` / `locations[]` / `samples[].{address,formula,depends_on}`。
+- `compile_errors[]`——合并最近一次写入留下的编译失败清单，与运行时错误并存时同时出现。
+- `warning_message`——仅在 `has_more=true` 时出现，告知调用方需要缩小 `--range` / 拆 `--sheet-id` 续读。
+
+## 结果判读规则
+
+- `status='success'` → 该扫描范围内公式零错误。
+- `status='partial'` → 扫描被内部上限截断，只覆盖了一部分。先缩小 `--range` 或拆 `--sheet-id` 续扫，**不允许**把 `partial` 当作 `success`。
+- `status='errors_found'` 且 `compile_errors[]` 非空 → 存在编译失败（这些单元格此刻是文本、不是公式）；按 `compile_errors[].reason` 定位是哪类语法问题（飞书函数名 / 范围语法 / 引用样式）。
+- `status='errors_found'` 且只剩运行时错误 → 按 `error_summary` 的 `samples[].formula` + `depends_on` 排查根因（零除？空值参与运算？引用越界？日期差写法？数组语义？）。
+
+注意：
+
+- "编译失败但运行时无报错"不算 zero-error（编译失败的单元格此刻是文本不是公式，源数据一变就再也算不出值）。
+- 靠肉眼读首末 5 行确认是不可靠的——表中段、隐藏行、合并区里的错误这样根本看不到。
+- 修复公式属于写操作，不在本只读命令的范围内；把 `+formula-verify` 报出的错误定位转述给用户即可。
+
+## 截断与续读
+
+后端有一个内部硬上限对总扫描单元格数做截断（不暴露给调用方），超过后立即返回 `has_more=true` + `warning_message`，`error_summary` / `compile_errors` 仅覆盖已扫描部分。处理路径：
+
+- 把工作簿按 `--sheet-id` / `--sheet-name` 拆成多次调用。
+- 同 sheet 内按 `--range` 切片（如先 `A1:Z200` 再 `AA1:AZ200`），逐块自检。
+- 每块都跑到 `has_more=false` 且 `status='success'` 才算这块通过。
+
+## 常见陷阱
+
+| 坑 | 应对 |
+|---|---|
+| 错误字符串本地化 | 后端按内部 `error_kind` / `compute_status` 字段识别错误类别，不走字符串匹配；调用方拿到的 7 类英文错误代码由后端统一规范输出，与 locale 无关。 |
+| `formatted_value` 可能隐藏错误 | 某些条件格式 / 自定义数字格式会把 `#DIV/0!` 显示成空白。后端直接读 cell `error_kind`，不依赖 `formatted_value`，绕开此类被遮蔽。 |
+| 把 `partial` 当 `success` | `partial` 仅表示**已扫描部分**无错误，剩余区域未知。必须续扫直到 `has_more=false` 且 `status='success'` 才能算通过。 |
+| 编译失败 vs 运行时错误 | 同一份报告里 `compile_errors[]` 与 `error_summary` 并存。先看 `compile_errors[]`（编译失败）、再看运行时错误。 |

package/shared/lark-cli/lark-sheets/references/lark-sheets-history.md

@@ -0,0 +1,70 @@
+# Lark Sheet History
+
+## 概念回顾
+
+每张飞书电子表格保留一串历史版本（`minor_histories`）。每个版本由 `history_version_id` 标识，并附带创建时间（`create_time`）、动作（`action`）与块修订信息（`all_block_revision`）。历史是**工作簿级**的（针对整张电子表格，不针对单个子表）。
+
+`+history-list` 读取版本列表；`+history-revert-status` 轮询某次回滚任务的状态（进行中 / 成功 / 失败）。若只是想拿**当前文档版本号（revision）**当作 `+changeset-get` 的起点锚点，直接用 `+revision-get`（见 `lark-sheets-workbook`）更轻量。
+
+## 使用场景
+
+读取历史版本列表、查询回滚状态。本 reference 覆盖 2 个只读 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看历史版本列表 | `+history-list` | 返回 `minor_histories`，每条含 `history_version_id` / `create_time` / `action` / `all_block_revision` 四个字段；支持向前分页（可选 `--end-version`） |
+| 查询回滚状态 | `+history-revert-status` | 传入 `--transaction-id`（回滚任务的异步受理标识）；轮询某次回滚的进行中 / 成功 / 失败状态 |
+
+**注意事项（必须了解）**：
+- **历史是工作簿级**：定位只需 `--url` / `--spreadsheet-token`（XOR），不需要子表选择器。
+- **`+history-list` 倒序分页**：首次查省略 `--end-version`，返回最新一页；若响应里附带 `next_end_version` 与 `has_more=true`，把 `next_end_version` 作为下一次的 `--end-version` 即可继续向更早翻页；当响应**不包含**这两个字段时表示已到最早一页，不必再翻。
+- **`+history-revert-status` 是只读轮询**：`--transaction-id` 是某次回滚任务的受理标识；回滚本身是高风险写操作，不在本只读集合内。
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+history-list` | read | 历史版本 |
+| `+history-revert-status` | read | 历史版本 |
+
+## Flags
+
+### `+history-list`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--end-version` | int | optional | 分页查询的最大版本（倒序）；首次查询省略，下一页传上一页返回的 next_end_version。 |
+
+### `+history-revert-status`
+
+_公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--transaction-id` | string | required | 异步回滚的受理标识 |
+
+## Examples
+
+公共定位：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token`（XOR，二选一）。
+
+### `+history-list`
+
+```bash
+# 列出某张电子表格的最新一页历史版本
+lark-cli sheets +history-list --url "https://sample.feishu.cn/sheets/SHTxxxxxx"
+
+# 用原始 spreadsheet token 定位
+lark-cli sheets +history-list --spreadsheet-token "SHTxxxxxx"
+
+# 翻到下一页：把上次响应里的 next_end_version 作为 --end-version 传入
+lark-cli sheets +history-list --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --end-version 12345
+```
+
+### `+history-revert-status`
+
+```bash
+# 查询某次回滚的当前状态（进行中 / 成功 / 失败）
+lark-cli sheets +history-revert-status --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --transaction-id "<transaction-id>"
+```

package/shared/lark-cli/lark-sheets/references/lark-sheets-pivot-table.md

@@ -0,0 +1,44 @@
+# Lark Sheet Pivot Table
+
+## 使用场景
+
+查看飞书表格中已有数据透视表对象的配置。本 reference 覆盖 1 个只读 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看已有透视表 | `+pivot-list` | 获取透视表的结构、数据源、配置与展开后的占用区域 |
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+pivot-list` | read | 对象 |
+
+## Flags
+
+### `+pivot-list`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--pivot-table-id` | string | optional | 按 id 过滤 |
+
+## Examples
+
+公共四件套：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（XOR）。
+
+### `+pivot-list`
+
+```bash
+lark-cli sheets +pivot-list --url "..." --sheet-id "$SID"
+```
+
+> **返回值含 `info`（展开后的占用区域与状态）**：每个透视表对象除 `position` / `snapshot` 外，还返回 `info`，标明它在 sheet 上的平铺区域与状态——`info.page_range`（筛选/分页区 A1）、`info.content_range`（主体数据区 A1）、`info.span_range`（空表合并区 A1）、`info.error_state`（错误状态，如 `None`/`Cover`/`Shrink`/`Loading`）、`info.is_empty` / `info.is_hidden`、`info.row`/`info.col`（锚点）等。
+> **用途（判断某单元格是否属于透视表）**：读到某单元格要判断它是普通单元格还是透视产物时，先 `+pivot-list` 拿 `info`，看该单元格是否落在 `page_range` / `content_range` 内——落在区域内即属于某个透视表（透视表单元格不能当普通单元格解读），落在区域外则是普通单元格。
+
+### Validate / DryRun / Execute 约束
+
+- `Validate`：`--url` / `--spreadsheet-token` XOR 必填；`--sheet-id` / `--sheet-name` XOR 必填一个。
+- `DryRun`：输出请求模板，零网络副作用。
+- `Execute`：发起透视表列表查询。