企业官网建设流程全解析

我最近的工作流变成这样了：早上开工，先扫一眼 issue 板，挑出三件可以并行推进的事——一件修线上 bug，一件给现有 API 加个参数，一件把老模块重构成新的目录结构。然后我同时开三个终端窗口，分别让 Codex CLI、Claude Code 这类 AI 编程 Agent 去处理其中一件。听起来很高效对吧？实际跑起来你会发现，真正的瓶颈根本不是 Agent 的智商，而是 Git 工作区只有一个。三个 Agent 抢同一个工作区，改到一半的文件互相踩，commit 历史乱成一锅粥，最后合并时冲突文件堆成山。

这个痛点我忍了很久。最后我决定自己写一个工具来解决，名字就叫Worktrunk——一个面向并行 AI Agent 工作流的 Git Worktree 管理 CLI。它的核心思路特别简单：把“分支管理”变成“目录管理”，让每个 Agent 任务拥有一个物理隔离的工作目录，互不干扰。这篇文章我会把整个设计思路、Git Worktree 的底层原理、CLI 的完整功能拆解，以及我这段时间实际使用的踩坑经验全部写出来。

1. 并行 AI Agent 工作流为什么需要 Worktrunk

1.1 一个 Agent 还能应付，三个 Agent 就乱套

先还原一下真实场景。假设你有一个仓库，叫my-service。你想让 Agent A 修 bug（分支fix/login-timeout），Agent B 加功能（分支feat/add-filter），Agent C 做重构（分支refactor/cleanup-handler）。

用人肉操作的话，你要做的是：

# 窗口1：切到 bug 分支 cd my-service git checkout -b fix/login-timeout # 开始让 codex 干活... # 窗口2：想并行做功能？先回主分支 git checkout main git checkout -b feat/add-filter # 但窗口1的 codex 正在跑，你 checkout 会把它的工作区也切走

问题就在这里。Git 在单个工作目录下，同一时间只能 checkout 一个分支。你切过去，另一个 Agent 的未提交修改就跟过来了，或者被 stash、被中断。两个 Agent 同时跑的时候，你甚至没法分辨当前工作区里这一堆文件到底是哪个 Agent 留下的。

我遇到过最崩溃的一次：Agent A 正在改src/auth/login.ts，Agent B 需要读src/auth/login.ts来改依赖它的组件。结果 B 一启动就把 A 改了一半的文件读了进去，生成了一堆基于错误上下文的代码。整个任务直接报废。

1.2 传统多分支方案的三个硬伤

有人可能会说，你用一个主工作区不断切分支不就行了吗？我试过，三个硬伤劝退：

• 共享可变状态是原罪。不管你怎么小心翼翼，多个 Agent 共享同一个工作目录就意味着它们共享同一份 working tree。Agent 可不像人那样有“我的暂时别动”的直觉，它读到的文件状态就是当时工作目录里的真实状态，污染在所难免。
• 上下文错配几乎必然发生。Agent 通常会把“当前分支”“当前目录”写进自己的上下文里。如果你在它运行期间手动切走分支，Agent 眼里看到的和实际工作区里的东西就对不上了，它接下来写的代码全是错的。
• 无法并行在前台操作。你只有一个工作区时，同一时刻只能让一个 Agent 真正“落笔”，其他 Agent 要么排队，要么在错误的文件状态上干活。这等于把并行硬生生降级成了串行。

1.3 核心痛点的本质：并行不是问题，共享可变状态才是

把问题抽象一下：所谓并行 AI Agent 工作流，本质上就是多个有“自主行动能力”的程序同时在一个代码库上操作。它们彼此之间没有像人一样的沟通机制，只能通过文件系统感知世界。所以，如果你让它们看到同一个可变目录，它们的世界观必然是错乱的。

解决方案也很直接：给每个 Agent 一个独立的、物理隔离的目录。表面上是多开几个文件夹，实际上每个目录背后对应一个独立分支、一份独立文件快照、一个独立的 index。这就是 Git Worktree 存在的意义。

2. Git Worktree 机制拆解：为什么它天生适合 Agent 并发

2.1 Worktree 到底是什么

简单说，git worktree add可以从同一个仓库创建出多个工作目录。每个目录都有自己独立的 working tree 和 index，但共享同一个.git仓库对象库。

# 在主仓库里创建一个名为 feat/add-filter 的分支，并把它 checkout 到 ../my-service-feat-add-filter 目录 git worktree add ../my-service-feat-add-filter -b feat/add-filter

执行完之后，你会在新的目录下看到一个.git文件，注意它是文件而不是目录，内容类似：

gitdir: /path/to/my-service/.git/worktrees/my-service-feat-add-filter

这个文件就是链接到主仓库的入口。你可以同时在my-service和my-service-feat-add-filter两个目录里操作，它们互不阻塞。你在新目录里 commit，提交会进入同一个仓库的feat/add-filter分支。

可以这样理解：一个仓库就像一个公司，.git对象库是公司的资料室，各个 worktree 是不同员工的工位。每个人（Agent）在自己的工位上干活，共享资料室，但桌子上的文件互不干扰。你不需要给每个员工盖一栋新楼（克隆整个仓库），只要多摆几张桌子就行。

2.2 原生 Git Worktree 命令的三个痛点

既然 Git 原生支持 worktree，为什么还需要 Worktrunk 这个 CLI？因为原生命令用起来真的很繁琐，尤其在 Agent 并行场景下：

痛点一：路径要靠脑子记。git worktree add每次都要写完整的目标路径，路径多了以后，你很容易忘记哪个目录对应哪个分支。我就出过这种事：想去feat/add-filter的目录，结果跑去了fix/login-timeout的目录，对着半天还纳闷代码怎么不对。

痛点二：清理流程繁琐。任务完成后的清理至少两步：

# 先移除 worktree 目录 git worktree remove ../my-service-feat-add-filter # 再删分支 git branch -d feat/add-filter

如果 worktree 里还有未提交的修改，git worktree remove还会拒绝执行，你得先处理掉那些改动。两个 Agent 在这里等着，你却在跟 worktree 清理命令搏斗，这体验很糟。

痛点三：状态不直观。原生git worktree list输出很朴素，只显示目录、分支和 commit。你不知道每个 worktree 对应什么任务、有没有未提交修改、离主干领先多少个 commit。并行跑五六个 Agent 时，光靠原始输出完全没法快速掌握全局。

2.3 为什么 Agent 场景下这个痛点被放大了

Agent 没有人的记忆。每次启动，它都是重新感知周围环境。如果你给了它一个路径混乱、worktree 状态不明的工作目录，它需要花大量时间去搞懂自己在哪、该做什么。Project-level 的 agent skill、memory 再好用，也架不住底层目录结构是乱来的。

另外，Agent 工具本身也在快速迭代。Codex CLI、Claude Code、ZCode CLI 这些工具，大多数都是“在一个目录里干活”的模型。它们不支持、也没必要支持跨目录会话管理。所以真正要做的是：用外部工具把目录安排好，让 Agent 始终在正确的目录里启动。Worktrunk 就是承担这个“管家”角色的。

3. Worktrunk CLI 的核心功能拆解

3.1 设计原则：做一个薄封装，而不是重造轮子

我在设计 Worktrunk 时给自己定了几条原则：

• 不重复实现 Git 的功能，只做 Git Worktree 的封装和任务态管理。
• 状态信息要能一目了然，人看和脚本看都方便。
• 保留底层命令的转义通道，高级用户能随时调原生 Git。

也就是说，Worktrunk 的价值不在于“发明新版本控制”，而在于把git worktree这个强大但原始的能力，封装成适合并行 Agent 工作流的实体任务处理界面。

3.2 核心命令总览

假设仓库叫my-service，Worktrunk 的常用命令如下：

创建任务是使用频率最高的操作：

cd my-service # 把仓库初始化成 Worktrunk 管理的状态 worktrunk init # 为三个 Agent 分别创建任务 worktrunk task create fix/login-timeout worktrunk task create feat/add-filter worktrunk task create refactor/cleanup-handler

执行后，默认会在../my-service-worktrees/目录下生成三个独立工作目录：

../my-service-worktrees/ fix-login-timeout/ feat-add-filter/ refactor-cleanup-handler/

为什么放在仓库外面？因为这样主工作目录保持干净，同时避免 worktree 目录被 Git 自身的忽略规则误伤。用..相对路径也能确保移动整个项目文件夹后依然可用。

3.3 任务状态追踪：让“全局视角”成为可能

worktrunk list是我每天用得最多的命令。它会输出类似这样的表格式状态：

任务 目录 分支 状态 ───────────────────────────────────────────────────────────────────────────────────── fix/login-timeout ../worktrees/fix-login-timeout fix/login-timeout ●2 个未提交变更 feat/add-filter ../worktrees/feat-add-filter feat/add-filter ✓已同步 refactor/cleanup-handler ../worktrees/refactor-cleanup refactor/cleanup-handler ↑领先 main 3 个提交

每个 Agent 任务的状态一目了然：有没有未提交的改动、离主分支领先多少、是否需要合并。在同时跑多个 Agent 的时候，这个全局视图省了我大量时间。

3.4 实现原理简述

Worktrunk 的实现其实不复杂。核心就是把git worktree add/remove/list包装成语义化任务，然后在.worktrunk/下存一份任务元数据（JSON 格式），记录任务名、分支名、目录路径、创建时间、状态等。

关键代码逻辑大致是这样：

# worktrunk task create 的核心伪代码 def create_task(name: str): branch = name.replace("/", "-") path = root / "worktrees" / branch subprocess.run(["git", "worktree", "add", str(path), "-b", name], check=True) metadata = load_metadata() metadata.tasks[name] = { "branch": name, "path": str(path), "created_at": now(), "status": "active", } save_metadata(metadata)

任务完成后执行worktrunk done <name>，它会依次完成：检查是否有未提交修改 → 把分支合并回主分支（默认是main或你配置的基线分支）→ 移除 worktree → 删除已合并分支 → 更新元数据。

注意：done默认只做本地合并。推到远端仍需要你手动git push，因为自动 push 在一个并行工作流里风险太大，我倾向于把“合并”和“发布”两个动作拆开。

4. 一场真实的并行 Agent 实战流程

4.1 场景设定：三个 Codex CLI 实例同时改一个代码库

拿我前几天的一单活儿来拆解。仓库是一个中等规模的 Go 后端服务，叫billing-api。我给它排了三个任务：

• Agent A（Codex CLI）：修复POST /v1/invoices在时区参数异常时返回 500 的 bug
• Agent B（Codex CLI）：给GET /v1/transactions增加tags过滤参数
• Agent C（Claude Code）：把handlers/目录下命名混乱的 handler 统一重命名

这三个任务涉及的文件区域基本不重叠，非常适合并行。

4.2 实际操作序列

第一步，初始化 Worktrunk 并创建任务：

cd billing-api worktrunk init worktrunk task create fix/invoice-tz-bug worktrunk task create feat/transactions-tags worktrunk task create refactor/handler-naming

第二步，启动三个 Agent，每个 Agent 在各自目录干活：

# 终端1 cd ../billing-api-worktrees/fix-invoice-tz-bug codex # 终端2 cd ../billing-api-worktrees/feat-transactions-tags codex # 终端3 cd ../billing-api-worktrees/refactor-handler-naming claude

注意一个关键细节：每个 Agent 进程只“看到”自己的工作目录。Codex CLI 默认把当前目录当作仓库根目录，自动检测 Git 分支。它在fix-invoice-tz-bug里 commit，提交只会进fix/invoice-tz-bug分支，对其他目录零影响。

第三步，随时监控全局状态。我会隔一段时间跑一次：

worktrunk list

看到 Agent A 的状态变成了“领先 main 2 个提交”，说明它已完成并提交了修改。其他两个还在处理中。

第四步，任务完成，合并分支。等 Agent B 也提交后，执行：

worktrunk done fix/invoice-tz-bug worktrunk done feat/transactions-tags

它会自动把分支合入main，删除临时 worktree 和已合并的分支。整个仓库目录保持干净，只剩还没结束的refactor/handler-naming。

4.3 如果 Agent 干砸了怎么办

Agent 和人的区别在于，它会一本正经地写出一堆自我感觉良好、实际却编译不过的代码。所以“回滚”能力很重要。

我的做法是：任务没验收前，绝不执行done。我会先去 worktree 里跑测试、看 diff。如果 Agent 改烂了，直接：

git reset --hard main git clean -fd

把工作目录恢复到干净基线，然后重新启动一个 Agent 实例接着干。因为 worktree 是物理隔离的，这种 reset 不会影响其他正在跑的任务。这在以前共享一个工作区时是根本不敢想的操作。

4.4 主工作区还剩下什么

这个流程跑完，我的主目录billing-api仍然是干净的main分支，没有残留任何临时文件、没有多余的本地分支。任何时刻我都可以直接用billing-api这个目录去启动 CI、跑测试或者做 code review。

这种“主目录恒干净”的体验，是并行 Agent 工作流里最奢侈的事情。

5. 踩坑实录与设计取舍

5.1.git是文件，不是目录

第一次用原生 worktree 时，我在新目录里执行git status报了错。查了才发现，linked worktree 里的.git是一个纯文本文件，指向主仓库的 worktree 注册目录。

这意味着：

• 如果你备份时只复制了一个 worktree 目录，它无法独立工作，依赖主仓库存在。
• 如果你引入了错误的工具扫描仓库结构，可能会因为这个.git文件而误判。

在 Worktrunk 的设计里，我把所有 worktree 统一放在仓库外部的../<repo>-worktrees/目录下，目的就是避免这种“半个仓库”的视觉混淆。看到目录在项目外面，你就不会把它当成一个完整项目去单独操作。

5.2 分支名和目录名的对应关系要强制一致

原生 worktree 里分支名和目录名没有强制绑定。git worktree add ../foo -b bar/baz完全合法，结果就是目录叫foo，分支叫bar/baz。人脑记一次还行，记三个就乱了。

Worktrunk 的做法是：目录名来自分支名的规范化版本，例如feat/transactions-tags→feat-transactions-tags。这样你在文件系统里只看目录名就能反推分支名，减少认知负担。

5.3 关于 worktree 目录位置的取舍

到底把 worktree 放在仓库外面还是里面？我一开始放在仓库内，比如my-service/.worktrees/xxx，结果很快就后悔了：

• 目录出现在 Git 状态里，需要额外配.gitignore。
• git worktree add如果目标路径在仓库内部，子目录里会出现嵌套的 worktree 结构，某些工具遍历文件时会出现诡异行为。
• 路径太深，shell 提示符会变得又长又烦。

后来统一改成放在仓库同级目录../<repo>-worktrees/。这个位置的好处是：仓库的.gitignore不用动，路径短，而且rm -rf ../billing-api-worktrees一把就能清干净全部临时目录，不影响主仓库。

5.4 别忘了子模块这个坑

如果你的仓库用到了 submodule，worktree 里对 submodule 的处理会比较麻烦。简单说：submodule 在 linked worktree 里默认不会自动初始化。你需要手动执行：

cd <worktree-directory> git submodule update --init --recursive

这条坑我记忆深刻。有一次 Agent C 在 worktree 里改完了代码，结果跑测试时一直报子模块相关的错误，排查了半天才发现是 submodule 没初始化的老问题。最终我在 Worktrunk 的task create流程里加了一个可配置项：创建任务后自动执行 submodule 初始化。如果涉及带子模块的仓库，这一步几乎必不可少。

5.5 Agent 重启后的定位问题

Agent 进程不是永远在线的。会话中断、超时、或者你嫌它写得不对手动把它 kill 了，再重启时它需要重新理解自己在干什么。如果只有一个目录，Agent 重启后的第一句话往往是“当前分支是 xxx，任务目标是 yyy”。Worktrunk 可以在启动 Agent 前注入任务信息：

cd <worktree-directory> WORKTRUNK_TASK="fix/invoice-tz-bug" \ WORKTRUNK_BASE_BRANCH="main" \ codex

Codex CLI 会把当前的 shell 环境变量带进它的会话上下文。Agent 不需要靠猜，直接就知道自己在一个什么分支上、要完成什么任务。好的工具设计就应该这样——把环境的可解释性做好，Agent 才能发挥出真正的生产力。

6. 我在实际使用中的体会与下一步计划

6.1 一个 CLI 的自我修养：保持功能克制

Worktrunk 用了一段时间后，我最大的体会是：工具要克制。它只做 “任务 → 目录 → 分支” 的映射和管理，剩下的 Git 操作全部交给原生命令。我不打算把 merge、rebase、conflict resolution 全部塞进 Worktrunk，因为那些场景太复杂，每个团队的工作流差异也太大了。与其做一个什么都管、什么都管不好的管理器，不如做一个路径清晰、状态透明的小工具。

这种克制的另一个好处是：你可以把 Worktrunk 轻松嵌入现有的脚本和 CI/CD 流程里。比如我在 CI 里加了一步——每次合并前跑worktrunk list --json，自动提示是否有未完成的任务目录残留，防止开发者在忙乱中把临时 worktree 忘在服务器上。

6.2 下一步：让 Agent 自己能感知 Worktrunk

目前 Worktrunk 对 Agent 来说还是个“外部工具”，人负责创建任务目录，Agent 只是被动地在一个干净的目录里干活。我正在琢磨怎么让 Agent 主动感知 Worktrunk 的任务语义。

方向有两个：

一是通过 CLI 暴露 declare 接口，让 agent 在任务目录里的操作能同步回 Worktrunk 的任务状态。比如 Agent 完成一个子步骤，就调用一次worktrunk task checkpoint <name> "完成xxx"，人随时能看到进度。

二是对接 Agent 的 MCP（Model Context Protocol）能力。现在 Codex CLI、Claude Code 都开始支持 MCP 服务器，我可以做一个 Worktrunk MCP Server，让 Agent 直接“看到”当前仓库有哪些任务、哪些分支需要处理、哪些 worktree 处于脏状态。这样一来，Agent 的计划能力就和 Worktrunk 的任务状态打通了，不再是两套割裂的信息系统。

6.3 如果你也要自己折腾这个方向

如果你不想直接用 Worktrunk，也有几个轻量替代方案可以参考：

• 用 shell 函数封装git worktree add，简化建目录和切分支的操作。
• 用.worktree-aliases之类的文件记录“分支 → 目录”的映射，手动维护一张表。
• 用 tmux 的会话管理配合原生 worktree，给每个 Agent 分配独立的 tmux session。

这些方案都能用，但都缺一个“全局状态视图”。我最后选择把 Worktrunk 做成一个独立 CLI，核心原因就是只有独立 CLI 才能持续积累任务元数据，慢慢形成一套可查询、可脚本化、可被 Agent 感知的状态层。

在我实际跑并行 Agent 项目这段时间，Worktrunk 带来的最大价值，不是把某条命令缩短了几秒，而是让我敢于真正放手去并行。以前我最多敢开两个 Agent，因为第三个一开，我就没法保证前两个的结果了。现在我可以同时跑五六个任务，每个任务一个目录，谁出了问题就处理谁、就重来谁，其他任务照常推进。这种“敢于放手”的底气，正是这个工具存在的意义。