Worktree-based Runtime Orchestrator for Multi-Agent Development，Runtime Orchestrator

-

最近做了Worktree-based Runtime Orchestrator for Multi-Agent Development，當工作流開始用worktree 做 多工處理，在做git追蹤的時候，多工agent就會遇到branch環境汙染的問題。

多agent ，在同一個workspace，切git分支 ，會造成環境混亂
A agent > fix/something_wrong
B agent > chore/design_system
C agent > feat/realtime-sync-design
D agent > doc/readme

這時候就適合用git worktree : allows you to have multiple branches of the same repository checked out simultaneously in separate directories。

git worktree就是一個git有多個本地倉庫，是在同一個倉庫下「開分身」也就是worktree，不是「複製整份倉庫」。
換句話說每個agent 有自己的實驗室，不用擔心互相影響，只需存新工作目錄的檔案，不需複製整個物件資料庫。

如果專案又在docker上執行，那每開一個worktree，執行檔會很大~~
所以如果把執行檔抽出來，那就runtime不會跑那麼大了。

於是就設計一個開發流調度規範，runtime就能做動態掛載，也不用每次都會因為worktree docker 就有一個肥大的執行檔。


Git Worktree Automation (GWA)

「以 Worktree 為核心的 AI 協作開發框架」

## 1. 主題：什麼是 以 Worktree 為核心的 AI 協作開發框架？

這是一套基於 Git Worktree 的開發流調度規範。它將開發環境拆解為三個平面：

  1. 邏輯平面 (Logic Plane)：透過 Git Worktree 實現任務間的代碼物理隔離。

  2. 資產平面 (Asset Plane)：透過「硬連結/Junction」管理大型靜態資源，解決空間肥大問題。

  3. 運行平面 (Runtime Plane)：透過動態掛載與同步，實現多個任務空間對單一執行環境的無縫切換。

## 2. 為什麼有這個想法？

在 AI Agent 參與開發 的時代，傳統的分支切換（git checkout）與單一工作區模式面臨崩潰：

  • AI 需要穩定的物理路徑：AI 在操作檔案時，如果檔案頻繁因為切換分支而消失/出現，會導致 AI 的路徑索引失敗。

  • 並行任務的常態化：我們經常需要讓 AI 跑任務 A 的同時，人類在任務 B 進行 Code Review，而測試環境卻只有一個。

  • 資源與效能的拉鋸：大檔案（影片/模型）放進 Git 太重，不放進 Git 又難以同步。

## 3. 解決什麼問題？

  • 硬碟空間爆炸：避免每個工作區都重複存放 GB 級的大型資產。

  • 環境切換成本：解決切換任務時需要重啟 Docker、重裝 node_modules 或重啟 Dev Server 的等待時間。

  • 資產衝突與污染：透過 wt-claim 機制，解決「共享資產」與「特定任務需修改資產」之間的矛盾。

  • AI 語境混亂：為每個 AI 提供獨立的 Worktree，確保它的操作範圍被限制在物理隔離的目錄內。

## 4. 好處是什麼？

  • 毫秒級切換：wt-use 透過軟/硬連結與增量同步，讓環境切換在瞬間完成。

  • 零成本資產管理：無需安裝與付費 Git LFS，利用 Linux/Windows 原生檔案系統特性達到相同效果。

  • 真相透明化：所有的切換與 Claim 紀錄都在 .wt/ 資料夾中以純文字存檔，人類與 AI 都能輕易追蹤系統狀態。

  • 高擴展性：這套架構不綁定任何語言或工具，只需一份 Markdown 規範文件，任何具備 Tool-use 能力的 AI 都能自我驅動這套系統。

## 5. 無法解決的問題 (非架構本身問題)

這套專注於「空間管理與環境調度」，以下問題屬於外部範疇：

  • 程式碼邏輯衝突 (Merge Conflicts)：雖然 Worktree 隔離了修改過程，但最終 git merge 時的邏輯衝突仍需透過 Git 原生機制解決。

  • 資料庫遷移同步 (DB Migration)：若任務 A 更改了資料庫結構，而單一 Runtime 連接同一個資料庫，任務 B 的執行可能會失敗。這屬於資料庫版本控制範疇。

  • 網路埠佔用 (Port Conflict)：GWA 傾向於「單一 Runtime」，但如果使用者嘗試同時啟動多個 Worktree 的服務且未更改 Port，仍會衝突。

  • 非檔案類的狀態遺失：存放在記憶體（Redis/Local Storage）中的狀態，在 wt-use 切換後仍會保留，這可能導致測試時的前後任務干擾。






留言

張貼留言