11 · Git 整合與並行任務
這一篇面向開發者
如果你不寫程式碼、工作空間裡沒有 Git 倉庫，這一章可以跳過——介面上相關入口會保持置灰。
當工作空間內包含 Git 倉庫時，原本需要切到終端或 IDE 才能完成的 Git 操作，可以直接在 WorkBuddy 內完成。兩項能力：
- 分支從隱式變顯式——建立任務時即可檢視當前檢出的分支，並安全切換
- 多工並行且互不干擾——讓多個任務在相互隔離的工作目錄中並行執行，檔案系統層面完全隔離
兩項能力都建立在 Git 原生語義之上——不引入額外概念，熟悉 Git 的人可以直接推斷系統的真實行為。
一、分支顯示與切換
建立任務時選分支
工作空間內包含 Git 倉庫時，新建任務頁面會顯示當前分支並支援直接切換：
- 顯示當前分支——預設展示當前檢出的本地分支名
- 切換分支——點分支選擇器，可切換至其他本地分支或遠端分支，支援搜尋
- 切換確認——切換分支後點傳送初始任務指令時會彈出確認對話方塊；未切換分支則不需要確認，直接開始
分支選擇器的狀態：
| 工作空間型別 | 分支選擇器 |
|---|---|
| 普通資料夾（非 Git 倉庫） | 不可操作（置灰） |
| 正常 Git 倉庫 | 可操作 |
有未提交改動時怎麼辦
切換分支時，如果當前工作區存在未提交的改動，確認彈窗提供三種處理方式：
| 處理方式 | 說明 |
|---|---|
| Commit 到當前分支（預設） | 彈出輕量提交面板，勾選變更檔案並填寫提交資訊，提交完成後再切換 |
| Stash 變更 | 自動把當前改動（含未跟蹤檔案）暫存起來，再切換 |
| 丟棄變更 | 放棄所有未提交的改動後切換，需二次確認 |
預設選中 Commit 是有道理的
Commit 是三者裡最安全的：改動進了歷史，隨時能找回來。
Stash 也能找回，但 stash 棧很容易被人忘掉——尤其是當 stash 是工具替你做的、而不是你自己敲的時候。
丟棄是真的沒了。它需要二次確認，請把那次確認當回事。
兩條保障機制：
- 若切換失敗，工作區會完整回滾到操作前的狀態，不會殘留中間態
- 選擇遠端分支時，系統會自動建立同名本地分支並跟蹤該遠端分支，再切換過去；若本地已存在同名分支，會提示你手動命名
執行中的分支顯示
在已有任務的對話介面中，工作區狀態列會即時顯示當前檢出的分支名，分支發生變化後自動重新整理。
這個顯示比看起來重要：多工並行的時候，「我現在這個 Agent 到底在哪個分支上改東西」是最容易搞混的事。
二、Worktree 並行任務
它是什麼
Worktree Task 利用 Git worktree 的原生能力，為每個並行任務提供完全隔離的工作目錄，同時與主倉庫共享分支和 Git 物件。
適用場景：你需要同時推進多個獨立任務（新特性開發、bug 修復、實驗性方案），又不希望它們與你當前的工作目錄互相干擾。
不開 Worktree 的話，兩個 Agent 在同一個目錄裡改檔案，結果是互相覆蓋、diff 混成一團。
建立
- 在新建任務頁面輸入任務指令
- 工作空間包含
.git目錄時，輸入框下方會展示 Worktree 開關（預設關閉） - 開啟後展開 Base Branch（基礎分支） 選擇器，預設選中本地主分支（如
main），可切換為其他本地或遠端分支，支援搜尋與 fetch 重新整理 - 傳送任務指令，系統開始建立，介面即時展示建立進度（大型專案可能需要數十秒到一分鐘）
- 建立完成後，Agent 自動啟動並執行任務指令
建立時系統自動完成三件事：
- 在
~/WorkBuddy/Worktrees目錄下建立獨立的 worktree 工作目錄 - 基於所選 Base Branch 的 HEAD commit 新建任務分支，命名格式為
workbuddy/{基础分支}-{8位随机哈希}（如workbuddy/main-a3f8c2b1）。字首workbuddy/用於與你手動建立的分支區分 - 建立失敗時自動回滾已建立的 worktree 與分支，不遺留半成品資源
三條約束
- 非 Git 專案（無
.git目錄）不展示 Worktree 開關，只能建立普通任務 - Base Branch 在任務建立後鎖定，不可修改；任務分支在生命週期內也不提供切換入口
- 建立任務時源工作區存在未提交改動不影響建立，新任務基於所選 Base Branch 的 HEAD commit 開始，不包含未提交改動
第三條容易踩：你手上改了一半的程式碼，不會跟著進 worktree。想帶過去，先 commit 或者 stash 後 apply。
任務標識
Worktree Task 在任務列表和詳情頁中有明確標識：
- 型別標識——任務列表標題前展示獨特的 fork 型別圖示，與普通任務明確區分；任務在列表中仍按原專案分組
- 分支標識——任務卡片與任務標題旁展示當前分支 Badge（如
workbuddy/main-a3f8c2b1），只讀展示，hover 檢視詳情，點選可複製分支名
自動清理
為避免 Worktree Task 持續累積佔用磁碟空間，系統有清理策略（僅針對 Worktree Task，建立普通任務不受任何限制）：
| 數量 | 行為 |
|---|---|
| 達到 25 個 | 在首頁建立新 Worktree Task 時展示數量較多的提示，建議清理 |
| 達到 50 個 | 勾選 Worktree 後彈出「任務工作區已達上限」清理確認彈窗，需選擇清理範圍（清理超過 7 / 15 / 30 天前的任務工作區分支和檔案），確認後才能繼續建立；取消則阻塞建立 |
別等到 50 個
每個 worktree 都是一份完整的工作目錄副本。大型專案 50 個 worktree 能吃掉相當可觀的磁碟。
養成習慣：任務做完、分支合併之後順手清理。或者定期在數量提示出現時（25 個）就處理一次。
什麼時候該用 Worktree
| 用普通任務 | 開 Worktree |
|---|---|
| 輕量改動、單點查詢 | 需要並行推進多個任務 |
| 只有一個 Agent 在幹活 | 多個 Agent 同時改程式碼 |
| 改動馬上就要合回去 | 隔離試驗性方案，可能會丟棄 |
| 小專案，建立 worktree 的開銷不值 | 大專案，混在一起 diff 會亂 |
官方的建議原話是：輕量改動、單點查詢使用普通任務即可；需要並行推進多個任務或隔離試驗性方案時，再開啟 Worktree。
建立 worktree 在大專案上要花幾十秒到一分鐘，這個成本對一次小修改來說不划算。
一個實際的用法
假設你要同時推進三件事：修一個線上 bug、開發一個新特性、試一個重構方案。
任务 A（Worktree，base: main）
修复登录页在 Safari 下的白屏问题，先复现再改。
任务 B（Worktree，base: develop）
给设置页加一个导出配置的功能，参考 docs/api.md 里的格式约定。
任务 C（Worktree，base: main）
试试把状态管理从 Redux 换成 Zustand，只改 src/store 下面的，不要动组件。三個任務在三個隔離目錄裡跑，各自有獨立的分支。C 試崩了直接刪掉分支，A 和 B 完全不受影響。
常見問題
Q：worktree 裡的改動怎麼合回主倉庫？
標準 Git 流程。任務分支是真實的 Git 分支，push、開 PR、merge 都照常。這就是「建立在 Git 原生語義之上」的意思。
Q：能在 IDE 裡開啟 worktree 目錄嗎？
能。~/WorkBuddy/Worktrees 下面就是普通的工作目錄。任務列表裡右鍵「打开文件夹」也能直接定位。
Q：清理 worktree 會刪掉分支上的提交嗎？
清理會移除 worktree 工作目錄和對應的任務分支。分支上的提交如果沒有 merge 或 push 到別處，就跟著沒了。重要的改動先合併或推送。
Q：當前版本還有什麼不支援的？
官方標註為 V1 版本，部分能力還在完善中，以你客戶端裡的實際表現為準。
進階章節到此結束
接下來兩條路：