diff --git a/skills/lark-sheets/SKILL.md b/skills/lark-sheets/SKILL.md index b00c35ad..290eafd6 100644 --- a/skills/lark-sheets/SKILL.md +++ b/skills/lark-sheets/SKILL.md @@ -81,7 +81,7 @@ metadata: - ⚠️ **`/wiki/` 知识库链接不能直接当表格定位用**：wiki 链接背后可能是电子表格，也可能是文档 / 多维表格等其它类型，`--url` **不会**自动把 wiki token 解析成 spreadsheet token，直接传会失败。必须先把它解析成真实文档 token —— `lark-cli wiki +node-get --node-token ""`，确认返回的 `obj_type` 为 `sheet` 后，取其 `obj_token` 作为 `--spreadsheet-token` 传入（解析细节见 [`../lark-wiki/SKILL.md`](../lark-wiki/SKILL.md)）。 - **例外**：`+workbook-create` 是新建一个还不存在的表格，**不接受任何 spreadsheet / sheet 定位 flag**（只有 `--title` / `--folder-token` / `--headers` / `--values`）。 2. **sheet 定位（公共四件套 shortcut 必填）**：`--sheet-id` 与 `--sheet-name` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --sheet-id or --sheet-name`。 - - ⚠️ **`--range` 里的 `Sheet1!` 前缀不能替代 sheet 定位**：即使写了 `--range "Sheet1!A1:B2"`，仍**必须**额外传 `--sheet-id` 或 `--sheet-name`，否则照样报上面的错。 + - ⚠️ **`--range` 里的 `Sheet1!` 前缀不能替代 sheet 定位**：即使写了 `--range "'Sheet1'!A1:B2"`，仍**必须**额外传 `--sheet-id` 或 `--sheet-name`，否则照样报上面的错。 - **例外**：徽章标为 `_公共：URL/token（无 sheet 定位）…_` 的 shortcut（如 `+workbook-info` / `+workbook-export` / `+batch-update` / `+dropdown-get|update|delete` / `+cells-batch-set-style` / `+cells-batch-clear` / `+sheet-create`）**不接受也不需要** sheet 定位，只给一组 spreadsheet 定位即可。 | Flag | Type | 必填 | 说明 | @@ -127,3 +127,35 @@ lark-cli sheets +cells-set --url "..." --sheet-name "Sheet1" --range "A1:B2" --c ``` **`@file` 接绝对路径会被拒，且被拒后不要照报错提示做。** `@file` 出于安全只接受 cwd 下的相对路径，传 `@/tmp/cells.json` 这类绝对路径或 cwd 之外的路径会被拒。此时报错会建议"先 cd 到目标目录，或改用相对路径"——**两条都不要照做**：cd 过去、或把临时文件写进用户项目目录，都会污染工作目录。正解是改用 stdin（`-- - < 文件`）。 + +## Shell 调用注意事项：A1 reference 含 `!` 的引号选择 + +A1 表示法的 sheet 前缀（`Sheet1!A1`）里那个 `!` 在 interactive bash（豆包 ShellExec / 任何带 history 的 shell）下是**历史展开触发字符**。`!Word` 形式会被 bash 当成"展开最近以 Word 开头的历史命令"，如果没有匹配就报： + +``` +bash: !A1: event not found +``` + +——命令根本到不了 lark-cli。**double-quote 内 `!` 仍会触发 histexpand**；只有 single-quote 或显式关闭 history expansion 才能让 `!` 字面通过。 + +**对 agent 的可执行规则**： + +| 场景 | 推荐写法 | 说明 | +|---|---|---| +| 一次性调用，sheet 名无特殊字符 | `--source 'Sheet1!A1:D100'` | shell single-quote 整段包住，A1 内部不带单引号也合法 | +| 一次性调用，sheet 名含 `-` / 空格 / 非 ASCII | `set +H; lark-cli sheets … --source "'Sales-Q1'!A1:D100"` | 先 `set +H` 关 histexpand，然后 double-quote 外层 + A1 内部 single-quote 包裹 sheet 名 | +| 该 shell session 后续会跑大量 lark-cli 命令 | 在 session 第一行执行 `set +H`，后续全程 double-quote 即可 | 一次性配置，减少每条命令的引号心智 | +| 实在写不对 | `+sheet-rename --title ` 先把含特殊字符的 sheet 改成 plain 名 | U046 模型走通的兜底路径，但要权衡是否会破坏其它引用 | + +**反模式**： + +- ❌ `--source "Sheet1!A1:D100"`（double-quote + 未关 histexpand）—— `!A1` 被吃掉，命令不达 lark-cli +- ❌ `--source 'Sales-Q1'\''!A1:D100'`（缺一节 `'\''`）—— shell 把 `Sales-Q1` 当字符串、`!A1` 又触发 histexpand +- ❌ `--source "'Sheet1'!A1"`（未 `set +H` 的 double-quote）—— A1 内部包是对的、但 shell 层的 `!A1` 还会被展开 + +**注意区分两层引号**： + +- **shell 层引号**（bash 的 `"..."` / `'...'`）：决定 bash 是否做参数展开、变量替换、history expansion +- **A1 层引号**（A1 reference 字符串里的 `'Sheet name'!A1`）：Excel/Sheets 标准，sheet 名含 `-` / 空格 / 非 ASCII 字符时**必须**单引号包裹；plain 名时可选（建议总是包裹以保持一致） + +bash single-quote 不可嵌套，要在 single-quote 中再放 single-quote，用序列 `'\''`（关闭外层 single-quote → 转义一个 single-quote → 重开外层 single-quote）；嫌麻烦就用 `set +H` 方案。 diff --git a/skills/lark-sheets/references/lark-sheets-chart.md b/skills/lark-sheets/references/lark-sheets-chart.md index f575cade..3c242f9e 100644 --- a/skills/lark-sheets/references/lark-sheets-chart.md +++ b/skills/lark-sheets/references/lark-sheets-chart.md @@ -53,7 +53,7 @@ > **正确做法**： > 1. 在 `data` 下显式设置 `"headerMode": "detached"`； > 2. `refs` **只覆盖该子集的纯数据**，不要向上/向左多带 1 行/列，也不要把全局表头整段并进来（否则会把其它分组的数据混进图）； -> 3. **`nameRef` 必填**：给 `dim1.serie.nameRef` 写真正表头中"类别名"那一格的 A1 引用（如 `Sheet2!A1`），给每个 `dim2.series[i].nameRef` 写对应数值列的 A1 引用（如 `Sheet2!C1`、`Sheet2!D1`）。任一缺失会被校验拦下并报 `headerMode=detached requires ... nameRef`； +> 3. **`nameRef` 必填**：给 `dim1.serie.nameRef` 写真正表头中"类别名"那一格的 A1 引用（如 `'Sheet2'!A1`，sheet 名按 A1 标准单引号包裹），给每个 `dim2.series[i].nameRef` 写对应数值列的 A1 引用（如 `'Sheet2'!C1`、`'Sheet2'!D1`）。任一缺失会被校验拦下并报 `headerMode=detached requires ... nameRef`； > 4. `refs[i].value` 必须是单元格或普通矩形范围（CELL / NORMAL），不接受整行/整列/开区间；`direction='column'` 时起始行必须 > 0，`direction='row'` 时起始列必须 > 0； > 5. `index` 仍按 `refs` 内的列/行号填，从 1 开始。 > @@ -173,7 +173,7 @@ lark-cli sheets +chart-create --url "https://example.feishu.cn/sheets/shtXXX" \ "size":{"width":600,"height":400}, "snapshot":{ "data":{ - "refs":[{"value":"Sheet1!A1:B10"}], + "refs":[{"value":"'Sheet1'!A1:B10"}], "dim1":{"serie":{"index":1}}, "dim2":{"series":[{"index":2}]} }, @@ -203,7 +203,7 @@ lark-cli sheets +chart-create --url "..." --sheet-name "Sheet1" --properties '{ }] }}, "data":{ - "refs":[{"value":"Sheet1!A1:B11"}], + "refs":[{"value":"'Sheet1'!A1:B11"}], "dim1":{"serie":{"index":1,"aggregate":true}}, "dim2":{"series":[{"index":2,"aggregateType":"sum"}]} } @@ -225,11 +225,11 @@ lark-cli sheets +chart-create --url "..." --sheet-name "Sheet2" --properties '{ "data":{ "headerMode":"detached", "direction":"column", - "refs":[{"value":"Sheet2!A11:D17"}], - "dim1":{"serie":{"index":1,"nameRef":"Sheet2!A1"}}, + "refs":[{"value":"'Sheet2'!A11:D17"}], + "dim1":{"serie":{"index":1,"nameRef":"'Sheet2'!A1"}}, "dim2":{"series":[ - {"index":3,"nameRef":"Sheet2!C1"}, - {"index":4,"nameRef":"Sheet2!D1"} + {"index":3,"nameRef":"'Sheet2'!C1"}, + {"index":4,"nameRef":"'Sheet2'!D1"} ]} } } @@ -250,9 +250,9 @@ lark-cli sheets +chart-create --url "..." --sheet-name "Sheet2" --properties '{ ```jsonc // 错误 1：refs 含全局表头但跨段 —— 多个区域被混进同一张图 -{"data":{"refs":[{"value":"Sheet!A1:E17"}], ... }} // 华东图混进华北 8 行 +{"data":{"refs":[{"value":"'Sheet'!A1:E17"}], ... }} // 华东图混进华北 8 行 // 错误 2：inline + refs 只取数据段、不写 detached/nameRef —— 图例显示成具体数据值 -{"data":{"refs":[{"value":"Sheet!A10:E17"}],"dim1":{"serie":{"index":1}}, ... }} +{"data":{"refs":[{"value":"'Sheet'!A10:E17"}],"dim1":{"serie":{"index":1}}, ... }} ``` ✅ 正确模式：3 张图各自 detached、refs 干净不重叠： @@ -261,15 +261,15 @@ lark-cli sheets +chart-create --url "..." --sheet-name "Sheet2" --properties '{ // 图 1：华北 {"data":{ "headerMode":"detached","direction":"column", - "refs":[{"value":"Sheet!A2:E9"}], - "dim1":{"serie":{"index":1,"nameRef":"Sheet!A1"}}, + "refs":[{"value":"'Sheet'!A2:E9"}], + "dim1":{"serie":{"index":1,"nameRef":"'Sheet'!A1"}}, "dim2":{"series":[ - {"index":3,"nameRef":"Sheet!C1"}, - {"index":4,"nameRef":"Sheet!D1"} + {"index":3,"nameRef":"'Sheet'!C1"}, + {"index":4,"nameRef":"'Sheet'!D1"} ]} }} -// 图 2：华东 —— refs 改 Sheet!A10:E17，其余同上 -// 图 3：华南 —— refs 改 Sheet!A18:E25，其余同上 +// 图 2：华东 —— refs 改 'Sheet'!A10:E17，其余同上 +// 图 3：华南 —— refs 改 'Sheet'!A18:E25，其余同上 ``` > `--properties` JSON 关键字段： diff --git a/skills/lark-sheets/references/lark-sheets-pivot-table.md b/skills/lark-sheets/references/lark-sheets-pivot-table.md index 3a8f1caf..4b8b524c 100644 --- a/skills/lark-sheets/references/lark-sheets-pivot-table.md +++ b/skills/lark-sheets/references/lark-sheets-pivot-table.md @@ -121,7 +121,7 @@ lark-cli sheets +pivot-list --url "..." --sheet-id "$SID" > 数据源 `--source` 必须从表头行开始；空行 / 汇总行会被当作数据参与聚合，需提前用 `+csv-get` 确认起止边界。`--source` 和 `--range` 是独立 flag（不要再放 `--properties`）；`rows` / `columns` / `values` 等数组字段走 `--properties`。 > > **先理清 `+pivot-create` 上 4 个位置类入参（语义不同，别混）**： -> - `--source`（**必填**）：**源数据**区域，须自带 `Sheet!` 前缀（如 `Sheet1!A1:D100`）。源 sheet 的名字在 `--source` 字符串里，**不**通过单独 flag 传。 +> - `--source`（**必填**）：**源数据**区域，须自带 `Sheet!` 前缀（如 `'Sheet1'!A1:D100`，sheet 名按 A1 标准单引号包裹）。源 sheet 的名字在 `--source` 字符串里，**不**通过单独 flag 传。 > - `--sheet-id` / `--sheet-name`：**透视表的落点 sheet**（即产物放哪张子表）。两个互斥（最多传一个），都不传时后端自动新建子表存放产物（强烈推荐）。**注意：跟其它 shortcut 不同，这里 `--sheet-id` / `--sheet-name` 表达的不是"数据源所在 sheet"而是"产物落点 sheet"**。 > - `--target-position`（可选，A1 表示法，默认 `A1`）：落点 sheet 内的起始 cell，映射到顶层 `target_position`。 > - `--range`（可选，A1 单值，仅 create 生效）：跟 `--target-position` 表达同一意图但映射到 `properties.range`，**两者不要同时给**。 @@ -136,13 +136,18 @@ lark-cli sheets +pivot-list --url "..." --sheet-id "$SID" ```bash # 策略 1（强烈推荐）：不传任何落点 flag → 后端自动新建子表，零覆盖风险 lark-cli sheets +pivot-create --url "..." \ - --source "Sheet1!A1:D100" --properties @pivot.json + --source "'Sheet1'!A1:D100" --properties @pivot.json # 策略 2：落进指定的已有目标子表（注意目标 sheet ≠ 源 sheet，否则要配 --target-position 避开源数据） lark-cli sheets +pivot-create --url "..." \ - --source "Sheet1!A1:D100" --sheet-id "$DEST_SID" --target-position "A1" --properties @pivot.json + --source "'Sheet1'!A1:D100" --sheet-id "$DEST_SID" --target-position "A1" --properties @pivot.json ``` +> ⚠️ 上面 bash 示例的 `--source` 用了双引号，在 interactive bash（含豆包 ShellExec）下 `!` 会触发 history expansion 报 `bash: !A1: event not found`。**实际跑命令时**用以下任一种写法： +> - **首选**：命令最前面加 `set +H;` 关掉 history expansion，全程 double-quote 不踩坑 +> - **次选**：`--source` 整体改 shell single-quote，但 sheet 名内的 A1 单引号需要 `'\''` 转义：`--source ''\''Sheet1'\''!A1:D100'` +> - **应急**：先 `+sheet-rename --title ` 把含 `-` / 空格的 sheet 名改成 plain 名（U046 模型最终走通的兜底路径） + ### `+pivot-update` > 不允许改 `--source` / `--range`（透视表创建后位置/数据源固定）；只能用 `--properties` 改 rows / columns / values / filters 等。先 `+pivot-list --pivot-table-id ` 回读再 patch，避免漏字段。 diff --git a/skills/lark-sheets/references/lark-sheets-sparkline.md b/skills/lark-sheets/references/lark-sheets-sparkline.md index 6c2bea74..090dbcda 100644 --- a/skills/lark-sheets/references/lark-sheets-sparkline.md +++ b/skills/lark-sheets/references/lark-sheets-sparkline.md @@ -108,8 +108,8 @@ lark-cli sheets +sparkline-create --url "..." --sheet-id "$SID" --properties @sp { "config": { "line_width": 2 }, "sparklines": [ - {"position": {"row": 1, "col": "F"}, "source": "Sheet1!A2:E2"}, - {"position": {"row": 2, "col": "F"}, "source": "Sheet1!A3:E3"} + {"position": {"row": 1, "col": "F"}, "source": "'Sheet1'!A2:E2"}, + {"position": {"row": 2, "col": "F"}, "source": "'Sheet1'!A3:E3"} ] } ``` @@ -122,8 +122,8 @@ lark-cli sheets +sparkline-create --url "..." --sheet-id "$SID" --properties @sp # 假设 +sparkline-list 已返回 group_id=grpA，组内 sparkline_id=sl_1 / sl_2 lark-cli sheets +sparkline-update --url "..." --sheet-id "$SID" --group-id "grpA" --properties '{ "sparklines": [ - {"sparkline_id":"sl_1","source":"Sheet1!A2:A20"}, - {"sparkline_id":"sl_2","source":"Sheet1!B2:B20"} + {"sparkline_id":"sl_1","source":"'Sheet1'!A2:A20"}, + {"sparkline_id":"sl_2","source":"'Sheet1'!B2:B20"} ] }' ``` diff --git a/skills/lark-sheets/references/lark-sheets-write-cells.md b/skills/lark-sheets/references/lark-sheets-write-cells.md index d19f2feb..3fe4926f 100644 --- a/skills/lark-sheets/references/lark-sheets-write-cells.md +++ b/skills/lark-sheets/references/lark-sheets-write-cells.md @@ -143,9 +143,9 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl | flag | 选项来源 | 适用场景 | |---|---|---| | `--options '["a","b","c"]'` | 写在命令里的固定列表 | 选项集是常量、不需要事后维护 | -| `--source-range 'Sheet1!T1:T3'` | 已有单元格里的值 | 选项要跟数据动态同步；想维护一张「枚举值」列后多处引用 | +| `--source-range '''Sheet1''!T1:T3'` | 已有单元格里的值 | 选项要跟数据动态同步；想维护一张「枚举值」列后多处引用 | -两个 flag **必须传一个、且只能传一个**——同时传或都不传，CLI 会立刻报错。`--source-range` 用 A1 + sheet 前缀写法（如 `Sheet1!T1:T3`），可以指同 sheet 也可以指其它 sheet（如 `Refs!A1:A10`）。 +两个 flag **必须传一个、且只能传一个**——同时传或都不传，CLI 会立刻报错。`--source-range` 用 A1 + sheet 前缀写法（如 `'Sheet1'!T1:T3`，sheet 名按 A1 标准单引号包裹），可以指同 sheet 也可以指其它 sheet（如 `'Refs'!A1:A10`）。 ### 配色：默认即上色，三种意图三条线 @@ -182,16 +182,18 @@ lark-cli sheets +dropdown-set \ --colors '["#bff7d9","#FFE699","#bacefd"]' ``` -**`--source-range` 模式**（先在 `Sheet1!T1:T3` 维护「男/女/保密」三行，再让 `B2:B21` 引用它）： +**`--source-range` 模式**（先在 `'Sheet1'!T1:T3` 维护「男/女/保密」三行，再让 `B2:B21` 引用它）： ``` lark-cli sheets +dropdown-set \ --url https://... --sheet-id \ --range B2:B21 \ - --source-range 'Sheet1!T1:T3' \ + --source-range ''\''Sheet1'\''!T1:T3' \ --colors '["#cce8ff","#ffd6e7","#e6e6e6"]' ``` +> ⚠️ `--source-range` 的 shell 包法：上面用 `''\''Sheet1'\''!T1:T3'` 是为了在 shell single-quote 外层中嵌入 A1 内部 single-quote（防 bash 历史展开 `!T1`）。等效更简单写法：命令最前加 `set +H;` 关 history expansion，然后 `--source-range "'Sheet1'!T1:T3"`。详见 SKILL.md「Shell 调用注意事项」。 + **纯白下拉**（明确告诉用户"不要彩色"时才用）： ```