第 9 章 Worktree 并行任务：两个 Agent 不打架
如果你是开发或者做过代码相关的任务，一定遇到过这个场景：
你在本地分支上让 AI Agent 改一个功能，改到一半发现另一个紧急 bug 要先修。但 Agent 正占着当前工作区，工作区里一堆未提交的改动。你只能让它停下来，要么手动 stash，要么开一个新的终端切分支——然后两边改完合并回来，冲突一堆。
WorkBuddy 的 Git Worktree 并行任务就是为了解决"一个工作区只能跑一个 Agent"的问题。
什么是 Worktree
Worktree 是 Git 的原生能力——它允许你为同一个仓库创建多个独立的工作目录，每个工作目录可以检出不同的分支，互不干扰。
WorkBuddy 把这个能力封装成了任务级别的并行机制：你可以在同一个仓库下，同时开多个 Agent 任务，每个任务跑在自己的 worktree 工作目录里，改的是各自的分支，互不影响。
| 对比 | 传统单工作区 | Worktree 并行任务 |
|---|---|---|
| 同时执行的任务数 | 1 个 | 多个 |
| 切换任务时的工作区状态 | 需 stash 或提交 | 不用动，各自独立 |
| 分支冲突风险 | 高，来回切容易冲突 | 低，每个任务独立分支 |
| 适合场景 | 串行开发 | 多任务并行、对照修改 |
当你的工作区包含 Git 仓库时，所有 Git 相关操作都可以直接在 WorkBuddy 里完成，不用切到终端或 IDE。
Git 分支显示与切换
在 WorkBuddy 里创建任务时，如果当前工作区是一个 Git 仓库，界面会显示当前所在的分支。
你可以直接在 WorkBuddy 里切换到其他本地分支或远程分支，切换面板还支持按名称搜索，分支多的时候不用翻列表。
切换分支时怎么处理未提交的改动
切换分支最麻烦的不是切本身，而是当前分支上还有没提交的改动。Git 不允许你在有未提交改动的情况下直接切分支（会报错或者把改动带过去）。
WorkBuddy 在你切换分支时，会弹出确认面板，给你三种选择：
| 选项 | 做什么 | 适合场景 |
|---|---|---|
| 提交到当前分支（默认） | 自动把改动 commit 到当前分支，然后切换 | 改动是有意义的，应该保留 |
| 暂存改动（stash） | 用 git stash 暂存改动，切完可以恢复 | 改动还没到提交的时候，但不想丢 |
| 丢弃改动 | 直接放弃未提交的修改 | 改动是试验性的，不需要了 |
默认选第一个——提交到当前分支。这样最安全，改动不会丢，切换后也干净。
如果你选 stash，记得切回来之后用 git stash pop 恢复。如果你选丢弃，改动就找不回来了，慎用。
创建 Worktree 并行任务
创建 Worktree 并行任务的过程跟创建普通任务几乎一样，只多了一步开关。
操作步骤：
- 像平时一样输入任务说明；
- 在任务创建面板里，打开 Worktree 开关；
- 选择 Base Branch（基准分支），也就是新 worktree 要从哪个分支拉出来；
- 发送任务；
- 等待进度条走完，Agent 自动开始执行。
创建过程中，WorkBuddy 会自动完成以下操作：
| 自动动作 | 说明 |
|---|---|
| 创建 worktree 目录 | 在 ~/WorkBuddy/Worktrees 下新建独立工作目录 |
| 创建任务分支 | 分支命名格式为 workbuddy/{base-branch}-{8位hash} |
| 检出分支 | 在新 worktree 目录中检出任务分支 |
比如你从 main 分支创建一个 Worktree 任务，生成的任务分支可能长这样：
workbuddy/main-a1b2c3d4这个分支名是自动生成的，你不需要手动指定。Base Branch 在任务创建后就锁定了，不能中途改。
创建完之后，这个 Agent 任务就在自己的 worktree 目录里独立运行，你可以同时创建另一个普通任务或 Worktree 任务，两边互不干扰。
怎么区分哪个是 Worktree 任务
当任务列表里有好几个任务时，怎么区分哪个是 Worktree 任务？
两个标识：
- 任务列表里的 Fork 图标。 Worktree 任务会带一个分叉图标，一眼就能认出来。
- 分支徽标。 任务上会显示它所在的任务分支名（如
workbuddy/main-a1b2c3d4），跟普通任务的分支名不一样。
看到这两个标识，你就知道这个任务跑在独立的 worktree 工作目录里，改的是它自己的分支，不会影响主工作区。
自动清理
Worktree 会创建独立的工作目录，每个占一份磁盘空间。用多了不清理，硬盘会越来越大。
WorkBuddy 有两级自动清理机制：
| 阈值 | 触发动作 |
|---|---|
| 累计 25 个 worktree | 提示警告，建议清理 |
| 累计 50 个 worktree | 强制弹出清理确认，必须处理才能继续创建 |
所以不需要你时刻记着清理。到了 25 个系统会提醒你，到了 50 个系统会拦住你，等你确认清理之后才能继续创建新的 Worktree 任务。
清理时，已完成的任务对应的 worktree 可以放心删；进行中的任务先等它跑完或停掉再清理。
使用建议
并行任务用 Worktree，串行任务用普通模式。 Worktree 的价值在于并行，如果你只有一个任务在跑，没必要开 Worktree，徒增管理成本。
Base Branch 选好再创建。 任务创建后 Base Branch 就锁定了，不能改。创建前想清楚你要从哪个分支拉——一般从
main或develop拉，不要从别的任务分支拉（V1 也不支持从已有的 Worktree 任务 fork）。用分支名追踪任务。 任务分支名里包含 Base Branch 和 hash，遇到合并冲突时，靠分支名就能判断是哪个任务改的。
及时清理已完成的 Worktree。 任务做完、代码合并后，对应的工作目录就没用了。在 25 个的警告线之前主动清理，避免堆积到 50 个被系统拦住。
V1 有这些限制要记住。 当前版本（V1）不支持云同步、不支持非 Git 仓库的 Worktree、不支持多仓库 Worktree、不能从已有的 Worktree 任务再 fork 出新的。如果你的项目不是 Git 仓库，或者需要多仓库并行，V1 暂时用不了 Worktree。
未提交改动优先选"提交到当前分支"。 切换分支时的三个选项里，默认的"提交到当前分支"最安全——改动有记录、不会丢、切回来也干净。除非你确定改动是临时试验，否则别选"丢弃改动"。