From bdad336cafa257087f4d14bcee36dfd98820503e Mon Sep 17 00:00:00 2001 From: xiongyuanwen-byted Date: Sat, 20 Jun 2026 14:11:02 +0800 Subject: [PATCH] =?UTF-8?q?docs(lark-sheets):=20sync=20from=20spec=20?= =?UTF-8?q?=E2=80=94=20set+H=20=E6=94=B9=E5=8D=95=E5=BC=95=E5=8F=B7=20/=20?= =?UTF-8?q?=E9=80=9F=E6=9F=A5=E8=A1=A8=E8=A1=A5=E8=87=86=E9=80=A0=E5=91=BD?= =?UTF-8?q?=E4=BB=A4=E5=90=8D=20/=20workbook-import=20=E5=BC=95=E5=AF=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/lark-sheets/SKILL.md | 10 +++++----- skills/lark-sheets/references/lark-sheets-workbook.md | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/skills/lark-sheets/SKILL.md b/skills/lark-sheets/SKILL.md index 3ad4dc4c3..15fd68b99 100644 --- a/skills/lark-sheets/SKILL.md +++ b/skills/lark-sheets/SKILL.md @@ -38,8 +38,8 @@ metadata: | 你要做的事 | ✅ 正确写法 | ❌ 不存在（会被 cobra 拒） | | --- | --- | --- | -| 读数据（纯值 / CSV） | `+csv-get`（范围用 `--range`） | — | -| 读值 + 公式 / 样式 / 批注 | `+cells-get --include value,formula,style,comment,data_validation` | `--with-styles`、`--with-merges`、`--include-merged-cells` | +| 读数据（纯值 / CSV） | `+csv-get`（范围用 `--range`） | `+get-range`、`+range-get`、`+cells-read` | +| 读值 + 公式 / 样式 / 批注 | `+cells-get --include value,formula,style,comment,data_validation` | `+get-cell`、`+cell-get`、`--with-styles`、`--with-merges`、`--include-merged-cells` | | 写纯文本值（整块 CSV 平铺，列里没有需保留的数值 / 日期语义） | `+csv-put`（定位用 `--start-cell`，单个左上角锚点格；也接受 `--range` 别名，区间自动取左上角） | — | | 写带类型的数据到**已有**表（列里有数字 / 金额 / 百分比 / 日期 / 计数，要可排序 / 求和 / 入图表 / 透视） | `+table-put`（列显式声明 `type` + `format`，类型保真；来源不限 DataFrame——Counter / dict / list 同理，详见 write-cells） | 在本地把数字拼成 `"$1,234"` / `"30.5%"` 字符串再 `+csv-put`（会落成文本、丢失计算能力） | | **新建**电子表格并写带类型的数据（类型保真需求同上，但目标表还不存在） | `+workbook-create --sheets`（协议与 `+table-put` 同构、一步建表 + typed 写入，无需先建空表再 `+table-put`；date / number 不丢，详见 workbook） | 用 `--values` 灌日期 / 数字（会落成文本、丢类型） | @@ -49,9 +49,9 @@ metadata: | 查找单元格 | `+cells-search`（关键字用 `--find`） | `+cells-find`、`+find`、`--query` | | 查找并替换 | `+cells-replace` | — | | 看子表结构（合并 / 行高列宽 / 冻结 / 隐藏） | `+sheet-info` | `+sheet-get`、`+structure-get`、`+sheet-structure-get` | -| 看工作簿 / 子表清单 | `+workbook-info` | — | +| 看工作簿 / 子表清单 | `+workbook-info` | `+sheet-list`、`+workbook-get`、`+workbook-list` | | 导出 xlsx / 单表 csv | `+workbook-export` | — | -| 导入本地 xlsx/xls/csv 文件为新表格 | `+workbook-import --file ./x.xlsx`（仅导入为电子表格；要导成多维表格走 `drive +import --type bitable`） | 把 .xlsx 在本地读成数据再 `+workbook-create` 重灌（丢原格式、低效） | +| 导入本地 xlsx/xls/csv 文件为飞书电子表格 | `+workbook-import --file ./x.xlsx`（本地表格文件 → 飞书电子表格的正解；仅要导成多维表格 bitable 时才用 `drive +import --type bitable`） | `drive +import`（导电子表格时绕了 drive 通道、还要多给 `--type`，应直接用 `+workbook-import`）、把 .xlsx 在本地读成数据再 `+workbook-create` 重灌 | | 清除内容 / 格式 | `+cells-clear`（范围维度用 `--scope`，取值 content / formats / all） | `--type` | | 批量清除多区域 | `+cells-batch-clear`（`--scope`） | `--target` | | 调整列宽 / 行高 | `+cols-resize` / `+rows-resize`（行、列是两个独立命令） | `--dimension`（无此 flag） | @@ -113,7 +113,7 @@ metadata: 2. **sheet 定位（公共四件套 shortcut 必填）**：`--sheet-id` 与 `--sheet-name` 二选一，**必须给其中之一**。两个都不给 → 校验报错 `specify at least one of --sheet-id or --sheet-name`。 - ⚠️ **不确定 sheet 名时禁止直接猜 `Sheet1`**：除非用户对话明确说出 sheet 名 / id，或上下文（之前的工具调用 / URL 锚点 `?sheet=xxx`）已经出现过具体值，否则**第一步先调 `+workbook-info --url "..."`**（或 `--spreadsheet-token`）拿 `sheets[].sheet_id` / `sheets[].title` 列表再选。中文环境下子表常叫"数据" / "Sheet"（无数字）/ "工作表 1" / 业务名，猜 `Sheet1` 大概率撞 `sheet not found`，比先查多耗一次失败调用 + 重试。 - ⚠️ **`--range` 里的 `Sheet1!` 前缀不能替代 sheet 定位**：即使写了 `--range 'Sheet1!A1:B2'`，仍**必须**额外传 `--sheet-id` 或 `--sheet-name`，否则照样报上面的错。 - - ⚠️ **A1 reference 含 `!`**（`--source` / `--range` / `--ranges`）**：shell session 起手先 `set +H`** 关 bash history expansion，否则 `"Sheet1!A1"` 会被拦成 `event not found`；含特殊字符（`-` / 空格 / 非 ASCII）的 sheet 名还要内部 single-quote 包，如 `--source "'Sales-2025'!A1:D100"`。 + - ⚠️ **A1 reference 含 `!`**（`--source` / `--range` / `--ranges`）**：整段用单引号包裹**，如 `--range 'Sheet1!A1:B2'`——单引号能挡住 bash 的 history expansion（`!` 被拦成 `event not found`；双引号挡不住）。**不要起手 `set +H` 去关 history expansion**：调用方的 shell 可能是 `sh` / `dash`，那里 `set +H` 是非法选项（`set: Illegal option -H`）、会让整条命令直接失败；单引号包裹对 bash 与 `sh` / `dash` 一致安全，无需 `set +H`。sheet 名含特殊字符（`-` / 空格 / 非 ASCII）需在内部按 A1 标准再包一层单引号时，用 `'\''` 转义保持外层单引号，如 `--source ''\''Sales-2025'\''!A1:D100'`。 - **例外**：徽章标为 `_公共：URL/token（无 sheet 定位）…_` 的 shortcut（如 `+workbook-info` / `+workbook-export` / `+batch-update` / `+dropdown-update|delete` / `+cells-batch-set-style` / `+cells-batch-clear` / `+sheet-create`）**不接受也不需要** sheet 定位，只给一组 spreadsheet 定位即可。`+pivot-create` 用 `--target-sheet-id` / `--target-sheet-name`（XOR，可都不传，落点细节见 `lark-sheets-pivot-table`）。 | Flag | Type | 必填 | 说明 | diff --git a/skills/lark-sheets/references/lark-sheets-workbook.md b/skills/lark-sheets/references/lark-sheets-workbook.md index e9374b086..7db3df264 100644 --- a/skills/lark-sheets/references/lark-sheets-workbook.md +++ b/skills/lark-sheets/references/lark-sheets-workbook.md @@ -297,7 +297,7 @@ lark-cli sheets +workbook-create --title "经营看板" --sheets '{ ### `+workbook-import` -把已有的本地 `.xlsx` / `.xls` / `.csv` 文件导入为一个**新的**飞书电子表格（异步任务 + 内置轮询），与 `+workbook-export`（导出）对称。底层复用 drive 的导入实现，固定导入为电子表格类型。 +把已有的本地 `.xlsx` / `.xls` / `.csv` 文件导入为一个**新的**飞书电子表格（异步任务 + 内置轮询），与 `+workbook-export`（导出）对称，固定导入为电子表格类型。 ```bash # 导入到云空间根目录；表格名默认取本地文件名（去掉扩展名） @@ -308,7 +308,7 @@ lark-cli sheets +workbook-import --file ./report.csv --folder-token