企业官网建设流程全解析

最近我在折腾 AI Agent 编程这件事，发现日常开发模式发生了很大变化。以前开一个分支，切来切去，还能勉强应付；现在我的终端里同时挂着 Codex CLI、Claude CLI，一个在加新接口，一个在修历史 bug，还有一个在处理重构落地。三个任务同时转，代码仓库就变成了灾难现场——不是 checkout 被未提交的修改挡住，就是分支一换，上下文全部乱套。后来我把 Git Worktree 的能力抽出来，做了个专门管理并行 Agent 工作流的 CLI 工具，也就是本文要聊的 Worktrunk。

这篇内容主要围绕 Worktrunk 的设计思路、核心功能、实操流程和实战排查展开。如果你正在用 AI Agent 辅助开发，或者团队里已经在同时跑多个编码智能体，这篇文章能帮你把并行开发这件事从"互相打架"变成"各干各的"。如果你只是听说过 Git Worktree 但一直没搞明白能用来干嘛，这篇文章也能给你一个非常具体的落地场景。

1. 并行 Agent 工作流到底遇到了什么问题

1.1 多个 Agent 同时改代码，仓库为什么会崩

先描述一个我再熟悉不过的场景。周一早上我接到三个任务：给支付模块加一个回调接口，修复登录页在 Safari 下的样式异常，把老项目中一个工具函数重构成 TypeScript 版本。按照以前的习惯，我会一个个来，但既然有 AI Agent 帮忙，我自然想同时开工。于是我在三个终端里分别启动了三个 Codex 会话，让它们各自工作。

不到半小时，问题就来了。Agent A 在feature/payment-callback分支上添加文件，Agent B 在fix/safari-login分支上修改同一个组件的样式，Agent C 在refactor/ts-utils分支上改动工具函数。问题是，这三个分支都在同一个工作目录里。每当我切换分支，Git 就会因为"当前工作目录有未提交的变更"而拒绝操作。我只能先把一个 Agent 的改动 commit 掉，再切到另一个分支，等它跑完再切回来。这一通操作下来，不仅浪费了大量时间，还经常出现两个 Agent 改到同一个文件、互相覆盖的情况。

这就是并行 Agent 工作流的第一个痛点：同一个工作目录只能对应一个分支状态，而 Agent 是自动运行的，它不会像人类一样先 stash 再 checkout，也不理解"你先把当前工作让出来"这种指令。它只会僵在那里，或者直接把改动写到当前目录里，把现场搞得一团糟。

1.2 分支、工作目录与 checkout 的本质

要理解 Worktrunk 的解法，得先把 Git 的底层原理理清楚。很多人把分支理解成"代码的一个版本"，实际上分支只是一个指向某个 commit 的轻量指针。真正存储代码内容的是 commit 对象和目录树对象，分支只是一个会移动的标签。

而工作目录（working directory）才是你真正看到和编辑文件的地方。当你运行git checkout切换分支时，Git 做的事情其实是：把目标分支指向的 commit 中的文件内容，解压出来覆盖到当前工作目录中。如果工作目录里有未提交的改动，覆盖就会产生冲突，所以 Git 会拦下你，提醒你先提交或者存储起来。

这里的关键限制在于：一个仓库默认只有一个工作目录。也就是说，不管你有多少个分支，同一时刻只有一个分支的内容能在磁盘上展开。对于串行开发来说这没什么问题，但到了多个 Agent 并行的场景，这个"单工作目录"的设计就成了最大的瓶颈。你总不能让一个 Agent 先停下来，等另一个 Agent 跑完再继续吧？

1.3 Worktree 为什么是答案

Git 原生提供了一个解决这个问题的能力：git worktree。它的核心思想是，允许你为同一个仓库创建多个工作目录，每个工作目录可以 checkout 不同的分支，而这些工作目录共享同一个.git对象数据库。

用人话说就是：你可以在同一个项目的不同文件夹里，同时存在多个不同分支的代码副本。比如：

/project # 主工作目录，对应 main 分支 /project/.worktrees/auth # 另一个工作目录，对应 feature/payment-callback 分支 /project/.worktrees/fix # 第三个工作目录，对应 fix/safari-login 分支

这三个工作目录互不干扰，任何一方 checkout 分支、修改文件、提交 commit，都不会影响另外两个。Agent A 在.worktrees/auth里干活，Agent B 在.worktrees/fix里干活，它们永远不会碰面，也永远不会改到同一个文件——至少在文件系统层面是隔离的。

Git Worktree 的这个特性和 AI Agent 的工作方式非常契合。Agent 通常是在一个目录里读代码、改代码、运行测试，它并不关心你用的是哪个分支，只要当前目录里的代码是正确的目标状态就行。Worktree 正好提供了这种"每个目录一个独立世界"的隔离环境。

不过，原生的git worktree命令用起来有几个问题：命令参数比较繁琐，目录管理需要自己规划，分支名和目录名靠人工约定，时间一长目录里堆了一堆 worktree 根本分不清哪个对应哪个任务。Worktrunk 就是在这个基础上做的封装和管理层。

2. Worktrunk 的核心设计：Agent 任务与 Worktree 生命周期绑定

2.1 设计原则：一个任务等于一个 Worktree

Worktrunk 最重要的设计决策，是把"一个 AI Agent 任务"与"一个 Worktree"强制绑定起来。在使用 Worktrunk 之前，我见过很多人用原生 worktree 做并行开发，但最终都失败了，原因就是没有建立清晰的映射关系：worktree 目录名叫什么、对应哪个分支、服务于哪个任务，全靠记忆，一旦任务多了立刻混乱。

Worktrunk 的做法是收起这些决策，用约定来取代配置。当你执行worktrunk create agent-a --base main时，它会自动帮你做这么几件事：

1. 在约定的工作区目录下（比如.worktrunk/agent-a）创建新的 worktree；
2. 从指定的基准分支（这里是main）拉出一个新的功能分支，分支名默认与任务名一致；
3. 记录这条 worktree 的元信息，包括创建时间、基准分支、关联的任务描述。

这样一来，目录名、分支名、任务名三者完全一致。你不需要去记"agent-a 的任务分支叫什么"，因为所有东西都有一个唯一的、可预测的命名规则。这在同时管理十个以上 Agent 任务时尤其重要。

2.2 Worktrunk 的状态机设计

光有命名规则还不够，还得管理 worktree 的生命周期。Worktrunk 内部为每个 worktree 维护了一个简单的状态机，状态包括：

• created：刚创建，Agent 还没开始工作；
• active：Agent 正在或已经在该 worktree 中修改代码；
• merged：该 worktree 的分支已经合并回主分支；
• cleaned：worktree 目录已被移除，元信息保留用于追溯。

这个状态机的价值在于，它能让你在一堆 worktree 里快速识别哪些任务还没完成、哪些已经合并但忘了清理目录、哪些处于中间状态。我实际使用中发现，AI Agent 任务经常出现"代码写完了但忘了合并"的情况，Worktrunk 在显示列表时会用状态列直接标出来，比我一个个git branch --merged去查要直观得多。

状态切换的规则也很直接。worktrunk list会读取 git 的分支信息与 worktree 配置文件，自动计算每个 worktree 的分支是否已经包含在主分支的历史中。如果包含了，就将状态标记为merged。这个检测不依赖任何外部服务，完全是纯本地的 git 操作，所以速度很快，几百个 worktree 的场景也能在毫秒级完成状态刷新。

2.3 与 Agent 工具的集成方式

Worktrunk 本身是一个 CLI，它的集成方式非常灵活。最简单的方式是在 shell 里手动操作：

worktrunk create agent-a cd .worktrunk/agent-a codex

但这还不够自动化。我的习惯是写一个简单的包装脚本，把"启动 Agent 并指定任务目录"变成一条命令。脚本的逻辑大致是：

worktrunk create "$1" cd ".worktrunk/$1" codex "$2"

这样每次开新任务只需要agent-start task-42 "为支付模块添加回调接口"，脚本会自动创建 worktree、切换目录、启动 Codex。Agent 看到的代码就是干净的目标分支状态，任务结束之后，我只要回到主目录执行worktrunk merge task-42，就能完成合并和清理。

更进一步，Worktrunk 还支持在创建时设置环境变量。比如worktrunk create agent-b --env-file .env.agent-b，它会把指定的环境变量注入到后续启动的 Agent 进程中。这个能力在调试多 Agent 协作时很有用，因为不同 Agent 可能需要访问不同的 API Key 或者配置不同的模型参数，而这些配置不需要写进代码里。

3. Worktrunk 实操：从零搭建并行 Agent 工作流

3.1 安装与初始化

Worktrunk 是 Go 写的，编译出来是单个二进制文件，所以安装非常省事。我这边用的是 Homebrew：

brew install worktrunk

或者直接从 GitHub Releases 页面下载对应平台的二进制丢到$PATH里。没有 Node 依赖，没有 Python 运行时，也没有环境变量要配。这一点对于我这种经常在 Mac 和 Linux 服务器之间切换的人来说特别重要，因为我不想在每个环境里都折腾一套依赖。

安装完之后，先进入你的项目仓库执行初始化：

cd /path/to/your/project worktrunk init

这个命令会检查当前目录是否是一个 Git 仓库，如果是，就在仓库根目录下创建一个.worktrunk/元数据目录，并把你的主分支设定为默认基准分支。它不会改动你现有的任何代码，也不碰你的.gitignore（除非你让它托管）。初始化之后，整个项目的 worktree 管理就可以交给 Worktrunk 了。

3.2 创建任务并启动 Agent

假设现在来了一个新任务：给订单模块加一个导出 Excel 的功能。我执行：

worktrunk create order-export --base develop --desc "订单导出Excel功能"

Worktrunk 会做下面这些事：

• 在.worktrunk/order-export下创建新的 worktree；
• 从develop分支拉出worktrunk/order-export分支并 checkout 到新 worktree 中；
• 在.worktrunk/元数据中记录任务描述和创建时间。

创建完成后，终端会输出类似这样的信息：

worktree created at .worktrunk/order-export branch: worktrunk/order-export status: created

然后我可以从多个终端同时启动多个任务：

# 终端1 worktrunk create order-export cd .worktrunk/order-export && codex # 终端2 worktrunk create login-password-migration cd .worktrunk/login-password-migration && trae_cli # 终端3 worktrunk create dashboard-performance-fix cd .worktrunk/dashboard-performance-fix && claude

三个 Agent 现在各自在独立的目录里跑，互不干扰。这是整个工具最核心的价值：并行，但没有冲突。

3.3 并行执行期间的主分支同步策略

并行跑了一段时间后，你很快会遇到一个新问题：Agent A 已经完成并合并回主分支了，而 Agent B 的 worktree 还是基于旧的主分支创建的，它后续如果涉及修改同一个文件，就可能产生上下文过期的问题。

比如 Agent A 改了src/utils/date.ts的接口签名，Agent B 还在用旧的签名写代码，等到合并时就会出现大量冲突。解决这个问题的方式，是定期让每个 worktree 把主分支的最新改动拉进来。

Worktrunk 提供了一个sync命令：

worktrunk sync agent-b

这个命令会在agent-b的 worktree 中执行git fetch origin，然后尝试把主分支并入当前分支。如果 Agent B 已经修改了文件并且产生了冲突，sync会把冲突标记暴露出来，但不会擅自帮你解决。你可以在 Agent B 的对话上下文里告诉它："主分支有更新，sync 出了冲突，你检查一下src/utils/date.ts这个文件，以新接口为准调整逻辑。"Agent 处理这种局部冲突通常很高效。

要注意的是，sync不应该开太频繁。如果主分支还在快速变更，你让 Agent B 每十分钟就同步一次，它反而会因为代码版本总在变而失去稳定性。我习惯的节奏是：Agent 完成一个独立的功能模块后，或者它明确报告"我改完了准备写测试"时，才做一次 sync。过早同步是并行开发中容易出现的问题。

3.4 任务合并与清理

当一个 Agent 完成工作后，合并流程应该是这样：

1. 先检查 Agent 在 worktree 里的改动是否符合预期。你可以自己跑一遍测试，或者把改动 diff 出来审一遍：

cd .worktrunk/order-export git log --oneline develop..HEAD git diff develop...HEAD

2. 确认没问题后，回到主仓库目录执行合并：

worktrunk merge order-export --delete

merge内部做的事情包括：确保 worktree 分支上没有未提交的改动，执行 checkout 到主分支（如果当前在主仓库目录），把 worktree 分支 merge 进来，并且如果有--delete参数，就顺手把 worktree 目录和对应分支删掉。

清理这一步很容易被忽略。原生git worktree remove有时候会因为 worktree 里有未提交文件而报错，Worktrunk 在删除前会做一次检查，如果有未提交修改会先警告你，并提示先提交或丢弃，避免误删数据。

4. 实际项目中的常见问题与排查方案

4.1 worktree 删除失败：目录不是空的

这是新手最容易遇到的问题。git worktree remove对非空目录是直接拒绝的，报错信息大概是 "contains modified or untracked files"。Worktrunk 的做法是，删除前先尝试执行git clean -fd和git reset --hard HEAD，把 worktree 里残留的未跟踪文件和未提交修改清掉，然后再删除。

但这里有个坑：如果你用了 Docker 或者构建工具，worktree 目录里可能有构建产物或者.env文件，这些文件并不是 git 跟踪的，git clean也不会误删它们。我在第一次清理时就吃过亏，因为 worktree 里跑过测试，生成了一个node_modules目录，删除时磁盘占用极大，还花了不少时间。后来我在.gitignore中把构建产物目录排除，并在创建 worktree 时用--skip-clean跳过不必要的清理动作，情况才好转。

4.2 分支被 Agent 提交信息搞乱

Agent 提交代码的习惯不太一样，有的工具喜欢在提交信息里加上模型名称和日期，比如feat: add excel export (claude-3.7, 2025-06-01)。这些信息本身没啥问题，但如果你用git log --format做自动化分析，或者通过 commit 信息做 CI 关联，就会遇到混乱。

我的建议是，在 Worktrunk 的create命令里通过--commit-template指定一个统一的提交信息模板，让 Agent 在 commit 时遵循团队规范。Worktrunk 会在创建 worktree 时把模板写入仓库的 git config 中，这样 Agent 无论用什么方式提交，都至少会被模板约束住。如果 Agent 不遵守模板，你可以在审查阶段用git rebase -i批量改写提交信息，但那就得靠人工了，我一般只在任务合并前做一次。

4.3 多个 worktree 的磁盘占用和构建缓存

很多人会忽略一个问题：每个 worktree 是一份完整的代码目录。如果一个项目有 3 万个文件，每个 worktree 都会把这 3 万个文件展开到磁盘上。虽然 Git 对象是共享的，但 working tree 是实打实占用空间的。我维护过一个大项目，同时开了 8 个 worktree，磁盘占用轻松超过 20GB。如果项目里再有node_modules或者构建缓存，这个数字会更离谱。

解决方案是让每个 worktree 共享构建缓存目录。前端项目可以把 npm 的缓存目录指向全局路径：

npm config set cache /shared/.npm-cache

或者直接用 pnpm 的全局 store 机制。对于 Python 项目，可以创建虚拟环境时复用已有的 pip 缓存。Worktrunk 在创建新的 worktree 时不会自动配置这些，所以我习惯在init阶段写好一个.worktrunk/profile.sh，里面定义好缓存路径相关的环境变量，每次创建 worktree 后 source 一下。这个脚本不是 Worktrunk 强制的，是我自己的实践，但效果非常好。

4.4 合并冲突：多个 Agent 仍然可能改到同一个文件

虽然 worktree 在工作目录层面完全隔离，但 git merge 时仍然可能产生代码冲突。比如 Agent A 和 Agent B 都改了config.py里的配置项，但各自基于不同的主分支版本。这种冲突不会在开发时暴露，只会在 merge 时爆发。

处理这种冲突的关键在于，不要试图在命令行里手动把几百行的冲突文件一点点改好。我建议把冲突文件丢回给 Agent 处理。具体做法是：git merge之后，如果发现冲突文件是 Agent 擅长处理的类型，直接用codex --task "resolve conflicts in config.py, keep both settings, follow the new structure"让它去解决。因为 Agent 有上下文记忆，它知道自己的改动意图，处理冲突的速度比人肉快得多。

如果冲突规模很大，比如两个 Agent 改了同一个模块不同的十几个文件，我通常会先中止合并，重新评估任务的拆分粒度。并行任务在文件层面应该尽量不重叠，这是任务拆分时就要想清楚的，而不是等 merge 之后再亡羊补牢。Worktrunk 在这方面帮不上忙，它只负责隔离，不负责替你设计任务边界。

4.5 Worktrunk 与 CI 系统的配合

还有一个容易被忽略的场景：CI 系统会监听分支的 push 事件。当 Agent 在各 worktree 中提交代码并 push 分支时，CI 可能会疯狂触发构建。对于小项目来说无所谓，对大型项目来说，这会浪费大量算力。

我的经验是，在 Worktrunk 创建 worktree 时，通过--skip-ci参数在推送的 commit message 中加上[skip ci]标记。或者反过来，在 CI 配置里只监听合并到主分支的构建，不监听功能分支的构建。前者更简单，因为不用改 CI 配置，缺点是会在提交历史里留下一堆[skip ci]标记。后者更干净，但对团队协作是一个约束：所有人的功能分支都不会触发 CI，只有最终合并到 main 时才会构建。我倾向于后者，Worktrunk 本身的定位是个人开发者工具，但也支持多人协作，只是需要约定好 CI 策略。

5. 最后：我的一些使用体会

5.1 别一上来就开十个 worktree

Worktrunk 把创建 worktree 的成本降得非常低，命令行敲一下一秒钟就能开一个新任务。但低成本的另一面是容易滥用。我试过同时开 10 个 Agent 任务，结果发现第二天有 4 个 Agent 都处于半完成状态，每个都在等我把测试用例补齐，或者等我回答一个设计问题。并行本身不是目的，把手头的任务约束在"我能在半天内审查完"的范围内，才是正确的使用姿势。

我现在基本控制在 3 到 5 个并行任务，再多就不太管得过来了。如果你的团队有专职的 review 人员，可以适当放宽，但不要指望 Agent 之间能自己协调依赖关系，至少在目前这个阶段，它们还没有这个能力。

5.2 Agent 的上下文管理比 worktree 管理更难

最后再分享一个我的观察。Worktrunk 解决了"工作目录隔离"的问题，但并行跑多个 Agent 时，真正让人头疼的其实是上下文管理。比如你让 Agent A 修改了一个公共组件的接口，然后 Agent B 正在用这个组件写新的页面，Agent B 不会自动知道接口已经变了。良好的任务拆分和定期的sync能缓解这个问题，但最终还是要靠人来把控全局。

如果你要用这套流程，请记住一条铁律：每个 Agent 任务的描述里，一定要写清楚它依赖哪些模块、这些模块可能正在被其他 Agent 修改，以及它应该优先保证自己负责的代码是正确的，而不是试图去"修复"其他 Agent 正在改的代码。有了这条约束，再加上 Worktrunk 的隔离能力，并行 AI Agent 工作流才能真正跑得起来。