docs history（历史版本与回滚）

用于查看 Docx 历史版本、按 history_version_id 回滚，以及查询回滚任务状态。

安全流程

先用分页接口 +history-list 找到目标版本的 history_version_id。
如果用户指定的是 revision_id，不要假设它唯一，也不要把 revision_id 直接传给 +history-revert。先拉一页并在 entries[] 中筛选 revision_id 相同的候选；如果未匹配到且 has_more=true，继续用 page_token 翻页；如果已匹配到候选，最多额外再拉一页补齐可能跨页的相邻候选。最终优先根据用户目标时间与 edit_time 的接近程度选择最合适的一条，取同一条的 history_version_id；如果没有目标时间，或多个候选无法可靠区分，再向用户展示候选版本（history_version_id、revision_id、edit_time、name/description）并确认后回滚。
如果用户指定的是某一时刻但没有指定 revision_id，按 entries[].edit_time 匹配；优先选择不晚于目标时刻的最近一条历史记录，无法明确匹配时先向用户确认候选版本。
再用 +history-revert --history-version-id <history_version_id> 发起回滚。默认最多等待 30 秒；如果返回 status: running，记录 task_id。
用 +history-revert-status 轮询 task_id，直到状态不再是 running。
回滚完成后，用 docs +fetch 读取文档确认内容。

按 revision_id 或时间点回滚

当用户说“回滚到 revision_id=42”“恢复到昨天下午 3 点的版本”这类需求时，流程是：

执行 docs +history-list --doc <doc> 获取第一页历史记录；+history-list 是分页接口，只有 has_more=true 且还需要更多候选时才继续传 --page-token 翻页。
如果用户给出 revision_id：先筛选当前页中 entries[].revision_id == 用户给出的 revision_id。如果未命中且 has_more=true，继续拉下一页；如果已经命中候选，最多额外再拉一页，补齐同一个 revision_id 可能跨页出现的相邻 history_version_id。若用户同时给出目标时间，在候选里选择 edit_time 与目标时间最接近的一条；若未给目标时间但候选只有一条，可直接使用；若多个候选无法可靠区分，不要自行取第一条，向用户展示候选并确认。
如果用户只给出时间：用 entries[].edit_time 匹配，选择目标时刻之前最近的一条；如果用户表达的是“最接近某时刻”，则选择绝对时间差最小的一条。
从最终匹配条目读取 history_version_id。history_version_id 对应服务端 minor_history.version，这是回滚接口需要的 ID。
执行 docs +history-revert --doc <doc> --history-version-id <history_version_id>。

候选确认时使用类似格式：

同一个 revision_id 命中多个历史版本，请确认要回滚哪一条：
- history_version_id=11 revision_id=42 edit_time=2026-06-22T12:24:45Z name=...
- history_version_id=12 revision_id=42 edit_time=2026-06-22T12:25:14Z name=...

命令

# 列出历史版本
lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20

# 翻页
lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20 --page-token "<page_token>"

# 回滚到指定 history_version_id（默认等待 30000ms）
lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42

# 只发起任务，不等待
lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42 --wait-timeout-ms 0

# 查询回滚任务状态
lark-cli docs +history-revert-status --doc "<docx_url_or_token>" --task-id "<task_id>"

参数

命令	参数	必填	说明
`+history-list`	`--doc`	是	Docx URL/token，或可解析为 Docx 的 wiki URL
`+history-list`	`--page-size`	否	返回条数，范围 `1-20`，默认 `20`
`+history-list`	`--page-token`	否	上一页返回的 `page_token`
`+history-revert`	`--doc`	是	Docx URL/token，或可解析为 Docx 的 wiki URL
`+history-revert`	`--history-version-id`	是	`+history-list` 返回的 `history_version_id`，必须大于 0
`+history-revert`	`--wait-timeout-ms`	否	等待回滚完成的毫秒数，范围 `0-30000`，默认 `30000`
`+history-revert-status`	`--doc`	是	同一个文档
`+history-revert-status`	`--task-id`	是	`+history-revert` 返回的 `task_id`

返回值要点

+history-list 返回：

{
  "entries": [
    {
      "revision_id": 42,
      "history_version_id": "11",
      "edit_time": "1780000000",
      "type": 1,
      "name": "版本名",
      "description": "版本说明",
      "editor_ids": ["ou_xxx"]
    }
  ],
  "has_more": true,
  "page_token": "page_token"
}

+history-revert 返回：

{
  "task_id": "task_xxx",
  "status": "running",
  "history_version_id": "11",
  "poll_after_ms": 10000
}

+history-revert-status 返回：

{
  "status": "partial_failed",
  "history_version_id": "11",
  "failed_block_tokens": ["blk_xxx"]
}

status 可能是 running、done、partial_failed、failed。当状态是 partial_failed 或 failed 时，优先检查 failed_block_tokens。

5.2 KiB Raw Permalink Blame History Unescape Escape

docs history（历史版本与回滚）

安全流程

按 revision_id 或时间点回滚

命令

参数

返回值要点

5.2 KiB

Raw Permalink Blame History