Collaboration SDK 概覽

Univer Collaboration SDK 是面向 Univer 文件模型的服務端協同 SDK。它提供操作轉換（OT¹）、修訂版本²、快照、即時同步與持久化，讓多個 Univer 用戶端編輯同一份以服務端為準的 Unit。

開發者將它嵌入自己的 Node.js 應用，透過 Middleware 接入身分驗證與授權，並透過 Middleware 或 Events 擴充日誌及其他應用邏輯。Database Adapter 則負責將協同資料連接到應用資料庫。

解決的問題

Web SDK 在瀏覽器中呈現並編輯 Sheet、Doc、Slide、Board 和 Base 內容。多人編輯還需要由服務端載入內容、確認並行變更、推進修訂版本，並讓斷線用戶端恢復到一致狀態。

它適合以下應用：

• 已使用 Univer 建立編輯器，需要即時多人編輯；
• 希望自行託管協同資料並選擇資料庫；
• 需要將既有身分、授權或租戶規則接入協同操作；
• 需要在核心協同之上增加 History、Thread Comment 或 Worktree 能力。

完整的協同服務

SDK 提供的能力

核心能力包括：

• 建立、載入、刪除及還原 Sheet、Doc、Slide、Board 和 Base Unit；
• 快照、變更集、修訂版本、OT 與提交冪等性；
• HTTP 內容載入，以及 WebSocket Session、Room、Presence、ACK 與廣播；
• Transport、Endpoint 和 Service 邊界上的 Middleware；
• Unit 建立、變更集提交、刪除及還原的程序內 Events；
• Memory、SQLite 及自訂 Database Adapter 契約；
• 透過多節點部署水平擴展：節點之間以 pub/sub 介面卡與共用的 Session Ticket 儲存協同，SDK 提供 Redis 實作。

核心流程運作後，應用可加入版本歷史、討論串留言、Worktree 草稿及服務端 Office 檔案轉換。這些能力各自具有 Service、Middleware、Events 或 Database Adapter。

應用負責的能力

三種通用擴充點

身分與授權透過 Middleware 接入。在操作執行前以 Middleware 進行驗證和限制；狀態確認後，以 Events 記錄變更或觸發後續工作。兩者均可支援日誌、請求追蹤、指標與衍生狀態更新。執行邊界請參閱 Middleware 與 Events。

從哪裡開始

1. 執行快速開始，在兩個瀏覽器中驗證完整流程。
2. 閱讀模組邊界與關係，瞭解各套件的用途。
3. 根據整合需求，繼續閱讀 Middleware 與 Events、身分與授權或資料庫配接器。
4. History、留言、Worktree 與檔案轉換請參閱協同擴充模組。

Footnotes

1. 操作轉換（OT） 會調整基於不同文件修訂號並行產生的操作，使它們能一致地套用。它處理的是編輯操作，而非用最後抵達的快照覆蓋整份文件。 ↩

2. 修訂號（revision）標示 Unit 已確認編輯歷史中的位置。變更集（changeset）包含一次提交的操作，確認後會推進歷史。修訂號不是 SDK 套件版本，也不是時間戳記。 ↩