git-worktree-setup

用途：为并行 AI 智能体执行创建隔离的 Git worktree 环境，适合需要多实例并行开发、按代理隔离文件系统与分支、以及为多实例分配端口的场景。\n\n主要能力：每个 agent 独立文件系统、共享 Git 对象库、独立分支、从 origin/main 干净检出；支持最多 15 个并发 worktree；采用确定性端口分配公式：slot = hash(adw_id) % 15，backend_port = 9100 + slot，frontend_port = 9200 + slot；生成 .ports.env 端口环境文件并合并到 .env。\n\n目录结构：repository_root/trees/{adw_id}/ 为隔离 worktree，agents/{adw_id}/adw_state.json 保存状态。\n\n使用方式：1) 规划 worktree 位置（默认 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、FRONTEND_PORT、VITE_BACKEND_URL；4) 复制环境：cp .env trees/{adw_id}/.env，再 cat trees/{adw_id}/.ports.env >> trees/{adw_id}/.env；5) 更新 MCP 等绝对路径配置；6) 安装依赖：cd app/server && uv sync --all-extras，cd app/client && bun install。\n\n校验清单：worktree 目录存在、git worktree list 可识别、分支正确、端口已配置、环境文件存在、依赖已安装、应用可启动。清理：git worktree remove trees/{adw_id}（可加 --force）、git worktree prune、git worktree list。\n\n限制与注意：端口冲突需排查占用或换 ID；worktree 已存在需先移除或换 ID；分支已存在需使用或先删除；权限拒绝需检查目录权限。版本 v1.0.0（2025-12-26）。完整文档见 @git-worktree-patterns.md、@adw-anatomy.md、@zte-progression.md。