AutoGPT 并行开发指南：基于 Git Worktree 的隔离工作区搭建与运行实践

本篇以 AutoGPT 仓库内置的 .claude/skills/worktree/SKILL.md 技能文档为主线，系统讲解如何利用 Git worktree 为 AutoGPT 平台搭建彼此隔离的并行开发工作区：从 worktree 创建、多目录 .env 环境文件复制、Poetry/pnpm 依赖安装与 Prisma 客户端生成，到后端端口释放与启动、CoPilot 测试模式切换与清理回收。读完本文，你可以在不污染主检出的前提下，快速为任意 PR 或特性分支建立一套可独立运行的 AutoGPT 开发环境。

技能定位：worktree 技能是什么

.claude/skills/worktree/SKILL.md 是 AutoGPT 团队为 Claude Code 编写的一个可用户调用（user-invocable: true）的技能，其 frontmatter 元数据声明了触发条件与参数：

• 触发时机：当用户要求“搭建 worktree”“在隔离环境中处理某个分支”“为某个分支或 PR 准备独立环境”时自动触发；
• 参数：[name] — 可选的 worktree 名称（如 AutoGPT7），省略时自动选取下一个可用的 AutoGPT<N> 编号；
• 版本：metadata 中标注 version: "3.0.0"，author: autogpt-team。

该技能的完整流程覆盖四个阶段：创建 worktree → 复制环境文件 → 安装依赖 → （可选）运行应用，并附带 CoPilot 测试注意事项与清理命令。它与同目录下的 setup-repo 技能 配套使用——后者负责从全新克隆的仓库初始化整套 worktree 布局（main + reviews + branch1..N），而 worktree 技能则专注于单个 worktree 的搭建。值得注意的是，setup-repo 技能中明确写道其 env 复制逻辑“刻意镜像 /worktree 技能的做法，两边需保持同步”，说明这两个技能的三处 env 路径清单是团队约定一致的。

第一步：创建 worktree

技能文档要求从 git toplevel 推导路径，避免硬编码绝对路径：

ROOT=$(git rev-parse --show-toplevel)
PARENT=$(dirname "$ROOT")

# From an existing branch
git worktree add "$PARENT/<NAME>" <branch-name>

# From a new branch off dev
git worktree add -b <new-branch> "$PARENT/<NAME>" dev

这里的关键设计决策：

1. worktree 放在主检出的兄弟目录（$PARENT/<NAME>），而不是仓库内部。这样每个工作区都拥有完整的文件树（包括 node_modules、venv 等被 gitignore 的内容），互不干扰；
2. 两种创建方式：附着到已有分支（适合接手别人的 PR 分支），或直接从 dev 分支切出新的特性分支（-b <new-branch>）；
3. 命名约定：未提供名称时检查 git worktree list 并选取下一个 AutoGPT<N>，保证多 worktree 并存时目录名不冲突。

这一布局与 setup-repo 技能 描述的最终目录结构一致：parent/ 下并排着 main/、reviews/ 和 branch1/ … branchN/。

第二步：复制环境文件（含回退逻辑）

AutoGPT 平台的环境配置分散在三个目录，技能脚本逐一处理，且带 .env.default 回退：

ROOT=$(git rev-parse --show-toplevel)
TARGET="$(dirname "$ROOT")/<NAME>"

for envpath in autogpt_platform/backend autogpt_platform/frontend autogpt_platform; do
  if [ -f "$ROOT/$envpath/.env" ]; then
    cp "$ROOT/$envpath/.env" "$TARGET/$envpath/.env"
  elif [ -f "$ROOT/$envpath/.env.default" ]; then
    cp "$ROOT/$envpath/.env.default" "$TARGET/$envpath/.env"
  fi
done

三个环境文件位置及其在仓库中的实际情况：

相对路径	作用	仓库中提供
autogpt_platform/backend/.env	后端服务配置（数据库、外部 API 密钥等，约 14KB 的完整模板）	.env.default
autogpt_platform/frontend/.env	前端（Next.js）环境变量	.env.default
autogpt_platform/.env	平台级数据库凭据（Docker 场景）	.env.default

其中 autogpt_platform/.env.default 的内容很简洁，仅包含 Docker Compose 中 db 服务硬编码凭据的镜像变量：

POSTGRES_HOST=db
POSTGRES_DB=postgres
POSTGRES_PORT=5432
# default user is postgres
POSTGRES_PASSWORD=your-super-secret-and-long-postgres-password

文件头部注释明确提示：这些凭据与 docker-compose.yml 中 db 服务绑定，若要修改需同步更新 docker-compose.platform.yml、backend/.env(.default) 和 frontend/.env(.default) 中的 DATABASE_URL / DIRECT_URL。

回退逻辑的价值：git worktree add 只检出被 git 跟踪的文件，.env 这类本地配置文件不会跟随出现。技能脚本先找主工作区的 .env（含开发者本地密钥），找不到再退回到版本化的 .env.default，从而保证新 worktree 开箱即有可用的环境文件。setup-repo 技能在此基础上还多了一层 .env.example 回退，并在找不到任何模板时向用户告警——两种写法互为印证，说明这份 env 路径清单是团队维护的既定约定。

第三步：安装依赖（三层包管理）

AutoGPT 平台的依赖分布在三个独立包管理器作用域内，技能脚本顺序执行：

TARGET="$(dirname "$(git rev-parse --show-toplevel)")/<NAME>"
cd "$TARGET/autogpt_platform/autogpt_libs" && poetry install
cd "$TARGET/autogpt_platform/backend" && poetry install && poetry run prisma generate
cd "$TARGET/autogpt_platform/frontend" && pnpm install

执行前需把 <NAME> 替换为实际 worktree 名（如 AutoGPT7）。逐行说明：

1. autogpt_platform/autogpt_libs：平台共享库（auth、logging、api key 等），用 Poetry 安装；
2. autogpt_platform/backend：FastAPI 后端，同样用 Poetry；poetry run prisma generate 是必要步骤——Prisma 客户端需基于 schema.prisma 在本地重新生成，因为 node_modules 与生成产物都不在 git 中，不会随 worktree 检出；
3. autogpt_platform/frontend：Next.js 前端，用 pnpm 安装。

setup-repo 技能对多 worktree 场景的补充建议值得参考：依赖安装很慢，建议按 worktree 逐个顺序执行并放到后台运行，完成后通知用户；每个 worktree 的三段安装用 && 串联，任何一段失败都会标记该 worktree 为 FAILED。

第四步：运行应用（可选）

技能文档指出，后端运行时会占用 8001、8002、8003、8005、8006、8007、8008 共 7 个端口，多个 worktree 与主工作区并存时会产生端口竞争，因此先释放端口再启动：

TARGET="$(dirname "$(git rev-parse --show-toplevel)")/<NAME>"
for port in 8001 8002 8003 8005 8006 8007 8008; do
  lsof -ti :$port | xargs kill -9 2>/dev/null || true
done
cd "$TARGET/autogpt_platform/backend" && poetry run app

lsof -ti :$port | xargs kill -9 按端口定位并终止占用进程（|| true 保证端口空闲时脚本不报错）。需要提醒的是：这条命令会杀掉主工作区正在运行的后端实例，实操中应确认这些端口上确实是你自己启动的进程。

CoPilot 测试的特殊限制

技能文档专门提示了 worktree 中测试 CoPilot 时的一个陷阱：

SDK mode spawns a Claude subprocess — won't work inside Claude Code. Set CHAT_USE_CLAUDE_AGENT_SDK=false in backend/.env to use baseline mode.

从后端源码可以印证这一说明。baseline/service.py 的模块 docstring 写道：

Baseline LLM fallback — OpenAI-compatible streaming with tool calling. Used when CHAT_USE_CLAUDE_AGENT_SDK=false, e.g. as a fallback when the Claude Agent SDK / Anthropic API is unavailable. Routes through any OpenAI-compatible provider (OpenRouter by default) and reuses the same shared tool registry as the SDK path.

也就是说，CoPilot 存在两条执行路径：SDK 路径（Claude Agent SDK）与 baseline 路径（走任意 OpenAI 兼容端点，默认 OpenRouter），两者复用同一套工具注册表。在 Claude Code 内部测试 CoPilot 时，SDK 路径要拉起 Claude 子进程会产生冲突，因此在 backend/.env 中设置 CHAT_USE_CLAUDE_AGENT_SDK=false 切到 baseline 模式即可。该配置项在 config_test.py 和 sdk/conftest.py 的测试中也作为受管环境变量出现，可见它是 CoPilot 模块被正式纳入测试覆盖面的配置开关。

清理 worktree

开发完成后，用一条命令移除工作区（文档中的 <NAME> 同样需替换为实际名称）：

git worktree remove "$(dirname "$(git rev-parse --show-toplevel)")/<NAME>"

注意 git worktree remove 默认会拒绝删除含未跟踪文件（如 node_modules、本地 .env）的目录；若确需连同这些产物一并丢弃，可先手动清理由于依赖安装产生的未跟踪内容，或按需追加 git 自带的强制移除参数。

替代方案：Branchlet

如果你已安装 branchlet（一个用于管理 worktree 分支的 npm 工具），技能文档给出了等价的快捷命令：

branchlet create -n <name> -s <source-branch> -b <new-branch>

参数含义：-n 指定 worktree 名称，-s 指定来源分支，-b 指定要创建的新分支。setup-repo 技能 还包含“把主工作区的 .branchlet.json 复制到各 worktree”的步骤，让 branchlet 能够管理子 worktree，两者配合使用可进一步简化 worktree 的增删改查。

小结

/worktree 技能把 AutoGPT 平台“多目录、多包管理器、多环境文件、固定端口集合”的复杂开发环境，固化成了四条可复制执行的 shell 片段：创建 → 复制 env（含回退）→ 安装依赖（含 prisma generate）→ 释放端口并启动，并额外覆盖了 CoPilot SDK 模式的测试限制与 branchlet 替代路径。对 AutoGPT 的贡献者而言，这套流程的价值在于：任何一个 worktree 都是主工作区的完整功能副本，可以独立启动后端、独立运行测试，多个 PR 可以真正并行推进，同时 .env 回退机制保证了新工作区不需要手动重建本地配置。