@amaster.ai/pi-lark 0.1.4 → 0.1.6

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

@@ -0,0 +1,130 @@
+# Lark Sheet Filter
+
+## 真对象硬约束 + 数量校验
+
+1. **真对象**：当用户要求"筛选 / 只看 / 仅保留 X"时，**必须**通过 `+filter-{create|update|delete}` 创建真实的筛选器对象。**禁止**用"删除不符合条件的行" / "新建子表只放符合条件的行" / 用 `+cells-set` 覆盖原表来代替——这些做法会让原数据丢失或不可恢复。
+2. **筛选数量必校**：执行筛选后**必须**回读，断言 `len(visible_rows) == expected_count`。`expected_count` 来自先用本地脚本在源数据上独立复现该筛选条件得到的结果数。两者不一致时禁止交付，需排查筛选条件 / 数据列类型问题。
+3. **混合文本列禁止字面比较**：筛选 key 是公式文本（如 `1000+200=1200`）或带单位的混合文本时，先在辅助列里抽出纯数值再筛选；不能直接用文本比较。
+
+## 使用场景
+
+读写筛选器对象。本 reference 覆盖 4 个 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看已有筛选器 | `+filter-list` | 获取筛选器的范围、规则和条件配置 |
+| 创建/更新/删除筛选器 | `+filter-{create|update|delete}` | 对筛选器执行写入操作 |
+
+典型工作流：先读取现有筛选器了解配置 → 执行创建/更新/删除 → **必须再次读取验证结果**。
+
+**只读场景例外**：用户只是想知道哪些数据满足条件、并不要求修改表格展示时，可以走 `lark-sheets-read-data` 读后文本回答，不必创建筛选器。
+
+**常见配置错误（必须注意）**：
+- **筛选范围必须覆盖表头行**：筛选器的 range 必须从表头行开始（如 `A1:F100`），不能只包含数据行。缺少表头会导致筛选条件无法正确匹配列
+- **更新已有筛选器前先读取**：如果子表上已存在筛选器，直接创建会报错或覆盖原有配置。应先用 `+filter-list` 查看是否存在筛选器，存在时使用 update 而非 create
+- **筛选条件的列索引要精确**：筛选条件中的列标识必须与实际数据列精确对应，不要凭猜测填写
+- **”调整筛选逻辑”要先读旧配置**：用户说”调整筛选”时，先读取现有筛选器的完整配置，理解当前规则后再修改，不要从零创建
+- **创建后必须验证**：调用 `+filter-list` 确认筛选器配置正确且生效
+- **筛选不支持正则表达式**：飞书表格筛选器不支持正则表达式，传入正则会当成普通文本处理。
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+filter-list` | read | 对象 |
+| `+filter-create` | write | 对象 |
+| `+filter-update` | write | 对象 |
+| `+filter-delete` | high-risk-write | 对象 |
+
+## Flags
+
+### `+filter-list`
+
+_公共四件套 · 系统：`--dry-run`_
+
+_仅含公共 / 系统 flag。_
+
+### `+filter-create`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--range` | string | required | 筛选范围（A1 表示法，含表头行，如 `A1:F1000`）；不要重复写入 `--properties` 中的 range 字段 |
+| `--properties` | string + File + Stdin（复合 JSON） | optional | 筛选规则 JSON：`rules`（列级筛选规则数组）+ `filtered_columns?`（激活列索引提示）。`--properties` 整体可选——传它时 `rules` 不可为空；不传则只在 `--range` 上建立空筛选器（无列条件）。`range` 是独立 flag（不要再放此 JSON 里） |
+
+### `+filter-update`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--properties` | string + File + Stdin（复合 JSON） | required | 筛选规则 JSON，含 `rules` 和 `filtered_columns?`；update 是整组覆盖式（传空 `rules: []` 清空）。`range` 已拎为独立 flag |
+| `--range` | string | required | 筛选作用的单元格范围（A1 表示法，如 `A1:F1000`）；优先级高于 `--properties` 中同名字段 |
+
+### `+filter-delete`
+
+_公共四件套 · 系统：`--yes`、`--dry-run`_
+
+_仅含公共 / 系统 flag。_
+
+## Schemas
+
+> 复合 JSON flag 字段速查（只列顶层 + 一层嵌套）。深层结构看下方 `## Examples`，或用 `--print-schema` 读完整 JSON Schema（用法见 SKILL.md「公共 flag 速查」与「Agent 使用提示」）。
+
+### `+filter-create` `--properties` / `+filter-update` `--properties`
+
+_创建/更新的筛选器属性_
+
+**顶层字段**：
+- `range` (string) — 筛选对象作用的单元格范围（A1 表示法） — ⚠️ 已拎为独立 flag `--range`，请勿在此 JSON 内重复填写（同名以独立 flag 为准）
+- `rules` (array<object>) — 列级筛选规则列表，每一项对应一个具体列的筛选条件 each: { column_index: string, conditions: array<oneOf>, filtered_rows?: array<number> }
+- `filtered_columns` (array<string>?) — 可选
+
+## 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"
+```
+
+### `+filter-create`
+
+`--range` 是独立 flag（含表头行）；`rules` 走 `--properties`：
+
+```bash
+lark-cli sheets +filter-create --url "..." --sheet-id "$SID" \
+  --range "A1:F1000" \
+  --properties '{"rules":[{"column_index":"B","conditions":[{"type":"multiValue","compare_type":"equal","values":["北京","上海"]}]}]}'
+```
+
+**`conditions[].type` × `compare_type` 取值**（`type` 决定可用的 `compare_type`；两者均必填）：
+
+| `type` | 可用 `compare_type` | `values` |
+|---|---|---|
+| `text` | `contains` / `doesNotContain` / `beginsWith` / `doesNotBeginWith` / `endsWith` / `doesNotEndWith` / `equals` / `notEquals` | 字符串数组 |
+| `number` | `equal` / `notEqual` / `greaterThan` / `greaterThanOrEqual` / `lessThan` / `lessThanOrEqual` / `between` / `notBetween` | 数值（或数值字符串）数组；`between` / `notBetween` 传两个边界 |
+| `multiValue` | `equal` / `notEqual` | 字符串数组（精确匹配其中任一值） |
+| `color` | `backgroundColor` / `foregroundColor` | 不传 `values`（按单元格颜色筛选） |
+
+> ⚠️ `text` 用 `equals` / `notEquals`（**带 s**），`number` / `multiValue` 用 `equal` / `notEqual`（**不带 s**）——别混。完整 schema 跑 `+filter-create --print-schema --flag-name properties`。
+
+### `+filter-update`
+
+> ⚠️ update 是覆盖式：`--properties` 中传新 `rules` 会替换旧组。如只想加一条，要带上已有的全部条件再追加。必填 `--range`。
+
+### `+filter-delete`
+
+```bash
+lark-cli sheets +filter-delete --url "..." --sheet-id "$SID" --yes
+```
+
+### Validate / DryRun / Execute 约束
+
+- `Validate`：XOR 公共四件套；`+filter-create` 校验 `--range` 至少 2 行（表头 + 至少 1 行数据）；`+filter-update` 必须先 `+filter-list` 确认目标存在；`+filter-delete` 强制 `--yes` 或 `--dry-run`。
+- `DryRun`：输出"将要 POST/PATCH/DELETE 的 filter 请求模板"。
+- `Execute`：写后不自动回读；如需确认，自行调用 `+filter-list` 查看当前筛选条件 + 已过滤行数。

package/skills/lark-sheets/references/lark-sheets-float-image.md

@@ -0,0 +1,159 @@
+# Lark Sheet Float Image
+
+> **选浮动图还是单元格图？只看一条**：这张图是不是**属于某条记录、要随那行一起排序 / 筛选 / 增删**？
+> - **是 → 单元格图片**（不在本 reference）：嵌进单元格、随行走。用 `+cells-set-image`（或 `+cells-set` 的 `rich_text` + `type: "embed-image"`，见 lark-sheets-write-cells）。典型：凭证 / 证件照 / 商品图 / 头像 / 二维码 / 每行配图；话里带「对应 / 每行 / 每条 / 这列」等绑定词即属此类。
+> - **否 → 浮动图片**（本 reference）：自由摆放、不绑数据的装饰 / 标识（logo / 水印 / 封面大图 / banner）。
+> - ⚠️ 别凭"浮动图位置尺寸更好控制 / 更熟"就选它——那是按操作便利选，不是按场景选；用浮动图承载"对应某记录"的图会在增删行 / 排序后错位。
+
+## 真对象硬约束
+
+当用户要求"插入图片 / 添加 logo / 放一张图"时，**必须**通过 `+float-image-{create|update|delete}`（浮动图片）或 `+cells-set-image` / `+cells-set` 的 `embed-image`（单元格图片）创建真实的图片对象。**禁止**只在文本回复中给出图片链接 / 描述图片内容代替插入。判断标准：交付后 `+float-image-list` 或单元格 `rich_text` 必须能读到该图片对象。
+
+## 使用场景
+
+读写**浮动图片**对象（悬浮在单元格上方的图片，不属于单元格内容）。本 reference 覆盖 4 个 shortcut：
+
+| 操作需求 | 使用工具 | 说明 |
+|---------|---------|------|
+| 查看已有浮动图片 | `+float-image-list` | 获取浮动图片的位置、大小和层级配置 |
+| 创建/更新/删除浮动图片 | `+float-image-{create|update|delete}` | 对浮动图片执行写入操作 |
+
+典型工作流：先读取现有浮动图片了解配置 → 执行创建/更新/删除 → **必须再次读取验证结果**。
+
+**常见配置错误（必须注意）**：
+- **单元格图片 vs 浮动图片选择错误（最易选错）**：图与某条记录一一对应、要随行排序 / 筛选 / 增删时，应走 `+cells-set-image`（见顶部判别），用浮动图会错位。
+- **图片位置参数要精确**：锚点单元格的行列索引和偏移量决定了图片位置，设置不当会导致图片遮挡数据
+- **创建后必须验证**：调用 `+float-image-list` 确认图片位置和大小正确
+
+图片来源有三种方式，`+float-image-create` 上三者 **XOR、必给其一**（`--image` / `--image-token` / `--image-uri`）：
+
+- **`--image <本地路径>`（首选，最省事）**：直接给本地图片文件路径（PNG/JPEG/GIF/BMP/HEIC 等）。CLI 会自动把它以 `parent_type=sheet_image` 上传，拿到 file_token 后创建浮动图，**不用你手动上传 / 取 token**。路径规则同其它本地文件 flag：必须是当前工作目录内的相对路径（绝对路径会被 Validate 拒，`--dry-run` 也会拦）。
+- `--image-token`：复用**已存在**的图片 file_token。常见来源：① `+float-image-list` 返回的 `image_token`（适合"换皮不换位置"复用同一张图）；② `+cells-set-image` 成功返回里的 `file_token`（它也是 `sheet_image` 上传句柄）。适合"同一张图复用到多处"，省去重复上传。
+- `--image-uri`：图片 URI（上传链路返回的句柄），**非**表内对象 reference_id；由系统自动转 file_token。
+
+> ⚠️ **`--image` 仅 `+float-image-create` 支持**。`+float-image-update` 换图仍只接受 `--image-token` / `--image-uri`，而且**图片源是 update 唯一可省的部分**——三者全不传则保留原图。但 `--image-name` / `--position-{row,col}` / `--size-{width,height}` 在 update 时和 create 一样**必填**（`+float-image-update` 强制要求这套核心字段，且 `+float-image-list` 不回传 `image_name` 供 CLI 回填）。要在 update 里换一张本地新图，先用 `+cells-set-image` 上传到任意临时单元格、从返回取 `file_token`，再把它传给 update 的 `--image-token`；用完清除该临时单元格，避免残留多余图片。
+
+## Shortcuts
+
+| Shortcut | Risk | 分组 |
+| --- | --- | --- |
+| `+float-image-list` | read | 对象 |
+| `+float-image-create` | write | 对象 |
+| `+float-image-update` | write | 对象 |
+| `+float-image-delete` | high-risk-write | 对象 |
+
+## Flags
+
+### `+float-image-list`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--float-image-id` | string | optional | 按 id 过滤；省略时列工作表全部 |
+
+### `+float-image-create`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--image-name` | string | required | 图片名称，含扩展名（如 `logo.png`） |
+| `--image-token` | string | xor | 图片 file_token（与 `--image-uri` 二选一）。常见来源：`+float-image-list` 返回的 `image_token` |
+| `--image-uri` | string | xor | 图片 URI（上传链路返回的句柄，非表内对象 reference_id；与 `--image-token` 二选一）；系统自动转换为 file_token |
+| `--position-row` | int | required | 图片左上角所在行（0-based） |
+| `--position-col` | string | required | 图片左上角所在列（列字母，如 `A` / `B`） |
+| `--size-width` | int | required | 图片宽度（像素） |
+| `--size-height` | int | required | 图片高度（像素） |
+| `--offset-row` | int | optional | 在 `--position-row` 基础上的行内偏移（像素） |
+| `--offset-col` | int | optional | 在 `--position-col` 基础上的列内偏移（像素） |
+| `--z-index` | int | optional | 图片 Z 轴层级，控制重叠顺序 |
+| `--image` | string | xor | 本地图片路径（PNG/JPEG 等）；CLI 自动上传为 sheet_image 并用返回的 file_token，省去手动拿 token（与 --image-token / --image-uri 三选一） |
+
+### `+float-image-update`
+
+_公共四件套 · 系统：`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--float-image-id` | string | required | 目标图片 id |
+| `--image-name` | string | required | 图片名称，含扩展名（如 `logo.png`） |
+| `--image-token` | string | optional | 可选图片 file_token；与 `--image-uri` 互斥，二者均省略时保留原图。常见来源：`+float-image-list` 返回的 `image_token` |
+| `--image-uri` | string | optional | 可选图片 URI（上传链路返回的句柄，非表内对象 reference_id）；与 `--image-token` 互斥，二者均省略时保留原图；系统自动转换为 file_token |
+| `--position-row` | int | required | 图片左上角所在行（0-based） |
+| `--position-col` | string | required | 图片左上角所在列（列字母，如 `A` / `B`） |
+| `--size-width` | int | required | 图片宽度（像素） |
+| `--size-height` | int | required | 图片高度（像素） |
+| `--offset-row` | int | optional | 在 `--position-row` 基础上的行内偏移（像素） |
+| `--offset-col` | int | optional | 在 `--position-col` 基础上的列内偏移（像素） |
+| `--z-index` | int | optional | 图片 Z 轴层级，控制重叠顺序 |
+
+### `+float-image-delete`
+
+_公共四件套 · 系统：`--yes`、`--dry-run`_
+
+| Flag | Type | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--float-image-id` | string | required | 目标图片 id |
+
+## Examples
+
+公共四件套：所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`（XOR）。浮动图片是 sheet 级对象——和单元格内嵌图片不同（后者走 `+cells-set`）。
+
+### `+float-image-list`
+
+```bash
+lark-cli sheets +float-image-list --url "..." --sheet-id "$SID"
+```
+
+### `+float-image-create`
+
+所有字段拍平为独立 flag：图片来源 `--image` / `--image-token` / `--image-uri`（三选一 XOR）/ `--image-name` / `--position-{row,col}` / `--size-{width,height}` / `--offset-{row,col}` / `--z-index`。
+
+```bash
+# 首选：直接给本地图片路径，CLI 自动上传（无需手动拿 token）
+# 注意：--image-name 是 required（即使路径 basename 已经是 logo.png 也要显式传）
+lark-cli sheets +float-image-create --url "..." --sheet-id "$SID" \
+  --image ./logo.png --image-name "logo.png" \
+  --position-row 2 --position-col B --size-width 300 --size-height 200 --z-index 1
+
+# 用已有 file_token（从 +float-image-list 的 image_token 或 +cells-set-image 返回的 file_token）
+lark-cli sheets +float-image-create --url "..." --sheet-id "$SID" \
+  --image-name "logo.png" --image-token "$TOKEN" \
+  --position-row 0 --position-col A --size-width 200 --size-height 150
+
+# 用 image URI（上传链路返回的句柄，非表内对象 reference_id；与 --image-token 二选一）
+lark-cli sheets +float-image-create --url "..." --sheet-id "$SID" \
+  --image-name "logo.png" --image-uri "$IMAGE_URI" \
+  --position-row 2 --position-col B --size-width 300 --size-height 200 --z-index 1
+```
+
+### `+float-image-update`
+
+> **update ≈ create，只有图片源可省**：`+float-image-update` 的 update 要求和 create 相同的核心字段——`--image-name`、`--position-{row,col}`、`--size-{width,height}` **全部必填**；唯一区别是**图片源（`--image-token` / `--image-uri`）可以全省**，省略即保留原图。这**不是**"只发改动字段"的 patch：缺任一核心字段会被拒绝（`+float-image-list` 不回传 `image_name`，CLI 无法替你回填）。
+>
+> 推荐流程：先 `+float-image-list --float-image-id <id>` 回读当前 position / size，再带上 `--image-name` 和完整的 position / size 调一次 `+float-image-update`。
+
+```bash
+# 调整位置 + 尺寸，保留原图（不传图片源）
+lark-cli sheets +float-image-update --url "..." --sheet-id "$SID" \
+  --float-image-id "$IMG_ID" --image-name "logo.png" \
+  --position-row 5 --position-col C --size-width 300 --size-height 200
+
+# 换图：额外带 --image-token，核心字段同样要给全
+lark-cli sheets +float-image-update --url "..." --sheet-id "$SID" \
+  --float-image-id "$IMG_ID" --image-name "new-logo.png" --image-token "$NEW_TOKEN" \
+  --position-row 5 --position-col C --size-width 300 --size-height 200
+```
+
+### `+float-image-delete`
+
+```bash
+lark-cli sheets +float-image-delete --url "..." --sheet-id "$SID" --float-image-id "$IMG_ID" --yes
+```
+
+### Validate / DryRun / Execute 约束
+
+- `Validate`：XOR 公共四件套；`+float-image-create` 要求 `--image` / `--image-token` / `--image-uri` **恰好给一个**，`--position-row/col` 与 `--size-width/height` 必填且为合法整数；传 `--image` 时还会校验路径安全（绝对路径 / 越出工作目录会被拒，`--dry-run` 同样拦）。`+float-image-update` 必须 `--float-image-id`，并和 create 一样必填 `--image-name` / `--position-{row,col}` / `--size-{width,height}`（缺任一核心字段本地直接报错，不会静默发 0）；图片源 `--image-token` / `--image-uri` 可省（省略保留原图），给则二选一；`+float-image-delete` 强制 `--yes` 或 `--dry-run`。
+- `DryRun`：写操作输出"将要 POST/PATCH/DELETE 的 float_image 请求模板"；传 `--image` 时会多打印一步本地图片上传（`POST /open-apis/drive/v1/medias/upload_all`，`parent_type=sheet_image`）。
+- `Execute`：写后不自动回读；如需确认，自行调用 `+float-image-list --float-image-id <id>` 比对新位置 / 尺寸。

package/skills/lark-sheets/references/lark-sheets-formula-translation.md

@@ -0,0 +1,276 @@
+# 飞书表格公式生成规则
+
+> **本文定位**：飞书公式正确性的**唯一权威**——书写任何飞书公式、或把 Excel 公式迁移到飞书前，先读本文。涵盖公式书写约定（绝对引用、范围语法）、投影 vs spill、ARRAYFORMULA / 数组语义、高风险引用函数、日期差、不支持函数清单。
+> **边界**：本文只讲"公式怎么写对"；公式**怎么写入表格**（`+cells-set` / 模板单元格 + `--copy-to-range` / 容错回读）见 `lark-sheets-write-cells`。**公式写入完成后的强制收尾**见 `lark-sheets-formula-verify`：不要把"翻译对了"误当成"已经交付完成"。本文不含 shortcut，通用编辑准则见主 SKILL.md「飞书表格编辑准则」。
+
+**核心原则：飞书不像 Excel 365 那样默认 spill（溢出展开）。飞书普通公式遇到区域时默认"投影"（只取当前行/列对应的单个值），必须显式使用 `ARRAYFORMULA` 或原生数组函数才能逐项展开。**
+
+## 公式书写约定（写任何公式都先满足）
+
+- **绝对引用 `$`**：向下 / 向右填充前判断哪些引用要锁定——用户指定的固定 cell（`$C$3`）、要固定的数据范围（`$A$2:$B$5`）、锁列不锁行（`$A2`）、锁行不锁列（`B$1`）。填充前检查是否需固定汇率 / 税率 / 查找表 / 权重表，以及同列 / 同行公式结构是否一致。
+- **公式字符串用飞书范围语法**：写 `H:H`、`A2:B5`，**禁止** `H2:H` / `2:2`。要在公式里引用整行，用显式范围（如 `$A2:$Z2`）替代禁用的 `2:2`。这与 CLI 工具参数（如 `--range` / `--copy-to-range`）的 A1 表示法写法不同：参数侧合法的 `D3:D`、`1:1`、`3:6` 在公式串里反而非法。**公式串 ≠ CLI 参数**，两套规则别互相照搬，混用会导致调用失败或公式报错。
+
+## 翻译后必做：代码复现校验
+
+公式语法翻译完之后，**必须**用本地脚本在源数据上独立复现一份"等价计算结果"再写入。流程：
+
+1. **挑 3-5 个代表性输入行**（首行 / 中段 / 末行 / 含空值 / 含异常格式各一）
+2. **用 Python 复现 Excel 原公式的语义**（不是飞书译文的语义，而是用户原本想要的结果）
+3. **写入飞书译文公式后回读这几行的实际值**
+4. **三方对照**：`Excel 原公式语义 == Python 复现 == 飞书译文回读值`，全部一致才交付；不一致先排查（数组语义？日期差？范围引用？）
+
+**理由**：Excel→飞书的语法翻译很容易在 spill / 数组 / 日期差 / 范围引用上出现等价性偏差，仅靠语法转换通过不足以保证业务结果正确。
+
+## 落表后的默认交接
+
+本文解决的是"公式怎么写对"，不是"写进表里后一定能零错误运行"。因此：
+
+1. 按本文完成公式改写后，用 `lark-sheets-write-cells` / `lark-sheets-batch-update` 把公式真实写入表格。
+2. 公式一旦落表，就默认进入 `lark-sheets-formula-verify` 的收尾阶段。
+3. 最终必须跑 `+formula-verify` 收敛到 `status='success'`；`errors_found` / `partial` 都不算完成。
+
+## 决策流程
+
+1. 最终结果是**标量**（单值）→ 通常不需要 `ARRAYFORMULA`
+2. 最终结果是**一维或二维数组**：
+   - 公式中**包含**飞书原生数组函数（如 FILTER、XLOOKUP、MAP 等）→ 无需加 `ARRAYFORMULA`，数组语义会自动传播到整个公式，包括原生数组函数外层接的标量运算（如 `+1`、`*100`）
+   - 公式中**不包含**任何原生数组函数，但在对区域做标量计算 → 加 `ARRAYFORMULA(<整个表达式>)`
+3. Excel 依赖 `ROW(range)` 逐项驱动 `SUBTOTAL/INDIRECT/OFFSET` → 改用 `MAP(ARRAYFORMULA(ROW(...)), LAMBDA(r, ...))`
+4. 内层 `INDEX/INDIRECT/OFFSET` 返回范围，外层 `SUMIF/COUNTIF/SUMIFS` 还要继续吃这些范围 → 改用 `MAP(..., LAMBDA(...))` 或 `REDUCE(..., LAMBDA(...))`
+5. 公式意图是"对多个区域分别计算再汇总"（例如用 INDIRECT/OFFSET 对每行生成一个范围，再对所有范围聚合）→ 飞书不能直接返回"区域的列表"，必须明确降维：用 `VSTACK` 垂直合并、`HSTACK` 水平合并、`TOCOL/TOROW` 展平，或 `REDUCE` 归约成标量
+6. 算日期差 → 不要写 `DAY(end-start)`，用 `DAYS`、`DATEDIF` 或直接 `end-start`
+
+## 飞书的投影行为（不是默认 spill）
+
+飞书普通公式对引用区域默认"投影"而不是"spill"：
+
+- 单列区域 → 按当前公式所在行取值
+- 单行区域 → 按当前公式所在列取值
+- 二维区域 → 只有当前公式位置能映射到该区域时才取值，否则报错
+- 数组常量 `{...}` 或函数返回矩阵，在普通标量上下文里通常只取左上角
+
+因此：
+- `=A1:A2` 在飞书普通公式里不会 spill，只会投影到当前行
+- `=ABS(A2:B2)` 不会得到一整行，要写 `=ARRAYFORMULA(ABS(A2:B2))`
+- `=TRUNC({1.1111,2.222},{1,2})` 要得到一整行，写 `=ARRAYFORMULA(TRUNC({1.1111,2.222},{1,2}))`
+
+## ARRAYFORMULA 使用规则
+
+**前提：以下规则适用于公式中没有任何原生数组函数的情况。** 若公式中已有原生数组函数（如 FILTER、XLOOKUP、MAP 等），数组语义会自动传播到整个公式的求值过程，后续标量运算无需额外包 `ARRAYFORMULA`（见下一节）。
+
+需要加 `ARRAYFORMULA` 的典型场景（公式中无原生数组函数时）：
+
+- 算术运算：`+ - * / ^ %`
+- 比较运算：`= <> > >= < <=`
+- 标量数学函数：`ABS ROUND INT TRUNC MOD LOG LN SQRT SIN COS TAN ...`
+- 文本函数：`LEN LEFT RIGHT MID UPPER LOWER TRIM TEXT VALUE ...`
+- 日期函数：`YEAR MONTH DAY DATE TIME EDATE EOMONTH ...`
+- 条件函数：`IF IFS IFERROR IFNA NOT ISNUMBER ISTEXT ISBLANK ...`
+- 引用函数（高风险）：`INDEX OFFSET COLUMN ROW MATCH`
+
+### 公式中有原生数组函数时，整个公式已进入数组模式
+
+飞书的数组语义会在整个公式求值过程中累积传播：一旦某个原生数组函数运行，后续所有运算符和函数也会自动逐元素处理，无论它们出现在哪一层。
+
+因此，以下写法**无需**额外包 `ARRAYFORMULA`：
+
+- `=FILTER(A2:A10,B2:B10="x")+1` ✓
+- `=XLOOKUP(E2:E10,A2:A10,B2:B10)*100` ✓
+- `=ABS(FILTER(A2:A10,B2:B10>0))` ✓
+- `=MAP(A2:A10,LAMBDA(x,x*2))-1` ✓
+
+对比：**没有原生数组函数**时必须加：
+
+- `=A2:A100*B2:B100` → `=ARRAYFORMULA(A2:A100*B2:B100)` ✓
+- `=IF(A2:A100>0,B2:B100,"")` → `=ARRAYFORMULA(IF(A2:A100>0,B2:B100,""))` ✓
+
+## 飞书原生数组函数清单
+
+以下函数按数组语义工作，通常**不需要额外包 `ARRAYFORMULA`**：
+
+`ARRAYFORMULA` `ARRAY_CONSTRAIN` `BYCOL` `BYROW` `CELL` `CHOOSECOLS` `CHOOSEROWS` `DROP` `EXPAND` `FILTER` `FLATTEN` `FREQUENCY` `GROWTH` `HSTACK` `IMPORTDATA` `IMPORTFEED` `IMPORTHTML` `IMPORTRANGE` `IMPORTXML` `LINEST` `LOGEST` `LOOKUP` `MAKEARRAY` `MAP` `MINVERSE` `MMULT` `MUNIT` `QUERY` `RANDARRAY` `REDUCE` `REGEXEXTRACT` `SCAN` `SEQUENCE` `SORT` `SORTBY` `SORTN` `SPLIT` `SUMPRODUCT` `SWITCH` `TAKE` `TEXTSPLIT` `TOCOL` `TOROW` `TRANSPOSE` `TREND` `UNIQUE` `VSTACK` `WRAPCOLS` `WRAPROWS` `XLOOKUP`
+
+> **注意：`SWITCH` 在飞书里被当作原生数组函数处理，这与 Excel 行为不同，不需要额外包 `ARRAYFORMULA`。**
+
+## IMPORTRANGE 跨工作簿引用限制
+
+用 `IMPORTRANGE` 跨电子表格引用数据时有两条硬上限：
+
+- **嵌套最多 5 层**：被引用的表里若又用 `IMPORTRANGE` 继续引下一张表，整条引用链最多 5 层。
+- **每个工作表最多 100 个 `IMPORTRANGE` 引用**。
+
+超限会让引用失效或报错。设计大量跨表汇总前先估算引用数，必要时先把数据落地到本表再计算。
+
+## INDEX / OFFSET / COLUMN / ROW / MATCH 是高风险函数
+
+这组函数容易让人误以为会自动把多值铺开，但在飞书里不能这样假设。
+
+**高风险信号：**
+
+- 行号 / 列号 / 偏移量本身是数组
+- 结果本来应该是一行或一块二维区域
+- 外层还有算术、比较、`IF` 等继续处理它
+
+更稳的写法：
+
+- `=ARRAYFORMULA(INDEX(...))`
+- `=ARRAYFORMULA(OFFSET(...))`
+- `=ARRAYFORMULA(COLUMN(...))`
+- `=ARRAYFORMULA(ROW(...))`
+
+**例外：** 如果返回值只是立刻交给聚合函数消费，不需要额外包：
+
+- `=SUM(INDEX(A1:B2,0,1))` ✓
+
+## Excel 隐式逐项求值，飞书里要显式写 MAP
+
+**典型特征：**
+
+- 外层是 `SUMPRODUCT`、`SUM` 等聚合
+- 内层用了 `SUBTOTAL`、`INDIRECT`、`OFFSET` 等更偏"单值/单引用"的函数
+- Excel 会把中间结果逐项带进去算
+- 飞书里直接照抄，往往不能得到同样的逐项语义
+
+同类本质也包括：`INDEX/INDIRECT/OFFSET` 先返回范围，外层再把这些范围交给 `SUMIF`、`COUNTIF`、`AVERAGEIF`、`SUMIFS` 等范围感知函数 —— 飞书里这些外层函数不会自动二次展开内层范围。
+
+这时不要只会补 `ARRAYFORMULA`，要显式写"遍历"。最常用模板：
+
+```excel
+=SUMPRODUCT(
+  MAP(
+    ARRAYFORMULA(ROW(目标范围)),
+    LAMBDA(r, 单行计算逻辑)
+  )
+)
+```
+
+同类场景也优先考虑 `MAP`：
+
+- `INDIRECT("A"&ROW(...))`
+- `OFFSET(...,ROW(...)-ROW(...),...)`
+- `SUBTOTAL(...)`
+- `SUMIF(内层返回范围, ...)`
+- `COUNTIF(内层返回范围, ...)`
+- `SUMIFS(内层返回范围, ...)`
+- 任何"希望对每一行 / 每一列各算一次"的模式
+
+## 多层范围结果与三维以上结果
+
+飞书公式结果只能是二维区域，不能是"数组的数组"。
+
+### 多层范围不能自动二次展开
+
+内层 `INDEX/INDIRECT/OFFSET` 返回的是二维范围，外层还想继续对这些范围做范围计算时，不要假设飞书会"再展开一层"。改用：
+
+- `MAP(..., LAMBDA(...))` 显式逐项算
+- `REDUCE(..., LAMBDA(...))` 显式累加/归约
+
+### 真正的三维或更高维结果不能直接返回
+
+典型触发场景：想把多个不同区域或不同条件的结果合并展示，例如：
+- 对 A 列、B 列、C 列分别做 FILTER，想把三列结果并排展示
+- 对多个月份分别生成数据行，想把所有月份上下堆叠展示
+
+飞书无法直接返回"多个区域的集合"，必须先决定降维方式：
+
+- 上下堆叠：`=VSTACK(slice1, slice2, slice3)`
+- 左右拼接：`=HSTACK(slice1, slice2, slice3)`
+- 压成单列：`=TOCOL(...)`
+- 压成单行：`=TOROW(...)`
+- 只保留聚合值：`=REDUCE(slice1, {slice2,slice3}, LAMBDA(acc,x,acc+x))`
+
+不要替用户"偷定"第三维展示方式；如果用户没有明确说明怎么展示，至少先把结果改写成可见的二维形状。
+
+## 不能机械照抄的 Excel 语法
+
+### `@` 隐式交叉
+
+Excel：`=@A1:A10`（强制单值，取当前行对应的值）
+
+飞书没有 `@` 运算符。飞书普通公式对引用区域默认就有投影语义，去掉 `@` 即可：
+
+- Excel: `=@A1:A10`
+- 飞书: `=A1:A10`
+
+### `#` spill range
+
+Excel：`=A1#`（引用 A1 公式溢出的整片区域）
+
+飞书没有此语法，迁移方式：
+
+- spill 区域已知 → 改成明确范围
+- spill 区域未知 → 回到源公式重写，或用 `TAKE` / `DROP` / `ARRAY_CONSTRAIN`
+
+### 结构化引用
+
+Excel：`=SUM(Table1[Amount])`
+
+飞书不支持结构化引用，改成显式 A1 区域：`=SUM(A2:A100)`
+
+### 老式 CSE 花括号
+
+Excel：`{=A1:A10*B1:B10}`（Ctrl+Shift+Enter 输入）
+
+飞书改为：`=ARRAYFORMULA(A1:A10*B1:B10)`
+
+## 日期序列与日期差
+
+飞书日期序列：`0 = 1899-12-30`，`1 = 1899-12-31`，没有 Excel 的 1900 年闰年兼容问题。
+
+**错误写法（不要用）：**
+
+- `=DAY(B2-A2)` ✗ — 差值会被当成日期序列号再拆字段
+- `=MONTH(B2-A2)` ✗
+- `=YEAR(B2-A2)` ✗
+
+**正确写法：**
+
+- 天数差：`=DAYS(B2,A2)` 或 `=DATEDIF(A2,B2,"D")` 或 `=B2-A2`
+- 月份差：`=DATEDIF(A2,B2,"M")`
+- 年份差：`=DATEDIF(A2,B2,"Y")`
+- 工作日差：`=NETWORKDAYS(A2,B2)`
+
+## 飞书不支持的函数
+
+> 本段是"飞书不支持函数"的**唯一权威清单**。以下函数在飞书里不存在或被禁用，禁止主动使用；用户明确要求时应拒绝并提供替代方案：
+
+- `STOCKHISTORY` — 实时股票数据，飞书无等价函数，需手动导入数据
+- `WEBSERVICE` — 外部 HTTP 请求，飞书无等价函数
+- 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` — 飞书不支持
+- `LET`、命名自定义函数（名称管理器里定义的 LAMBDA）、独立调用的 `LAMBDA`（如 `=LAMBDA(x,x+1)(5)`）— 会报 `#NAME?`；改用嵌套 IF / 辅助列。**例外**：`LAMBDA` 作为 `MAP` / `REDUCE` / `BYROW` / `BYCOL` / `SCAN` / `MAKEARRAY` 的内联参数时**支持**（见上方「飞书原生数组函数清单」）
+
+## 代表性改写示例
+
+- 基础逐项计算
+  - Excel: `=A2:A100*B2:B100`
+  - 飞书: `=ARRAYFORMULA(A2:A100*B2:B100)`
+- 条件判断
+  - Excel: `=IF(A2:A100>0,B2:B100,"")`
+  - 飞书: `=ARRAYFORMULA(IF(A2:A100>0,B2:B100,""))`
+- 原生数组函数（无需改动）
+  - Excel: `=FILTER(A2:C100,B2:B100="East")`
+  - 飞书: `=FILTER(A2:C100,B2:B100="East")`
+- 原生数组函数 + 标量运算（无需改动，数组语义自动传播）
+  - Excel: `=XLOOKUP(E2:E10,A2:A10,B2:B10)*100`
+  - 飞书: `=XLOOKUP(E2:E10,A2:A10,B2:B10)*100`
+- 高风险引用函数
+  - Excel: `=INDEX(A1:D2,{2,1},0)`
+  - 飞书: `=ARRAYFORMULA(INDEX(A1:D2,{2,1},0))`
+- 日期差
+  - 错误: `=DAY(B2-A2)`
+  - 推荐: `=DAYS(B2,A2)` 或 `=DATEDIF(A2,B2,"D")` 或 `=B2-A2`
+- Excel 隐式逐项求值
+  - Excel: `=SUMPRODUCT(SUBTOTAL(103,INDIRECT("E"&ROW($E$16:$E$387))))`
+  - 飞书: `=SUMPRODUCT(MAP(ARRAYFORMULA(ROW($E$16:$E$387)),LAMBDA(row,SUBTOTAL(103,INDIRECT("E"&row)))))`
+- 多层范围 / 二次展开
+  - 错误思路: `=SUMIF(INDIRECT("E"&ROW($E$16:$E$387)),">0")`
+  - 飞书: `=MAP(ARRAYFORMULA(ROW($E$16:$E$387)),LAMBDA(r,SUMIF(INDIRECT("E"&r),">0")))`
+- 三维降二维（保留所有层）
+  - 飞书: `=VSTACK(slice1,slice2,slice3)` 或 `=HSTACK(slice1,slice2,slice3)`
+- 三维降二维（只保留聚合值）
+  - 飞书: `=REDUCE(slice1,{slice2,slice3},LAMBDA(acc,x,acc+x))`

package/skills/lark-sheets/references/lark-sheets-formula-verify.md

@@ -0,0 +1,77 @@
+# Lark Sheet Formula Verify（+formula-verify）
+
+> **本文定位**：飞书表格"公式写入后是否真的零错误"的自检入口，也是所有写公式任务的**强制收尾步骤**。公式的书写规则与 Excel→飞书迁移的语义规则一律以 `lark-sheets-formula-translation` 为唯一权威，本文不重复；本文聚焦"写完了之后怎么用一次调用确认 zero-error"。
+>
+> **边界**：本文不讲公式怎么写（去 `lark-sheets-formula-translation`），也不讲公式怎么写入表格（去 `lark-sheets-write-cells` / `lark-sheets-batch-update`）。本文只讲一件事：**只要任务里发生了公式落表、批量填充公式、`--copy-to-range` 扩展公式、导入含公式 workbook，收尾就必须用 `+formula-verify` 自检到 zero-error 才能交付**。
+
+## 为什么需要自检
+
+飞书在线表格已经实时算好结果，但"算出来"和"算对了"是两件事。常见缺口：
+
+- 公式编译失败 → 单元格落成文本（写入类 shortcut 返回的 `formula_errors[]` 是**编译失败**信号）。
+- 公式编译成功但**运行时错误**：`#REF!` / `#DIV/0!` / `#VALUE!` / `#NAME?` / `#NULL!` / `#NUM!` / `#N/A`——这一类只看 `formula_errors[]` 看不到，必须扫单元格值。
+
+`+formula-verify` 把两路信号合并成一份统一 JSON：一次调用聚合全表错误清单 + 编译失败清单 + 每类错误的定位与样本，AI 一眼就能定位修复，链路也能据 `status` 强制收敛到 `success`。
+
+## 调用契约
+
+最小调用形态：
+
+| 入参 | 含义 |
+|---|---|
+| `--url` / `--spreadsheet-token` | 表格定位（XOR 二选一，必填） |
+| `--sheet-id` / `--sheet-name` | 限定子表（mutually exclusive；省略则扫全部可见子表） |
+| `--range` | 限定 A1 范围；省略则用各 sheet 的 `current_region` |
+| `--max-locations` | 每类错误样本上限，默认 20 |
+| `--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` 续读。
+
+## 写入收尾收敛规则
+
+任何批量公式 / 含公式列写入完成后调用 `+formula-verify` 直到 `status='success'` 才能交付。不要等用户显式说"校验一下公式"才想到这里；**只要任务动作包含写公式，这一步默认就该做**。触发场景：
+
+- `+cells-set` / `+csv-put`
+- `+cells-set --copy-to-range` / 模板单元格向整列或整块扩展公式
+- `+workbook-import`
+- `+batch-update` 中含写入子操作
+- `+table-put`（任意列含公式时）
+- `+workbook-import`（导入的 xlsx 含公式时）
+
+收敛规则：
+
+1. `status='success'` → 通过；可以把链路标完成。
+2. `status='partial'` → 扫描被内部上限截断。先缩小 `--range` 或拆 `--sheet-id` 续扫，**不允许**把 `partial` 当作 `success`。
+3. `status='errors_found'` 且 `compile_errors[]` 非空 → **先解决编译失败**：根据 `compile_errors[].reason` 修正公式语法（飞书函数名 / 范围语法 / 引用样式），用 `+cells-set` 重写后再调一次 `+formula-verify`。
+4. `status='errors_found'` 且只剩运行时错误 → 按 `error_summary` 的 `samples[].formula` + `depends_on` 排查根因（零除？空值参与运算？引用越界？日期差写法？数组语义？），修复后重新自检。
+5. 同一处错误连续修复 3 次仍未通过 → 改用 `IFERROR` 包裹兜底，或退回纯值写入；不要在 `errors_found` 状态下扩展 `+cells-set --copy-to-range`、追加批量写入。
+
+注意：
+
+- 在 `status='errors_found'` 的状态下调用 `+cells-set --copy-to-range` 继续扩展会把错误复制放大。
+- "编译失败但运行时无报错"不是 zero-error（编译失败的单元格此刻是文本不是公式，源数据一变就再也算不出值）。
+- 跳过自检直接交付、靠肉眼读首末 5 行确认是不可靠的——表中段、隐藏行、合并区里的错误这样根本看不到。
+
+## 截断与续读
+
+后端有一个内部硬上限对总扫描单元格数做截断（不暴露给调用方），超过后立即返回 `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[]`、再做运行时自检。 |