Worktree-based Runtime Orchestrator for Multi-Agent Development，Runtime Orchestrator
Worktree-based Runtime Orchestrator
for Multi-Agent Development
當多個 AI Agent 同時在同一個 repository 開工，傳統的 git 分支切換模式開始崩潰。 這篇文章介紹一套以 Git Worktree 為核心的開發流調度規範——用三個平面解耦邏輯、資產與 Runtime， 讓每個 Agent 擁有獨立的物理工作空間，同時共享同一個執行環境。
1. 問題是怎麼來的
當工作流開始用 worktree 做多工處理，在做 git 追蹤的時候，多工 agent 就會遇到 branch 環境污染的問題。 想像四個 Agent 同時在跑：
fix/something_wrongB agent →
chore/design_systemC agent →
feat/realtime-sync-designD agent →
doc/readme
在同一個 workspace 做 git checkout，就會造成環境混亂——AI 的路徑索引失效、任務互相干擾、
Docker 需要重啟。這就是 Git Worktree 派上用場的地方。
git worktree allows you to have multiple branches of the same repository checked out simultaneously in separate directories。
換句話說，每個 Agent 有自己的實驗室，不用擔心互相影響，
只需存新工作目錄的檔案，不需複製整個物件資料庫。
但問題來了：如果專案又在 Docker 上執行，那每開一個 worktree，執行檔會很大。 解法是把執行檔抽出來做動態掛載，讓 Runtime 不會因為 worktree 的數量而線性膨脹。
2. 什麼是三平面架構（GWA）
Git Worktree Architecture 將開發環境拆解為三個平面，各自解決不同層次的問題：
邏輯平面
透過 Git Worktree 實現任務間的程式碼物理隔離，每個 Agent 獨立的分支目錄，互不影響。
資產平面
透過硬連結 / Junction 管理大型靜態資源，解決硬碟空間肥大問題，無需 Git LFS。
運行平面
動態掛載與增量同步，多個任務空間對單一執行環境無縫切換，毫秒完成。
三個平面的分離是這套架構的核心設計思想：程式碼隔離、資產共享、Runtime 唯一。 Control Plane 負責協調三者的狀態，使同步、依賴安裝、reload 各自解耦，互不阻塞。
3. 傳統模式在 AI 時代的四個崩潰點
AI 路徑索引失效
AI 在操作檔案時，如果檔案頻繁因為切換分支而消失或出現，會導致 AI 的路徑索引失敗，任務中斷。
並行任務無法共存
我們經常需要讓 AI 跑任務 A 的同時，人類在任務 B 進行 Code Review，而測試環境卻只有一個。
大型資產的空間拉鋸
大檔案（影片 / 模型）放進 Git 太重，不放進 Git 又難以同步，兩難困境無解。
環境切換成本高
任務切換需重啟 Docker、重裝 node_modules 或重啟 Dev Server，等待時間吞噬開發節奏。
4. 核心指令流程
GWA 定義了一組標準化指令，搭配 Dependency Reconciliation Pipeline 確保環境一致性：
wt-init — 初始化 Worktree
以 git worktree add 為各 Agent 任務分支建立獨立目錄，在 .wt/ 資料夾記錄路由與狀態。
wt-use — 切換工作任務
透過增量同步將 Runtime 環境切換至目標 Worktree，毫秒完成，不重啟 Docker。觸發 dependency reconciliation pipeline。
wt-install — 依賴調和
偵測目標 Worktree 的依賴差異，只安裝 delta 部分，共享不變的依賴，避免重複安裝。
wt-reload — Hot Reload
通知 Runtime 執行 hot reload，Runtime Invalidation 機制確保 asset promotion 與 reload 的一致性。
wt-claim — 獨佔資產
需要修改共享資產時，解除硬連結並複製副本至當前 Worktree，避免污染其他任務的資產平面。
5. 多維狀態模型：避免不一致 Runtime 執行
GWA 設計了三個維度的狀態追蹤，任一維度 invalid 時，系統拒絕執行測試或 deploy， 直到 reconciliation 完成：
| 狀態維度 | 意義 | 觸發時機 |
|---|---|---|
| runtime_sync | Runtime 是否與目標 Worktree 的程式碼同步 | wt-use 切換後尚未 reload |
| dependency_sync | 依賴版本是否與 package.json / lockfile 一致 | 切換至有新依賴的 Worktree |
| execution_validity | 整體執行環境是否可信任（前兩者皆 valid） | 任一維度 invalid 時自動降級 |
搭配 event-driven lifecycle 與 snapshot 驗證流程，所有狀態轉移都有紀錄， 支援 agent coordination 與 deterministic replay，讓除錯有跡可循。
6. 核心技術優勢
Runtime Projection
Shared Runtime + Isolated Worktree，切換分支不重建環境。
Control Plane 分離
同步、依賴安裝、reload 解耦，各自獨立觸發不互相阻塞。
Lazy Copy-on-Write
資產按需物化，共享依賴重用，大幅減少磁碟消耗。
多 Worktree 並行
每個 AI Agent 獨立 Worktree，並行效率最大化，彼此不干擾。
Event-driven Lifecycle
Snapshot 驗證 + deterministic replay，可觀測性大幅提升。
真相透明化
所有狀態以純文字存入 .wt/，人類與 AI 都能即時追蹤。
7. 架構邊界：這套不解決什麼
GWA 專注於「空間管理與環境調度」，以下問題屬於外部範疇，設計上刻意不涵蓋：
程式碼邏輯衝突（Merge Conflicts）
Worktree 隔離了修改過程，但最終 git merge 的邏輯衝突仍需透過 Git 原生機制解決。
資料庫遷移同步（DB Migration）
若任務 A 更改了資料庫結構，而單一 Runtime 連接同一個資料庫，任務 B 的執行可能會失敗。屬於資料庫版本控制範疇。
網路埠佔用（Port Conflict）
GWA 傾向「單一 Runtime」，但如果嘗試同時啟動多個 Worktree 的服務且未更改 Port，仍會衝突。
非檔案類的狀態遺失
存放在記憶體（Redis / Local Storage）中的狀態，在 wt-use 切換後仍會保留，可能導致前後任務干擾。
留言
張貼留言