一任务一分支:zerostack Git Worktree 与 --parallel 并行代理的完整指南
一任务一分支:zerostack Git Worktree 与 --parallel 并行代理的完整指南
zerostack 是一款用 Rust 编写的轻量级编码代理(coding agent),它内置了完整的 Git worktree 集成:通过 /worktree 斜杠命令或 --parallel 命令行参数,你可以为每个任务自动创建独立分支和独立工作目录,让多个代理并行开发同一个仓库互不干扰,退出时再自动合并回主分支。
为什么 AI 代理需要「一任务一分支」
当 AI 编码代理帮你干活时,最常见的尴尬是:
- 代理正在改代码,你突然想切到别的分支看问题——切换会打断它;
- 同时开两个代理修同一个仓库的两个模块——文件直接互相覆盖;
- 任务没做完就退出了,半成品改动散落在主仓库里。
Git worktree 的官方定位就是解决这件事:一个仓库、多个工作目录,每个目录停在各自分支上。zerostack 把这套机制做成了开箱即用的功能(git-worktree 特性默认开启),创建、进入、合并、退出全程在聊天界面里完成,不用手写 git worktree add。
三个斜杠命令跑通完整工作流
在 zerostack 的聊天界面里,worktree 集成提供 3 个命令(源码见 src/ui/slash/features.rs):
| 命令 | 作用 |
|---|---|
/worktree <name> |
在新分支 <name> 上创建 git worktree 并自动进入。分支已存在或目录被占用时会拒绝 |
/wt-merge [branch] |
把 worktree 分支合并进目标分支(默认 main/master),合并验证通过后清理 worktree 并返回主仓库。只本地合并、不 push |
/wt-exit |
不合并不推送,直接退出 worktree 回到主仓库 |
标准四步工作流:
- 创建 — 输入
/worktree feature-x,新分支和新目录就绪,代理自动cd进去; - 干活 — 正常使用 zerostack 写代码、跑测试,所有改动都留在 feature-x 分支上;
- 合并 —
/wt-merge触发--squash合并、删除 worktree 和分支、回到主仓库; - 退出 — 不想要了就
/wt-exit,一行命令干净离场。
创建逻辑位于 src/extras/git_worktree/mod.rs,它会先校验名字、检查分支是否已存在,再执行 git worktree add -b <name>。
--parallel:并行代理的全自动模式
斜杠命令需要你手动敲;如果你想「开 N 个代理同时干活、完全不用管 worktree 生命周期」,用 --parallel:
zerostack --parallel
它一次做了两件事(参数定义见 src/cli.rs):
- 自动建 worktree:生成时间戳+进程号的分支名
wt-<ts>-<pid>,即使同一秒启动多个实例也不会撞名(见 src/ui/app.rs); - 退出自动合并:隐含了
--wt-auto-merge,退出时自动把分支 squash 合并回main/master,然后删除 worktree 和分支。
所以典型的并行开发姿势是开多个终端:
# 终端 A:一个代理修认证模块
zerostack --parallel
# 终端 B:另一个代理重构数据库层
zerostack --parallel
两个代理各自在自己的 worktree 里改代码,磁盘上互不干扰;关掉终端时各自自动合并回主分支。
⚠️ 注意:
--parallel和--worktree <name>同时给出时,--parallel优先并打印警告。合并永远是本地 squash merge,不会 push,推送请自己执行git push。
worktree 相关 CLI 参数对照表
| 参数 | 说明 |
|---|---|
--worktree <name> |
启动即在分支 <name> 上创建 worktree 并进入 |
--parallel |
创建时间戳命名的 worktree,退出时自动合并 |
--wt-auto-merge |
单独开启「退出时自动合并」 |
--wt-force |
允许清理未合并的脏 worktree 和分支(-D 强删) |
--wt-base-dir <dir> |
指定 worktree 存放目录(默认:仓库的父目录,不存在会自动创建) |
合并冲突时怎么办
退出触发自动合并时,如果 worktree 里有未提交改动,会先提示:
[c]ommit all and continue [a]bort merge
选 c 只会自动提交已跟踪文件(未跟踪的新文件需要你自己提交)。若合并出现冲突,zerostack 会列出冲突文件并给出三个选项:
[a]bort [l]eave for manual resolution [h]elp (agent resolves)
a— 中止合并,恢复干净状态,保留 worktree 和分支;l— 把冲突留在主仓库,用git mergetool手动解决(解决后记得git stash pop);h— 中止后重新召唤代理,由它带着交互式指导帮你把冲突修完。
进阶:编排多个并行代理
zerostack 还内置了 orchestrator 提示词(data/prompts/orchestrator.md),它定义了「workers 写代码,你负责合并」的多代理协议:每个并行 worker 独占一个 worktree + 一个分支,只留下未提交改动和结果标记文件,绝不执行 merge、push、worktree remove;由编排者逐个验证、在主检出目录里顺序 squash 合并(协议细节见 Worktree Merge Protocol)。
配合 zerostack -p 无头模式,就能实现「主会话派工 → 3 个 worker 并行 → 逐个合并验证」的流水线,输出互相隔离、失败可单独重试。
使用前的注意事项
- 🏷️ 名字规则:worktree 名字必须是单个单词——不能有空格、斜杠或前导短横线(因为它同时是目录名);已存在的分支会被拒绝;
- 🚫 detached HEAD 的 worktree 无法合并,先 checkout 到一个分支;
- 🌱 pull 是尽力而为:本地
main/master没有上游也能正常本地合并; - 🧹 想彻底删除一个没合并完的脏 worktree,加
--wt-force,否则清理会拒绝脏状态。
参考资料
- 📖 命令总览:docs/COMMANDS.md
- 📖 快速上手指南:docs/GET_STARTED.md
- 📖 架构说明:ARCHITECTURE.md
- 🧩 提示词目录(orchestrator 等):data/prompts/
- 📦 安装:
cargo install zerostack(默认构建已含git-worktree特性),或从 https://gitcode.com/gh_mirrors/zer/zerostack 克隆源码构建

