larksuite · wittam-01 · Apr 30, 2026
diff --git a/shortcuts/drive/drive_version.go b/shortcuts/drive/drive_version.go
diff --git a/shortcuts/drive/drive_version_test.go b/shortcuts/drive/drive_version_test.go
diff --git a/shortcuts/drive/shortcuts.go b/shortcuts/drive/shortcuts.go
@@ -16,6 +16,10 @@ func Shortcuts() []common.Shortcut {
 		DriveExport,
 		DriveExportDownload,
 		DriveImport,
+		DriveVersionHistory,
+		DriveVersionGet,
+		DriveVersionRevert,
+		DriveVersionDelete,
 		DriveMove,
 		DriveDelete,
 		DriveStatus,

diff --git a/shortcuts/drive/shortcuts_test.go b/shortcuts/drive/shortcuts_test.go
@@ -15,6 +15,10 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		"+create-folder",
 		"+create-shortcut",
 		"+download",
+		"+version-history",
+		"+version-get",
+		"+version-revert",
+		"+version-delete",
 		"+add-comment",
 		"+export",
 		"+export-download",

diff --git a/skills/lark-drive/SKILL.md b/skills/lark-drive/SKILL.md
@@ -20,6 +20,7 @@ metadata:
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要在 Drive 里上传、创建、读取、覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
+- 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
 - 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
 - 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 `lark-cli drive +upload --wiki-token <wiki_token>`；不要误切到 `wiki` 域命令。
@@ -236,6 +237,10 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+export`](references/lark-drive-export.md) | Export a doc/docx/sheet/bitable to a local file with limited polling; supports `--file-name` for local naming |
 | [`+export-download`](references/lark-drive-export-download.md) | Download an exported file by file_token |
 | [`+import`](references/lark-drive-import.md) | Import a local file to Drive as a cloud document (docx, sheet, bitable) |
+| [`+version-history`](references/lark-drive-version-history.md) | List historical versions of a file with only_tag=true and cursor-based pagination |
+| [`+version-get`](references/lark-drive-version-get.md) | Download a specific historical version of a file |
+| [`+version-revert`](references/lark-drive-version-revert.md) | Revert a file to a specific historical version |
+| [`+version-delete`](references/lark-drive-version-delete.md) | Delete a specific historical version of a file |
 | [`+move`](references/lark-drive-move.md) | Move a file or folder to another location in Drive |
 | [`+delete`](references/lark-drive-delete.md) | Delete a Drive file or folder with limited polling for folder deletes |
 | [`+push`](references/lark-drive-push.md) | File-level local → Drive mirror. Duplicate remote `rel_path` conflicts fail by default; `newest` / `oldest` only apply to duplicate files when you explicitly want to target one remote file. `--if-exists` supports `skip` / `smart` / `overwrite` (`smart` skips files whose remote `modified_time` is already up to date, but falls through to the same overwrite path when the remote is older, so it inherits overwrite's rollout caveat). `--delete-remote` requires `--yes`. `--local-dir` must stay inside cwd. |

diff --git a/skills/lark-drive/references/lark-drive-version-delete.md b/skills/lark-drive/references/lark-drive-version-delete.md
@@ -0,0 +1,35 @@
+# drive +version-delete
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+删除指定的历史版本。该 shortcut 同时支持 `--as user` 和 `--as bot`；自动化场景推荐使用 `--as bot`。
+
+## 命令
+
+```bash
+lark-cli drive +version-delete \
+  --file-token boxcnxxxxxxxx \
+  --version 7633658129540910621 \
+  --as bot
+
+lark-cli drive +version-delete \
+  --file-token boxcnxxxxxxxx \
+  --version 7633658129540910621 \
+  --as user
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 目标文件 token |
+| `--version` | 是 | `drive +version-history` 返回的长数字 `version` 字段，不是 `tag` |
+
+## 返回值
+
+无额外业务字段，以命令成功 / 失败为准。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
diff --git a/skills/lark-drive/references/lark-drive-version-get.md b/skills/lark-drive/references/lark-drive-version-get.md
@@ -0,0 +1,86 @@
+# drive +version-get
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+下载指定版本的文件内容。该 shortcut 同时支持 `--as user` 和 `--as bot`；自动化场景推荐使用 `--as bot`。
+
+## 命令
+
+```bash
+lark-cli drive +version-get \
+  --file-token boxcnxxxxxxxx \
+  --version 7633658129540910621 \
+  --as bot
+
+lark-cli drive +version-get \
+  --file-token boxcnxxxxxxxx \
+  --version 7633658129540910621 \
+  --as user
+
+lark-cli drive +version-get \
+  --file-token boxcnxxxxxxxx \
+  --version 7633658129540910621 \
+  --output ./downloads/ \
+  --as bot
+
+lark-cli drive +version-get \
+  --file-token boxcnxxxxxxxx \
+  --version 7633658129540910621 \
+  --output ./artifact.bin \
+  --overwrite \
+  --as bot
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 目标文件 token |
+| `--version` | 是 | `drive +version-history` 返回的长数字 `version` 字段，不是 `tag` |
+| `--output` | 否 | 本地保存路径或目录；省略时直接在 stdout 返回下载内容 |
+| `--overwrite` | 否 | 覆盖已存在的本地输出文件 |
+
+## 关键行为
+
+- 省略 `--output` 时，CLI 不落盘，直接返回 `content`
+- `--output` 指向已存在目录，或以 `/` / `\\` 结尾时，CLI 会使用远端文件名保存
+- 目标文件已存在时，只有显式传 `--overwrite` 才会覆盖
+
+## 返回值
+
+省略 `--output` 时：
+
+```json
+{
+  "ok": true,
+  "identity": "bot",
+  "data": {
+    "file_token": "boxcnxxxxxxxx",
+    "version": "7633658129540910621",
+    "file_name": "artifact.bin",
+    "content": "file bytes decoded as UTF-8 text",
+    "size_bytes": 12345
+  }
+}
+```
+
+指定 `--output` 时：
+
+```json
+{
+  "ok": true,
+  "identity": "bot",
+  "data": {
+    "file_token": "boxcnxxxxxxxx",
+    "version": "7633658129540910621",
+    "file_name": "artifact.bin",
+    "saved_path": "/abs/path/artifact.bin",
+    "size_bytes": 12345
+  }
+}
+```
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
diff --git a/skills/lark-drive/references/lark-drive-version-history.md b/skills/lark-drive/references/lark-drive-version-history.md
@@ -0,0 +1,73 @@
+# drive +version-history
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+列出指定文件的历史版本快照。该 shortcut 同时支持 `--as user` 和 `--as bot`；自动化场景推荐使用 `--as bot`。
+
+## 命令
+
+```bash
+lark-cli drive +version-history \
+  --file-token boxcnxxxxxxxx \
+  --as bot
+
+lark-cli drive +version-history \
+  --file-token boxcnxxxxxxxx \
+  --as user
+
+lark-cli drive +version-history \
+  --file-token boxcnxxxxxxxx \
+  --limit 50 \
+  --cursor 1777013761763 \
+  --as bot
+
+lark-cli drive +version-history \
+  --file-token boxcnxxxxxxxx \
+  --dry-run \
+  --as bot
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 目标文件 token |
+| `--limit` | 否 | 返回条数上限，范围 `1-200`，默认 `20` |
+| `--cursor` | 否 | 分页游标；取上一页返回的 `next_cursor` 回填 |
+
+## 关键行为
+
+- shortcut 内部固定传 `only_tag=true`
+- 返回 `has_more=true` 时，使用 `next_cursor` 继续翻页
+- `versions[].version` 是传给 `drive +version-get` / `+version-revert` / `+version-delete` 的长数字版本串；`tag` 只是展示序号，不能替代 `version`
+- `versions[].is_deleted` 为布尔值，表示该历史版本是否已被删除
+
+## 返回值
+
+```json
+{
+  "ok": true,
+  "identity": "bot",
+  "data": {
+    "versions": [
+      {
+        "version": "7633658129540910621",
+        "name": "report.md",
+        "edited_at": "1777013761763",
+        "edited_by": "ou_xxx",
+        "size_bytes": "12345",
+        "action_type": "upload",
+        "is_deleted": false,
+        "tag": 7
+      }
+    ],
+    "has_more": true,
+    "next_cursor": "1777013761763"
+  }
+}
+```
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
diff --git a/skills/lark-drive/references/lark-drive-version-revert.md b/skills/lark-drive/references/lark-drive-version-revert.md
@@ -0,0 +1,35 @@
+# drive +version-revert
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+将文件回滚到指定历史版本。该 shortcut 同时支持 `--as user` 和 `--as bot`；自动化场景推荐使用 `--as bot`。
+
+## 命令
+
+```bash
+lark-cli drive +version-revert \
+  --file-token boxcnxxxxxxxx \
+  --version 7633658129540910621 \
+  --as bot
+
+lark-cli drive +version-revert \
+  --file-token boxcnxxxxxxxx \
+  --version 7633658129540910621 \
+  --as user
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 目标文件 token |
+| `--version` | 是 | `drive +version-history` 返回的长数字 `version` 字段，不是 `tag` |
+
+## 返回值
+
+无额外业务字段，以命令成功 / 失败为准。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数