---
{
  "id": "platform.note.editing-and-versioning",
  "topic": "note",
  "title": "Note 編輯、衝突與 roll-forward 版本",
  "locale": "zh-TW",
  "version": "2026-08-25",
  "summary": "Note update 保留省略欄位、整組替換 tags、拒絕空白 content，並以 optimistic locking 與 immutable roll-forward history 保護版本。",
  "content": "`update_note` 是 partial update：省略欄位會保留原值，但有傳入 `tags` array 時會整組替換，不會 merge。顯式空字串或全空白 `content` 會以 `NOTE_CONTENT_EMPTY` 拒絕；action 不支援清空內文，省略 `content` 才代表保留。多人並行編輯時，先 `get_note`，再把讀到的 version 當 `expectedVersion`；若回 `RESOURCE_CONFLICT` 並附 expected／actual versions，需重讀、明確合併後用新版本重試，不可盲目重送舊寫入。\n\n每次成功 create、update、restore 都寫入完整 snapshot，note version 單調遞增。`list_versions`／`get_version` 是 owner-scoped reads，list result 以 `isCurrent` 標示現行快照。`restore_version` 採 roll-forward：把舊 snapshot 複製成新的現行版本，不刪除或改寫歷史；restore 前的現行內容本來就有自己的 snapshot，日後仍可再還原。\n\n`create_named_version` 把目前 title、content、tags 存成耐久 checkpoint，可附 label。它不需 confirmation、只允許私有執行、採 Strict drift，只在使用者明確要求時呼叫。\n\nRestore 會清除既有 CRDT state 並同步線上編輯者，同步是否成功以 live result 為準。registry 對 `restore_version` 的 confirmation 是 `none`，但它會覆蓋現行內容；執行前應先 `get_version`，向使用者摘要該 snapshot 並確認意圖，不可聲稱平台還會額外跳 confirmation。`create_note`／`update_note` 的 serialized arguments 上限各為 32 KiB，而 content 是 whole-body replacement；超過此界線的大型筆記無法用這些 actions 全文改寫，也不可虛構 append／patch 能力。\n",
  "aliases": [
    "編輯筆記",
    "更新記事",
    "筆記版本歷史",
    "版本衝突",
    "還原筆記",
    "expectedVersion",
    "NOTE_CONTENT_EMPTY"
  ],
  "tags": [
    "note",
    "editing",
    "versions",
    "optimistic-locking",
    "collaboration"
  ],
  "relatedActions": [
    "arinova.note.get_note",
    "arinova.note.create_note",
    "arinova.note.update_note",
    "arinova.note.list_versions",
    "arinova.note.get_version",
    "arinova.note.create_named_version",
    "arinova.note.restore_version"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/zh-tw/kb/note/editing-and-versioning/"
}
---

`update_note` 是 partial update：省略欄位會保留原值，但有傳入 `tags` array 時會整組替換，不會 merge。顯式空字串或全空白 `content` 會以 `NOTE_CONTENT_EMPTY` 拒絕；action 不支援清空內文，省略 `content` 才代表保留。多人並行編輯時，先 `get_note`，再把讀到的 version 當 `expectedVersion`；若回 `RESOURCE_CONFLICT` 並附 expected／actual versions，需重讀、明確合併後用新版本重試，不可盲目重送舊寫入。

每次成功 create、update、restore 都寫入完整 snapshot，note version 單調遞增。`list_versions`／`get_version` 是 owner-scoped reads，list result 以 `isCurrent` 標示現行快照。`restore_version` 採 roll-forward：把舊 snapshot 複製成新的現行版本，不刪除或改寫歷史；restore 前的現行內容本來就有自己的 snapshot，日後仍可再還原。

`create_named_version` 把目前 title、content、tags 存成耐久 checkpoint，可附 label。它不需 confirmation、只允許私有執行、採 Strict drift，只在使用者明確要求時呼叫。

Restore 會清除既有 CRDT state 並同步線上編輯者，同步是否成功以 live result 為準。registry 對 `restore_version` 的 confirmation 是 `none`，但它會覆蓋現行內容；執行前應先 `get_version`，向使用者摘要該 snapshot 並確認意圖，不可聲稱平台還會額外跳 confirmation。`create_note`／`update_note` 的 serialized arguments 上限各為 32 KiB，而 content 是 whole-body replacement；超過此界線的大型筆記無法用這些 actions 全文改寫，也不可虛構 append／patch 能力。