私有 workbook 版本歷史

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 永遠為準。

Related actions

arinova.sheet.list_versions, arinova.sheet.get_version, arinova.sheet.create_named_version, arinova.sheet.restore_version, arinova.sheet.copy_version

Also known as

workbook history, sheet version, restore workbook, named version, expectedHeadVersionId, pre restore checkpoint, 版本歷史, 還原活頁簿

---

Machine-readable Markdown · Knowledge index