Git Worktree 创建

创建独立的 worktree 用于并行开发，避免污染主工作目录。

使用流程

1. 确认参数

需要以下信息：

• 分支名称: 新功能/修复的分支名（如

  feature/add-login

  ,

  fix/user-auth

  ）
• 基础分支: 从哪个分支创建（默认

  main

  ）
• worktree 目录: 统一放在

  ../AgentsMesh-Worktrees/<branch-name>

2. 创建 Worktree

# 1. 获取最新代码
git fetch origin

# 2. 创建 worktrees 目录（如不存在）
mkdir -p ../AgentsMesh-Worktrees

# 3. 创建 worktree 和新分支
# 分支名中的 / 替换为 - 作为目录名
git worktree add -b <branch-name> ../AgentsMesh-Worktrees/<dir-name> origin/<base-branch>

# 4. 进入 worktree 目录
cd ../AgentsMesh-Worktrees/<dir-name>

# 5. 验证状态
git status
git log --oneline -3

3. 初始化开发环境 [必须执行]

⚠️ 重要：此步骤为必须执行，不可跳过或询问用户是否执行。 Worktree 创建后必须立即初始化开发环境，确保环境可用。

# 进入 deploy/dev 目录
cd deploy/dev

# 一键启动完整开发环境
./dev.sh

脚本会自动：

• 根据 worktree/分支名生成隔离的

  .env

  配置（端口自动偏移，避免冲突）
• 启动 Docker 后端服务（PostgreSQL、Redis、MinIO、Backend、Nginx、Runner）
• 执行数据库迁移和初始化测试账号 seed 数据
• 启动本地前端（Next.js + Turbopack，性能更好）

4. 完成后输出

创建完成后，告知用户：

已创建 worktree:
- 路径: /Users/xxx/Works/AIO/AgentsMesh-Worktrees/feature-user-auth
- 分支: feature/user-auth (基于 origin/main)

开发环境:
- 前端: http://localhost:3000
- API:  http://localhost:<port>/api
- 测试账号: dev@agentsmesh.local / devpass123
- Adminer: http://localhost:<adminer-port>
- MinIO: http://localhost:<minio-port>

常用命令:
- 前端日志: tail -f deploy/dev/web.log
- 后端日志: cd deploy/dev && docker compose logs -f backend
- 停止环境: cd deploy/dev && ./dev.sh --clean

完成开发后:
- 提交代码: git add . && git commit -m "..."
- 推送分支: git push -u origin feature/user-auth
- 清理 worktree: cd <主仓库> && git worktree remove <worktree-path>

完整示例

用户说："创建一个 worktree 开发用户认证功能"

必须完整执行以下所有步骤（不可中断或询问用户）：

# 步骤 1: 创建 worktree
git fetch origin
mkdir -p ../AgentsMesh-Worktrees
git worktree add -b feature/user-auth ../AgentsMesh-Worktrees/feature-user-auth origin/main
cd ../AgentsMesh-Worktrees/feature-user-auth
git status
git log --oneline -3

# 步骤 2: 初始化开发环境 [必须执行，不可跳过]
cd deploy/dev
./dev.sh

注意事项

• 分支名遵循约定：

  feature/*

  ,

  fix/*

  ,

  refactor/*

  ,

  docs/*

• 所有 worktree 统一放在

  ../AgentsMesh-Worktrees/

  目录下
• 目录名使用分支名，将

  /

  替换为

  -

  （如

  feature/user-auth

  →

  feature-user-auth

  ）
• 如果分支已存在，使用

  git worktree add <path> <existing-branch>

• 每个 worktree 的开发环境端口自动隔离（包括前端端口），可并行运行多个
• 清理前确保所有更改已提交或推送
• 清理环境：

  ./dev.sh --clean