Sheet mutation 與樂觀版本控制

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。

Related actions

arinova.sheet.get_workbook_summary, arinova.sheet.read_range, arinova.sheet.update_cells, arinova.sheet.append_rows

Also known as

baseVersion, version mismatch, modified concurrently, update cells, append rows, validation warnings, 樂觀鎖, 並行修改, 附加資料

---

Machine-readable Markdown · Knowledge index