---
{
  "id": "platform.sheet.version-history",
  "topic": "sheet",
  "title": "私有 workbook 版本歷史",
  "locale": "zh-TW",
  "version": "2026-08-25",
  "summary": "Workbook 歷史為私有且 mutation 會自動 checkpoint；舊版可在確認後原地 restore，也可安全複製成新 workbook。",
  "content": "Sheet 有五個私有 history Actions：`list_versions` 以 `cursor` 與 bounded `limit` 分頁；`get_version` 回 bounded、read-only 的歷史 preview；`create_named_version` 建立具 label 的 checkpoint；`restore_version` 原地還原選定內容；`copy_version` 則把舊版建立成另一個 workbook。歷史可能含現行 workbook 已移除的 cells，因此所有 version Actions 都是 `allow_in_public: false`。\n\n一般 Agent mutation 已強制建立 automatic checkpoint，不需每次寫入都手動命名。只有使用者明確要求時才用 `create_named_version`；它不需 confirmation，支援 optional `expectedHeadVersionId` 與 `idempotencyKey`。其 registry drift policy 為 Strict；head 或參數改變時必須重新載入與核對，不得靜默接受。\n\n`restore_version` 是 Sheet family 唯一需要 UserConfirm 的 Action，必須帶 `workbookId`、`versionId`、`expectedHeadVersionId`，同樣採 Strict drift，並支援 idempotency key。Restore 先把目前狀態存成 pre-restore checkpoint，再以選定歷史內容原地覆寫。Workbook 的整數 `version` 不會倒退到舊值；成功還原後現行 version 會前進，因此後續 mutation 要重新讀取並以新 version 作 `baseVersion`。\n\n使用者想查看或救回歷史內容、但不想覆寫現行 workbook 時，優先使用 `copy_version`。它需要 `workbookId` 與 `versionId`，會建立具全新 history 的 workbook，不需 confirmation，並採 Strict drift。只有使用者明確要改變目前 workbook 時才用 restore。Registry schemas、`canRestore` 類 runtime result、權限、confirmation 與 typed history errors 永遠為準。\n",
  "aliases": [
    "workbook history",
    "sheet version",
    "restore workbook",
    "named version",
    "expectedHeadVersionId",
    "pre restore checkpoint",
    "版本歷史",
    "還原活頁簿"
  ],
  "tags": [
    "sheet",
    "versions",
    "restore",
    "confirmation"
  ],
  "relatedActions": [
    "arinova.sheet.list_versions",
    "arinova.sheet.get_version",
    "arinova.sheet.create_named_version",
    "arinova.sheet.restore_version",
    "arinova.sheet.copy_version"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/zh-tw/kb/sheet/version-history/"
}
---

Sheet 有五個私有 history Actions：`list_versions` 以 `cursor` 與 bounded `limit` 分頁；`get_version` 回 bounded、read-only 的歷史 preview；`create_named_version` 建立具 label 的 checkpoint；`restore_version` 原地還原選定內容；`copy_version` 則把舊版建立成另一個 workbook。歷史可能含現行 workbook 已移除的 cells，因此所有 version Actions 都是 `allow_in_public: false`。

一般 Agent mutation 已強制建立 automatic checkpoint，不需每次寫入都手動命名。只有使用者明確要求時才用 `create_named_version`；它不需 confirmation，支援 optional `expectedHeadVersionId` 與 `idempotencyKey`。其 registry drift policy 為 Strict；head 或參數改變時必須重新載入與核對，不得靜默接受。

`restore_version` 是 Sheet family 唯一需要 UserConfirm 的 Action，必須帶 `workbookId`、`versionId`、`expectedHeadVersionId`，同樣採 Strict drift，並支援 idempotency key。Restore 先把目前狀態存成 pre-restore checkpoint，再以選定歷史內容原地覆寫。Workbook 的整數 `version` 不會倒退到舊值；成功還原後現行 version 會前進，因此後續 mutation 要重新讀取並以新 version 作 `baseVersion`。

使用者想查看或救回歷史內容、但不想覆寫現行 workbook 時，優先使用 `copy_version`。它需要 `workbookId` 與 `versionId`，會建立具全新 history 的 workbook，不需 confirmation，並採 Strict drift。只有使用者明確要改變目前 workbook 時才用 restore。Registry schemas、`canRestore` 類 runtime result、權限、confirmation 與 typed history errors 永遠為準。