一任务一分支:zerostack Git Worktree 与 --parallel 并行代理的完整指南

原创2026-10-10 18:18:431,365 阅读

一任务一分支:zerostack Git Worktree 与 --parallel 并行代理的完整指南

zerostack 是一款用 Rust 编写的轻量级编码代理(coding agent),它内置了完整的 Git worktree 集成:通过 /worktree 斜杠命令或 --parallel 命令行参数,你可以为每个任务自动创建独立分支和独立工作目录,让多个代理并行开发同一个仓库互不干扰,退出时再自动合并回主分支。

zerostack 编码代理项目横幅

为什么 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 回到主仓库

标准四步工作流:

  1. 创建 — 输入 /worktree feature-x,新分支和新目录就绪,代理自动 cd 进去;
  2. 干活 — 正常使用 zerostack 写代码、跑测试,所有改动都留在 feature-x 分支上;
  3. 合并 — /wt-merge 触发 --squash 合并、删除 worktree 和分支、回到主仓库;
  4. 退出 — 不想要了就 /wt-exit,一行命令干净离场。

创建逻辑位于 src/extras/git_worktree/mod.rs,它会先校验名字、检查分支是否已存在,再执行 git worktree add -b <name>。

zerostack 终端界面中代理正在执行代码审查任务

--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,否则清理会拒绝脏状态。

参考资料

登录后查看全文
zerostack