企业官网建设流程全解析

1. 项目背景与核心思路

1.1 多个 Agent 同时改一个仓库，撞车是必然的

最近半年，身边不少朋友都开始用 Codex CLI、Claude Code 这类终端里的 AI 编程助手。这工具确实猛，给一个足够清晰的任务描述，它能在几分钟内改完一个模块、跑完测试、提一个 commit。但用着用着大家就发现一个尴尬的场景：一个项目仓库，我只开了一个工作区，Agent 改到一半我切回来看它的进度，然后手工改了几行代码，再让另一个 Agent 去修别的模块。两个 Agent 和我在同一份代码里交错操作，结果就是——改动互相覆盖、未提交的临时文件四处乱飞、某个测试挂了但谁都不承认是自己改的。

这就是并行 AI Agent 工作流最核心的矛盾：AI 编程助手的产出效率已经远超单人手工编码，但 Git 仓库的工作区隔离能力还停留在“一个人在一个工作区里干活”的旧模型上。你不可能真正并行地让多个 Agent 同时干活，因为你只有一份工作目录。

我一开始的应对方案很原始：用git stash暂存当前改动，让 Agent 跑一批，再 pop 回来继续改。但试过你就知道，这方案在串行场景下都勉强，并行场景下简直是灾难。我试过同时让两个 Agent 分别改前后端代码，A 改完要提交，B 那边还攒着一堆未提交改动，git stash把 B 的改动也卷进去了。那一刻我就明白了，靠git stash组织多 Agent 协作是死路，必须要做工作目录级别的隔离。

1.2 Git Worktree 是答案，但原生命令太“原始”

Git 其实早就有解决这个问题的机制——Git Worktree。它允许你在同一个仓库里创建多个工作目录，每个目录各自对应一个分支，互不干扰。你在agent-a分支的目录里让 Codex 改代码，在agent-b分支的目录里让 Claude Code 改另一块，两者提交互不影响，push 时各自推各自的分支。

道理是这个道理，但真去用原生git worktree命令的时候，你会发现体验非常硬核：

git worktree add ../project-feature-x -b feature/x git worktree list git worktree remove ../project-feature-x

听起来不复杂对吧？但实际用起来问题一堆。首先，路径你得自己维护，worktree 工作目录建在哪、叫什么名字、对应哪个分支，全靠脑记；其次，删除时如果工作目录里有未提交的改动，git worktree remove会直接报错拒绝执行，你得先手动去那个目录里清理；再者，多个 Agent 并行跑起来之后，每个 worktree 对应哪个 Agent、在跑什么任务，完全没有记录，过两天连你自己都忘了某个目录是干嘛的。

更麻烦的是，git branch -D删分支时如果这个分支正被某个 worktree 占用，Git 会拒绝，提示信息虽然明确但挺绕。真要管四五个并行 worktree，命令复杂度立刻上来。这时候我就意识到，需要有人在 Git Worktree 之上封装一层真正面向 AI Agent 工作流的工具。Worktrunk 就是奔着这个需求去的。

2. 核心机制拆解：Worktrunk 到底做了什么

2.1 Worktree 的底层原理，为什么它是隔离的正确姿势

要理解 Worktrunk 的价值，得先说清楚 Git Worktree 的工作原理。普通情况下，一个 Git 仓库只有一个工作树（working tree），就是你在git checkout之后看到的那个目录。.git目录里存着索引（index）、HEAD 指针、对象库等全部元数据。

Worktree 的本质，是让一个仓库可以有多个工作树。每个 worktree 共享同一个.git对象库（objects）和引用库（refs），但各自有独立的 HEAD、独立的工作目录、独立的索引文件。这意味着什么？意味着在 worktree A 里修改文件、暂存、提交，完全不影响 worktree B 里的工作状态，因为两边用的是同一套对象库，但索引和工作目录是分开的。

用大白话说，就是一张银行卡分出了好多张副卡，共用同一个账户余额（对象库），但每张卡的消费记录、取款记录（索引和状态）是独立的。分支就是每张卡各自的消费额度上限。

这在多 Agent 并行场景下简直完美：Agent 1 在 worktree A 上改user-service模块，Agent 2 在 worktree B 上改order-service模块，它们各自提交的 commit 都进入了共享的仓库对象库。等两边都改完，你把两个分支合并到一起，或者用 rebase 同步一下最新主干，Git 会正常处理合并。关键是整个过程中，任何一个 Agent 都看不到另一个 Agent 半成品状态的脏文件。

对比一下其他方案：

多 clone 方案我不是没考虑过，但缺点太明显：克隆一份完整仓库动辄几百 MB 甚至更大，而且多个 clone 之间是彻底隔离的，代码同步全靠 push/pull，一旦 Agent 需要跨模块改代码（比如前端调后端 API 接口），手动同步成本让人崩溃。Worktree 就不同，所有分支共享对象库，本地 pull 一下就能拿到其他分支的提交，方便得多。

2.2 Worktrunk 在原生 Worktree 之上的三层封装

Worktrunk 做的事，不是重新发明一套隔离机制，而是把原生 Git Worktree 的能力封装成真正适合 AI Agent 工作流的 CLI。它主要做了三层事情：

第一层，生命周期管理。所有 worktree 的创建、枚举、删除都收敛到一个命令入口。不用记git worktree add的复杂参数，Worktrunk 自动处理目录命名、分支命名、路径规范这些琐碎细节。创建 worktree 时只需要说“给 agent-1 开一个分支”，剩下的全部自动完成。

第二层，用途注册与状态记录。每个 worktree 创建时，可以绑定一段描述信息——这个工作区是给哪个 Agent 用的、要完成什么任务、关联哪个 issue。Worktrunk 会把这段元数据记录下来，随时可以查看。这就是原生 Worktree 没有的，因为在多 Agent 场景下，worktree 的目的追踪和代码本身一样重要。你同时跑 4 个 Agent，过一天之后，光靠分支名根本记不住谁是谁。

第三层，并行工作流的便利性整合。比如批量创建 worktree、批量清理、统一查看状态、一键切分支合并等。这些操作单独用原生 Git 命令也能做，但每条都要敲一长串，且非常容易出错。Worktrunk 把高频操作收敛成短命令，降低误操作概率。

这三层封装的核心逻辑，是把 Git 的隔离能力从“需要自己维护状态”变成“开箱即用的工作流服务”。我知道有朋友会说，这些功能我自己写个 shell 脚本也能实现。是，但写过之后你会发现，脚本只落在一个项目里，换个仓库、换台机器就要重新适配，而 Worktrunk 是一个通用工具，配置一次全局可用。

3. 实操指南：从安装到并行 Agent 工作流落地

3.1 安装与初始化配置

Worktrunk 的安装依赖你已经有了一个正常的 Git 环境，并且本机装了 Node.js 18+（它本身是一个 Node.js CLI 工具）。安装方式很简单：

npm install -g @worktrunk/cli

装完之后先验证一下：

worktrunk --version

然后进入你的项目仓库目录，做一次初始化。这里需要注意，Worktrunk 的初始化不会改动你的 Git 配置，它只会创建一个隐藏目录.worktrunk/来存放元数据，比如每个 worktree 的用途描述、任务状态等。

cd your-project worktrunk init

初始化成功后，它会显示当前仓库的基础信息，包括默认分支、当前所在 worktree、已存在的 worktree 列表。如果之前没有用过 Worktree 功能，列表里通常只有主工作区一条。

这里有个小坑提示：如果你的仓库是一个刚git clone的仓库，主工作区的分支名可能是main或master，Worktrunk 会默认把它当作“主干工作区”来管理。如果你项目用的是develop作为主干，可以在初始化后手动设置一下：

worktrunk config set main-branch develop

3.2 高频命令速览与使用路径

Worktrunk 的命令设计很直白，核心路径就四个：创建（create）、使用（use）、查看（list）、清理（remove）。

创建 worktree 的基本语法：

worktrunk create agent-1 --branch feature/agent-1-user-service --description "agent-1: 用户服务模块重构"

这条命令干了三件事：基于当前主干分支切出一个新分支feature/agent-1-user-service；在统一的 worktree 目录（默认是项目根目录下.worktrunk/workspaces/agent-1）创建新工作目录；把“agent-1: 用户服务模块重构”这段描述记入元数据。

创建完之后，你会看到终端提示新 worktree 的绝对路径。进入这个目录，就是一次正常的工作会话：

cd .worktrunk/workspaces/agent-1 # 在这个目录里可以让任意 AI Agent 放心修改代码

查看所有 worktree 的状态：

worktrunk list

输出会展示每个 worktree 的 ID、分支名、当前所在 Agent 用途描述、最后修改时间、是否有未提交改动。这个列表的设计很有意思，它不是简单调git worktree list给你看路径，而是把元数据也整合进来，让你一眼就知道哪个工作区是干嘛的。

用完某个 worktree，想删掉：

worktrunk remove agent-1

Worktrunk 会先检查这个 worktree 里有没有未提交的改动。有的话它会给你两个选择：强制删除，或者先去提交/暂存再回来删。这个提示比原生git worktree remove友好得多，原生命令在遇到未提交改动时只会冷冰冰拒绝，然后你自己去那个目录里慢慢收拾。

3.3 从零搭建三路并行 Agent 工作流

说了这么多，来一个完整的实战演示。假设现在有一个电商项目仓库，我需要同时做三件事：

• Agent A：重构用户服务模块的 API 接口
• Agent B：修复订单模块的一个超时 bug
• Agent C：给前端页面新增优惠券展示位

以往的做法是排队等——先让 A 跑完、测试通过、合并，再开始 B。现在有了 Worktrunk，三路并行没有任何问题。

第一步，创建三个 worktree：

worktrunk create agent-a --branch feature/user-api-refactor --description "Agent A: 用户服务API重构" worktrunk create agent-b --branch fix/order-timeout --description "Agent B: 订单超时bug修复" worktrunk create agent-c --branch feature/coupon-display --description "Agent C: 优惠券展示位"

第二步，三个终端窗口分别进入各自的工作目录，启动对应的 AI Agent CLI（Codex CLI、Claude Code 或其他）：

cd .worktrunk/workspaces/agent-a && codex cd .worktrunk/workspaces/agent-b && claude cd .worktrunk/workspaces/agent-c && gemini

我实测下来，这种模式下三个 Agent 完全不会互相干扰。它们在各自的 worktree 里读文件、改文件、跑测试、提交 commit，整个过程是真正的并行。你唯一要操心的，是如果三个 Agent 会改到同一个公共文件（比如package.json），合并时需要手动解决冲突。

第三步，各 Agent 跑完后，用 Worktrunk 查看整体状态，然后逐个把分支合并回主干：

worktrunk list # 确认所有 worktree 都已提交，无未提交脏数据 git checkout main git merge feature/user-api-refactor git merge fix/order-timeout git merge feature/coupon-display

如果中间有合并冲突，Git 会提示，你在主工作区里正常解决就行。这个流程最舒服的地方是，跟在主工作区里排队等 Agent 挨个跑的体验完全不一样，你不会因为 A 的测试跑了半小时就卡住 B 和 C 的进度。

4. 并行工作流的组织策略与避坑指南

4.1 怎么给 Agent 切分任务，才能避免冲突

工具只是基础，真正决定并行成功率的，是任务切分的颗粒度。我开发和工作里同时跑 Agent 的经验是，切分的第一原则：高内聚模块完整交给一个 Agent，公共文件尽量少交叉。

比如上一个例子里，用户服务、订单服务、前端优惠券展示，三者代码基本不重叠，天然适合并行。但如果任务是“改一个底层的数据库连接池配置”，只这一个改动会影响所有模块，那这个任务就不适合并行，老老实实一个人改完合并再分流。

还有一种情况很容易踩坑：多个 Agent 都依赖某个公共包。比如 Agent A 和 Agent B 都要装一个新的 npm 依赖包，它们在各自 worktree 的package.json里都加了一行依赖。合并时 Git 会报冲突，而且是那种很烦人的依赖冲突——两个分支的package.json更新区域不同但位置相邻，自动合并常常出错。

应对方法有两个。第一个：任务切分时明确指定“谁负责更新公共依赖”，其他 Agent 如果发现需要新依赖，先记录在给主分支的 TODO 里，不直接改。第二个：合并时优先处理package.json和 lock 文件，用项目统一版本的 lock 文件覆盖掉 Agent 各自生成的版本，再重新 install。我是习惯用第一种，因为不断手写 lock 文件很痛苦，让 Agent 自己折腾 lock 文件经常会弄出重复依赖。

4.2 与 AI 编程工具搭配使用时的心得

我这段时间一直在用 Codex CLI 这类终端编程工具配合 Worktrunk 工作，有几个细节感受很深。

首先，工具的工作目录很重要。Worktrunk 创建了几个 worktree 之后，Agent CLI 一定要从对应 worktree 的目录内启动，绝不能在主工作区里指派 Agent 去改别的目录。很多 Agent CLI 默认只在当前目录及子目录下操作文件，如果你在agent-a的 worktree 目录里启动 Codex，它只会看到并修改这个目录下的文件。这就天然保证了 Agent 不会越界碰别的任务的文件。

其次，我强烈建议每个 Agent 拿到 worktree 后，先让它做一件事：查看当前分支和代码结构。也就是说，你在启动 Agent 的时候，prompt 里明确包含“你在分支 X 上，任务目标是 Y，项目结构请看 README”。这样 Agent 的上下文会一开始就锚定在正确的工作区和任务上，而不是靠它自己去猜。

再一个经验是关于测试的。多个 Agent 并行时，不要让它们同时在各自的 worktree 里跑完整的测试套件。测试套件经常涉及数据库、缓存、消息队列等共享资源，两个 Agent 同时跑测试会导致相互干扰，出现各种诡异的偶发失败。我的做法是：各 Agent 在开发过程中只跑自己改动模块的单元测试，全量测试最后由我来跑，在主工作区合并完成后统一执行一次。这样既保证并行效率，又不浪费资源在重复的集成测试上。

4.3 Worktrunk 与 CI/CD 的联动

Worktrunk 不只是开发期的工具，它在 CI/CD 场景下也能发挥意想不到的价值。

我在一个项目里试过这样的流程：CI 流水线提交代码后，动态创建一个 worktree，在这个 worktree 里跑针对特定分支的静态检查、单元测试、构建等任务。跑完后自动删除 worktree。由于 worktree 和主工作区是隔离的，CI 里再乱来都不会污染主分支的工作状态。

具体来说，我能用它实现“一个分支一个验证环境”的效果。比如代码评审时，我需要验证 Agent B 的fix/order-timeout分支功能是否完整，可以：

worktrunk create verify-order-timeout --branch fix/order-timeout --description "验证订单超时修复" # 在这个 worktree 里启动服务、验证修复、跑测试 worktrunk remove verify-order-timeout

验证完后直接删掉，主工作区干干净净。这种用法在以前没 Worktrunk 时，我需要临时 stash 当前工作、切分支、验证、切回、再 stash pop，中间有一个环节出错就白干了。现在这个流程非常顺滑，而且完全不影响正在并行跑的 Agent。

4.4 目录命名与仓库大小管理

Worktrunk 默认把所有 worktree 放在.worktrunk/workspaces/下，我建议你不要改这个路径。统一路径有很多好处：一是.worktrunk/可以加进.gitignore，避免这些工作目录被提交到仓库；二是路径统一后，如果哪天想批量清理或者写脚本处理，会非常方便。

另外要注意磁盘占用。每个 worktree 虽然共享对象库，但工作目录里的构建产物（node_modules、target、dist这类目录）是各存各的。三个 Agent 并行跑一个前端项目，node_modules就占了三份，动辄几个 GB。这个成本是 Git Worktree 模式天生的，解决方案很简单：要么在.gitignore里排除构建产物并定期清理，要么让 Agent 统一用pnpm这类支持硬链接的包管理器。如果你用 pnpm，多个 worktree 的 node_modules 共享硬链接，磁盘占用会大幅降低。

5. 常见问题与排查心得

5.1 高频报错速查表

我整理了一部分实际使用 Worktrunk 和原生 Worktree 时容易遇到的报错，做成一个速查表，你碰到了可以直接对照处理：

这里特别说一下第二个报错。Worktrunk 和其他 CLI 工具一样，你只能在仓库的根目录初始化，然后创建 worktree。但创建出来的 worktree 是一个独立的目录结构，它本身是仓库的 worktree，不是仓库的“源头”，所以理论上你不应该在 worktree 里再执行worktrunk create去创建下一层 worktree。如果误操作，工具会直接拒绝。

5.2 worktree 清理与磁盘空间回收

很多人用 Git Worktree，最大的困惑是：为什么我明明删了分支，磁盘空间没释放？原因在于，worktree 目录本身携带了独立的工作文件，删除分支只是删了引用，不会自动删除工作目录文件。

Worktrunk 的remove命令会帮你处理这个问题，它会先确认 worktree 里的改动状态，然后调用git worktree remove清理工作目录，最后更新元数据。但这个清理不是实时的，如果你已经手工用git worktree remove删过一些工作目录，Worktrunk 里的元数据可能还残留着记录。这时候需要用：

worktrunk prune

它会扫描元数据里记录的 worktree 是否实际存在，不存在的自动清理掉。我在日常使用中养成的好习惯是：每天晚上下班前，把所有 Agent 的工作产物提交或 reset，然后worktrunk prune一遍，保持仓库状态清爽。这比攒一周再收拾省心得多。

5.3 切换 Agent 上下文时，别让“记忆”混乱

AI Agent 工作流里一个容易被忽略的问题是跨 worktree 的上下文转移。我遇到过这种情况：Agent A 在feature/user-api-refactor里做了个关键决策，写在代码注释里了；Agent C 在feature/coupon-display里需要调用一个被 A 改动的接口，但它看到的还是旧接口签名。由于 worktree 隔离，它根本不知道 A 的改动，自然也就不会适配。

这个问题的解法，不是让 Agent C 去看 A 的 worktree，而是把跨模块依赖的接口约定单独提交到主干分支并推送。我的习惯是：如果发现两个 Agent 的任务在接口层有依赖，就先手动创建一个接口约定的分支，让所有相关 Agent 在各自 worktree 里先git fetch origin && git merge origin/spec/api-contract把接口定义同步过来。这样虽然看起来多了一步，但比 Agent 们互相猜改接口省出大量返工时间。

还有一个更简单的习惯：每次 Agent 完成一个里程碑动作（比如接口改好、测试通过），让它立刻 commit 并 push。这样其他 worktree 随时可以通过git fetch && git log origin/branch查阅最新状态。Worktrunk 的list命令会显示最后修改时间，但这个“修改时间”是基于本地文件时间的，不一定代表 push 到远程的时间，要确认远程状态还得看git log origin/...。

5.4 多个 Agent 并行时的网络与认证问题

并行 Agent 跑起来之后，网络层面的坑也不少。最典型的：多个 Agent 同时执行git push或git fetch，如果你的 Git 远程配置了需要认证的 HTTP 方式，并发操作可能会触发凭证冲突，出现类似bad line length character或Authentication failed的报错。

我建议所有用 Worktrunk 管多 Agent 的场景，优先给 Git 配 SSH 方式访问远程仓库，而不是 HTTP + 个人访问令牌（PAT）。SSH 的凭证管理在多进程并发下稳定得多，不会因为多个进程同时用同一个 token 触发服务端限流。

另外要提醒的是，如果你在公司防火墙后面开发，多个 Agent 同时拉取外部依赖（npm install、pip install）时，最好给它们配置统一的代理镜像源或本地缓存。否则并发下载不仅慢，还可能把内网代理打挂。

最后再分享一个小技巧

整个 Worktrunk 使用下来，我最大的感受是：它的核心价值不是替代 Git，而是把 Git 的隔离能力封装成了 AI Agent 工作流的第一公民。在我用过的众多 Git 辅助工具里，很少有工具是专门为“多智能体并行”这个场景设计的，Worktrunk 的定位非常精准。

有一个我一直在用但可能不算主流的小技巧：我会在每个 worktree 创建后，在.worktrunk/workspaces/<id>/README.md里放一份简短的 Agent 指令文件，内容包含这个 worktree 对应 Agent 的优先级、技术约束、验收标准。然后启动 Agent 时，prompt 里直接写“首先阅读项目根目录的 WORKTRUNK_AGENT.md，然后开始执行任务”。这样 Agent 每次开始工作，都能快速恢复正确的工作状态，不会因为上下文丢失而跑偏。我把这个文件路径固定在每个 worktree 的根目录下，配合 Worktrunk 的创建模板能力，每次新建 worktree 都会自动生成。

如果你现在正被“多个 AI Agent 同时改一个仓库”这个难题卡着，我真心建议你用 Worktrunk 搭一个并行工作流试试。刚开始可能只是觉得省了点切换时间，但跑几天之后你会发现，开发节奏完全不一样了。