---
{
  "id": "platform.doc.permissions-versioning-and-collaboration",
  "topic": "doc",
  "title": "Doc 權限、版本計數器與協作同步",
  "locale": "zh-TW",
  "version": "2026-08-25",
  "summary": "Doc 權限是使用者權限與 Agent grant 的交集；metadata version 是 concurrency counter，協作錯誤必須保留「已持久化」語意。",
  "content": "Doc 權限取 triggering user authority 與 Agent grant 的交集。Personal Doc 需 direct grant；shared-space Doc 可用 direct 或 Space grant。read grant 寫入回 `permission_denied`；無 read authority 回 `resource_not_found`，與不存在不可區分。`list_docs` 只回「使用者可見 ∩ Agent 可讀」；沒列出不代表不存在。\n\nMetadata `version` 是 optimistic concurrency counter，與耐久 history 不同。私有 history Actions 是 `list_versions`、`get_version`、`create_named_version`、`restore_version`。具名 checkpoint 不需 confirmation、採 Strict drift。Restore 需 UserConfirm、`docId`、`versionId`、目前 `expectedVersion`；它先保留 pre-restore checkpoint，再向前。衝突時重新 `get_doc`，不可盲目重送。\n\n成功寫入會先持久化，再同步到 Yjs live collaboration room。「saved but collaboration sync failed」代表內容已保存、live room 可能暫時落後；可安全重讀確認，不是資料遺失。\n\n`archive_doc` 需要 write access，會移出 active lists；`unarchive_doc` 用相同 owner/resource/space grant 檢查反轉 lifecycle state，兩個 mutation 都以執行 Agent 留下 audit attribution。`includeArchived: true` 仍可列出 archived Doc，`get_doc` 也仍可讀。\n\n永久 `delete_doc` 只能用於已 archived 的 Doc，需 UserConfirm 與 Strict drift，不能繞過 archive-first lifecycle safety。\n\n`export_doc` 接受 PDF、DOCX、HTML 或 Markdown，存入 personal File Center。它只解析已授權 ready images，不抓 external URL；dry-run 不建檔，runtime 為準。\n",
  "aliases": [
    "Doc permission",
    "document grant",
    "version conflict",
    "collaboration sync",
    "封存文件",
    "shared space document",
    "文件權限"
  ],
  "tags": [
    "doc",
    "permissions",
    "concurrency",
    "collaboration"
  ],
  "relatedActions": [
    "arinova.doc.get_doc",
    "arinova.doc.list_docs",
    "arinova.doc.archive_doc",
    "arinova.doc.unarchive_doc",
    "arinova.doc.export_doc",
    "arinova.doc.update_doc",
    "arinova.doc.append_content",
    "arinova.doc.set_page_settings",
    "arinova.doc.format_text",
    "arinova.doc.format_block",
    "arinova.doc.list_versions",
    "arinova.doc.get_version",
    "arinova.doc.create_named_version",
    "arinova.doc.restore_version",
    "arinova.doc.delete_doc"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/zh-tw/kb/doc/permissions-versioning-and-collaboration/"
}
---

Doc 權限取 triggering user authority 與 Agent grant 的交集。Personal Doc 需 direct grant；shared-space Doc 可用 direct 或 Space grant。read grant 寫入回 `permission_denied`；無 read authority 回 `resource_not_found`，與不存在不可區分。`list_docs` 只回「使用者可見 ∩ Agent 可讀」；沒列出不代表不存在。

Metadata `version` 是 optimistic concurrency counter，與耐久 history 不同。私有 history Actions 是 `list_versions`、`get_version`、`create_named_version`、`restore_version`。具名 checkpoint 不需 confirmation、採 Strict drift。Restore 需 UserConfirm、`docId`、`versionId`、目前 `expectedVersion`；它先保留 pre-restore checkpoint，再向前。衝突時重新 `get_doc`，不可盲目重送。

成功寫入會先持久化，再同步到 Yjs live collaboration room。「saved but collaboration sync failed」代表內容已保存、live room 可能暫時落後；可安全重讀確認，不是資料遺失。

`archive_doc` 需要 write access，會移出 active lists；`unarchive_doc` 用相同 owner/resource/space grant 檢查反轉 lifecycle state，兩個 mutation 都以執行 Agent 留下 audit attribution。`includeArchived: true` 仍可列出 archived Doc，`get_doc` 也仍可讀。

永久 `delete_doc` 只能用於已 archived 的 Doc，需 UserConfirm 與 Strict drift，不能繞過 archive-first lifecycle safety。

`export_doc` 接受 PDF、DOCX、HTML 或 Markdown，存入 personal File Center。它只解析已授權 ready images，不抓 external URL；dry-run 不建檔，runtime 為準。