---
{
  "id": "platform.sheet.mutations-and-versioning",
  "topic": "sheet",
  "title": "Sheet mutation 與樂觀版本控制",
  "locale": "zh-TW",
  "version": "2026-07-25",
  "summary": "每次 Sheet mutation 都串接最新 workbook version、保留未指定 cells、寫入歷史 checkpoint，並把驗證違規當成成功寫入後的 warnings。",
  "content": "`update_cells` 與 `append_rows` 都採樂觀鎖。先從 `get_workbook_summary` 或 `read_range` 讀 `version` 作 `baseVersion`；成功後把新 `version` 接到下一次 mutation。不可重用舊版或自行 +1。舊 base 會回 `resource_conflict: version mismatch`，`details` 含 `baseVersion` 與 `currentVersion`；應重新讀取、核對並重試。即使 base 相符，競爭仍可能回 `resource_conflict: workbook was modified concurrently`，同樣重新讀取後再試。\n\n`update_cells` 是 sparse patch：只改列出的單一 cell keys，其他 cells 不變；null 寫成 blank，不會刪除列欄。`append_rows` 接在最後一個非空 used row 後，不是 declared `rowCount` 後；空 sheet 從第 1 列開始，需要時自動擴增 `rowCount`。結果回 one-based `startRow`、`appendedRows`、`appendedCells`、實際 A1 `range` 與新 `version`。\n\n兩種 mutation 都可能回含 `cell`、`rule`、`message` 的 `validationWarnings`。這是軟性警告，寫入已成功；要轉告使用者，不可當失敗重試。每次成功的 Agent mutation 都在同一 transaction 強制建立歷史 checkpoint；必要 checkpoint 失敗時，mutation 會失敗，不留下無歷史寫入。\n\n成功後平台會 broadcast 新 workbook version 並清 cache，開著的 Sheet UI 會自動更新，不必叫使用者重新整理。大量寫入每批最多 5,000 cells；append 每批另限 500 rows，且仍不得超過 5,000 cells，每批用上一批回傳 version。此處只有 `create_workbook` 有明確 dry-run 結果；update/append 的 success 表示 live commit，不得描述成 dry-run。\n",
  "aliases": [
    "baseVersion",
    "version mismatch",
    "modified concurrently",
    "update cells",
    "append rows",
    "validation warnings",
    "樂觀鎖",
    "並行修改",
    "附加資料"
  ],
  "tags": [
    "sheet",
    "mutation",
    "optimistic-locking",
    "checkpoints"
  ],
  "relatedActions": [
    "arinova.sheet.get_workbook_summary",
    "arinova.sheet.read_range",
    "arinova.sheet.update_cells",
    "arinova.sheet.append_rows"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/zh-tw/kb/sheet/mutations-and-versioning/"
}
---

`update_cells` 與 `append_rows` 都採樂觀鎖。先從 `get_workbook_summary` 或 `read_range` 讀 `version` 作 `baseVersion`；成功後把新 `version` 接到下一次 mutation。不可重用舊版或自行 +1。舊 base 會回 `resource_conflict: version mismatch`，`details` 含 `baseVersion` 與 `currentVersion`；應重新讀取、核對並重試。即使 base 相符，競爭仍可能回 `resource_conflict: workbook was modified concurrently`，同樣重新讀取後再試。

`update_cells` 是 sparse patch：只改列出的單一 cell keys，其他 cells 不變；null 寫成 blank，不會刪除列欄。`append_rows` 接在最後一個非空 used row 後，不是 declared `rowCount` 後；空 sheet 從第 1 列開始，需要時自動擴增 `rowCount`。結果回 one-based `startRow`、`appendedRows`、`appendedCells`、實際 A1 `range` 與新 `version`。

兩種 mutation 都可能回含 `cell`、`rule`、`message` 的 `validationWarnings`。這是軟性警告，寫入已成功；要轉告使用者，不可當失敗重試。每次成功的 Agent mutation 都在同一 transaction 強制建立歷史 checkpoint；必要 checkpoint 失敗時，mutation 會失敗，不留下無歷史寫入。

成功後平台會 broadcast 新 workbook version 並清 cache，開著的 Sheet UI 會自動更新，不必叫使用者重新整理。大量寫入每批最多 5,000 cells；append 每批另限 500 rows，且仍不得超過 5,000 cells，每批用上一批回傳 version。此處只有 `create_workbook` 有明確 dry-run 結果；update/append 的 success 表示 live commit，不得描述成 dry-run。