docs(sheets): wrap A1 sheet names in handwritten examples + bash histexpand guide

Synced from spec. Affects 4 reference md (chart / pivot-table / sparkline /
write-cells) and SKILL.md.

In addition to wrapping sheet names in single quotes in all remaining
handwritten examples (covers chart refs.value / nameRef, sparkline source,
write-cells --source-range, pivot-create narrative), SKILL.md gains a new
"Shell quoting for A1 references with !" section.

The new section addresses bash history expansion: in interactive bash
(e.g., ShellExec sandbox), unescaped `!Word` after `"..."` triggers
`bash: !A1: event not found`, dropping the command before lark-cli sees
it. The section gives 4 quoting strategies (shell single-quote outer,
`set +H` prefix, mixed quoting, sheet-rename fallback) and an anti-pattern
list.

Affected files:
- skills/lark-sheets/SKILL.md (new section)
- skills/lark-sheets/references/lark-sheets-chart.md
- skills/lark-sheets/references/lark-sheets-pivot-table.md
- skills/lark-sheets/references/lark-sheets-sparkline.md
- skills/lark-sheets/references/lark-sheets-write-cells.md

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 "<wiki 链接或 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（`--<flag> - < 文件`）。
+
+## 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 <ASCII 名>` 先把含特殊字符的 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` 方案。

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"}],
+      "refs":[{"value":"'Sheet2'!A11:D17"}],
-      "dim1":{"serie":{"index":1,"nameRef":"Sheet2!A1"}},
+      "dim1":{"serie":{"index":1,"nameRef":"'Sheet2'!A1"}},
       "dim2":{"series":[
-        {"index":3,"nameRef":"Sheet2!C1"},
+        {"index":3,"nameRef":"'Sheet2'!C1"},
-        {"index":4,"nameRef":"Sheet2!D1"}
+        {"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"}],
+  "refs":[{"value":"'Sheet'!A2:E9"}],
-  "dim1":{"serie":{"index":1,"nameRef":"Sheet!A1"}},
+  "dim1":{"serie":{"index":1,"nameRef":"'Sheet'!A1"}},
   "dim2":{"series":[
-    {"index":3,"nameRef":"Sheet!C1"},
+    {"index":3,"nameRef":"'Sheet'!C1"},
-    {"index":4,"nameRef":"Sheet!D1"}
+    {"index":4,"nameRef":"'Sheet'!D1"}
   ]}
 }}
-// 图 2：华东 —— refs 改 Sheet!A10:E17，其余同上
+// 图 2：华东 —— refs 改 'Sheet'!A10:E17，其余同上
-// 图 3：华南 —— refs 改 Sheet!A18:E25，其余同上
+// 图 3：华南 —— refs 改 'Sheet'!A18:E25，其余同上
 ```
 
 > `--properties` JSON 关键字段：

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 <ASCII 名>` 把含 `-` / 空格的 sheet 名改成 plain 名（U046 模型最终走通的兜底路径）
+
 ### `+pivot-update`
 
 > 不允许改 `--source` / `--range`（透视表创建后位置/数据源固定）；只能用 `--properties` 改 rows / columns / values / filters 等。先 `+pivot-list --pivot-table-id <id>` 回读再 patch，避免漏字段。

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": 1, "col": "F"}, "source": "'Sheet1'!A2:E2"},
-    {"position": {"row": 2, "col": "F"}, "source": "Sheet1!A3:E3"}
+    {"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_1","source":"'Sheet1'!A2:A20"},
-    {"sparkline_id":"sl_2","source":"Sheet1!B2:B20"}
+    {"sparkline_id":"sl_2","source":"'Sheet1'!B2:B20"}
   ]
 }'
 ```

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 <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 调用注意事项」。
+
 **纯白下拉**（明确告诉用户"不要彩色"时才用）：
 
 ```