26 KiB
26 KiB
Lark Sheet Workbook
Sheet 结构变更保守化（编辑类任务必做）
+sheet-{create|delete|rename|move|copy|hide|unhide|set-tab-color} 会改变原表的物理结构，是高副作用动作。执行前必须遵守：
- 删除 / 重命名 / 隐藏 / 移动原 Sheet 需用户明示：除非用户明示要这些操作，禁止擅自对已存在的 Sheet 执行 delete / rename / hide / move。新建 Sheet 是允许的（用于承载中间结果或透视表 / 图表对象），但应优先在原表右侧加列；只有当中间结果数量较大或会与原数据混淆时，才新建空白 Sheet（同 R1）。
- Sheet 级操作前先列清单：调用
+sheet-{create|delete|rename|move|copy|hide|unhide|set-tab-color}之前，必须先调用+workbook-info，把"当前所有 Sheet 名 + 可见性 + 行列数"列出来，再决定是否操作。禁止跳过列清单直接 create / delete / rename。 - 删除 / 重命名前向用户确认：删除是不可逆的，重命名会让其他公式 / 透视表 / 图表的数据源失效——执行前必须在回复里确认"将删除 / 改名 X，影响 Y 个引用"。
使用场景
读写。管理工作簿结构。本 reference 覆盖 14 个 shortcut：
| 操作需求 | 使用工具 | 说明 |
|---|---|---|
| 查看工作簿结构 | +workbook-info |
获取子表列表、名称、行列数、冻结位置等元数据 |
| 获取当前 revision | +revision-get |
获取当前文档 revision（版本号），可作为 recover / undo / changeset 复核的版本锚点 |
| 新建工作簿（可预填数据） | +workbook-create |
从内存数据建一张新表（--values / --sheets typed） |
| 导入本地文件为新表 | +workbook-import |
把本地 .xlsx / .xls / .csv 导入为新的飞书电子表格 |
| 导出工作簿到本地 | +workbook-export |
导出为本地 .xlsx（整簿）或单子表 .csv |
| 变更工作簿结构 | `+sheet-{create | delete |
| 切换子表网格线显隐 | +sheet-show-gridline / +sheet-hide-gridline |
显示 / 隐藏单个子表的网格线 |
注意：
- 如果用户请求包含多个动作，例如"先重命名，再新建工作表"，请按顺序发起多次调用，覆盖全部动作
create时若用户指定了工作表名称，应显式传入sheet_name；不要省略后依赖默认命名- 若
+workbook-info返回包含warning_message，说明部分sheet_id已失效（被删除/改名或输入错误），应停止复用这些 id，重新不带sheet_ids全量获取结构后再继续操作
常见配置错误（必须注意）：
- 获取结构是第一步：任何表格操作前必须先调用
+workbook-info，不要跳过直接操作。返回的行列数、子表列表是后续所有操作的基础 - sheet_id 不要写错：从
+workbook-info返回值中精确获取sheet_id，不要手动拼写或从 URL 中猜测 - 优先使用
sheet_id：虽然飞书表格不允许子表重名，但sheet_id是稳定标识符，跨多轮操作时不会因用户中途重命名而失效
Shortcuts
| Shortcut | Risk | 分组 |
|---|---|---|
+workbook-info |
read | 工作簿 |
+revision-get |
read | 工作簿 |
+sheet-create |
write | 工作簿 |
+sheet-delete |
high-risk-write | 工作簿 |
+sheet-rename |
write | 工作簿 |
+sheet-move |
write | 工作簿 |
+sheet-copy |
write | 工作簿 |
+sheet-hide |
write | 工作簿 |
+sheet-unhide |
write | 工作簿 |
+sheet-set-tab-color |
write | 工作簿 |
+sheet-hide-gridline |
write | 工作簿 |
+sheet-show-gridline |
write | 工作簿 |
+workbook-create |
write | 工作簿 |
+workbook-export |
read | 工作簿 |
+workbook-import |
write | 工作簿 |
Flags
+workbook-info
公共：URL/token（无 sheet 定位） · 系统：--dry-run
仅含公共 / 系统 flag。
+revision-get
公共：URL/token（无 sheet 定位） · 系统：--dry-run
仅含公共 / 系统 flag。
+sheet-create
公共：URL/token（无 sheet 定位） · 系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--title |
string | required | 新工作表名称 |
--index |
int | optional | 插入位置（0-based）；省略时附加到末尾 |
--row-count |
int | optional | 初始行数（默认 200，上限 50000） |
--col-count |
int | optional | 初始列数（默认 20，上限 200） |
--type |
string | optional | 新子表类型：sheet（电子表格）；默认 sheet（可选值：sheet） |
+sheet-delete
公共四件套 · 系统：--yes、--dry-run
仅含公共 / 系统 flag。
+sheet-rename
公共四件套 · 系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--title |
string | required | 新名称 |
+sheet-move
公共四件套 · 系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--index |
int | required | 目标位置（0-based） |
--source-index |
int | optional | 源位置（0-based）；standalone 调用时可选，未传时由 CLI runtime 根据 --sheet-id / --sheet-name 当前在工作簿中的 index 自动派生。但在 +batch-update 内不可省（须显式传）——batch 中途无法发起结构查询自动派生 |
+sheet-copy
公共四件套 · 系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--title |
string | optional | 副本名称；省略时由服务端生成 |
--index |
int | optional | 副本插入位置（0-based）；省略时附加到末尾 |
+sheet-hide
公共四件套 · 系统：--dry-run
仅含公共 / 系统 flag。
+sheet-unhide
公共四件套 · 系统：--dry-run
仅含公共 / 系统 flag。
+sheet-set-tab-color
公共四件套 · 系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--color |
string | required | Hex 色值如 #FF0000，传空 "" 清除 |
+sheet-hide-gridline
公共四件套 · 系统：--dry-run
仅含公共 / 系统 flag。
+sheet-show-gridline
公共四件套 · 系统：--dry-run
仅含公共 / 系统 flag。
+workbook-create
系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--title |
string | required | 新 spreadsheet 标题 |
--folder-token |
string | optional | 目标文件夹 token；省略时放在云空间根目录 |
--values |
string + File + Stdin（简单 JSON） | optional | untyped 初始数据，一个 JSON 二维数组（表头并入第一行）：[["列A","列B"],["alice",95]]；值原样写入、类型由飞书自动识别（日期 / 数字会落成文本，需类型保真改用 --sheets），走与 --sheets 相同的分批 +cells-set；配 --styles 控制格式/颜色/合并/行列尺寸 |
--sheets |
string + File + Stdin（复合 JSON） | optional | 建表后写入的 typed 表格协议 JSON（同 +table-put）：顶层 {"sheets":[...]}，每个数组项是一张子表 {name, start_cell?, mode?, header?, allow_overwrite?, columns:["colA","colB",...], data:[[...]], dtypes?:{colA:pandasDtype, ...}, formats?:{colA:numberFormat, ...}} —— name 与外层 sheets 数组都不可省。Agents 用 scripts/sheets_df.py 的 df_to_sheet(df, name) 把 DataFrame 转成一项再包 {"sheets":[...]}。与 --values 互斥；新表默认子表复用为第一个子表，日期/数字类型保真。 |
--styles |
string + File + Stdin（复合 JSON） | optional | 建表时同时写入的视觉处理操作 JSON：顶层 {styles:[...]}，每项对应一个目标子表、含 name，并至少给 cell_styles / row_sizes / col_sizes / cell_merges 之一。cell_styles 用 A1 单元格 range + 扁平样式字段（字段同 +cells-set-style，含 number_format / 颜色 / 对齐 / border_styles）；row/col sizes 用行/列范围 + type/size；merges 用单元格 range + 可选 merge_type。与 --sheets 搭配时 styles 数组长度/顺序/name 必须与 --sheets.sheets 对应；与 --values 搭配时只给一个 styles 项（其 name 忽略）。完整 cell_styles 字段结构跑 +workbook-create --print-schema --flag-name styles。 |
+workbook-export
公共：URL/token（无 sheet 定位） · 系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--file-extension |
string | optional | 导出文件格式；csv 模式必须配 --sheet-id（可选值：xlsx / csv）（默认 xlsx） |
--sheet-id |
string | optional | 仅 csv 模式必填：指定要导出哪张 sheet 为 CSV。这是 +workbook-export 专有 flag，与公共四件套的 sheet 定位无关（本 shortcut 不接受公共 sheet 定位） |
--output-path |
string | optional | 本地保存路径；省略时只触发并轮询导出任务、不下载文件（返回 file_token / status，便于稍后续传）。要落盘传具体路径（如 ./out.xlsx）或目录（如 .，服务端给的文件名落在该目录下）。注意：对应的 lark-cli drive +export --doc-type sheet 走 --output-dir / --file-name / --overwrite 三 flag 且默认下载到当前目录——本 wrapper 把它们合成单一 --output-path 简化常见用例，但默认不下载，需要的话也可改用 drive +export。 |
+workbook-import
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--file |
string | required | 本地文件路径（.xlsx / .xls / .csv） |
--folder-token |
string | optional | 目标文件夹 token；省略则导入到云空间根目录 |
--name |
string | optional | 导入后表格名称；省略则用本地文件名（去掉扩展名） |
Schemas
复合 JSON flag 字段速查（只列顶层 + 一层嵌套）。深层结构看下方
## Examples，或用--print-schema读完整 JSON Schema（用法见 SKILL.md「公共 flag 速查」与「Agent 使用提示」）。
+workbook-create --sheets
一个或多个子表的 typed 数据，每个数组元素写入一张子表；支持多 DataFrame → 多子表一次写入
数组项（类型 object）：
name(string) — 目标子表名start_cell(string?) — 写入起点单元格（A1 记法，如 "B2"），默认 "A1"mode(enum?) — overwrite（默认）：从 start_cell 起写「表头 + 数据」块；append：把数据追加到子表已有数据下方（默认不重复表头） [overwrite / append]header(boolean?) — 是否写一行列名表头allow_overwrite(boolean?) — 为 false 时，若写入会落在非空单元格则拒写以保护原数据（返回 partial_success）columns(array) — 列名字符串数组，顺序与data中每行取值一一对应data(array<array<string|number|boolean|null>>) — 数据行；每行是一个数组，长度必须等于columns数dtypes(object?) — 可选formats(object?) — 可选
+workbook-create --styles
数组项（类型 object）：
cell_merges(array