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 版本，部分能力还在完善中，以你客户端里的实际表现为准。
进阶章节到此结束
接下来两条路：