docs(sheets): chart coordinate base / quoting + filter condition enums

Sync three reference-doc corrections from the spec source: 1. chart: label position.row as 0-based (first row = row:0), distinct from the 1-based row numbers used by A1 ranges and +dim-insert --position, removing the row-base ambiguity. 2. chart: convert the three runnable examples whose JSON contains a quoted sheet prefix ('Sheet1'!A1) from inline single-quoted --properties '{...}' to a stdin heredoc (--properties - <<'JSON'). Inside an inline single-quoted string bash strips the inner quotes around the sheet name (and splits names with spaces into words), corrupting the JSON; a quoted heredoc delimiter performs no shell substitution and preserves it. Adds a short note on the pitfall. 3. filter / filter-view: add the full conditions[].type x compare_type enum table (text / number / multiValue / color and their respective compare_type values and values shape), and call out the equals/notEquals (with s) vs equal/notEqual (no s) gotcha. The docs previously only showed two values via examples.
2026-07-07 09:11:44 +08:00 · 2026-06-09 16:07:27 +08:00
parent 7ac8a7d30e
commit e96acad2c5
3 changed files with 48 additions and 18 deletions
--- a/skills/lark-sheets/references/lark-sheets-chart.md
+++ b/skills/lark-sheets/references/lark-sheets-chart.md
@@ -85,7 +85,7 @@

 1. **查尺寸**：`+workbook-info` 拿该 sheet 的 `row_count` / `column_count`（下文记为 rowCount / columnCount；`+sheet-info` 只返回布局，不含行列总数）。
 2. **估跨度**：默认单元格 **105 px 宽 × 27 px 高**，`needCols = ceil(width/105)`，`needRows = ceil(height/27)`。
-3. **校验**：`position.row + needRows ≤ rowCount` 且 `col_idx + needCols ≤ columnCount`（col 按 A=0、B=1、…、Z=25、AA=26… 换算）。
+3. **校验**：`position.row + needRows ≤ rowCount` 且 `col_idx + needCols ≤ columnCount`（`position.row` 为 **0-based**：首行 = `row:0`，与 A1 区间 / `+dim-insert --position` 的 1-based 行号不同；col 按 A=0、B=1、…、Z=25、AA=26… 换算）。
 4. **不够就先扩表**，二选一，禁止硬塞越界位置：
   - **优先**放数据下方空区：`position = {row: data_end_row + 2, col: "A"}`；
   - 否则先调 `+dim-insert`（`lark-sheets-sheet-structure`）扩行/列，再 create。
@@ -167,24 +167,28 @@ _创建/更新的图表属性_

 > **`snapshot.data` 必填 `dim1.serie.index` 或 `dim2.series[].index` 之一**（1-based，对应 `refs.value` 范围内的列序）。schema 允许传空 `{}` 但 server 运行时强制：缺则被拒为 `snapshot.data.dim1.serie.index and dim2.series[].index are both missing; at least one must be set`，即便侥幸通过也只会渲染空图。

+> ⚠️ **含 `'Sheet'!` 前缀的 `--properties` 必须走 stdin 或 `@file`，不要用 inline 单引号**。`refs` / `nameRef` 里的 sheet 前缀带单引号（`'Sheet1'!A1`），若塞进 inline 的 `--properties '{...}'`，bash 会把内层那对单引号吃掉（sheet 名带空格还会被拆成多个词），JSON 直接被破坏。下面示例统一用 `--properties - <<'JSON' … JSON`（heredoc 定界符加引号 = 不做 shell 替换），或 `--properties @file.json`（`@` 只接 cwd 下相对路径）。
+
 最小可用列图（inline 模式：refs 含表头行）：

 ```bash
 lark-cli sheets +chart-create --url "https://example.feishu.cn/sheets/shtXXX" \
-  --sheet-name "Sheet1" --properties '{
-    "position":{"row":42,"col":"A"},
-    "size":{"width":600,"height":400},
-    "snapshot":{
-      "data":{
-        "refs":[{"value":"'Sheet1'!A1:B10"}],
-        "dim1":{"serie":{"index":1}},
-        "dim2":{"series":[{"index":2}]}
-      },
-      "plotArea":{"plot":{"type":"column"}}
-    }
-  }'
+  --sheet-name "Sheet1" --properties - <<'JSON'
+{
+  "position":{"row":42,"col":"A"},
+  "size":{"width":600,"height":400},
+  "snapshot":{
+    "data":{
+      "refs":[{"value":"'Sheet1'!A1:B10"}],
+      "dim1":{"serie":{"index":1}},
+      "dim2":{"series":[{"index":2}]}
+    },
+    "plotArea":{"plot":{"type":"column"}}
+  }
+}
+JSON

-# 走文件（推荐配置较多时）
+# 或落到 cwd 下相对路径文件再用 @file
 lark-cli sheets +chart-create --url "..." --sheet-name "Sheet1" --properties @chart-config.json
 ```

@@ -193,7 +197,8 @@ lark-cli sheets +chart-create --url "..." --sheet-name "Sheet1" --properties @ch
 饼图比 column / bar 更复杂：`sectors` 是 object，里面再包一个**单数** `sector` 数组——CLI 不替你 normalize，写错路径会被 server schema 直接拒。

 ```bash
-lark-cli sheets +chart-create --url "..." --sheet-name "Sheet1" --properties '{
+lark-cli sheets +chart-create --url "..." --sheet-name "Sheet1" --properties - <<'JSON'
+{
  "position":{"row":24,"col":"F"},
  "size":{"width":600,"height":450},
  "snapshot":{
@@ -211,7 +216,8 @@ lark-cli sheets +chart-create --url "..." --sheet-name "Sheet1" --properties '{
      "dim2":{"series":[{"index":2,"aggregateType":"sum"}]}
    }
  }
-}'
+}
+JSON
 ```

 **数据与表头分离（必须用 `detached` + `nameRef`）**：
@@ -219,7 +225,8 @@ lark-cli sheets +chart-create --url "..." --sheet-name "Sheet1" --properties '{
 场景：周度销量明细表，真实表头在第 1 行（A1=周次、C1=订单量、D1=退款量），数据按 B 列"店铺"分段；用户只要"3 号店"那一段（第 11–17 行）。

 ```bash
-lark-cli sheets +chart-create --url "..." --sheet-name "Sheet2" --properties '{
+lark-cli sheets +chart-create --url "..." --sheet-name "Sheet2" --properties - <<'JSON'
+{
  "position":{"row":7,"col":"F"},
  "size":{"width":600,"height":360},
  "snapshot":{
@@ -236,7 +243,8 @@ lark-cli sheets +chart-create --url "..." --sheet-name "Sheet2" --properties '{
      ]}
    }
  }
-}'
+}
+JSON
 ```

 约束：
--- a/skills/lark-sheets/references/lark-sheets-filter-view.md
+++ b/skills/lark-sheets/references/lark-sheets-filter-view.md
@@ -109,6 +109,17 @@ lark-cli sheets +filter-view-create --url "..." --sheet-id "$SID" \
  --properties '{"rules":[{"column_index":"C","conditions":[{"type":"number","compare_type":"greaterThan","values":[100]}]}]}'
 ```

+**`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-view-create --print-schema --flag-name properties`。
+
 > `--range` **必须覆盖表头行**（如 `A1:F1000`），不能只包含数据行；`--view-name` 重名时服务端自动改名。

 ### `+filter-view-update`
--- a/skills/lark-sheets/references/lark-sheets-filter.md
+++ b/skills/lark-sheets/references/lark-sheets-filter.md
@@ -102,6 +102,17 @@ lark-cli sheets +filter-create --url "..." --sheet-id "$SID" \
  --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`。