企业官网建设流程全解析

1. 为什么我在跑了几个月 AI Agent 之后，开始认真研究 Worktrunk

先说个场景。我大概是半年前开始重度使用 Codex CLI、Claude Code 这类工具来改代码。最开始我是老老实实开一个分支，让 agent 在里面自由发挥，自己切回主分支干别的活。结果一周之后，我的git branch --list里躺着三十多个分支，有的叫fix-login-token，有的叫wip-agent-20250213，还有几个压根不知道是干嘛的。想清理的时候，完全不敢删，因为根本不知道哪些分支已经合并过了，哪些还留着 agent 写到一半的重要改动。

后来我尝试同时跑两个 agent，一个让我改前端交互，一个去处理后端接口联调。它们俩基于同一个工作目录、同一条主分支展开了各自的修改。等我准备把两边的工作合并起来的时候，冲突已经大到让我想直接rm -rf整个仓库重新 clone。

就是在这个节骨眼上，我接触到了 Git Worktree 的高级玩法，后来又折腾出了一个叫 Worktrunk 的命令行小工具——它本质上是给 Git Worktree 加了一层面向并行 AI Agent 工作流的管理编排。如果你也在用 AI Agent 编程，或者你正在搭建自己的自动化代码工作流，这篇东西应该能帮你省掉不少弯路。

先解释一下 Worktrunk 能解决什么问题。它解决的并不是"AI 会不会写代码"的问题，而是"多个 AI Agent 在同一个代码仓库里并行干活时，怎么让它们互不干扰、改完的东西还能干干净净合回来"的问题。这里的核心手段就是 Git 自带的 worktree 机制，但直接裸用 worktree 只能解决一半，另一半——分支管理、生命周期、状态追踪、并行隔离——正是 Worktrunk 这个 CLI 存在的意义。

这篇文章适合这样的读者：正在用各种 Agent CLI 工具写业务代码的开发者，想在自己的项目里接入并行 AI 开发流程的团队，以及单纯对 Git 底层机制感兴趣的工程师。我会从工作流的痛点出发，拆解 Worktrunk 的设计思路，然后给出一套可以直接复制的实操流程，最后把我踩过的坑一起交代清楚。

2. 并行 AI Agent 工作流的核心矛盾，以及 Git Worktree 为什么是解药

2.1 先搞懂并行 Agent 到底在并行什么

很多人提到"并行 AI Agent"，脑子里第一反应是多个模型实例同时推理、同时生成 token。但在代码工程这个场景里，真正有价值的并行不是模型层面的，而是任务执行层面的。什么意思呢？就是你让 Agent A 去修一个登录态的 bug，让 Agent B 去重构一个工具函数，让 Agent C 去补测试用例，三个任务在逻辑上是互不依赖的，理论上可以同时开工。

但如果你只有一个工作目录、一条主分支，这三件事没法真正并行。Agent A 改了文件，Agent B 也改了同一个文件，后写的覆盖先写的，或者 Git 直接报冲突。更麻烦的是，很多 Agent CLI 在跑任务的时候会执行npm install、跑测试、跑 linter，这些操作会改动node_modules、生成构建产物，彼此之间根本没法共享同一个工作目录。

我之前就遇到过：Agent A 跑完前端构建之后把dist/目录里的东西改了一轮，Agent B 紧接着跑测试直接挂了，因为它拿到的dist/是 A 改到一半的状态。这种问题根本不是 prompt 能解决的，它是工作区隔离问题。

2.2 Git Worktree 解决了隔离问题，但制造了管理问题

Git 从 2.5 版本开始支持git worktree，它的原理很简单：一个仓库可以同时存在多个工作目录，每个工作目录可以检出不同的分支。这些工作目录共享同一个.git对象库，所以提交历史和对象都是共享的，但工作区文件、索引、HEAD 都是各自独立的。

这意味着什么？意味着你可以在同一个项目里开三个终端，分别进入三个不同的 worktree 目录，让三个 Agent 分别干活。它们各自有完整的代码副本、各自的依赖目录、各自的构建产物，互不干扰。改完之后，每个 Agent 在自己的分支上提交代码，你最后统一做代码审查和合并即可。

但裸用git worktree的问题很快就暴露了。我列几个我自己真实遇到的：

1. 分支管理混乱：每个 Agent 跑起来就得先开分支，跑完我还得记住哪个分支对应哪个任务，分支名稍微起得随意一点就彻底完蛋。
2. worktree 生命周期无人管理：Agent 任务失败、中断、跑挂了，worktree 目录还躺在磁盘上，占地方不说，还会让git worktree list越看越乱。
3. 无法一眼看清并行状态：三个 Agent 同时在跑，我切来切去查看它们各自改了什么、改到哪一步了、能不能合并，靠人肉记忆非常痛苦。
4. 合并时机难以掌握：Agent 自己跑完不等于代码能合并，你必须自己判断合入时机。没有系统化的协作机制，合并的时候就只能靠运气。

2.3 Worktrunk 的设计出发点：把 worktree 变成一等公民

Worktrunk 的思路，是把 worktree 从"Git 的一个底层特性"提升为"并行 Agent 工作流中的一等公民"。它用 CLI 的方式把一整条工作流串起来：创建 worktree、绑定任务、启动 Agent、跟踪状态、提交改动、合并回主分支、清理现场。

你可以把 Worktrunk 理解为 Git worktree 的一个前端编排器，它把git worktree add这种底层命令藏起来，暴露出的是worktrunk session start、worktrunk list、worktrunk merge这种和 Agent 任务直接对应的语义化命令。

3. Worktrunk 的核心功能拆解

3.1 Session（会话）：一个 Agent 任务 = 一个独立会话

Worktrunk 里最重要的抽象是 Session。一个 Session 对应一个 Agent 任务，它包含：

• 一个独立的 worktree 工作目录
• 一个独立的分支（基于某个基线分支拉出）
• 一段描述性的任务说明
• 当前状态（运行中、待合并、已合并、已中止等）

这样做的好处是，你不需要记住"分支feat/user-auth-refactor是给哪个任务开的"，你只需要用worktrunk list就能看到所有 Session 的名称、状态、分支名、最后修改时间，一目了然。

从我的实际经验来看，Session 这个概念让整个团队协作变得简单了很多。我和同事共享一个仓库时，不再需要口头同步"我在哪个分支上干活"，直接看worktrunk list就知道彼此在做什么，整个并行开发的状态完全透明。

3.2 自动分支命名与隔离策略

手动创建 worktree 时，最头疼的问题之一是怎么给分支起名。你想让名字能描述任务，又不能太长，还得避免重名——这在多 Agent 并行时尤其麻烦。

Worktrunk 的策略是：默认基于任务名生成短横线分隔的分支名，同时自动加一个时间戳后缀来避免冲突。比如你启动一个 "fix login token expiration" 的任务，生成的分支名就是类似wt/fix-login-token-expiration-20250213T1530这种格式。wt/前缀让你一眼识别这是 worktree agent 会话分支，时间戳后缀保证了唯一性。

这个做法虽然看起来简单，但实际用起来非常香。因为 Agent 在任务执行中往往会产生很多中间提交，你希望它能自由提交而不用担心污染主分支。分支隔离让你可以大胆地让 Agent 任意操作，反正大不了整个分支不要了。

3.3 状态追踪与进度掌握

我最开始用裸 worktree 的时候，最痛苦的就是"不知道 Agent 干到哪一步了"。Agent 跑完任务后静默退出，你以为它成功了，打开代码一看发现改了一半。或者 Agent 一直在跑，但不确定它在思考还是在死循环。

Worktrunk 的状态追踪机制把这个问题系统化了。它会在 Session 里记录最近一次 Agent 执行的时间、当前所在提交的哈希值、以及已变更文件的数量。我只要运行worktrunk status，就能知道每个 Session 的活跃程度：

• 如果某个 Session 很长一段时间没有新的提交产生，说明 Agent 可能卡住了
• 如果某个 Session 产生了大量变更文件但还没有提交，说明 Agent 可能正在大改代码，我需要提高警惕
• 如果某个 Session 显示待合并，说明 Agent 已完成任务并准备交付

这种"心跳追踪"的概念，让并行 Agent 工作流变得可控。我称之为 Agent 工作流的"仪表盘效应"——你要是看不到状态，你就无法管理，你能看到状态，你才能谈得上介入和控制。

4. 实操：从安装到跑通一个完整的并行 Agent 工作流

4.1 安装与环境准备

Worktrunk 的安装方式很简单，如果你用的是 macOS 或者 Linux 环境，直接通过包管理器装就行：

npm install -g worktrunk

或者如果你用 Homebrew：

brew install worktrunk

安装完之后验证一下版本：

worktrunk --version

需要注意的是，Worktrunk 依赖你本地的 Git 版本不低于 2.5（worktree 特性需要），但我建议直接把 Git 升到 2.40 以上，因为新版 Git 在 worktree 的性能和稳定性上有不少改进。实测下来，Git 版本太老会出现 worktree 元数据同步异常之类的问题，升级到新版基本都能解决。

4.2 初始化工作区：worktrunk init

在一个已经存在的 Git 仓库里，运行：

worktrunk init

这个命令会在仓库里创建一个隐藏的.wt/目录，用来保存 Worktrunk 的会话元数据。你可以把它理解成 Worktrunk 的"数据库"，记录着当前仓库所有 Session 的状态。

如果你是从零开始一个新项目，也可以先git init创建仓库，再执行worktrunk init完成初始化。初始化完成后，worktrunk list会显示一个空的 Session 列表，这时候就可以开始干活了。

4.3 启动第一个 Agent 会话：worktrunk session start

假设我要让 Agent A 去实现一个用户登录接口的 JWT 令牌刷新功能。我打开终端，运行：

worktrunk session start --name "implement jw t refresh flow" --base main

这条命令会做几件事：基于main分支拉出一个新分支wt/implement-jwt-refresh-flow-<timestamp>，在.wt/sessions/下创建一个对应的 worktree 目录（默认路径是.wt/sessions/implement-jwt-refresh-flow/），然后把这个 Session 标记为"运行中"。

接着我切到那个 worktree 目录里启动 Agent：

cd .wt/sessions/implement-jwt-refresh-flow codex "implement JWT refresh token endpoint and update frontend to use it"

这里有个关键点：Agent 跑完之后，所有的改动都留在该 Session 自己的 worktree 目录里。主目录、主分支完全不受影响。我可以同时开三个终端，分别让三个 Agent 在三个 Session 里跑三个互不相关的任务。

4.4 管理并行状态：worktrunk list 与 worktrunk status

Agent 们开始跑之后，我一般会开一个独立终端来巡查状态。最常用的命令就俩：

# 查看所有会话的简要列表 worktrunk list # 查看指定会话的详细状态 worktrunk status <session-name>

worktrunk list的输出大概长这样：

Session Branch Status Updated implement-jwt-refresh-flow wt/imp-jwt-20250213T1530 running just now refactor-utils-to-ts wt/ref-util-20250213T1532 running 2 min ago add-cypress-e2e-for-checkout wt/add-cyp-20250213T1540 ready 1 hour ago fix-login-token-expiration wt/fix-log-20250213T1601 needs-review 5 min ago

有了这个列表，我对整个并行工作流的状态全盘掌握。哪个还在跑，哪个已经跑完等待验证，哪个需要人工介入做 code review，看一眼就够了。

4.5 合并与清理：worktrunk merge 与 worktrunk session close

当某个 Session 的 Agent 跑完任务，并且我 review 过代码之后，就可以合并了。Worktrunk 封装了一个安全的合并流程：

worktrunk merge fix-login-token-expiration --target main

执行这条命令时，Worktrunk 会先检查目标和源分支之间是否有冲突。如果没有冲突，它直接执行一次 fast-forward 或者默认的 merge commit；如果有冲突，它会停下来告诉你冲突文件列表，等你手动处理完再继续。

合并完成之后，清理现场：

worktrunk session close fix-login-token-expiration

这个命令会合并后的分支删除（可选保留）、移除 worktree 目录、并把 Session 状态标记为"已关闭"。整个生命周期干净利落。

5. 我在真实项目中踩过的坑，以及设计上的取舍分析

5.1 坑一：Agent 的工作目录依赖问题

第一个大坑是关于 Agent 安装依赖的。很多 AI 编程 CLI 在你进入目录执行任务时，会自动检查依赖是否安装，甚至会自动执行npm install或者pip install。在独立 worktree 里跑 Agent，每个 Session 都要重新装一份依赖。

刚开始我觉得这很浪费磁盘空间，后来发现这反而是特性不是 bug。因为 Agent 在改代码的过程中会频繁跑测试，如果测试失败是因为依赖环境变了，那没法定位是 Agent 改坏了代码还是环境坏了。独立目录让环境隔离变得绝对可靠，代价是磁盘空间换稳定性，我个人认为非常值。

如果你确实需要省空间，可以在 Worktrunk 的配置里开启依赖目录共享，但我不推荐，因为这意味着多个 Agent 共享node_modules的时候可能出现依赖版本冲突。

5.2 坑二：合并时机靠猜，需要"变更摘要"来兜底

第二个坑是合并时机。Agent 说"我完成了"，但实际改出来的代码可能跟任务描述差别很大。如果你不做任何 review 就直接 merge 回主分支，等于把信任完全交给了模型。

我的经验是：在合并之前，先运行worktrunk diff查看这个 Session 相对基线分支的完整改动：

worktrunk diff implement-jwt-refresh-flow

这个命令会展示一个结构化的变更摘要：哪些文件新增了、哪些文件修改了、哪些文件被删了、每个文件的修改行数。更重要的是，Worktrunk 可以调用本地大模型生成变更说明——它会自动阅读 diff，生成一段人话总结，告诉你"这次改动实际上做了什么"。

别小看这个功能。模型生成的变更说明虽然不是 100% 准确，但它能帮你快速抓住 diff 的主体意图，你只需要重点检查那些说明里没提到的改动——那些往往是 Agent 擅自加的私货或者改错了方向的东西。

5.3 坑三：多 Agent 同时改公共基础设施文件的冲突

最后一个我想展开的坑，是多个 Agent 同时改了公共文件——比如package.json、tsconfig.json、全局样式文件——导致的合并灾难。

Worktrunk 的缓解方案是引入"文件锁"概念：你可以在 Session 启动时声明它将要修改的关键文件路径：

worktrunk session start --name "upgrade-react-version" --lock package.json tsconfig.json

当另一个 Session 尝试启动并且也声明要改package.json时，Worktrunk 会给出警告，提醒你两个任务之间存在文件层面的潜在冲突。你可以选择忽略警告强行启动，也可以排队等第一个任务完成后再启动第二个。

这个方法本质上是在合并冲突发生之前提前检测，把冲突从"合并时爆发"提前到了"任务启动前预警"。配合上面对变更摘要的 review，基本上把并行 Agent 的冲突风险降到了可控范围。

5.4 设计取舍：为什么不做自动冲突解决

有一个设计我想特别解释一下：为什么不直接让 Worktrunk 自动合并冲突？

我的答案很简单：自动解决冲突在代码上是有上限的。模型可以解决空行冲突、格式冲突这种低级别冲突，但遇到逻辑层面的冲突——比如两个 Agent 都对同一个函数进行了语义性的重写——自动合并带来的风险远大于收益。我曾经试过让 Agent 自己 merge 一个逻辑冲突，结果它把两边各砍掉一半，产出了一个两边都不要的行为。从那以后我坚定地认为，代码语义层面的冲突必须由人来做最终判断。

所以 Worktrunk 在设计上刻意不做自动冲突解决，只提供冲突检测、冲突预警和冲突文件查询。把"解决冲突"这个责任保留给人类开发者，它只负责把冲突暴露得足够清楚。

6. 常见问题速查与进一步拓展

6.1 高频问题汇总

6.2 从 Worktrunk 到团队级并行 Agent 工作流

Worktrunk 目前是我个人的效率工具，但它的使用场景天然适合小团队。我设想的一个理想用法是：团队共享同一个仓库，每个成员的 Agent 任务都在自己的 Worktrunk Session 里跑，大家通过worktrunk list实时同步状态。合并之前，Session 的所有变更都经过一次人工 review。

更进一步，Worktrunk 还可以接入 CI 流程。比如做一个脚本，自动检查所有处于"待合并"状态的 Session 是否通过了测试，只有测试通过的 Session 才允许 merge。这等于把 Agent 产出的代码用 CI 的标尺量过一遍，质量门槛就有了保障。

我实际使用下来的体会是，Worktrunk 这种工具最核心的价值不在于"创建 worktree"这个动作本身——那个用 git 原生命令几秒钟就能做到——而在于它把并行 Agent 工作流的所有状态变成了可查询、可管理、可审计的数据。在这个基础上，你才能放心地把多个任务同时交给 Agent 去跑，你掌握的是全局的掌控感，而不是盲目的信任和随机性的救火。

最后再分享一个小技巧。如果你经常用 codex 或者 claude 这类 CLI Agent，建议在启动命令里加上"只修改本目录内文件"的约束提示词，再配合 Worktrunk 的文件锁机制，双保险下来，Agent 偶尔手滑乱改文件的问题基本能杜绝。并行 Agent 工作流这件事，工具只解决一半，另一半靠流程纪律。Worktrunk 至少让我这种普通人，也能把并行 Agent 玩得明明白白。