Worktree
了解草稿隔離、版本基線、OT 合入,以及 AI SDK 如何串接 Agent 與人類審閱。
Worktree 為 Office 內容提供隔離的草稿,人和 Agent 仍可在草稿上協同編輯。Agent 可以修改預算、整理資料或重寫方案,同時人繼續編輯主文件,也就是 trunk。草稿經過驗證和審閱之後,其修改才會合入主線。
隔離的物件是文件內容及其變更,而不是 Git 的工作目錄。一個任務可以跨越多個 Unit(內容單元),例如一個工作簿、一篇文件和一份簡報。
隔離原理:從共同基線演進
為已有 Unit 建立 Worktree 時,伺服器端會把該 Unit 當前主線的 revision 記錄為 Baseline(基線)。草稿從這一版本開始,擁有獨立的 Snapshot、changeset、revision、Presence 和協同 Room。草稿中的修改不會進入主線。
| 概念 | 作用 |
|---|---|
| Baseline | 草稿起始的主線版本,用於比較和合入。 |
| Draft head | 草稿中最新的已確認版本,每次向草稿提交都會推進該版本。 |
| Ready head | 標記 Ready 時凍結的草稿版本,決定本輪審閱和合入的內容。 |
主線和草稿獨立演進。revision 只描述各自的提交序列,因此僅比較數字大小無法判斷哪一方的內容更新。拉取草稿只會同步草稿自身的修改。主線上的新修改不會自行進入正在審閱的版本,需要由合入預覽和正式合入進行協調。
AI SDK 如何連接草稿
AI SDK 的 Collaboration Runtime 負責一個 Unit 的快照、changeset 和 revision。Worktree 的建立、生命週期與合入由 Server SDK 的 Worktree 服務負責。Runtime 不需要為 Worktree 再內建一套文件編輯引擎。
應用將 worktreeID + unitID 解析為草稿的 snapshot、submit、WebSocket 和 Session Ticket 地址,並交給 Runtime。這樣,同一套檢查和編輯工具既可以作用於主線,也可以作用於草稿。
同一個 Unit ID 可以同時存在於主線和多個 Worktree 中,因此 target 必須指明它所在的 Worktree。inspect、execute、截圖和 Web 預覽都應使用同一個 target,否則工具可能從草稿讀取,卻向主線寫入。Web 端使用與該草稿匹配的協同配置載入同一份草稿。
| 分工 | 負責內容 |
|---|---|
| Web SDK | 共用的內容引擎,既用於 Agent 在 Headless 中的操作,也用於在瀏覽器中編輯。 |
| Server SDK | 隔離草稿、持久化 changeset 與 revision、管理生命週期,並執行 OT 合入。 |
| AI SDK | 可組合的 Runtime、Inspection、API 查詢、Facade 執行和視覺檢查。 |
| 你的應用 | 選擇模型、對映 target、管理身分與授權,以及組織任務和審閱介面。 |
Agent 從編輯到交付
應用可以為每個 Agent 分配獨立的 Worktree,從而並行執行任務。Agent 編輯草稿、檢查結果,然後將草稿標記為 Ready。人再逐份審閱草稿,對需要進一步修改的草稿執行 Reopen,並把透過的草稿合入當前主線。
- 建立 Worktree 並載入:選擇任務涉及的 Unit,連線對應的 Worktree target,再
pull最新的草稿內容。 - 使用 Inspection 瞭解結構和資料,按需查詢 API,所有改動都透過 Facade 執行。
- 將修改提交到草稿,回讀資料和計算結果,必要時截圖。Slides 還可以執行 Layout Lint。如果檢查發現問題,則繼續修改草稿。
- 標記 Ready:凍結各 Unit 當前的草稿版本,停止編輯,等待審閱。
- 審閱:將透過的草稿 Merge;需要人或 Agent 繼續修改的草稿先 Reopen 回 Draft;不需要的草稿則 Discard。
| 操作 | 作用 |
|---|---|
runtime.commit() | 僅提交到草稿,並推進草稿的 revision。 |
markReady() | 固定待審閱的版本,不合入主線。 |
reopenWorktree() | 將草稿從 Ready 恢復為 Draft,以便繼續編輯。 |
mergeWorktree() | 將凍結的草稿修改逐個 Unit 合入主線。 |
Commit、Ready 和 Merge 是三個相互獨立的操作。草稿一旦進入 Ready,無論是人還是 Agent,都必須先 Reopen 才能繼續編輯。Runtime 與 CLI 的配合方式見 AI SDK Worktree 工作流。
合入原理:修改套用到最新主線
如果 Unit 來自主線,伺服器端會讀取 Baseline 到 Ready head 之間的草稿 changeset,收集其中的 mutation,再提交給主線的 Collaboration Service。如果主線在此期間已經前進,協同引擎會使用 OT(操作轉換),將這些 mutation 變換到其後的 trunk 修改上,再確認新的主線版本。
因此,合入是將修改應用到當前文件,而不是用舊快照覆蓋整個最新文件。可以轉換的並行修改會被協調。無法轉換或已不適用的修改會作為衝突返回,由應用處理。OT 也不會自動解決所有業務分歧。
在 Worktree 中新建的 Unit 沒有可合入的主線基線。合入時會在主線中建立該 Unit,但不會複製整段草稿 changeset 歷史。
審閱:改了什麼,合入會怎樣
- 如需檢視草稿做了哪些修改,可以使用內容比較對比基線與 Ready 草稿的完整內容,新增、刪除和修改都會列出。
- 如需瞭解當前合入的效果,可在 Ready 之後呼叫
evaluateUnitMerge()。主線已經前進時,該呼叫會在隔離的 Runtime 中將經 OT 轉換的候選修改應用到當前主線,生成只讀預覽;它不提交 changeset,也不會修改主線或草稿。
預覽只反映發起請求時的狀態。主線之後仍可能變化,實際的 Merge 會按執行時讀取到的主線狀態重新計算。多個 Unit 的合入也不是一個原子事務,因此某個 Unit 失敗時,已經合入的 Unit 會保留在主線中。需要逐個 Unit 展示結果,並逐個處理失敗。
接入與範圍
將 Worktree 的 Client、Service、Endpoint 和資料庫介面卡與協同核心組合。草稿使用獨立儲存,Session Ticket Store 與主線共用一份。草稿的訪問權限與主線的寫入權限由應用分別授權,隔離本身並不授予訪問權限。
目前支援 Sheet、Doc、Slide、Canvases 和 Relational Table,不包含 PDF。Worktree 範例、擴充套件模組和 Agent 接入指南是建議的起點。
你覺得這篇文檔如何?