企业官网建设流程全解析

最近在做 AI Agent 工程化落地时，我发现一个特别反直觉的现象：很多人每天花大量精力调 Prompt、选模型、搭 MCP 服务，但真正卡住并行 AI Agent 跑起来的，往往不是模型能力，也不是上下文窗口，而是一个最不起眼的东西——Git 工作区。

手头同时跑两三个 AI 编程代理（比如 Codex CLI、Claude Code CLI、Gemini CLI）时，它们会同时修改同一个目录下的文件，互相覆盖、互相踩踏。改完之后连 git status 都分不清哪行是谁改的，更别提交代清楚让哪个 Agent 继续完成哪部分工作了。一次两次还能忍，任务一多、仓库一大，整个工作流就乱成一锅粥。

我捣鼓了小半个月，最后解决方案落地在一个叫 Worktrunk 的 CLI 工具上——它专门做 Git Worktree 的管理，核心目标就是服务并行 AI Agent 工作流。这篇文章把它的原理、用法、以及我在实践中踩过的坑完整写出来，希望能帮到同样被这个问题折磨的人。

1. 并行 AI Agent 时代，最大瓶颈竟然是 Git 工作区

1.1 多 Agent 协作的"文件踩踏"困境

先描述一个我实际经历过的典型混乱场景。

某次我把一个中等规模的后端仓库交给两个 AI Agent 并行改：Agent A 负责新增用户登录接口，Agent B 负责把工具函数库从 lodash 迁移到原生实现。两个任务互不依赖，按说完全能并行。结果跑了不到十分钟，Agent A 发现src/utils/http.ts里的辅助函数被改得面目全非，Agent B 则发现它启动时读的配置文件里多了一段不属于它的代码。

这就是典型的"文件踩踏"：多个 Agent 共享同一个工作目录，彼此对文件的修改没有隔离，谁后保存谁覆盖。更麻烦的是，Agent 的上下文（比如它读过的文件、做过的决策）往往绑定在一组具体路径上，一旦其他 Agent 改了同一个文件，它的后续决策就会基于过期甚至错误的信息，错误的代码像滚雪球一样累积。

很多人第一反应是"让 Agent 改不同目录不就行了"。问题是你不能用目录层面去硬隔离代码——同一个仓库里，服务层和工具层是互相引用的，Agent A 改了接口定义，Agent B 的代码很快就编不过了。真正的隔离不是在目录上做文章，而是让每个 Agent 拥有独立的、完整的、可随时切换上下文的代码版本。

1.2 为什么git branch切换解决不了本质问题

那直接用 Git 分支呢？Agent A 在feat/login分支上跑，Agent B 在chore/lodash-migration分支上跑，听起来很合理，但用起来全是坑。

第一个问题是物理工作目录只有一个。Agent A 正在改代码时，你想让 Agent B 开工，就必须先暂停 A、提交或暂存当前改动，然后切到 B 的分支。可是 Agent A 可能正在读文件、分析代码，强行切分支会导致它的文件句柄失效、状态错乱，Agent B 再一跑，两个会话就互相污染了。

第二个问题是"上下文丢失"。AI Agent 不像人，它不会"记住刚才在想什么"。每次切换分支回来，它需要重新读文件、重新构建上下文。你让它切三次分支，它的有效工作时间至少打七折。而且很多 CLI 工具的会话状态是绑定在绝对路径上的，切了分支之后路径虽然没变，但文件内容全变了，它的"记忆"就全错位了。

所以分支隔离解决了"变更归属"问题，但没有解决"工作目录独占"问题。磁盘上同一时间只有一份工作目录，它就是所有 Agent 共享的可变状态——只要这个共享状态存在，并行就永远只是伪并行。

1.3 Git Worktree：被严重低估的原生并行机制

Git 其实从 2.5 版本开始就提供了一个专门用来解决这个问题的原生机制：git worktree。

它允许你在同一个仓库下创建多个工作目录，每个工作目录对应一个独立的分支，彼此完全隔离。但它们共享同一个.git对象数据库和引用数据库，所以不产生额外的远端仓库拷贝，磁盘开销非常小。你可以把 worktree 理解成"同一份代码仓库的多个互不干扰的副本，但它们底层共享着同一个对象库"。

对我来说，worktree 最舒服的一点在于：每个工作目录都是一个完整的、独立的、可随时跑起来的分支副本。Agent A 在/workspace/repo-agent-a里改代码，Agent B 在/workspace/repo-agent-b里改代码，它们看到的是各自分支的最新状态，互不可见、互不影响。两个人同时写同一个文件都不冲突，因为它俩物理上就不在同一份文件上。

这才是并行 AI Agent 工作流真正需要的底层能力。但就像很多好用的原生能力一样，Git Worktree 的命令行交互在复杂场景下会变得很繁琐：你要记住每个 worktree 的路径、记住哪个分支对应哪个任务、跑完之后要手动清理、稍不注意就会把 worktree 删错。这些重复劳动叠加起来，恰恰是 Worktrunk 这类工具存在的价值。

2. Worktrunk 的核心原理与设计思路

2.1 底层机制拆解：.git/worktrees/与 HEAD 隔离

想用好 Worktrunk，必须先理解git worktree在底层到底做了什么。

当你执行git worktree add /path/to/wt -b feat/login时，Git 会做三件事：一是在.git/worktrees/wt目录下创建一个元数据子目录，里面记录了这个 worktree 的 HEAD、index、以及它对应的.git文件路径；二是把feat/login分支检出到/path/to/wt这个工作目录；三是更新相关引用的 reflog。

这个机制带来的两个关键隔离是：第一，每个 worktree 有独立的 HEAD 和 index。index是什么？它是暂存区的数据库，记录了你git add了哪些文件。主工作区暂存了 A 文件，不会影响其他 worktree 的暂存状态。第二，每个 worktree 共享对象库和远程引用的获取。你在 worktree A 里git fetch拿到的新提交，在 worktree B 里执行git log也能看到，因为 refs 是共享的。

有一点需要特别注意：同一个分支不能在两个 worktree 中同时检出。比如主工作区在main分支上，另一个 worktree 想切到main，Git 会直接拒绝，并提示main is already checked out at /path/to/main-worktree。这个限制看起来烦人，实际上是为了保护并发写入的安全性，逻辑是对的。

Worktrunk 在设计上就是依托这套机制：它负责管理 worktree 的生命周期、命名规则、分支映射和状态展示，而底层的数据一致性完全交给 Git 自身的机制来保证。这种"不重复发明轮子、把复杂状态管理交给底层原生能力"的设计理念，让工具本身非常轻量且可靠。

2.2 Worktrunk 的 CLI 设计哲学：声明式配置替代记忆负担

如果用原生git worktree命令管理少量任务，手动操作完全能应付。但当你同时管理五六个 Agent 任务时，痛点就出来了：每个 worktree 对应哪个分支？哪个任务已经跑完了可以清理？哪些 worktree 还有未提交的改动不能动？

Worktrunk 把这些问题收敛到了一套声明式配置里。你不需要记住每个 worktree 的命令历史，只需要在一个配置文件中声明"我有哪几个任务、每个任务用什么分支名、跑在哪个目录"，然后让 Worktrunk 帮你把目标状态和实际状态对齐。

它的核心命令面我做了一张速查表：

list和plan是我个人使用频率最高、也最推荐优先体验的两个子命令。list帮你一眼看清当前所有 worktree 的分布情况，plan则是"模拟运行"，它会告诉你如果执行up会发生什么，避免误操作。这种"先看计划再执行"的思路，和terraform plan的哲学很像，对管理多个并发环境非常友好——你永远知道自己将要改变什么。

2.3 为什么手写脚本管理 worktree 是个坑

看到这里你可能会说："这不就是几个git worktree命令套个壳吗？我自己写个 shell 脚本也能做到。"

确实，简单的创建和列出，用脚本完全够。但我在实际项目里发现，真正复杂的是边界情况，而脚本很难把这些情况处理干净。举例来说，当你想要清理一个还有未提交改动的 worktree 时，git worktree remove会拒绝执行，你必须先确认这些改动是否可以丢弃。在脚本里你要么写-f强删（危险），要么写一堆交互逻辑（复杂）。

另一个麻烦是 worktree 的"悬挂"问题。如果你直接手动删除了 worktree 的目录（比如rm -rf），Git 的.git/worktrees里会残留一个失效的元数据记录。之后你执行git worktree list还能看到那个目录，但访问它就会报错。git worktree prune可以清理这种悬挂记录，但一般开发者根本不知道要跑这个命令。

Worktrunk 的价值不是替代 Git 命令，而是把"多 worktree 生命周期管理"这件事变成第一等公民。它处理悬挂目录、处理脏状态检查、处理配置漂移，这些恰恰是脚本最容易踩坑、也最不显眼的地方。我的建议是：如果你只是偶创建一两个 worktree，直接用原生命令没问题；如果工作流里已经出现了"多个 Agent 并行跑"的形态，那一个专门的管理 CLI 带来的收益会非常明显。

3. 从零到一：安装、配置与多 Agent 工作区搭建

3.1 环境要求与安装方式

Worktrunk 对运行环境的要求很朴素：一个是 Git 版本，另一个是你本机的 CLI 环境。

Git 方面，git worktree从 2.5 版本开始引入，早期版本有一些缺陷，比如 worktree 内的git status性能较差、某些命令不支持--git-dir路径解析等。我建议至少使用 Git 2.30 或者更高版本，在 Linux/macOS/WSL 上运行基本没有问题。Windows 原生环境也可以跑，但路径分隔符对 worktree 元数据的处理有时会有一些小毛病，更推荐在 WSL 下使用，体验会顺畅很多。

安装方面，Worktrunk 本质上是一个单二进制 CLI 工具，你可以从项目的 Release 页面下载对应平台的二进制，也可以从源码构建。如果你的机器上有 Go 工具链，一条命令就能装好：

go install github.com/worktrunk/worktrunk@latest

装完后执行worktrunk version确认安装成功。如果输出正常，说明环境就绪。

顺便说一句，如果你之前安装过 Codex CLI 或者 Claude Code CLI，应该对这类单文件 CLI 的安装套路不陌生。Worktrunk 和它们可以无缝协作——它不关心你跑的是哪个 Agent 客户端，只关心你的 Git 仓库里有没有并行的 worktree。

3.2 用配置文件声明你的并行任务

Worktrunk 的核心用法是通过worktrunk.yaml配置文件来声明你的工作区目标状态。

我自己在项目里用的配置是这样的：

# worktrunk.yaml project: my-app agents: - name: agent-login task: feature/login branch: feat/agent-login path: worktrees/agent-login - name: agent-utils task: refactor/utils branch: refactor/agent-utils path: worktrees/agent-utils - name: agent-fix task: fix/payment-timeout branch: fix/agent-payment-timeout path: worktrees/agent-fix

这份配置声明了三件事：每个 Agent 的标识（name）、它要处理的任务（task）、以及对应的 Git 分支和目录路径。path是相对于仓库根目录的，所以worktrees/agent-login表示在仓库根目录下的worktrees/agent-login子目录中创建 worktree。

有了配置之后，先执行worktrunk plan看一下差异：

$ worktrunk plan - will create worktree: worktrees/agent-login (branch feat/agent-login) - will create worktree: worktrees/agent-utils (branch refactor/agent-utils) - will create worktree: worktrees/agent-fix (branch fix/agent-payment-timeout)

确认没问题之后执行worktrunk up，它会批量创建这些 worktree。创建完成后，项目的目录结构大概是这样的：

my-app/ ├── .git/ ├── worktrunk.yaml ├── worktrees/ │ ├── agent-login/ # 分支 feat/agent-login │ ├── agent-utils/ # 分支 refactor/agent-utils │ └── agent-fix/ # 分支 fix/agent-payment-timeout └── src/ # 主工作区，通常在 main 分支

每个 worktree 都是一个完整的独立工作副本。你现在可以分别把三个目录交给三个不同的 AI Agent 去并行干活了。

有一点要留意：配置文件中不要写成path: worktrees/agent-login/这种带尾斜杠的形式，Git worktree 在解析路径时把带尾斜杠的目录当作"已存在目录"处理，有时会报一个奇怪的错。我在最初使用时就被这个问题卡了一次，后来统一去掉尾斜杠就好了。

3.3 日常操作与批量执行

创建 worktree 只是第一步，日常维护才是大头。一旦 worktree 建立起来，我用得最频繁的几个命令是：

# 查看所有 worktree 的状态 worktrunk list # 在某个 Agent 的 worktree 里执行 git 操作 cd worktrees/agent-login && git status # 在所有 worktree 里批量执行测试 worktrunk exec -- "go test ./..." # 清理已经合并完成的分支对应 worktree worktrunk clean --merged

worktrunk exec是我非常推荐的一个功能。在并行开发场景下，让所有 Agent 的代码一起跑一遍完整测试是很常见的要求。原生做法是写一个 for 循环在目录间切换，Worktrunk 把这一步收敛成了一个命令。它会把每一个 worktree 里的执行结果分别标注清楚，方便你快速定位是哪个 Agent 的改动引起了测试失败。

注意worktrunk clean我加了--merged参数，它的意思是只清理那些分支已经被合并进主分支的 worktree，保留还有独立开发的 worktree。这个参数非常有用，避免了你手动判断哪些分支可以删、哪些必须留。

4. 实战：三个 AI Agent 并行改同一个仓库的完整流程

4.1 任务拆分与 worktree 映射

理论讲完，说一个实际跑通的案例。

我最近在维护一个 Go 后端服务，同时有三个模块需要改动：登录认证模块、工具函数库清理、以及一个支付超时 bug 修复。这三个任务在代码层面有少量文件重叠，但大致是独立演进的。如果串行做，每个任务要等上一个任务完成，整体耗时至少是三倍；如果并行做，就必须解决工作区隔离问题。

我的做法是先给三个任务分别建分支，然后通过 Worktrunk 配置文件把它们映射到三个 worktree 上。接下来，我分别用三个终端窗口启动不同的 AI Agent（这里我实际用的是 Codex CLI 和 Claude Code CLI），并告诉它们各自的工作目录和任务目标：

# 终端1：Agent A 处理登录模块 cd /workspace/my-app/worktrees/agent-login codex "实现用户登录接口，包含手机号验证码登录和 Token 刷新" # 终端2：Agent B 处理工具库迁移 cd /workspace/my-app/worktrees/agent-utils claude "把 src/utils 下的 lodash 用法全部替换为原生实现" # 终端3：Agent C 修复支付超时 cd /workspace/my-app/worktrees/agent-fix codex "修复支付回调偶发超时的问题，重点排查数据库连接池配置"

关键点是：每个 Agent 只在它自己的 worktree 目录下读写文件。Agent A 看不到 Agent B 的改动，Agent B 也没法破坏 Agent C 的现场。三个 Agent 同时跑，互不干扰。

4.2 并行开发中的隔离策略与验收

并行跑起来之后，最有意思的现象是 git status 完全互不可见。如果你在agent-login目录下执行git status，你只会看到 Agent A 的改动；在agent-utils下，只会看到 Agent B 的改动。这和"分支隔离+工作区共享"时代是完全不同的体验——那种模式下 git status 往往是两个任务改动的混合体，根本没法用。

但这不代表你完全不用管隔离之外的依赖关系。这里有一个重要的实践建议：共享文件的变更尽量控制在"加函数/加接口"层面，避免大范围重命名。我在这个项目里虽然三个 Agent 在各自的 worktree 中开发，但它们的改动最终要合并到同一份main分支上。如果 Agent B 把utils.go里的Foo()函数改名为FooV2()，而 Agent A 的代码恰好调用了Foo()，合并时就会产生编译冲突。这种冲突在 worktree 并行阶段完全不可见，只有合并时才会暴露。

所以我在每个 Agent 跑完后，都会有一个"验收前检查"步骤：

cd worktrees/agent-login git diff --stat # 看改动范围 git diff --name-only # 看改了哪些文件 worktrunk exec -- "go build ./..." # 全工作区编译验证

go build ./...在各自 worktree 里独立跑，编译通过只是一个基础门槛。真正的验收是看是否影响了其他 Agent 的代码，这个问题只能留到合并阶段去验证。

4.3 合并取舍：顺序、冲突与代码评审

三个 Agent 都跑完后，合并是一个技术活。这时 Worktrunk 的价值在于它把"哪些分支已就绪"展示得一清二楚，你可以根据任务风险来决定合并顺序。

我的合并策略是：先从最底层、被依赖最多的模块开始合并。在这个例子中，Agent B 改的工具函数库被另外两个 Agent 都依赖，所以优先合并它。然后合并 Agent A 的登录模块，最后合并 Agent C 的支付修复，因为它的影响面最小、独立性强。

合并过程：

git switch main git pull origin main git merge refactor/agent-utils git merge feat/agent-login git merge fix/agent-payment-timeout

顺序合并的好处是：如果 B 的工具库改动导致了 A 的编译失败，这个冲突会在我合并 B 之后立刻暴露出来，而不是等三个分支一起汇合时才能发现。一个一个小冲突地解决，比三个大冲突一起堆在面前要轻松得多。

合并时如果遇到多个分支同时修改了同一个函数，我会先拉出三个 diff 对比一下谁改的是哪个逻辑片段，再决定保留谁、或者手动找一个兼容方案。这里不建议让 AI Agent 自动解决合并冲突，它们在冲突解决上的误判率相当高。我在实际中遇到过一次 Agent 自动把两个分支里完全不同的新功能"融合"成了一个不伦不类的实现，编译能过，但逻辑完全错误。从那以后所有合并冲突都坚持手动处理。

5. 踩坑实录与工程化建议

5.1 worktree 的边界条件：分支互斥与清理陷阱

第一类坑和 Git worktree 自身的规则有关。

最典型的是同分支互斥。主工作区如果在main分支上，那么任何其他 worktree 都不能再检出main。这本身是特性不是 bug，但配合 Agent 工作流时有个隐性问题：如果某个 Agent 的任务中途变成了"直接改主分支"，你得先把主工作区切到其他分支，或者专门为它新建一个 worktree。

第二类坑是worktree 清理。git worktree remove会在目录里有未跟踪文件时拒绝删除，这时你通常需要-f强制删除。但-f之后，worktree 的元数据可能没有完全清理干净。在 Worktrunk 里，worktrunk clean默认不做-f，因为它希望你先确认这些文件是否真的可丢弃。如果要清理的对象是正在被某个 Agent 进程占用的目录，删除会报 "directory not empty" 错误。解决方案是先停掉 Agent 进程再删除，这个顺序问题在并行运行时特别容易踩到。

第三类坑是路径大小写和符号链接，在 macOS 上尤其明显。默认文件系统大小写不敏感，如果你有两个 worktree 路径只是大小写不同（WorkTREEvsworktree），Git 可能把它们当作同一个目录，导致各种诡异错误。Worktrunk 的做法是在配置解析阶段检查路径冲突，发现时直接报错。如果你绕开 Worktrunk 手写脚本，这类问题排查起来非常费时。

5.2 与 IDE、工具链的兼容问题

Worktree 模式对命令行工具是透明的（因为它们只关心当前目录），但对 IDE 和守护进程并不是。

以 VS Code 为例，如果你同时打开了主工作区和worktrees/agent-login两个窗口，第一次打开没有问题，但在某些版本中会出现"工作区信任"提示混乱、以及调试器无法绑定正确工作目录的问题。我的习惯是只打开当前需要用到的 worktree 窗口，其他 worktree 保持命令行状态，不开启 GUI 编辑。

另一个容易踩的坑是后台守护进程。如果你有一个文件监听器（比如 Air、nodemon、go-watcher）在主工作区跑着，它监听的路径是固定的。当你切到 worktree 下开发时，那个守护进程监听的还是原来的路径，不会自动跟着切。结果就是你在 worktree 里的改动触发了自动重载，但重载加载的是主工作区的代码——这个 bug 排查起来非常隐蔽。

我现在的工程规范是：每个 worktree 独立启动自己的守护进程，监听路径直接指向 worktree 目录。Worktrunk 的exec命令在这里也能派上用场，批量启动所有 worktree 的开发服务器：

worktrunk exec -- "air"

虽然这个命令要求每个 worktree 里都有对应的二进制或脚本，但一次拉起全部开发环境，效率确实高。

5.3 多 Agent 并行开发的规范建议

最后分享一些我在多 Agent 并行开发中总结出的工程规范。

第一，约定文件所有权。虽然 worktree 从物理上隔离了改动，但最终合并时仍然会冲突。建议在任务拆分阶段就明确"谁负责哪些文件"，尽量避免两个 Agent 同时改同一个文件的不同位置。Worktrunk 配置文件里的task字段除了说明任务外，其实也在文档化这个所有权约定。

第二，配置文件的版本管理。worktrunk.yaml本身应该提交到仓库里。团队成员拉取仓库后，执行一个worktrunk up就能重现整个并行开发环境。我之前犯过一个错误是把 worktrunk.yaml 加进了.gitignore，结果另一个同事怎么都复现不了我的环境，排查半天才发现是这个文件没被提交。

第三，定期 prune。Worktrunk 在内部维护 worktree 元数据，但如果你手动删除了 worktree 目录，元数据会出现悬挂。建议每隔一段时间跑一次worktrunk clean和git worktree prune，把所有陈旧状态一次性清理干净。这也是我通常在合并完一批分支后做的收尾工作。

第四，也是最重要的一条：永远不要在 worktree 之间共享未跟踪文件。worktree 解决了已跟踪文件的隔离，但未跟踪文件（比如.env、本地配置文件、临时脚本）默认是互不可见的。如果你在agent-login里创建了一个.env，Agent B 那边是看不到的。你要么把这些文件纳入 Git 跟踪（并做加密处理），要么专门建一个公共的配置同步目录。这个坑我只踩过一次就学乖了，代价是一个 Agent 因为没有环境变量跑了半小时全部失败。

6. 下一步还能怎么扩展

跑通这套流程之后，我开始把 Worktrunk 往更深的自动化方向用。

一个方向是把它接入 CI：每次合并完一批分支后，自动执行worktrunk clean --merged，保持仓库整洁。另一个方向是把它和任务管理工具联动——每个 worktree 对应一个 Jira 或 GitHub Issue，合并分支后自动关闭 issue。这些如果做成脚本，会和 Worktrunk 的命令面配合得很自然。

还有一个大的思路：用 Worktrunk 把 Agent 会话"容器化"。每个 agent 不再直接接收"去改src/services"这种模糊指令，而是接收"去/workspace/xxx/worktrees/y目录，完成 y 分支上的 y 任务"这种带明确目录、明确分支、明确边界的指令。这样即使未来并行的 Agent 数量从 3 个变成 10 个，也只需要在配置里多加几行，工作流不会崩。

我自己在这套方案下最直观的感受是：并行 Agent 没再互相"打架"过，git status 永远是干净的、可解释、可追踪的，合并时的冲突从"一坨"变成了"可数的、逐项解决的"。这个体验差距，用回单工作区后就再也回不去了。