kunchenguid/treehouse

解決的問題

Treehouse 管理一個可重複使用、相互隔離的 git worktree 池，消除手動處理同一個倉庫多個克隆版本的需要，或為每個 AI 代理會話創建新的 worktree。它防止代理之間產生衝突，並確保依賴項和建構快取在會話之間得以保留，從而加快代理執行速度。

工作原理

Treehouse 在配置的根目錄中維護一個 worktree 池（默認為 ~/.treehouse/）。當使用者或代理請求一個 worktree 時，Treehouse 會掃描池中是否存在閒置、乾淨且可重用的 worktree。若找到，則將該 worktree 重置到最新的預設分支；否則，會以分離 HEAD 模式創建一個新的 worktree。

關鍵機制包括：

• 子殼存取：使用者會被放入 worktree 內的子殼中；退出殼層後，worktree 會返回池中。
• 持久租用：worktree 可以租用以進行持久使用，無需長時間運行的進程，必須使用明確的還原命令才能回收。
• 使用中檢測：工具會掃描正在運行的進程和預留狀態，確保不會將正在使用的 worktree 發放出去。
• 安全檢查：預設情況下，worktree 的清理和刪除操作為預演模式，僅移除乾淨且已合併到預設分支的 worktree，除非使用特定的覆蓋標誌。

適用對象

需要為同一專案建立多個隔離環境，但又不希望承受克隆的開銷或失去建構快取的開發者和 AI 代理操作員。

特色

• 即時隔離：無需手動設定，快速進入一個乾淨的 worktree。
• 可重用環境：保留依賴項和建構快取，避免重複安裝。
• 無衝突：自動檢測正在使用的 worktree，防止代理之間互相干擾。
• 安全管理：強大的清理機制，可清除孤立的 worktree，並支援損壞池狀態檔案的狀態恢復。