協同擴充模組

History、Thread Comment 和 Worktree 是可按需啟用的獨立協同擴充模組。它們可重用 Transport、身分系統及實體資料庫，但各自保有 Service、Middleware、Event、Database Adapter 與生命週期邊界。

服務端 Office 檔案轉換是一項應用流程：將檔案轉換與 Collaboration Service API 組合，而非開啟主 Service 的功能開關。

模組關係

History、Thread Comment 和 Worktree 各自設定 Middleware、Events 與 Database Adapter。

版本歷史

History 將 Unit 建立及已確認變更集分組為使用者可見的歷史項目。它是衍生索引：Unit 內容的權威來源仍是核心 Collaboration Service 中已確認的變更集。

const historyService = new UniverHistoryService({  collabService,  dbAdapter: historyDatabase,  userProvider,});transport.register(new UniverHistoryEndpoint(historyService));

建構 History Service 時即訂閱核心 Service 的 unitCreated 和 changesetCommitted Events 並更新索引。dispose() 會解除這些訂閱。預設策略按時間視窗與特殊 mutation 分組，而非每個變更集建立一筆歷史。

History 提供 getHistoryList、listHistoryCreators 與 getHistoryChangesets 讀取 Middleware。索引由 Service 在內部維護。userProvider 只補充名稱、頭像等顯示資料，不負責驗證或授權。Event Listener 失敗不會回滾已確認的核心變更集，因此應始終將 History 視為可重建的衍生資料。

討論串留言

Comment Service 管理 Sheets 和 Docs 的留言本文、回覆、編輯、刪除及已解決狀態：

const commentService = new UniverCommentService({  database: commentDatabase,  userProvider,});transport.register(  new UniverCommentEndpoint({    service: commentService,    roomHost: collabEndpoint,  }),);

留言本文屬於 Comment Adapter。隨 Sheet 或 Doc 內容移動的錨點仍屬於核心快照與變更集。Comment Endpoint 可透過主 Collaboration Endpoint 的 Unit Room 發布 comment_update，但即時訊息不是權威留言狀態；用戶端可重新取得留言清單以還原。

Comment Service 提供新增、清單、回覆、解決／重新開啟、編輯、刪除的 Middleware，以及 commentCommitted Event。它不繼承核心 Service 的讀取或編輯策略。

Worktree 草稿與合併

Worktree 為一個或多個 Unit 增加隔離草稿、凍結、合併評估與逐 Unit 合併：

create → draft → ready → merging → merged           ↑       │           └ reopen┘draft / ready → discarded

const worktreeService = new UniverCollabWorktreeService({  trunk: {    service: collabService,    dbAdapter: coreDatabase,  },  dbAdapter: worktreeDatabase,});

Worktree 以 (worktreeID, unitID) 儲存獨立草稿變更集，同時重用核心 Service 的 Unit、OT 與提交引擎。只有 draft 狀態接受後續編輯。markReady() 凍結目前草稿修訂版本，mergeWorktree() 將 Unit 逐一合併到主幹。

Worktree Service 有獨立的生命週期、讀取、草稿 submit/apply/commit Middleware，以及建立、狀態變更、合併結果、草稿變更集提交的 Events。最終寫入主幹仍會通過核心 Service 自身的 Middleware。

多 Unit 合併並非跨 Unit 原子操作。應用應顯示每個 Unit 的合併結果。

服務端 Office 檔案轉換

服務端 Exchange 結合 @univerjs-pro/exchange-node 和 Collaboration Service API，在檔案與協同狀態之間轉換：

Office 檔案  → exchange-node 匯入  → Snapshot + Sheet Blocks  → createUnitFromSnapshot()已確認的 Unit 修訂版本  → getUnitLoadDataWithBlocks()  → UnitSnapshotMaterializer  → exchange-node 匯出  → Office 檔案

官方範例將 XLS、XLSX、CSV 或 TSV 匯入為新的協同 Sheet，並將目前已確認修訂版本匯出為 XLSX、CSV 或 TSV。

檔案儲存、任務狀態、存取控制、大小限制與業務 API 由應用負責。Exchange 沒有獨立的協同 Database Adapter；它透過核心 Service 讀取或建立權威 Unit。

獨立擴充點

啟用擴充模組時，分別評估每個邊界：

這些 Adapter 可使用相同 SQLite 檔案，但仍是具有獨立契約的不同物件。Service 和 Adapter 也應分別釋放。

選擇能力

完整執行命令與頁面網址請參閱範例索引。

連接 Web SDK 歷史介面

將 History Endpoint 與協同端點一起掛載。Web SDK 的 historyServerUrl 是 /{unitId}/list、/{unitId}/creators 與 /{unitId}/cs 的共同前綴，預設為 /universer-api/history。若使用其他前綴，請為宿主 History 外掛與品類 History UI 外掛設定相同位址。

還原版本會透過協同 mutation 提交，不是呼叫獨立的歷史還原 REST 介面。請保留協同載入、提交與授權設定。createUnitComparisonEngine() 對兩份完整快照進行唯讀比較，不需要執行歷史服務，也不會儲存或還原版本。