---
{
  "id": "platform.mindmap.tree-and-root-invariants",
  "topic": "mindmap",
  "title": "Mindmap forest 與 root 不變量",
  "locale": "zh-TW",
  "version": "2026-08-07",
  "summary": "Forest root 可變動，而單一 parent、拒絕 cycle、節點上限與 client-provided node ID 不變量仍嚴格成立。",
  "content": "一張 Mindmap 可有零到多個 roots。`add_node` 省略 `parentId` 或傳 null 會建立獨立的單節點樹；可傳 `manualOffset` 設定畫布 anchor。Root 可用 `move_node` 掛到同一張圖的任一 active node 下，將兩棵樹合併。非 root 以 `newParentId: null` 搬移時，會把整個 subtree 斷開成新 root，且必須傳當下絕對 `manualOffset`；已是 root 再搬到 null 會 conflict，重新定位應更新 layout。\n\n每個節點仍最多只有一個 parent，且 `move_node` 不可把節點搬到自己或任何 descendant 底下。非 null 的新 parent 必須是同一張 Mindmap 的 active node；另一張圖或不存在的 parent 會失敗，不會建立跨圖 edge。對 root 呼叫 `delete_node` 會把該整棵樹當成同一 batch 軟刪；對 root 呼叫 `delete_node_promote_children` 則只刪 root，讓每個 direct child 成為獨立 root。即使已有其他 active roots，也可 restore 已刪 root。\n\n單張 Mindmap 最多有 2,000 個 active nodes。Label 會先 trim，之後長度必須為 1–1,000 字元。這些屬於 invalid-input 邊界，不要用同一份超限內容重試。\n\nClient 可自行提供 `nodeId`，讓 `add_node` 具備 idempotent retry：相同 ID 與相同內容會回既有 row；相同 ID 但內容不同會 conflict。`clientMutationId` 只會 echo 給前端 reconciliation，不影響 server identity、冪等性或持久化狀態。\n",
  "aliases": [
    "root 節點",
    "搬移分支",
    "節點 parent",
    "node id 重試",
    "tree cycle",
    "mindmap forest"
  ],
  "tags": [
    "mindmap",
    "root",
    "forest",
    "invariant"
  ],
  "relatedActions": [
    "arinova.mindmap.create_mindmap",
    "arinova.mindmap.add_node",
    "arinova.mindmap.move_node",
    "arinova.mindmap.delete_node",
    "arinova.mindmap.delete_node_promote_children",
    "arinova.mindmap.replace_outline"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/zh-tw/kb/mindmap/tree-and-root-invariants/"
}
---

一張 Mindmap 可有零到多個 roots。`add_node` 省略 `parentId` 或傳 null 會建立獨立的單節點樹；可傳 `manualOffset` 設定畫布 anchor。Root 可用 `move_node` 掛到同一張圖的任一 active node 下，將兩棵樹合併。非 root 以 `newParentId: null` 搬移時，會把整個 subtree 斷開成新 root，且必須傳當下絕對 `manualOffset`；已是 root 再搬到 null 會 conflict，重新定位應更新 layout。

每個節點仍最多只有一個 parent，且 `move_node` 不可把節點搬到自己或任何 descendant 底下。非 null 的新 parent 必須是同一張 Mindmap 的 active node；另一張圖或不存在的 parent 會失敗，不會建立跨圖 edge。對 root 呼叫 `delete_node` 會把該整棵樹當成同一 batch 軟刪；對 root 呼叫 `delete_node_promote_children` 則只刪 root，讓每個 direct child 成為獨立 root。即使已有其他 active roots，也可 restore 已刪 root。

單張 Mindmap 最多有 2,000 個 active nodes。Label 會先 trim，之後長度必須為 1–1,000 字元。這些屬於 invalid-input 邊界，不要用同一份超限內容重試。

Client 可自行提供 `nodeId`，讓 `add_node` 具備 idempotent retry：相同 ID 與相同內容會回既有 row；相同 ID 但內容不同會 conflict。`clientMutationId` 只會 echo 給前端 reconciliation，不影響 server identity、冪等性或持久化狀態。