From b85311c8730da485bbdae998852fcb28074643b6 Mon Sep 17 00:00:00 2001 From: xiongyuanwen-byted Date: Sat, 23 May 2026 13:45:44 +0800 Subject: [PATCH] docs(sheets): sync lark-sheets skill spec from upstream Refine reference docs and flag-defs descriptions from upstream sheet-skill-spec (--depth wording for +dim-group / +dim-ungroup, plus assorted reference clarifications). Description-only; no CLI behavior or flag surface change. --- shortcuts/sheets/data/flag-defs.json | 4 ++-- skills/lark-sheets/SKILL.md | 2 +- .../lark-sheets/references/lark-sheets-chart.md | 10 ++++------ .../references/lark-sheets-core-operations.md | 12 ++---------- .../lark-sheets-formula-translation.md | 11 ++++++++--- .../references/lark-sheets-pivot-table.md | 7 ++++++- .../references/lark-sheets-range-operations.md | 2 +- .../references/lark-sheets-read-data.md | 2 ++ .../references/lark-sheets-search-replace.md | 6 +++++- .../references/lark-sheets-sheet-structure.md | 6 +++--- .../references/lark-sheets-sparkline.md | 17 ++++------------- .../references/lark-sheets-visual-standards.md | 4 ++-- .../references/lark-sheets-write-cells.md | 8 ++++---- 13 files changed, 44 insertions(+), 47 deletions(-) diff --git a/shortcuts/sheets/data/flag-defs.json b/shortcuts/sheets/data/flag-defs.json index 48dcdc94c..ab97963bc 100644 --- a/shortcuts/sheets/data/flag-defs.json +++ b/shortcuts/sheets/data/flag-defs.json @@ -975,7 +975,7 @@ "kind": "own", "type": "int", "required": "optional", - "desc": "Nesting level (used by `+dim-group`); default 1", + "desc": "Nesting level for grouping; default 1", "default": "1" }, { @@ -1060,7 +1060,7 @@ "kind": "own", "type": "int", "required": "optional", - "desc": "Nesting level (used by `+dim-group`); default 1", + "desc": "Group nesting level to ungroup; default 1 (outermost)", "default": "1" }, { diff --git a/skills/lark-sheets/SKILL.md b/skills/lark-sheets/SKILL.md index ace2edcf5..91cddfd53 100644 --- a/skills/lark-sheets/SKILL.md +++ b/skills/lark-sheets/SKILL.md @@ -63,7 +63,7 @@ metadata: | --- | --- | --- | --- | | `--dry-run` | bool | 否 | 零副作用：仅打印请求路径与参数模板，不发起调用；多步操作会输出每个子操作的请求模板 | | `--yes` | bool | 是（仅 `high-risk-write`） | 二次确认；不带时退出码 10。详见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 高风险审批协议 | -| `--print-schema` | bool | 否 | 本地打印复合 JSON flag 的 JSON Schema 并退出，不发起任何调用、不需要其它 required flag。与 `--flag-name ` 搭配指定要查哪个 flag；省略 `--flag-name` 时列出该 shortcut 所有可查询的 flag。仅在 shortcut 含复合 JSON flag 时有效。 | +| `--print-schema` | bool | 否 | 本地打印复合 JSON flag 的 JSON Schema 并退出，不发起任何调用、不需要其它 required flag。与 `--flag-name ` 搭配指定要查哪个 flag；省略 `--flag-name` 时列出该 shortcut 所有可查询的 flag。**仅在 shortcut 含复合 JSON flag 时有效**——判断方法：该 shortcut 的 Flags 表里出现类型标注为「复合 JSON」的 flag（如 `--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys` / `--options`）即支持；纯标量 flag 的 shortcut 不支持。 | | `--flag-name` | string | 否 | 配合 `--print-schema` 使用，指定要打印 JSON Schema 的 flag 名（不带 `--` 前缀，如 `cells` / `properties` / `operations`）。 | **Agent 使用提示**：写复合 JSON flag（`--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys` 等）时，如果对结构不确定，先跑 `lark-cli sheets --print-schema --flag-name ` 把完整 JSON Schema 读出来再构造 payload，比靠 reference 的速查表更精确，也避免因为字段拼写或缺失被服务端拒绝。reference 的 `## Schemas` 段只给一层结构，深层只能靠 `--print-schema` 或 `## Examples` 的真实示例。 diff --git a/skills/lark-sheets/references/lark-sheets-chart.md b/skills/lark-sheets/references/lark-sheets-chart.md index 312f0a482..7134f94fe 100644 --- a/skills/lark-sheets/references/lark-sheets-chart.md +++ b/skills/lark-sheets/references/lark-sheets-chart.md @@ -20,9 +20,9 @@ | 用户说 | 图表类型 | 备注 | |--------|---------|------| | "占比"、"比例"、"各XX占多少" | 饼图（pie） | 单维度占比首选 | -| "对比"、"各XX的YY" | 柱状图（bar） | 多类别数值对比 | +| "对比"、"各XX的YY" | 柱形图（column，纵向） | 多类别数值对比；横向条形用 `bar` | | "趋势"、"变化"、"走势" | 折线图（line） | 时间序列首选 | -| "堆积"、"组成构成" | 堆积柱状图（bar + stack） | 多系列累加 | +| "堆积"、"组成构成" | 堆积柱形图（column + stack） | 多系列累加 | | "分布"、"相关性" | 散点图（scatter） | 两变量关系 | **多图表需求**：当用户同时提到多种分析（如"统计占比 + 对比数量"），必须创建多个图表，每个对应一种类型，不要只做一个。 @@ -30,7 +30,7 @@ **`--properties` 结构锚点（构造前必读）**：`--properties` 顶层只有 `position` / `offset` / `size` / `snapshot` 四个字段，**没有**顶层 `data`，也没有再嵌一层 `properties`。图表数据配置全部挂在 `snapshot.data` 下——下文及示例里出现的 `refs` / `headerMode` / `dim1` / `dim2` / `nameRef` 一律指 `snapshot.data.refs` / `snapshot.data.headerMode` / `snapshot.data.dim1` / `snapshot.data.dim2`（及其下的 `serie.nameRef` / `series[].nameRef`）；样式 / 堆叠 / 数据标签等在 `snapshot.plotArea` 下。完整结构以 `lark-cli sheets +chart-create --print-schema --flag-name properties` 为准。 **常见配置错误（必须注意）**： -- **图表类型选择错误**：用户说"堆积柱状图/百分比堆积"时，应在 `properties.snapshot.plotArea.plot.extra.stack` 中配置堆叠；百分比堆叠需在该 stack 下设置 `percentage: true`。用户说"占比/比例"时，优先考虑饼图或百分比堆积图 +- **图表类型选择错误**：用户说"堆积柱形图/百分比堆积"时，应在 `properties.snapshot.plotArea.plot.extra.stack` 中配置堆叠；百分比堆叠需在该 stack 下设置 `percentage: true`。用户说"占比/比例"时，优先考虑饼图或百分比堆积图。注意区分 `column`（柱形图，纵向）与 `bar`（条形图，横向）是两个不同的 type 取值，"对比/各 XX" 类纵向柱默认用 `column` - **数据标签缺失**：用户需要看到具体数值时，需配置 `properties.snapshot.plotArea.plot.labels`（数据标签）相关字段 - **数据源范围与系列名来源要对齐**： - **默认情况（inline 模式）**：`refs` 范围**应包含表头行**（首行/首列即系列名），且范围要精确覆盖目标数据，不要多选或少选。 @@ -69,7 +69,7 @@ ## ⚠️ chart 数据源引用 pivot 时必须排除总计行（高频致命错误） 当 chart 要基于刚创建的 pivot 产物画图时，**禁止凭猜写 `refs`**。pivot 默认启用 `show_row_grand_total` / `show_col_grand_total`，产物最后一行/一列通常是"总计"。如果 `refs` 把总计行一并框进去： -- **柱状图**末尾会多一根天文数字柱子（=所有数据求和），把其他柱子压扁到看不见 +- **柱形图**末尾会多一根天文数字柱子（=所有数据求和），把其他柱子压扁到看不见 - **饼图**会多一个"总计"扇区占 33%+，真实类别的比例完全失真 **正确流程**： @@ -78,8 +78,6 @@ 3. 识别并排除"总计"/"小计"行（通常最后一行；嵌套 pivot 还要排除中间层小计） 4. `+chart-create create` 时 `snapshot.data.refs` 精确到数据行（如 pivot 占 A1:D9、总计在 row9 → chart 用 `A1:D8`） -详细规则见 `lark-sheets-pivot-table` 第 5 节"pivot → chart 组合场景"。 - ## 图表位置选择（创建前必做） 凭感觉挑列号/行号会被 API 拒（`position is out of sheet range`），浪费一轮调用。按以下四步走： diff --git a/skills/lark-sheets/references/lark-sheets-core-operations.md b/skills/lark-sheets/references/lark-sheets-core-operations.md index d489700ef..62e6138ca 100644 --- a/skills/lark-sheets/references/lark-sheets-core-operations.md +++ b/skills/lark-sheets/references/lark-sheets-core-operations.md @@ -57,7 +57,7 @@ 除此之外，每次读完还必须查三个字段——交叉表和扁平列表都用得到： - `actual_range`：本次实际返回的范围（请求超边界时自动裁剪） - `current_region`：连续数据矩形（Excel Ctrl+Shift+\*）；若末行 > 请求 range 末行说明数据还没读全 - - `has_more`：因 `max_bytes` 被截断时为 `true`，按 `actual_range` 末行+1 分页续读，或改走路径 A + - `has_more`：返回体超过 `--max-chars` 被截断时为 `true`，按 `actual_range` 末行+1 分页续读，或改走路径 A **`current_region` 远大于可灌入上下文的量（如几百行）时**：切换到路径 A（分批 `+csv-get` 导出到本地 + 本地脚本处理），不要用路径 B 翻页硬塞到上下文。 @@ -251,15 +251,7 @@ print(df.head(10)) # 必做：横向——确认表头行 + - 公式来自 Excel 或包含数组场景时，先读取 `lark-sheets-formula-translation` 完成改写，再生成公式。 - 数组公式必须写成 `=ARRAYFORMULA(数组公式)` 语法。 - 在公式字符串中，数据范围应使用飞书支持的语法，例如 `H:H`、`A2:B5`。禁止使用不符合飞书公式语法的写法，如 `H2:H`、`2:2` 等。 -- 飞书表格不支持以下函数，禁止主动使用；当用户明确要求使用这些函数时，应拒绝并说明飞书不支持： - - CUBE 相关函数，如 `CUBEMEMBER`、`CUBESET`、`CUBEVALUE`、`CUBERANK` - - `GOOGLEFINANCE`、`GOOGLETRANSLATE` 等 Google 特有函数 - - `FORECAST.ETS` 相关函数，如 `FORECAST.ETS`、`FORECAST.ETS.STAT` - - `INFO`、`RTD` 等系统信息相关函数 - - `PIVOT` - - `AMORDEGRC` - - `PHONETIC` - - `DETECTLANGUAGE` +- 飞书表格不支持部分 Excel / Google 专有函数（如 CUBE 系列、`GOOGLETRANSLATE`、`STOCKHISTORY`、`WEBSERVICE` 等），禁止主动使用；当用户明确要求使用这些函数时，应拒绝并说明飞书不支持。**完整的"飞书不支持函数"清单（含替代方案）见 `lark-sheets-formula-translation` 的「飞书不支持的函数」段——以那里为唯一权威清单。** ### 向下填充与绝对引用 diff --git a/skills/lark-sheets/references/lark-sheets-formula-translation.md b/skills/lark-sheets/references/lark-sheets-formula-translation.md index 03ceef07c..50fe849a7 100644 --- a/skills/lark-sheets/references/lark-sheets-formula-translation.md +++ b/skills/lark-sheets/references/lark-sheets-formula-translation.md @@ -205,13 +205,18 @@ Excel：`{=A1:A10*B1:B10}`（Ctrl+Shift+Enter 输入） - 年份差：`=DATEDIF(A2,B2,"Y")` - 工作日差：`=NETWORKDAYS(A2,B2)` -## 飞书不支持的 Excel 专有函数 +## 飞书不支持的函数 -以下函数在飞书里不存在，遇到时需要告知用户并提供替代方案： +> 本段是"飞书不支持函数"的**唯一权威清单**（`lark-sheets-core-operations` 不再单列，统一指向这里）。以下函数在飞书里不存在或被禁用，禁止主动使用；用户明确要求时应拒绝并提供替代方案： - `STOCKHISTORY` — 实时股票数据，飞书无等价函数，需手动导入数据 - `WEBSERVICE` — 外部 HTTP 请求，飞书无等价函数 -- `CUBEVALUE`、`CUBEMEMBER`、`CUBESET` 等 — OLAP cube 函数，飞书不支持 +- 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` — 飞书不支持 ## 代表性改写示例 diff --git a/skills/lark-sheets/references/lark-sheets-pivot-table.md b/skills/lark-sheets/references/lark-sheets-pivot-table.md index dbc8512b3..3f59214be 100644 --- a/skills/lark-sheets/references/lark-sheets-pivot-table.md +++ b/skills/lark-sheets/references/lark-sheets-pivot-table.md @@ -120,6 +120,11 @@ lark-cli sheets +pivot-list --url "..." --sheet-id "$SID" ### `+pivot-create` > 数据源 `--source` 必须从表头行开始；空行 / 汇总行会被当作数据参与聚合，需提前用 `+csv-get` 确认起止边界。`--source` 和 `--range` 是独立 flag（不要再放 `--properties`）；`rows` / `columns` / `values` 等数组字段走 `--properties`。 +> +> **落点 flag 三选一的决策（避免冲突）**： +> - **默认（推荐）**：`--target-sheet-id` / `--target-position` / `--range` 都不传 → 自动新建子表存放透视表产物。 +> - **放进指定的已有子表**：传 `--target-sheet-id <落点子表 id>` + 可选 `--target-position <子表内起点 cell，默认 A1>`。 +> - **`--range`** 只在不指定落点子表、想精确指定左上角 cell（映射到 `properties.range`）时用；与 `--target-position` 表达同一意图但落不同 wire 字段，**两者不要同时给**。一般用前两种即可，无需 `--range`。 ```bash lark-cli sheets +pivot-create --url "..." --sheet-id "$SRC_SID" \ @@ -142,4 +147,4 @@ lark-cli sheets +pivot-delete --url "..." --pivot-table-id "$PID" --yes - `DryRun`：写操作输出"将要 POST/PATCH/DELETE 的 pivot 请求模板"+ 预估输出尺寸（行数 × 列数）。 - `Execute`：写后调用 `+pivot-list --pivot-table-id ` 回读 + `+csv-get` 抽样读透视产物，envelope.meta.verification 给出实际输出尺寸 + 总计行位置。 -> ⚠️ pivot 输出包含总计 / 小计行；后续 chart 引用 pivot 时，`data_range` 必须排除这些行（见 `lark-sheets-chart` 决策段）。 +> ⚠️ pivot 输出包含总计 / 小计行；后续 chart 引用 pivot 时，`snapshot.data.refs` 必须排除这些行（见 `lark-sheets-chart` 的「⚠️ chart 数据源引用 pivot 时必须排除总计行」段）。 diff --git a/skills/lark-sheets/references/lark-sheets-range-operations.md b/skills/lark-sheets/references/lark-sheets-range-operations.md index 94ae8593b..77527029b 100644 --- a/skills/lark-sheets/references/lark-sheets-range-operations.md +++ b/skills/lark-sheets/references/lark-sheets-range-operations.md @@ -262,6 +262,6 @@ lark-cli sheets +range-sort --url "..." --sheet-id "$SID" --range "A1:E100" --ha ### Validate / DryRun / Execute 约束 -- `Validate`：XOR 公共四件套；`+cells-clear` 强制 `--yes` 或 `--dry-run`；`+range-*` 校验源 / 目标 range 在同一 spreadsheet；`+range-sort` 的 `--sort-keys` 必须合法 JSON 数组且 col 都在 `--range` 内；`+rows-resize` / `+cols-resize` 的 `--type` 必填，`--type pixel` 时 `--size` 必填、其它 type 时 `--size` 应省略；`+cols-resize.--type` 不接受 `auto`（只行高支持自适应）。 +- `Validate`：XOR 公共四件套；`+cells-clear` 强制 `--yes` 或 `--dry-run`；`+range-*` 校验源 / 目标 range 在同一 spreadsheet；`+range-sort` 的 `--sort-keys` 必须合法 JSON 数组且 col 都在 `--range` 内；`+rows-resize` / `+cols-resize` 的 `--type` 必填，`--type pixel` 时 `--size` 必填、其它 type 时 `--size` 会被忽略（传了无害）；`+cols-resize.--type` 不接受 `auto`（只行高支持自适应）。 - `DryRun`：所有写操作输出"将要 PATCH 的 range + 受影响 cell 数估算"。 - `Execute`：写后调用 `+cells-get --range <影响范围>` 抽样回读对比，envelope.meta.verification 沉淀对比结果。 diff --git a/skills/lark-sheets/references/lark-sheets-read-data.md b/skills/lark-sheets/references/lark-sheets-read-data.md index 9bed8b3d9..71a754e12 100644 --- a/skills/lark-sheets/references/lark-sheets-read-data.md +++ b/skills/lark-sheets/references/lark-sheets-read-data.md @@ -21,10 +21,12 @@ |---------|----------------|---------|------| | 快速查看纯值数据、批量处理 | `+csv-get` | 对话上下文 | 返回 CSV 文本；大表请按 `--range` 行窗口分批读（单次返回量由 `--max-chars` 自动兜底，截断时看 `has_more`） | | 查看公式、样式、批注、数据验证 | `+cells-get` | 对话上下文 | 返回单元格完整信息，token 开销较大 | +| 查看某区域的下拉框（数据验证）选项 | `+dropdown-get` | 对话上下文 | 返回该 A1 范围已配置的下拉列表选项 | **选择原则**： - 只看值或做数据处理 → `+csv-get`；大表分批读取，避免一次拉全表撑爆上下文 - 需要公式/样式/批注 → `+cells-get` +- 只想知道某区域下拉框有哪些选项 → `+dropdown-get` ⚠️ 超大数据请走"`+csv-get` 按 `--range` 行窗口（如 `A1:Z500` / `A501:Z1000` …）分批读到本地文件 + 本地脚本处理 + `+csv-put` 分批回写"。 diff --git a/skills/lark-sheets/references/lark-sheets-search-replace.md b/skills/lark-sheets/references/lark-sheets-search-replace.md index 473e7dc12..2272e9a06 100644 --- a/skills/lark-sheets/references/lark-sheets-search-replace.md +++ b/skills/lark-sheets/references/lark-sheets-search-replace.md @@ -15,7 +15,7 @@ | 操作需求 | 使用工具 | 说明 | |---------|---------|------| | 搜索/定位文本 | `+cells-search` | 返回匹配的单元格位置，支持正则、精确匹配等 | -| 查找并替换文本 | `+cells-replace` | 批量替换文本，支持正则捕获组引用 | +| 查找并替换文本 | `+cells-replace` | 批量替换文本；`--regex` 模式下 `--replacement` 可用 `$1`、`$2` 引用 `--find` 的捕获组 | **常见配置错误（必须注意）**： - **不要把操作动词当搜索词**：用户说"汇总金额"是一个操作动作（求和），不是要搜索"汇总金额"这个文本。只有当确实需要定位某个文本值的位置时才用 `+cells-search` @@ -95,6 +95,10 @@ lark-cli sheets +cells-replace --url "https://example.feishu.cn/sheets/shtXXX" \ # 确认后执行 lark-cli sheets +cells-replace --url "https://example.feishu.cn/sheets/shtXXX" \ --sheet-name "Sheet1" --find "v1" --replacement "v2" + +# 正则捕获组：把 "2026-03" 重排成 "03/2026"（$1/$2 引用 --find 的捕获组） +lark-cli sheets +cells-replace --url "https://example.feishu.cn/sheets/shtXXX" \ + --sheet-name "Sheet1" --regex --find "(\\d{4})-(\\d{2})" --replacement "$2/$1" --dry-run ``` > `+cells-replace` 虽然 Risk = write，但范围大或正则错可能改一堆。**强烈推荐工作流**：先 `+cells-search` 看匹配数，再 `+cells-replace --dry-run` 预览，最后真正执行。 diff --git a/skills/lark-sheets/references/lark-sheets-sheet-structure.md b/skills/lark-sheets/references/lark-sheets-sheet-structure.md index 4fccee7d3..1a8636b50 100644 --- a/skills/lark-sheets/references/lark-sheets-sheet-structure.md +++ b/skills/lark-sheets/references/lark-sheets-sheet-structure.md @@ -129,7 +129,7 @@ _公共四件套 · 系统：`--dry-run`_ | `--dimension` | string | required | 维度方向（行或列）（可选值：`row` / `column`） | | `--start` | int | required | 起始位置（0-based） | | `--end` | int | required | 结束位置（exclusive） | -| `--depth` | int | optional | 嵌套层级（`+dim-group` 用），默认 1 | +| `--depth` | int | optional | 嵌套分组的层级（创建到第几层），默认 1 | | `--group-state` | string | optional | 分组初始展开状态（可选值：`expand` / `fold`）（默认 `expand`） | ### `+dim-ungroup` @@ -141,7 +141,7 @@ _公共四件套 · 系统：`--dry-run`_ | `--dimension` | string | required | 维度方向（行或列）（可选值：`row` / `column`） | | `--start` | int | required | 起始位置（0-based） | | `--end` | int | required | 结束位置（exclusive） | -| `--depth` | int | optional | 嵌套层级（`+dim-group` 用），默认 1 | +| `--depth` | int | optional | 要取消的分组层级，默认 1（最外层） | ### `+dim-move` @@ -205,6 +205,6 @@ lark-cli sheets +dim-freeze --url "..." --sheet-id "$SID" --dimension row --coun ### Validate / DryRun / Execute 约束 -- `Validate`：XOR 公共四件套；`--start ≤ --end`；`+dim-delete` 强制 `--yes` 或 `--dry-run`；`+rows-resize` / `+cols-resize` 的 `--type` 必填，`--type pixel` 时 `--size` 必填、其它 type 时 `--size` 应省略；`+rows-resize` / `+cols-resize` 的行 vs 列 `--type` 差异详见 `lark-sheets-range-operations.md`。 +- `Validate`：XOR 公共四件套；`--start ≤ --end`；`+dim-delete` 强制 `--yes` 或 `--dry-run`；`+rows-resize` / `+cols-resize` 的 `--type` 必填，`--type pixel` 时 `--size` 必填、其它 type 时 `--size` 会被忽略（传了无害）；`+rows-resize` / `+cols-resize` 的行 vs 列 `--type` 差异详见 `lark-sheets-range-operations.md`。 - `DryRun`：写操作输出"将要 PATCH 的 dimension 区间 + 目标参数"。 - `Execute`：写后自动调用 `+sheet-info --include row_heights,col_widths,hidden_rows,hidden_cols,groups,frozen` 回读对比，envelope.meta.verification 给出受影响的范围。 diff --git a/skills/lark-sheets/references/lark-sheets-sparkline.md b/skills/lark-sheets/references/lark-sheets-sparkline.md index cbe5ba675..8eadd0978 100644 --- a/skills/lark-sheets/references/lark-sheets-sparkline.md +++ b/skills/lark-sheets/references/lark-sheets-sparkline.md @@ -82,8 +82,7 @@ _创建/更新/部分删除的迷你图属性_ > **何时需要先 `+sparkline-list`：** > - `+sparkline-update`：**总是**需要——拿到组内每一项的 `sparkline_id`，回填到 `properties.sparklines[i]`，server 用它做映射。 -> - `+sparkline-delete` 删单个 / 部分项：需要——同样要把 `sparkline_id` 填进 `properties.sparklines[i]`。 -> - `+sparkline-delete` 删整组：**不需要** `sparkline_id`，只要 `--group-id`。 +> - `+sparkline-delete`：**不需要** `sparkline_id`——CLI 仅支持按 `--group-id` 整组删除（该 shortcut 没有 `--properties`）。 ### `+sparkline-list` @@ -131,19 +130,11 @@ lark-cli sheets +sparkline-update --url "..." --sheet-id "$SID" --group-id "grpA ### `+sparkline-delete` -> 两种模式： -> - **删整组**：不传 `--properties`，仅 `--group-id`。删完后该 group 整个清掉。 -> - **删单个 / 部分项**：传 `--properties '{"sparklines":[{"sparkline_id":"..."},...]}'`，每项必须含 `sparkline_id`；删指定项后组内为空会自动清理 group。 -> -> 强制 `--yes` 或 `--dry-run`；先 `--dry-run` 确认要删的目标。 +> CLI 仅支持**整组删除**：传 `--group-id` 删掉该组全部迷你图。该 shortcut **没有** `--properties`，无法只删组内单项（需求上要"留一部分"时，改用 `+sparkline-update` 重写该组的 `sparklines` 列表，而不是 delete）。强制 `--yes` 或 `--dry-run`；先 `--dry-run` 确认要删的目标组。 ```bash # 删整组 lark-cli sheets +sparkline-delete --url "..." --sheet-id "$SID" --group-id "grpA" --yes - -# 删组内指定项（先 +sparkline-list 拿到 sparkline_id） -lark-cli sheets +sparkline-delete --url "..." --sheet-id "$SID" --group-id "grpA" \ - --properties '{"sparklines":[{"sparkline_id":"sl_1"}]}' --yes ``` ### Validate / DryRun / Execute 约束 @@ -151,8 +142,8 @@ lark-cli sheets +sparkline-delete --url "..." --sheet-id "$SID" --group-id "grpA - `Validate`： - XOR 公共四件套；`+sparkline-{update,delete}` 必须 `--group-id`。 - **`+sparkline-update`**：当 `properties.sparklines` 非空时，每一项必须含 `sparkline_id`（CLI 预检，错误信息会指回 `+sparkline-list`，避免命中服务端的不可读拒绝）；只传 `properties.config`（config-only update）合法、不触发 sparkline_id 检查。 - - **`+sparkline-delete`**：不传 `--properties` = 删整组（合法路径，不需要 sparkline_id）；传 `properties.sparklines` 时每项必须含 `sparkline_id`（server contract；CLI 本地暂未预检 delete 的 partial-item 分支，缺 id 会到 server 端才被拒）。 - - `--properties` 顶层只接 `config`（同组共享样式）和 `sparklines`（迷你图项数组）；`+sparkline-create` 要求每个 `sparklines[i]` 含 `position` 与 `source`（或 `source_range`，二选一）。 + - **`+sparkline-delete`**：只接 `--group-id`（整组删除），**没有** `--properties`，无法删组内单项。 + - `--properties`（仅 `+sparkline-create` / `+sparkline-update`）顶层只接 `config`（同组共享样式）和 `sparklines`（迷你图项数组）；`+sparkline-create` 要求每个 `sparklines[i]` 含 `position` 与 `source`（或 `source_range`，二选一）。 - `+sparkline-delete` 强制 `--yes` 或 `--dry-run`。 - `DryRun`：写操作输出"将要 POST/PATCH/DELETE 的 sparkline group 请求模板"。 - `Execute`：写后调用 `+sparkline-list --group-id ` 回读，envelope.meta.verification 给出 `config` / `sparklines` 字段级对比。 diff --git a/skills/lark-sheets/references/lark-sheets-visual-standards.md b/skills/lark-sheets/references/lark-sheets-visual-standards.md index 3cc284540..df00c7679 100644 --- a/skills/lark-sheets/references/lark-sheets-visual-standards.md +++ b/skills/lark-sheets/references/lark-sheets-visual-standards.md @@ -17,7 +17,7 @@ 2. **对齐方式**：文本列左对齐、数值 / 货币 / 百分比列右对齐、日期 / 分类列居中；垂直方向统一居中 3. **数值格式**：每列统一小数位 + 千分位（用 `number_format`）；金额列统一货币符号；同一列内**禁止**出现 0 位 / 1 位 / 2 位小数混杂 4. **边框**：覆盖范围按上方「美化范围必须覆盖所有用户语义目标」规则（含汇总 / 总计 / 表尾说明行），内外框线清晰 -5. **列宽 + 行高 + 自动换行**：详细规则见 `lark-sheets-range-operations` 的「写入后列宽自适应」章节（按最长字符数扩列宽 / 长文本设置 `wrap=true` + 调高行高 / 长数字设置 `number_format` 防科学计数法） +5. **列宽 + 行高 + 自动换行**：详细规则见 `lark-sheets-range-operations` 的「写入后列宽自适应」章节（按最长字符数扩列宽 / 长文本设置 `cell_styles.word_wrap="auto-wrap"` + 调高行高 / 长数字设置 `number_format` 防科学计数法） **差异化标注场景**：用户要求"重复行 / 异常值 / 重要项视觉区分"时，标注列 / 行必须设置与普通数据**显著不同**的 `cell_styles`（背景色 + 加粗 + 字体色至少改一项），不能与普通数据格式完全一致。 @@ -135,7 +135,7 @@ - 若倒数两行背景色不同（如 #FFFFFF 与 #F3F4F6），新行按奇偶延续，不要固定一个色 - `border_styles` 最易遗漏（四边都要复制），否则新行会缺框线 -> 具体采样调用与工作流见 `lark-sheets-read-data` 的「格式采样工作流（新增行时继承原有格式）」章节。 +> 具体采样调用（用 `+cells-get` 读源行 `cell_styles` + `border_styles`、`+sheet-info` 读行高合并）见 `lark-sheets-write-cells` 的「新增列 / 新增行的样式继承」章节。 #### 2B. 基于模板区域的修改（copy 保留所有格式） diff --git a/skills/lark-sheets/references/lark-sheets-write-cells.md b/skills/lark-sheets/references/lark-sheets-write-cells.md index 5f1718f51..935932f65 100644 --- a/skills/lark-sheets/references/lark-sheets-write-cells.md +++ b/skills/lark-sheets/references/lark-sheets-write-cells.md @@ -109,7 +109,7 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl - **语义信号**（二选一）：用户 prompt 含"合计/汇总/总计/统计/各科平均分/最下面加一行算…/底部总计"等意图词；或上下文明确是"表尾追加一行做聚合" - **结构信号**：新行全行都在做聚合（含 `=SUM/AVERAGE/COUNT/MAX/MIN/SUBTOTAL(...)`，支持 IFERROR 包裹），**不是**单个 cell 算个参考值或每行都算的派生列 -满足上述时，**不要在本 skill 里猜样式**，直接去读 `lark-sheets-visual-standards` 的"汇总行规范"章节，按那里的规则配齐 `font.bold / horizontal_alignment / background_color / border_styles`。 +满足上述时，**不要在本 skill 里猜样式**，直接去读 `lark-sheets-visual-standards` 的「场景一 → 1A. 添加汇总行 / 表头行」章节，按那里的样式要点配齐 `font.bold / horizontal_alignment / background_color / border_styles`。 反例（**不是**汇总行，禁止自动加粗）： - 用户说"在 H5 帮我算个 AVERAGE 参考"→ 单 cell 计算 @@ -132,7 +132,7 @@ Step 2: 再用 `+cells-set` 单独写具体 value/formula（不再传样式， `+cells-set` — range="C11:F11", cells=[[{formula: "=AVERAGE(C2:C10)"}, {formula: "=AVERAGE(D2:D10)"}, ...]] ``` -⚠️ **Step 1 `cell_styles` 禁止留空**：只铺 border、不铺 `cell_styles`，等于新行从格式上"裸奔"——没字体、没对齐、没背景色。如果新行是汇总行，这意味着 bold 丢失，用户感受"没做样式"。Step 1 的 `cell_styles` 要么继承源区块（`+cells-get` 读相邻已有行样式后复用），要么按汇总行规范（见 `lark-sheets-visual-standards`）配齐。 +⚠️ **Step 1 `cell_styles` 禁止留空**：只铺 border、不铺 `cell_styles`，等于新行从格式上"裸奔"——没字体、没对齐、没背景色。如果新行是汇总行，这意味着 bold 丢失，用户感受"没做样式"。Step 1 的 `cell_styles` 要么继承源区块（`+cells-get` 读相邻已有行样式后复用），要么按汇总行样式要点（见 `lark-sheets-visual-standards` 的「场景一 → 1A. 添加汇总行 / 表头行」）配齐。 **做法 B：一次写入但每个 cell 都显式带样式** @@ -295,9 +295,9 @@ _列表选项_ 示例： ```bash -# 纯值（数组形态） +# 纯值（数组形态）；默认即覆盖非空 cell，无需显式传 --allow-overwrite lark-cli sheets +cells-set --url "https://example.feishu.cn/sheets/shtXXX" \ - --sheet-name "Sheet1" --range "A1:B2" --allow-overwrite \ + --sheet-name "Sheet1" --range "A1:B2" \ --cells '[[{"value":"name"},{"value":"score"}],[{"value":"alice"},{"value":95}]]' # 富 cell（公式 + 样式，cells 是二维矩阵每元素一个 cell schema）