name: git-worktree-setup description: 为具有隔离环境的代理并行化设置 Git 工作树。当设置并行代理执行、为每个代理创建隔离环境或启用并发开发工作流时使用。 allowed-tools: Read, Grep, Glob

Git 工作树设置技能

指导为并行代理执行创建隔离的 Git 工作树环境。

何时使用

设置并行代理执行
创建隔离的开发环境
配置多个实例的端口分配
规划工作树目录结构

核心概念

为什么使用工作树？

Git 工作树提供：

每个代理的文件系统隔离
共享的 Git 对象数据库
独立的分支
从 origin/main 的干净检出

目录结构

repository_root/
├── trees/
│   ├── {adw_id}/           # 隔离的工作树
│   │   ├── src/
│   │   ├── .ports.env
│   │   └── ...
│   └── ...                  # 最多 15 个并发
├── agents/
│   └── {adw_id}/
│       └── adw_state.json
└── main codebase/

端口分配

确定性公式：

slot = hash(adw_id) % 15
backend_port = 9100 + slot
frontend_port = 9200 + slot

设置工作流

步骤 1：规划工作树位置

确定工作树应放置的位置：

默认: trees/{adw_id}/
替代: .worktrees/{adw_id}/

步骤 2：创建工作树

要执行的命令：

# 获取最新
git fetch origin

# 使用新分支创建工作树
git worktree add trees/{adw_id} -b {branch_name} origin/main

步骤 3：配置端口

创建 .ports.env：

BACKEND_PORT={backend_port}
FRONTEND_PORT={frontend_port}
VITE_BACKEND_URL=http://localhost:{backend_port}

步骤 4：复制环境

cp .env trees/{adw_id}/.env
cat trees/{adw_id}/.ports.env >> trees/{adw_id}/.env

步骤 5：更新配置

对于任何绝对路径配置（MCP 等）：

更新路径指向工作树位置
使用绝对路径，而非相对路径

步骤 6：安装依赖

cd trees/{adw_id}
# 后端依赖
cd app/server && uv sync --all-extras
# 前端依赖
cd app/client && bun install

验证清单

设置后，验证：

[ ] 工作树目录存在
[ ] Git 识别工作树（git worktree list）
[ ] 分支正确
[ ] 端口已配置
[ ] 环境文件存在
[ ] 依赖已安装
[ ] 应用可以启动

清理操作

移除单个工作树

git worktree remove trees/{adw_id}
# 或强制移除如果有未提交的更改
git worktree remove trees/{adw_id} --force

修剪过时工作树

git worktree prune

列出所有工作树

git worktree list

关键记忆参考

@git-worktree-patterns.md - 完整工作树文档
@adw-anatomy.md - ADW 使用工作树
@zte-progression.md - ZTE 需要并行化

输出格式

提供设置计划：

## 工作树设置计划

**ADW ID:** {adw_id}
**分支名称:** {branch_name}
**工作树路径:** trees/{adw_id}

### 端口分配
- 后端: {backend_port}
- 前端: {frontend_port}

### 要执行的命令
1. `git fetch origin`
2. `git worktree add trees/{adw_id} -b {branch_name} origin/main`
3. 创建 `.ports.env`
4. 复制和配置环境
5. 安装依赖

### 验证步骤
- [ ] 验证工作树已创建
- [ ] 测试端口可用性
- [ ] 确认依赖已安装

故障排除

问题	解决方案
工作树已存在	先移除或使用不同的 ID
端口在使用中	检查使用情况，终止或使用不同的端口
分支已存在	使用现有分支或先删除
权限被拒绝	检查目录权限

版本历史

v1.0.0 (2025-12-26): 初始发布

最后更新

日期: 2025-12-26 模型: claude-opus-4-5-20251101