diff --git a/shortcuts/sheets/data/flag-defs.json b/shortcuts/sheets/data/flag-defs.json index b53b6e66..8772c1fc 100644 --- a/shortcuts/sheets/data/flag-defs.json +++ b/shortcuts/sheets/data/flag-defs.json @@ -4824,5 +4824,97 @@ "desc": "" } ] + }, + "+history-list": { + "risk": "read", + "flags": [ + { + "name": "url", + "kind": "public", + "type": "string", + "required": "xor", + "desc": "Spreadsheet locator" + }, + { + "name": "spreadsheet-token", + "kind": "public", + "type": "string", + "required": "xor", + "desc": "Spreadsheet locator" + }, + { + "name": "dry-run", + "kind": "system", + "type": "bool", + "required": "optional", + "desc": "" + } + ] + }, + "+history-revert": { + "risk": "write", + "flags": [ + { + "name": "url", + "kind": "public", + "type": "string", + "required": "xor", + "desc": "Spreadsheet locator" + }, + { + "name": "spreadsheet-token", + "kind": "public", + "type": "string", + "required": "xor", + "desc": "Spreadsheet locator" + }, + { + "name": "history-version-id", + "kind": "own", + "type": "string", + "required": "required", + "desc": "History version to revert to (from +history-list)." + }, + { + "name": "dry-run", + "kind": "system", + "type": "bool", + "required": "optional", + "desc": "" + } + ] + }, + "+history-revert-status": { + "risk": "read", + "flags": [ + { + "name": "url", + "kind": "public", + "type": "string", + "required": "xor", + "desc": "Spreadsheet locator" + }, + { + "name": "spreadsheet-token", + "kind": "public", + "type": "string", + "required": "xor", + "desc": "Spreadsheet locator" + }, + { + "name": "history-version-id", + "kind": "own", + "type": "string", + "required": "required", + "desc": "History version whose revert status to query (from +history-list)." + }, + { + "name": "dry-run", + "kind": "system", + "type": "bool", + "required": "optional", + "desc": "" + } + ] } } diff --git a/shortcuts/sheets/flag_defs_gen.go b/shortcuts/sheets/flag_defs_gen.go index 37f3d639..21e2b020 100644 --- a/shortcuts/sheets/flag_defs_gen.go +++ b/shortcuts/sheets/flag_defs_gen.go @@ -646,6 +646,32 @@ var flagDefs = map[string]commandDef{ {Name: "exit-on-error", Kind: "own", Type: "bool", Required: "optional", Desc: "When status=errors_found, exit non-zero. Useful for CI gate after batch formula writes."}, }, }, + "+history-list": { + Risk: "read", + Flags: []flagDef{ + {Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"}, + {Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"}, + {Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"}, + }, + }, + "+history-revert": { + Risk: "write", + Flags: []flagDef{ + {Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"}, + {Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"}, + {Name: "history-version-id", Kind: "own", Type: "string", Required: "required", Desc: "History version to revert to (from +history-list)."}, + {Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"}, + }, + }, + "+history-revert-status": { + Risk: "read", + Flags: []flagDef{ + {Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"}, + {Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"}, + {Name: "history-version-id", Kind: "own", Type: "string", Required: "required", Desc: "History version whose revert status to query (from +history-list)."}, + {Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"}, + }, + }, "+pivot-create": { Risk: "write", Flags: []flagDef{ diff --git a/skills/lark-sheets/SKILL.md b/skills/lark-sheets/SKILL.md index 638c5b05..47b04351 100644 --- a/skills/lark-sheets/SKILL.md +++ b/skills/lark-sheets/SKILL.md @@ -154,6 +154,7 @@ metadata: | [Lark Sheet Filter View](references/lark-sheets-filter-view.md) | 管理飞书表格中的筛选视图(filter view)。当用户需要"建一个 XX 视图"、"保存这个筛选状态"、"切换不同筛选"、维护一个 sheet 上多份独立筛选配置时使用。视图与筛选器(filter)相互独立,可在同一 sheet 共存;视图的隐藏行仅在用户进入该视图时本地生效,不影响其他协作者。 | | [Lark Sheet Sparkline](references/lark-sheets-sparkline.md) | 管理飞书表格中的迷你图(折线迷你图、柱形迷你图、胜负迷你图)。当用户需要在单元格内嵌入小型图表来展示数据趋势时使用。也适用于"趋势线"、"单元格内图表"、"迷你图"等场景。注意:不等同于被禁用的 SPARKLINE() 公式函数。 | | [Lark Sheet Float Image](references/lark-sheets-float-image.md) | 管理飞书表格中的浮动图片。当用户需要在表格中插入浮动图片、调整图片位置和大小、查看已有浮动图片、删除图片时使用。也适用于"插入图片"、"添加 logo"、"放一张图"等场景。注意:如果用户需要将图片嵌入到某个单元格内部(单元格图片),请阅读 lark-sheets-write-cells。 | +| [Lark Sheet History](references/lark-sheets-history.md) | 查询飞书表格的历史版本并回滚到指定版本。当用户需要查看一张表的编辑历史版本列表、回滚到某个历史版本、或查询回滚的异步状态(进行中/成功/失败)时使用。回滚为异步操作,发起后通过状态查询轮询结果。仅针对飞书表格。 | ## 公共 flag 速查 diff --git a/skills/lark-sheets/references/lark-sheets-history.md b/skills/lark-sheets/references/lark-sheets-history.md new file mode 100644 index 00000000..8e75379e --- /dev/null +++ b/skills/lark-sheets/references/lark-sheets-history.md @@ -0,0 +1,87 @@ +# Lark Sheet History + +## 概念回顾 + +每张飞书电子表格保留一串历史版本(`minor_histories`)。每个版本由 `history_version_id` 标识,并附带创建时间(`create_time`)、动作(`action`)与块修订信息(`all_block_revision`)。历史是**工作簿级**的(针对整张电子表格,不针对单个子表)。 + +回滚(revert)把电子表格的当前内容覆盖回某个历史版本——这是一个**写入 / 不可逆**操作,且为**异步**:发起后立即返回受理标识,真正的回滚在后台进行,需通过状态查询轮询最终结果(进行中 / 成功 / 失败)。 + +`+history-list` 读取版本列表以挑选目标;`+history-revert` 发起回滚;`+history-revert-status` 轮询回滚结果。 + +## 使用场景 + +读取历史版本、发起回滚、查询回滚状态。本 reference 覆盖 3 个 shortcut: + +| 操作需求 | 使用工具 | 说明 | +|---------|---------|------| +| 查看历史版本列表 | `+history-list` | 返回 `minor_histories`,每条含 `history_version_id` / `create_time` / `action` / `all_block_revision` 四个字段 | +| 回滚到指定历史版本 | `+history-revert` | 传入 `--history-version-id`;异步受理,返回可查询标识 | +| 查询回滚状态 | `+history-revert-status` | 轮询某次回滚的进行中 / 成功 / 失败状态 | + +典型工作流:`+history-list` 拿到目标版本的 `history_version_id` → `+history-revert` 发起回滚 → `+history-revert-status` 轮询直到成功或失败。 + +**注意事项(必须了解)**: +- **回滚是写入 / 不可逆操作**:会用历史版本内容覆盖当前表格,发起前请确认目标 `history_version_id` 正确。 +- **回滚是异步的**:`+history-revert` 返回的是受理标识,不代表回滚已完成;必须用 `+history-revert-status` 确认最终结果。 +- **`history_version_id` 取自 `+history-list`**:不要臆造或复用别的标识。 +- **历史是工作簿级**:定位只需 `--url` / `--spreadsheet-token`(XOR),不需要子表选择器。 + +## Shortcuts + +| Shortcut | Risk | 分组 | +| --- | --- | --- | +| `+history-list` | read | 工作簿 | +| `+history-revert` | write | 工作簿 | +| `+history-revert-status` | read | 工作簿 | + +## Flags + +### `+history-list` + +_公共:URL/token(无 sheet 定位) · 系统:`--dry-run`_ + +_仅含公共 / 系统 flag。_ + +### `+history-revert` + +_公共:URL/token(无 sheet 定位) · 系统:`--dry-run`_ + +| Flag | Type | 必填 | 说明 | +| --- | --- | --- | --- | +| `--history-version-id` | string | required | 要回滚到的历史版本(取自 +history-list) | + +### `+history-revert-status` + +_公共:URL/token(无 sheet 定位) · 系统:`--dry-run`_ + +| Flag | Type | 必填 | 说明 | +| --- | --- | --- | --- | +| `--history-version-id` | string | required | 要查询回滚状态的历史版本(取自 +history-list) | + +## Examples + +公共定位:所有 shortcut 顶部排列 `--url` / `--spreadsheet-token`(XOR,二选一)。`--history-version-id` 取自 `+history-list` 的输出。 + +### `+history-list` + +```bash +# 列出某张电子表格的历史版本 +lark-cli sheets +history-list --url "https://sample.feishu.cn/sheets/SHTxxxxxx" + +# 用原始 spreadsheet token 定位 +lark-cli sheets +history-list --spreadsheet-token "SHTxxxxxx" +``` + +### `+history-revert` + +```bash +# 回滚到指定历史版本(异步受理) +lark-cli sheets +history-revert --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --history-version-id "" +``` + +### `+history-revert-status` + +```bash +# 查询某次回滚的当前状态(进行中 / 成功 / 失败) +lark-cli sheets +history-revert-status --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --history-version-id "" +```