企业官网建设流程全解析

我最早被并行 AI Agent 开发逼疯，是在一个不算大的 Node.js 服务仓库里同时跑三个任务：一个修登录模块的竞态条件，一个接支付回调，还有一个重构日志中间件。当时我偷懒的方式很朴素——开了三个终端标签页，每个里git checkout -b feature/xxx，然后切来切去。结果不到半天就崩了：Agent A 改了package-lock.json，Agent B 构建时直接心态爆炸；Agent C 顺手跑了个测试脚本，把公共缓存目录清掉了；最后提交时，三个分支里混着彼此的工作产物，review 的时候根本分不清哪个 diff 属于哪个任务。

后来我把目光放到了我一直知道、但总觉得“没必要用”的git worktree上，再配合我自己写的一个 CLI 工具Worktrunk，把整套流程彻底重做了。这篇文章就聊聊为什么要给并行 AI Agent 工作流配 worktree 管理工具、Worktrunk 的设计逻辑是什么，以及我把三个 Agent 塞进同一个仓库并行开发时总结出来的实操经验和坑。

1. AI Agent 并行开发的痛点，藏在一个“同一份工作区”里

1.1 Agent 的工作方式，天然不适合“一个目录多分支切换”

人和 AI Agent 在并发任务上的差异，远比很多人想象的大。人类开发者在一个仓库里开多个分支来回切换，是可行的：因为人知道“我现在切到 feature-a 分支，工作区里残留的 feature-b 产物我要小心处理”，这个判断力是基于全局上下文和经验的。

AI Agent 没有这个意识。它被要求“修登录模块的 bug”，就会开始读文件、改文件、跑测试、安装依赖、生成临时文件。它不会管你当前工作区是不是还残留着另一个任务的东西，也不会在切换任务前主动帮你清理。让多个 Agent 共享同一个工作目录，就像让三个厨师共用同一块案板切不同的菜——不是不能，但串味是必然的。

我自己实际遇到的典型事故包括：

• Agent A 依赖安装时生成了新的package-lock.json，Agent B 在执行构建前发现依赖不匹配，自动帮你“修复”了锁文件，导致 A 的改动全乱。
• 两个 Agent 同时在自己的上下文里读取了src/config.ts，但各自基于不同版本的缓存内容做了修改，最后提交时互相覆盖。
• 某个 Agent 在“探索性测试”阶段创建了一堆临时文件和 mock 数据目录，另一个 Agent 误以为那是自己任务的产物，顺手提交了上去。

1.2 git worktree 提供了什么：独立目录 + 共享对象库

git worktree的核心能力，一句话概括：同一个仓库可以拥有多个工作目录，每个工作目录独立检出、独立操作、互不干扰，但共享同一个.git对象库和引用（refs）。它解决的不是 Git 存储层面的问题，而是“物理隔离”层面的问题。

核心原理是git worktree add会为每个新工作区创建独立的index、HEAD、和工作文件，并将这些元数据记录在主仓库的.git/worktrees/<name>目录中。所有工作区共享同一个objects数据库，所以提交、分支切换、对象查询都能在毫秒级完成，不会因为目录数量增加而膨胀。

用大白话说：你在一个项目里开出几个互不干扰的“平行工作间”，每个房间都有自己的文件状态和待办区，但楼下共用同一个仓库货架，东西放上去之后大家都能看到。

1.3 原生命令够用，但在多 Agent 场景下没人帮你“串起来”

git worktree原生命令确实能做基本的事：

git worktree add ../feature-a -b feature-a git worktree list git worktree remove ../feature-a

但在并行 AI Agent 工作流里，原生命令的粒度太低了：

• 你记不住哪个 worktree 路径对应哪个 Agent 在跑的任务。
• 你没法快速判断某块工作区是“进行中”“待评审”还是“可以清理”。
• 你没法批量创建、批量清理、批量执行检查。
• 你更没法把这个过程暴露给 Agent 自己的上下文——Agent 拿到一个孤零零的目录，并不知道它在这个大工作流里处于什么位置。

所以我设计了 Worktrunk：一个把 worktree 管理抽象成“任务工作区管理”的 CLI。它的核心思路不是发明新的 Git 机制，而是把 Git 原生的 worktree 能力包装成适合多人/多 Agent 协作的心智模型。

2. Worktrunk 的设计逻辑：把分支抽象成“可隔离的工作席位”

2.1 数据模型：任务、工作区、Agent

Worktrunk 内部把一切都组织为三个实体：

• Task（任务）：一个可追踪的开发目标，比如“修复登录竞态条件”“接入支付回调”。它映射到一条分支、一个工作目录、一组元数据。
• Worktree（工作区）：任务在磁盘上的物理落点，指的就是git worktree add创建的那个目录。
• Agent（执行者）：负责该任务的 AI 工具。可以是 Codex CLI、Claude Code、本地自定义脚本，甚至人类自己。它本身不是必要实体，但记录下来之后，你可以一眼看出“这个任务目前在谁手里”。

对应到磁盘上的元数据，我采用的是一个简单 JSON 文件（存放在.git/worktrunk/state.json），因为这样人类可读、脚本可解析，未来接 Web UI 也不费劲。一个最小示例长这样：

{ "version": "1", "workspaces": [ { "name": "login-fix", "branch": "feature/login-fix", "baseBranch": "origin/main", "path": ".worktrunk/login-fix", "status": "in-progress", "agent": "codex", "createdAt": "2025-06-10T10:00:00+08:00", "lastActiveAt": "2025-06-10T11:30:00+08:00" } ] }

这个模型奠定了后续所有命令的基础。因为有了“任务”这个层级，Worktrunk 就不只是操作一堆无序的目录，而是你可以问它：“当前有哪些活跃任务？Agent 是哪个？哪些三天没动了？”

2.2 命令集的心智模型：开、看、切、收

在设计 CLI 命令时，我一直提醒自己要克制。很多工具死在“什么命令都加”上，包括我曾经写过的内部脚本，最后命令数比功能数还多。Worktrunk 的命令集只需要围绕四个动作展开：

这套命令背后的状态机是：未开始 → 进行中 → 待评审 → 已合并 → 待回收。每个工作区都有自己的状态，list输出中会直接展示出来，focus只允许聚焦到未结束的任务，clean只会回收已经合并或明确标记完成的工作区。

为什么这样设计？因为只有把命令减少到四个方向，使用者（包括 Agent 自己）才能在没有文档的情况下快速形成肌肉记忆。我自己实际用下来的感受是：AI Agent 只需要知道create和focus，人只需要知道list和clean，角色边界非常清晰。

2.3 为什么是 CLI，而不是 IDE 插件或 GUI

这个问题的答案，一开始可能会让人觉得“逆潮流”。AI 编程时代大家都在做 GUI、做 IDE 集成，为什么 Worktrunk 还是要做 CLI？

几个实际原因：

• AI Agent 的交互入口本来就长在终端上。Codex CLI、Claude Code、Devin 这类工具的调用方式都是终端命令。CLI 可以被 Agent 直接调用和解析，GUI 不行。
• 脚本化、可组合。支持--json输出意味着可以轻松接进 CI、巡检脚本、定时任务。我要在没人在场的时候自动清理三天未动的 worktree，GUI 做不到。
• 部署门槛低。一个二进制文件，装到任意有 Git 的机器上就能跑，不依赖图形环境，在远程开发服务器上也能用。

这个选择背后是务实：CLI 是 Agent 生态的“最小公分母”。你的工具只要还在 CLI 层暴露能力，就能被未来任何新的 Agent 工具直接复用。

2.4 元数据放哪：项目内、.git 目录，回避两个极端

元数据存放位置是个容易翻车的设计决策。如果存到工作区根目录，比如worktrunk.json，好处是可以在代码评审里看到，坏处是它会被提交进仓库，污染每个任务的 diff。如果存到用户级目录（比如~/.worktrunk/state.json），又没法保证多个仓库互不干扰。

我的选择是存进.git/worktrunk/state.json。理由：

• 它天然属于仓库元数据，不会污染工作目录和提交历史。
• 它在git clone时不会被带过去，但本机所有 worktree 都能访问到。
• 删除仓库时一起被清理，不会留垃圾。

这个思路和 Git 自身的设计高度一致：关于本仓库的元信息，都应放在.git里。

3. 安装和核心命令逐条拆解

3.1 安装与前置条件

Worktrunk 是一个单二进制 CLI，安装方式取决于项目发布渠道。我当时是直接把编译后的二进制丢进$PATH，后来正式化之后支持了常用的安装方式：

# 如果你用 Homebrew brew install worktrunk # 或者通过 npm 全局安装 npm install -g @worktrunk/cli # 或者直接拉取官方发布的二进制 curl -sSL https://example.com/worktrunk/install.sh | bash

前置条件很轻：

• Git 版本建议 2.30 以上，因为git worktree的若干交互修复集中在这个版本之后。
• 如果你在 Windows 上用，建议开启git config --global core.longpaths true，这个坑后面专门讲。
• shell 建议 bash/zsh/fish，PowerShell 也能用，只是focus的 shell 集成需要额外配置。

3.2 初始化：worktrunk init

进入一个已有的 Git 仓库目录，执行：

cd ~/apps/my-service worktrunk init

输出类似：

Initialized Worktrunk in /Users/me/apps/my-service Default worktree path: .worktrunk Agent base template: none

init会做三件事：

1. 检查当前目录是否是 Git 仓库。
2. 在.git/worktrunk/下创建元数据目录和默认state.json。
3. 读取你当前的 Git 配置，写入默认基分支、默认工作区路径、Agent 模板等基础配置。

这里有一个很反直觉的设计：我不把 worktree 放到项目外的兄弟目录，而是默认放在项目内的.worktrunk/<workspace-name>。理由是，当你用相对路径在子目录里工作时，编辑器、索引服务、文件监听器对路径的识别更稳定；同时.gitignore里加一行.worktrunk/就能避免误提交。如果你更习惯放在项目外，也可以改配置。

3.3 创建任务工作区：worktrunk create

create是使用频次最高的命令，也是参数最多的一个。我列举几个实用参数：

worktrunk create login-fix worktrunk create payment-callback --agent claude --base origin/main --template claude worktrunk create log-refactor --agent custom --path .worktrunk/log-svc

执行示例：

$ worktrunk create payment-callback --agent claude --base origin/main --template claude ✔ Created workspace at .worktrunk/payment-callback Branch: feature/payment-callback Base: origin/main Agent: claude Template: claude

内部逻辑是：git worktree add -b feature/payment-callback .worktrunk/payment-callback origin/main，然后把元数据写进.git/worktrunk/state.json。如果配置了模板，还会在工作区里生成CLAUDE.md或AGENTS.md等上下文引导文件，让 Agent 一进来就知道这个任务的目标、约束和验收标准。

这个模板注入能力对 AI Agent 工作流格外关键。我的做法是：每个任务的CLAUDE.md里明确写清楚“本工作区只处理支付回调相关代码，禁止改动其他模块、禁止读取兄弟目录”。实际效果比在 prompt 里反复叮嘱好得多。

3.4 状态总览：worktrunk list

list是日常使用最多的巡检命令：

$ worktrunk list ╭──────────────────┬─────────────┬──────────────────────┬────────┬───────╮ │ Workspace │ Branch │ Status │ Agent │ Last │ ├──────────────────┼─────────────┼──────────────────────┼────────┼───────┤ │ login-fix │ feature/… │ in-progress │ codex │ 10:31 │ │ payment-callback │ feature/… │ in-progress │ claude │ 09:02 │ │ log-refactor │ feature/… │ ready-for-review │ custom │ 昨天 │ ╰──────────────────┴─────────────┴──────────────────────┴────────┴───────╯

如果你要写脚本轮询，list --json输出结构化数据更好用：

worktrunk list --json

[ { "name": "login-fix", "status": "in-progress", "branch": "feature/login-fix", "agent": "codex", "lastActiveAt": "2025-06-10T10:31:00+08:00" } ]

我编这个命令的时候，最看重的是“一屏扫完”的体验。因为并行工作流的瓶颈通常不在操作，而在“信息聚合”——你是不是能快速知道哪个任务卡住了、哪个 agent 还在跑、哪个可以收工了。

3.5 切换：worktrunk focus 与 shell 集成

focus的设计初衷是“把当前终端切换到目标工作区并绑定对应上下文”，实现方式比较特殊。因为 CLI 子进程不能修改父 shell 的$PWD，我采用输出 shell 代码让用户eval的方式：

eval "$(worktrunk focus payment-callback)"

执行后：

• 当前 shell 会cd到.worktrunk/payment-callback。
• 导出$WORKTRUNK_ACTIVE、$WORKTRUNK_TASK环境变量。
• 如果配置了模板，会重新加载.worktrunrc之类的环境文件（如果有）。

我实际用下来的体验是：配合 tmux 或 zellij 尤其舒服。一个窗口一个 Agent，每个窗口执行一次eval "$(worktrunk focus xxx)"，窗口标题都会自动变成任务名，再也不会找不到自己在哪。

3.6 任务完成与回收：worktrunk close / clean

close标记任务完成：

worktrunk close login-fix

close不会删除工作区，只是把状态改为completed，防止你误操作。

clean才真正回收：

worktrunk clean login-fix

回收前 Worktrunk 会做四重检查：

1. 工作区是否存在未提交变更或未推送提交。
2. 分支是否已经合并回基分支（或者通过--force强制跳过）。
3. 是否有其他进程在工作区内运行（通过简单的 PID 探测）。
4. 是否处于in-progress状态（默认禁止清理进行中任务）。

只有在全部通过后，才会执行git worktree remove并同步删除.git/worktrunk/state.json里的记录。这个安全策略帮我挡住过至少三次误操作。

3.7 配置项与 shell 补全

Worktrunk 的配置分两层：

• 用户级配置：~/.config/worktrunk/config.toml，存放默认 Agent 模板、默认基分支、是否自动开启提示符插件。
• 仓库级配置：.git/worktrunk/config.json，存放当前仓库的 worktree 路径前缀、默认分支前缀等。

# ~/.config/worktrunk/config.toml [defaults] base = "origin/main" agent = "codex" worktree_root = ".worktrunk" [agent.codex] template = "codex" [agent.claude] template = "claude"

Shell 补全支持 bash/zsh/fish，安装时自动写入：

# zsh 示例 eval "$(worktrunk completion zsh)"

4. 实战演练：三个 Agent 并行开发一个 Web 服务

4.1 场景设定

仓库~/apps/pay-server，这是一个 Node.js Web 服务，当前main分支稳定在 v1.2.0。我同时收到三个任务：

1. login-fix：修复登录模块的竞态条件，派给 Codex CLI。
2. payment-callback：接入支付回调验签，派给 Claude Code。
3. log-refactor：重构日志中间件，我自己写（或者派给本地脚本 Agent）。

4.2 从 0 到 1 建三个工作区

cd ~/apps/pay-server worktrunk init worktrunk create login-fix --agent codex --base origin/main --template codex worktrunk create payment-callback --agent claude --base origin/main --template claude worktrunk create log-refactor --agent custom --base origin/main --template agents

此时目录结构变为：

pay-server/ ├── .git/ │ └── worktrunk/ │ ├── state.json │ └── config.json ├── .worktrunk/ │ ├── login-fix/ # Codex CLI 的私有工作区 │ ├── payment-callback/ # Claude Code 的私有工作区 │ └── log-refactor/ # 自定义 Agent 的工作区 ├── src/ ├── package.json └── ...

每个工作区里都有独立的node_modules（或者由包管理器以 symlink 方式复用，取决于你的设置），有独立的package-lock.json，还有各自的CLAUDE.md/AGENTS.md模板文件。三个 Agent 从这一刻起就彻底分居了。

4.3 三个 Agent 并行开工，我作为调度者在做什么

我开了三个 tmux 窗口：

窗口一：

eval "$(worktrunk focus login-fix)" codex

Codex CLI 进来后，会自动读取工作区里的AGENTS.md，知道自己的目标范围，默认不会跨目录扫描兄弟工作区。

窗口二：

eval "$(worktrunk focus payment-callback)" claude

Claude Code 同样被模板约束，只负责支付回调相关目录。

窗口三我自己写日志中间件。

在实际开发过程中，我会隔一段时间执行一次worktrunk list，看状态有没有卡住。Agent 跑完一个阶段后，通常会自己在工作区里提交 commit。我只需要看到某个工作区的分支领先 main 若干 commit，就知道这部分可以进入 review 了。

一个很实用的巡检脚本思路，可以每天定时跑一次：

#!/usr/bin/env bash # 找出超过24小时没有活动、但状态仍是 in-progress 的任务 worktrunk list --json | jq -r ' .[] | select(.status == "in-progress") | select((now - (.lastActiveAt | fromdateiso8601)) > 86400) | .name ' | while read name; do echo "[提醒] 任务 $name 已超过24小时未更新" done

这套思路的本质是：把 worktree 的状态变成可编程的数据，然后让脚本替人盯梢。

4.4 合并和清理：每个 Agent 结束时我做了什么

当 Agent 通知任务完成，我对待login-fix的流程是：

eval "$(worktrunk focus login-fix)" # 拉取最新 main 并 rebase，确保可以干净合并 git fetch origin main git rebase origin/main # 跑一遍测试 npm test # 确认没问题后切回主工作区并合并 cd ~/apps/pay-server git checkout main git merge --no-ff feature/login-fix -m "feat: 修复登录竞态条件" worktrunk close login-fix worktrunk clean login-fix

clean执行后，.worktrunk/login-fix目录被移除，state 里对应记录消失，整个流程无残留。

三个任务也可以有先后地合并，互不影响。即使 payment-callback 还没做完，login-fix 也可以先发布上线——这在传统单工作区模式下需要小心翼翼，在 worktree 模式下是自然操作。

4.5 用 --json 把工作区状态接进 CI 和 Agent 上下文

有状态的地方就能做自动化。Worktrunk 的--json输出让它可以很自然地和 CI 集成：

• 在 pre-merge 检查时，要求对应 worktree 的测试全部通过才允许合并。
• 在定时巡检时，把list --json的结果推送到企业 IM 机器人，提醒过期任务。
• 在部署流水线里，用脚本筛选出所有状态为ready-for-review的工作区，批量发起 PR。

对于 Agent 本身，也可以让它们通过 CLI 感知全局状态。我在自己的 Agent 工具链里加了一个系统命令别名：wt直接输出当前工作区的任务描述，让 Agent 每次决策前都能重新确认“自己在为哪个目标工作”。

5. 实际使用中踩过的坑

5.1 clean 误删未提交变更，差一点丢掉半天的成果

第一次做clean时，我以为工作区分支已经合并了，就把login-fix干净利落地删了。结果等想起来里面还有一个没推送的 debug 脚本时，已经太晚了。查了.git/fsck才把 dangling commit 捞回来。

后来我给clean加了三层保护：

1. 默认只允许清理状态为completed或分支已合并的工作区。
2. 执行前做一次git status --porcelain检查，有未提交变更就拒绝。
3. 即使是强制清理（--force），也会先把工作区历史压缩归档到.git/worktrunk/archive/，保留 7 天。

这次教训让我深刻意识到：任何“批量回收”类命令，都必须默认开启“后悔药”模式。人很容易过度相信自己做过的检查，而工具应该替你挡住这一层。

5.2 Windows 下的长路径问题是最大的绊脚石

git worktree本身在 Windows 上可用，但路径嵌套一旦变深，就会撞上 Windows 传统的 260 字符路径限制。由于 Worktrunk 的工作区默认放在项目内部（比如C:\Users\me\repo\.worktrunk\some-long-task-name），很容易触发。

解决办法是提前设置：

git config --global core.longpaths true

如果问题依旧，可以自定义更短的工作区路径前缀：

worktrunk config set workspace.root "C:\\wt"

这样每个工作区就变成C:\wt\login-fix，路径短一大截，基本能绕开限制。

5.3 子模块和 monorepo 的兼容细节

如果你所在仓库使用了git submodule，直接对父仓库建 worktree 时，子模块的版本指针会跟着切换，但子模块本身的.git目录不会自动跟随，容易造成子模块目录状态错乱。我目前实践出来的两个方案：

• 方案 A（推荐）：把子模块当作独立仓库，为每个子模块单独创建 worktree。父仓库的 worktree 只负责锁定子模块的提交哈希。
• 方案 B：在每次worktrunk create后，手动执行git submodule update --init --recursive，确保子模块文件完整。

对于 monorepo（比如 pnpm workspace / turborepo），我的经验是先在整个仓库建 worktree，然后在工作区里只对packages/内需要修改的包执行包管理器命令。不要尝试在每个包里单独建 worktree，那样会让依赖解析和本地链接变得极其痛苦。

5.4 AI Agent 对“工作目录”的适配差异，比我想象的大

不同 Agent 对工作目录的认知方式差异，是实际使用中隐藏最深的坑。

• Codex CLI偏向以当前目录作为根，读取根目录的AGENTS.md和项目配置，相对守规矩。
• Claude Code的 memory 和 MCP 配置是全局的，如果不加约束，它会跨工作区读取自己的记忆文件，导致任务 A 里记住的上下文被带到任务 B。
• 某些本地 Agent 脚本会把“当前目录”当作唯一感知对象，很容易忽略工作区外的大仓库全局状态。

我的应对方案是：

1. 模板注入。每个 Agent 工作区生成专属的上下文文件，明确“只处理本目录内与任务相关的范围，禁止跨界读取”。
2. 环境变量隔离。在focus时导出WORKTRUNK_TASK_MEM_DIR之类变量，Agent 的记忆目录按任务名隔离。
3. 物理隔离优先。不要指望 Agent 自觉，直接把兄弟工作区设成它无权限访问的位置。

一句话总结：Agent 的自我约束能力是有限的，工具的物理隔离能力是无限的。能用物理隔离解决的问题，别指望 prompt 解决。

6. 我认为 Worktrunk 下一步该往哪里长

6.1 并发锁与无人值守

目前clean对“进程是否在工作区里运行”的检测很粗糙（扫描打开文件句柄或 PID 列表）。下一步应该引入更严格的锁机制：Agent 开工时在工作区里写一个lock文件，释放时删除；clean看到锁就拒绝操作。只有这样才能在无人值守的夜间任务中放心地做自动回收。

6.2 与问题任务系统的联动

Worktrunk 现在并不知道当前这个任务是来自 issue 还是自行发起的。如果能和 GitHub Issue、Jira、飞书/Lark 多维表格之类的任务系统打通，worktrunk create #123 login-fix就能自动拉取 issue 描述、生成分支、创建 PR、回写状态，这会大幅降低团队协作成本。核心设计只需要保留--json的注入点，剩下的是各个平台的适配器。

6.3 hook 机制

参考 Git hook，Worktrunk 也可以支持on-create、on-focus、on-close、on-clean四类 hook。我的设想是：

• on-create时自动向 Agent 模板里注入任务明细。
• on-merge时触发 CI。
• on-clean时通知任务系统“工作区已回收”。

这类自动化会让“并行 Agent 工作流”真正变成一个可观测、可治理的管道，而不是几个人各自开着终端乱跑。

6.4 要不要做 Web UI / TUI

我的答案目前是：不做，或者说暂时不做。原因不是技术难度，而是受众问题。单人使用场景下，CLI 已经是效率天花板；多人大规模协作时，Web UI 才有意义。到了 worktree 数量超过 20 个、你需要让不熟悉命令行的人也能看到“哪些任务堵了”的时候，Web 面板才会成为刚需。

但核心数据结构已经是 JSON，未来接 UI 只是加一层壳的事。我一直认为：先做好数据层的可编程性，UI 只是顺水推舟。

最后分享一个我实际养成的小习惯：在每个 Agent 工作区里，第一时间把分支名和任务描述写进AGENTS.md的开头，并把WORKTRUNK_ACTIVE变量显示在终端提示符里。这样不管是人类还是 Agent，在任何时刻看一眼提示符就知道自己身处哪个平行世界，而不是靠记忆和猜。Worktrunk 帮我解决的，说到底不只是“目录隔离”，而是“上下文隔离”——在 AI Agent 并行开发成为常态的今天，这件事比什么都值得认真处理。