ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
8.6 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 覆盖 11 个 shortcut：
| 操作需求 | 使用工具 | 说明 |
|---|---|---|
| 查看工作簿结构 | +workbook-info |
获取子表列表、名称、行列数、冻结位置等元数据 |
| 变更工作簿结构 | `+sheet-{create | delete |
注意：
- 如果用户请求包含多个动作，例如"先重命名，再新建工作表"，请按顺序发起多次调用，覆盖全部动作
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 | 工作簿 |
+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 | 工作簿 |
+workbook-create |
write | 工作簿 |
+workbook-export |
read | 工作簿 |
Flags
+workbook-info
公共：URL/token（无 sheet 定位） · 系统：--dry-run
仅含公共 / 系统 flag。
+sheet-create
公共：URL/token（无 sheet 定位） · 系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--title |
string | required | 新工作表名称 |
--index |
int | optional | 插入位置；省略时附加到末尾 |
--row-count |
int | optional | 初始行数（默认 200，上限 50000） |
--col-count |
int | optional | 初始列数（默认 20，上限 200） |
+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）；可选，未传时由 CLI runtime 根据 --sheet-id / --sheet-name 当前在工作簿中的 index 自动派生 |
+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，传空 "" 清除 |
+workbook-create
系统：--dry-run
| Flag | Type | 必填 | 说明 |
|---|---|---|---|
--title |
string | required | 新 spreadsheet 标题 |
--folder-token |
string | optional | 目标文件夹 token；省略时放在云空间根目录 |
--headers |
string + File + Stdin（简单 JSON） | optional | 表头行 JSON 数组：["列A","列B"] |
--values |
string + File + Stdin（简单 JSON） | optional | 初始数据 JSON 二维数组：[["alice",95]] |
+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 | 本地保存路径；省略时只触发导出不下载 |
Examples
公共四件套：所有 shortcut 顶部排列 --url / --spreadsheet-token / --sheet-id / --sheet-name（XOR）。+workbook-info 只用前两者；+sheet-* 系列对单个工作表操作，需 --sheet-id 或 --sheet-name。
+workbook-info
输出契约：返回 sheets[]，每个含 sheet_id / title（工作表显示名；旧 payload 用 sheet_name，读取时优先取 title、缺失再回退 sheet_name）/ row_count / column_count / index / is_hidden，以及计数字段 merged_cells_count / chart_count / pivot_table_count / float_image_count（无 frozen_* 字段，冻结信息请用 +sheet-info 读取）。是操作飞书表格的第一步——任何后续 sheet 级动作都需要先拿这里的 sheet_id。
+sheet-create
示例：
lark-cli sheets +sheet-create --url "https://example.feishu.cn/sheets/shtXXX" \
--title "汇总" --index 0
+sheet-delete
⚠️ 工作表删除不可逆；先
--dry-run看输出 sheet_id + title 确认是要删的那张。
+sheet-rename
lark-cli sheets +sheet-rename --url "..." --sheet-id "$SID" --title "汇总"
+sheet-move
standalone 路径在缺 --source-index / 只给 --sheet-name 时会自动发起一次 +workbook-info 读把它们解出来。
⚠️ 在
+batch-update内调用+sheet-move：必须同时显式传--sheet-id、--source-index和--index（目标位置）。batch 中途无法发起结构查询，且--index不显式给会静默落到默认位置 0，所以 batch translator 强制要求三者都显式。
+sheet-copy
# --title 省略时由服务端生成副本名
lark-cli sheets +sheet-copy --url "..." --sheet-id "$SID" --title "副本"
+sheet-hide / +sheet-unhide
lark-cli sheets +sheet-hide --url "..." --sheet-id "$SID"
lark-cli sheets +sheet-unhide --url "..." --sheet-id "$SID"
+sheet-set-tab-color
# Hex 色值；传空字符串 "" 清除标签色
lark-cli sheets +sheet-set-tab-color --url "..." --sheet-id "$SID" --color "#FF0000"
Validate / DryRun / Execute 约束
Validate：XOR 公共四件套；+sheet-create校验--title非空、--row-count≤ 50000、--col-count≤ 200；+sheet-delete必须--yes或--dry-run。DryRun：+sheet-*写操作输出"将要 PATCH 的 sheet metadata"；--sheet-name在 dry-run 输出里生成为<resolve:Sheet1>占位符，不实际解析为 sheet-id。Execute：写操作不自动回读；如需确认目标 sheet 的新状态，自行调用+workbook-info。