企业官网建设流程全解析

如果你在一台机器上同时跑三个 AI 编程 Agent，大概很快就能撞上我当年那种尴尬：每个 Agent 看起来都在认真干活，但它们的改动全都堆在同一个工作目录里，分支来回切，文件互相覆盖，最后连谁改了什么都说不清。更刺激的是，某个 Agent 为了“同步主分支”顺手执行了git checkout main，另一个 Agent 刚写了一半的代码瞬间原地消失，那种心情跟加班到凌晨发现没保存差不多。

我后来把整套并行流程搬到 Git Worktree 上，又基于它写了一个叫 Worktrunk 的命令行工具。简单说，Worktrunk 是面向并行 AI Agent 工作流的 Git Worktree 管理 CLI，核心思路很简单：一个 Agent 一个独立工作区，代码互不干扰，合流按固定流程走。这篇文章就聊聊这个工具要解决的问题、底层原理、实操接入方式，以及我在真实并行场景里踩过的坑。

1. 并行 AI Agent 究竟卡在哪：分工、合流与 Git Worktree 的天然契合

1.1 一个可以复现的“现场事故”

先说一个我后来在朋友那边也经常复现的场景。你给 Agent A 安排“重构认证模块”，给 Agent B 安排“补接口测试”，两个 Agent 都在同一个仓库目录下启动。表面上看它们各自读文件、改文件，互不干扰，但问题在于它们共享同一个工作区、同一个分支、同一个索引状态。

Agent B 跑了一会儿，可能因为某个用例失败，手动执行了git checkout main来“回到干净基线”，这一下就把 Agent A 还没提交的修改全部被动清除。更隐蔽的是，如果两个 Agent 都往src/utils.ts里追加工具函数，你最终得到的是互相穿插、语义错乱的代码，别说自动合并，连人肉 Review 都很难受。

这种问题的本质是共享可变状态。多个并发执行者操作同一份文件系统状态，任何一方做出全局性操作都会波及其他人。

1.2 Git Worktree 的底层机制：为什么能做到互不干扰

Git 2.5 之后提供的 Worktree 特性，是解决这个问题的天然抓手。它允许同一个仓库同时存在多个工作目录，每个工作目录拥有自己的文件快照、自己的索引、自己的 HEAD。

用一条命令就能创建独立工作区：

git worktree add ../agents/agent-auth -b agent-auth

这个命令会在../agents/agent-auth目录下生成一个完整可用的代码副本，同时指向同一个.git对象库。从底层看，主仓库的.git/worktrees/agent-auth会多出一套管理元数据，新目录里的.git只是指向主仓库的实际.git文件，对象数据、引用数据都是共享的。

这里有个关键约束：同一时间，一个分支只能在一个工作区里被检出。

fatal: 'agent-auth' is already checked out at '...'

这条限制看着讨厌，但对并行 Agent 工作流恰恰是好事。它强行保证了“一个 Agent 的分支只存在于这一个 Agent 的工作区”，不会出现两个执行者同时在一个分支上乱写。你要做的只是给每个 Agent 都分配独立分支，工作区之间就形成了逻辑隔离。

对比普通分支协作模式，差异很明显：

如果只是偶尔用一次，git worktree原生命令确实够用。但当你同时管理七八个 AI Agent 时，问题就变成了“如何记录哪个工作区对应哪个任务、下一步该合并谁、哪些工作区已经可以清理”。

1.3 手写命令的痛点与 Worktrunk 的定位

我一开始也老老实实手写。规范是有的，比如统一用git worktree add -b agent/${日期}-${任务名} -m "..."，但执行几天后明显吃力。

最大的难点不是创建，而是“上下文记录”。真实项目里，每个工作区背后都跟着一长串任务上下文：当前进度、计划文档、卡住的点、最后一次同步时间、Agent 退出前的输出日志。这些零散信息放在终端之外，时间一长就变成黑盒。

Worktrunk 的做法，是把 Git Worktree 当底层能力，在上层套一层“Agent 工作区”的抽象。每个 Agent 分配一个命名工作区，工作区里除了独立 checkout，还自动带上任务描述、计划文件、状态元数据。工具本身内置了 trunk-based 的开发纪律：主干分支长期只有一个，Agent 的工作区全部从主干分裂出去，完成后统一合回主干。

2. 从零把 Worktrunk 跑起来：常用命令、目录约定与状态管理

2.1 安装与初始化

Worktrunk 提供了常见包管理器的安装方式，你可以根据自己的环境选：

# Go 用户 go install github.com/worktrunk/worktrunk@latest # Node 用户 npm install -g worktrunk

安装完成后，进入任意已初始化的 Git 仓库，执行初始化：

cd ~/projects/server-repo worktrunk init --trunk main

这个命令会在仓库根目录生成.worktrunk/配置目录，默认把main设为唯一主干。后面所有 Agent 工作区都从main分裂，合流也回到main。

配置目录里会生成类似这样的结构：

server-repo/ ├── .git/ ├── .worktrunk/ │ ├── config.toml │ └── workspaces/ └── src/

config.toml记录主干分支名、默认基础镜像、Agent 命令模板等。目录结构很轻量化，不干预你的常规 Git 操作。

2.2 创建一个 Agent 工作区

核心命令是worktrunk create：

worktrunk create agent-auth \ --base main \ --task "把认证模块从单体服务中抽成独立模块"

这条命令背后做三件事。它先通过git worktree add创建独立分支和独立目录；然后在.worktrunk/workspaces/agent-auth/下写入任务元数据与计划模板；最后输出这个工作区的绝对路径，方便直接丢给 Agent 工具使用。

生成后的目录长这样：

.worktrunk/workspaces/agent-auth/ ├── plan.md # 任务目标、约束、测试命令 ├── context.md # 背景资料、相关文件路径 └── repo/ # 实际 Git Worktree

之所以把repo/嵌套在任务目录里，而不是把agent-auth本身当作工作区目录，是为了给 Agent 上下文文件留下独立空间。Agent 被启动后，会读取上一级的plan.md和context.md，再进入repo/动手改代码。

2.3 日常操作：状态查看、同步、收官、清理

并行跑多个 Agent 后，你最需要的不是创建命令，而是状态总览。

worktrunk status

输出类似：

Workspace Branch Base Status Last Sync agent-auth agent-auth main work in progress just now agent-payment agent-payment main work in progress 2h ago agent-docs agent-docs main ready to finish -

一眼扫过去就能知道：谁还在写、谁已经可以合、谁离线太久需要检查。

日常同步使用sync，把一个 Agent 工作区更新到最新主干：

worktrunk sync agent-payment

方案执行的是“把主干分支合并进 Agent 分支”，而不是直接rebase。原因后面会细说，这里先记住一个原则：Agent 上下文里的改动量往往很大，尽量用可回溯的 merge 方式，别用会重写历史的方式。

Agent 工作完成后收官：

worktrunk finish agent-auth

默认会把 Agent 分支压缩成一个 commit（如果你没有设置关闭 squash），尝试将其合并回main，然后清理对应工作区。如果合并发生冲突，它会停下来，等你处理完再继续清理。

如果有 Agent 任务被中途废弃，或者某个工作区已经不需要了：

worktrunk abort agent-docs

与finish的区别是，abort不合并任何内容，直接把工作区删除。

最后还有一个兜底清理命令：

worktrunk prune

有时候 Agent 自己执行了rm -rf或者其他操作，导致目录和 Git 元数据对不上，prune会扫描所有登记过的工作区，清理掉已经不存在或失去引用的脏数据。

2.4 我默认启用的几项配置

实践下来，有几个配置我是强烈建议打开的。

autosync可以设置每个工作区每隔一段时间自动执行同步。并行任务跑久了，主干分支很容易领先 Agent 分支几百个 commit，到收官阶段再一次性合并，冲突规模会非常吓人。

squash-on-finish建议默认打开。Agent 在实现过程中会产生大量碎片化提交，整体不审查价值。压成一个 commit 之后，代码评审者只需要看一个清晰的 diff，体验好得多。

orphan-ttl决定一个“被废弃且没有新提交”的工作区多久后被系统视为孤儿，方便定期清理并防止磁盘膨胀。

3. 与 Codex CLI / Claude Code 等 Agent 工具链的三种接入方式

3.1 把任务上下文“喂”进 Worktree

光有独立工作区还不够，你得让 Agent 知道这轮要干嘛。我的习惯是充分利用plan.md和context.md。

在plan.md里写清楚三件事：任务目标列表、明确禁止修改的文件或模块、验收标准与测试命令。在context.md里放相关文件路径、历史决策记录、可能依赖的接口文档。

然后启动 Agent 时，直接把这两个文件指给它。

以 OpenAI Codex CLI 为例：

cd .worktrunk/workspaces/agent-auth/repo codex exec --full-auto \ --sandbox workspace-readonly \ "读取 ../plan.md 和 ../context.md，严格按计划实现，完成后运行 npm run test"

Claude Code 端类似：

claude -p "请先阅读上层的 plan.md 与 context.md，按其中约束完成任务，并执行代码检查" \ --output-format json

这种“上下文文件 + Agent 自读”方式的好处是：不依赖嵌套在对话里的临时 prompt，任何新会话都可通过同一份上下文文件恢复进度。即使 Agent 崩溃了，重开一个会话也能快速回到正确的轨道上。

3.2 在 Worktree 里完成编译与验证闭环

工作区独立之后，验证环节也要跟着独立化。我在每个 Agent 工作区里直接跑测试：

cd .worktrunk/workspaces/agent-auth/repo npm run build && npm run test

由于每个工作区有自己独立的node_modules（或者你配置的依赖方案），不同 Agent 安装不同版本的依赖时不会互相影响。这也是 Worktree 并行相对“多个 Agent 在同一目录乱跑”的又一个决定性优势。

有一个很现实的坑要提一下：很多 Agent 工具的 CLI 是外部安装的，你的 shell 环境如果没把它们的路径暴露给 Agent 子进程，启动时就会遇到类似unable to locate the codex cli binary这类报错。这个问题的本质不是 Worktree 造成的，而是执行环境 PATH 不一致。建议你在运行 Agent 的用户环境下先执行：

which codex which claude

确认能找到可执行文件，再给启动脚本设置统一 PATH。我在真实项目里见过太多次“明明能跑，换成 Agent 执行就找不到二进制”的情况，基本都是环境变量没对齐。

验证完之后，用git diff --stat快速看改动面：

cd .worktrunk/workspaces/agent-auth/repo git diff --stat

如果改动量远超任务本身范围，就要小心 Agent 是不是顺手把别的模块也改了。这个信号比看代码内容更早暴露异常。

3.3 目录级自动化：wrapper 脚本与 MCP tool 接法

跑一次 Agent 的启动流程其实很固定：创建工作区、写上下文、进入 repo 目录、启动 Agent、同步、验证。每次手工敲一遍太繁琐，我选择用一个 wrapper 脚本固定这套流程。

#!/usr/bin/env bash set -euo pipefail ALIAS="$1" TASK="$2" worktrunk create "$ALIAS" --base main --task "$TASK" cd ".worktrunk/workspaces/$ALIAS/repo" # 把项目级指令写入 plan cat > ../plan.md <<EOF # $TASK ## 约束 - 只修改与任务直接相关的文件 - 保持向后兼容 ## 验收 - 确保 PascalCase 命名规范 - 执行 npm run test 全部通过 EOF # 启动 Agent（这里以 codex 为例） codex exec --full-auto "读取 ../plan.md 与 ../context.md 后开始实现"

这个脚本让整个工作流可以重复执行，再配合 CI 或定时任务，就能做到“丢一个任务进去，自动开一个工作区，Agent 自己干活”。

更进一步，Worktrunk 也可以作为一个 MCP（Model Context Protocol）服务暴露给 Agent。MCP 就是让 Agent 与外部工具交互的一套协议，接入后 Agent 不再需要通过 shell 拼接 Git 命令，而是直接调用 Worktrunk 暴露的工具接口，例如create_workspace、sync_branch、finish_workspace。

这样一来，Agent 自己就能完成“开工作区、更新基线、合回主干”的完整生命周期，全程不需要人类手输命令。

4. 并行场景下的取舍与踩坑：依赖、文件冲突与残留清理

4.1 依赖目录的重复消耗与软链方案

Worktree 的隔离不是没代价的。每个工作区都有自己的一份依赖，大型 Node 项目跑 8 个 Agent，光node_modules就可能吃掉十几 GB 磁盘。

有些人会直接把依赖目录软链到共享目录：

ln -s ../_shared_node_modules repo/node_modules

实测下来，这种方式能省空间，但风险不小。很多构建工具基于真实路径解析模块，一旦软链产生路径差异，就会冒出各种离奇错误，比如“模块找不到”或“缓存命中异常”。如果你的包管理器本身支持内容寻址存储（比如 pnpm），建议优先用包管理器自身的机制解决重复问题；手工软链只适合临时磁盘紧张的场景。

我的取舍标准很简单：换磁盘空间换稳定。常规规模项目里依赖重复安装基本可以接受，毕竟多花的时间是一次性的，而排查一个软链引起的诡异构建错误可能耗费数小时。

4.2 多个 Agent 写同一个文件的冲突策略

要彻底避免文件冲突，靠的不是 Worktree，而是任务拆解方式。

我常用的策略是把任务按模块切分，并在context.md里声明文件所有权。比如“认证模块属于 agent-auth，支付模块属于 agent-payment，公共工具库只允许 agent-common 修改”。每个 Agent 被要求先检查自己是否越界，再开始动手。

如果两个 Agent 还是不可避免地改到了同一个文件，处理时机比处理技巧更关键。我观测到的规律是：越晚同步，冲突越大。所以我在 Worktrunk 里加入了自动同步策略，当主干分支更新时，正在运行的工作区会被通知尽快 sync。

对比一下不同同步策略：

我目前使用折中方案：Agent 任务完成前至少主动 sync 一次，中间过程如果有较大主干更新也立刻 sync。宁可合并多几次，也不要攒到最后一次性处理。

另外提一个 Git 的冷知识：git stash在所有 worktree 之间是共享的。你在某个工作区里 stash 的改动，跑到另一个工作区里git stash pop可能互相干扰。Agent 一旦自己执行 stash 相关操作，很容易产生混乱，所以我的 Worktrunk 工作区默认不建议 Agent 使用 stash，而是让它们保持普通 commit，靠分支隔离保证安全。

4.3 Agent 中断后的工作区残留

Agent 被强制终止是常态。代码写到一半、进程被 kill、上下文文件还没生成完毕，工作区就会残留一堆半成品文件。

传统的做法是直接删掉。但我在刚开始并行运行时吃了大亏：有一次 Agent 中断后我以为它什么都没产出，顺手跑了清理。两个小时后才发现，它其实已经把核心模块的接口定好了，只是还没来得及提交。

现在的流程是：中断的工作区先进入 orphan 状态，保留 48 小时。期间可以用worktrunk list --orphan查看，用git diff检查是否有值得挽救的内容。确认没有价值后再手动清理，而不是自动删除。

4.4 与主干同步的正确节奏

主干分支不要被 Agent 直接写入，这一点怎么强调都不过分。所有 Agent 的改动都走 Worktrunk 完成合流，主干的唯一入口是finish或sync流程。

同步节奏上，我的习惯是主干每次有稳定提交后，跑一遍所有存活工作区的worktrunk sync。这个操作可以定时做，也可以在 CI 推送后触发。同步的时候如果某个 Agent 正处于长时间的关键运行状态，可以设置跳过下一次，避免打断它的执行流。

5. 一次 8 个 Agent 同仓库并行后的复盘与流程优化

5.1 任务拆解与 Worktree 分配

这个季度我在一个中等规模服务仓库里做了一次压力测试：并行运行 8 个 Agent，分别处理认证模块重构、支付计价逻辑、日志结构化、错误码统一、接口文档生成、集成测试补充、性能埋点和依赖版本升级八个任务。

任务拆分阶段最花时间。每个任务我都在context.md里写清了要改的文件目录和不要碰的文件目录，还把潜在的跨模块接口标注成“只读参考”。这一步做好后，8 个 Agent 运行三天，实际发生的跨目录改动非常少。

分支命名规则则是agent-${任务别名}，一眼就能从分支名看出谁负责哪块。worktrunk status的表格视图在这样的并发规模下特别好用。

5.2 合并顺序与冲突处理

8 个 Agent 并行的收官顺序需要刻意安排。我的策略是优先合并改动范围小、依赖公共代码少的任务；公共库的改动则留到中间阶段，让后续 Agent 通过sync尽快感知。

最终冲突主要出现在两处：支付计价逻辑中两个 Agent 都引用了同一个公共函数；日志结构化和性能埋点同时改了同一个请求处理中间件。这两处冲突都发生在“即将收官”的窗口期，原因是任务拆解时隐式共享了这部分代码。

处理方式是先把一个 Agent 的分支合到主干，另一个 Agent 执行worktrunk sync，冲突解决后重新跑一遍测试，然后完成合并。整个过程在两小时内搞定，没有出现灾难性大面积冲突。

5.3 Agent 卡死或改错方向的拦截

长时间运行的 Agent 很容易在某个局部问题上反复打转，或者偏离计划目标越改越远。我为此设了一个非常朴素的监控手段：定时查看每个工作区的git diff --shortstat。

cd .worktrunk/workspaces/agent-xxx/repo git diff --shortstat

如果改动文件数量和行数异常暴涨，十有八九是 Agent 把明明不该动的东西也改了。我会立刻查看它的最近提交，必要时终止进程，从最后的正常 commit 状态重新拉起 Agent。

另一种卡死情况是 Agent 陷入“编辑-测试失败-再编辑-再失败”的循环，但 diff 几乎不变。这时候我通常会在context.md里追加一条“如果是 x 类问题，直接采用 y 方案”，然后让 Agent 重读上下文，避免它继续在死胡同里转。

经过这一轮压力测试，我对并行 Agent 工作流的理解收敛成一件事：真正重要的不是让 Agent 跑多快，而是让 Agent 失败时不牵连别人。Worktrunk 的每个设计，从工作区隔离到自动同步再到 orphan 保留，本质上都是在给“失败”和“不确定性”留余地。

如果你也准备在自己的仓库上跑多个 AI Agent，我的建议是先把主干分支锁死，只允许 Agent 在独立 Worktree 分支里动代码，所有落回主干的合并操作都走 Worktrunk 的流程。这会让并行从“看起来很美”变成“真的可靠”。