git-worktree-manager

Git Worktree 管理器

使用 Git worktree 管理并行开发工作流，提供确定性命名、自动分配端口、同步环境文件、安装依赖和自动清理功能。针对多 Agent 工作流进行了优化：每个 Agent 或终端会话都拥有独立的 worktree，以及专属端口、环境和运行中的服务。

核心功能

• Worktree 生命周期 — 从新分支或现有分支创建 worktree，采用确定性命名，复制 .env 文件，根据锁文件检测并安装依赖，列出 worktree 时显示干净/脏状态及领先/落后状态，并在检测到未提交更改时安全移除。
• 端口分配 — 为每个 worktree 确定性地分配端口（base + index * stride），检测运行中进程是否占用端口，在 .worktree-ports.json 中持久化映射，并生成 Docker Compose 覆盖配置。
• 多 Agent 隔离 — 每个 worktree 对应一个分支和一个 Agent，状态互不共享，可无冲突并行执行，并通过任务 ID 映射实现追踪。
• 自动清理 — 根据时长检测陈旧 worktree，检测已合并分支以便安全移除，警告脏状态，并在确认安全后批量清理。

适用场景

• 你需要同时打开 2 个或更多分支，并运行开发服务器。
• 你希望为功能开发、紧急修复和 PR 审查提供隔离的环境。
• 多个 AI Agent 需要互不干扰的独立工作区。
• 当前分支受阻，但有紧急修复需要处理。
• 你希望自动清理，而不是手动执行 rm -rf 操作。

请先确认

管理 worktree 之前，先确定以下输入。如果缺少某项输入或描述含糊，且会影响结果，请先询问；如果不会影响结果，则采用合理默认值并说明所用默认值。

• 操作： 创建、列出、移除或清理 worktree（决定使用 worktree_manager.py 操作、port_allocator.py 还是 worktree_validator.py）。
• 分支和基线： worktree 跟踪哪些分支，以及使用哪个基线（决定 worktree 的命名和隔离方式）。
• 端口/服务需求： 开发服务器或 Docker 是否需要分配端口（决定确定性端口区间和生成的 Docker Compose 覆盖配置）。

只询问此请求中最重要的两三项输入，不要把清单全部问一遍。如果用户希望立即获得结果，请直接生成结果，并在开头说明你的假设。

工具

工具	用途	命令
worktree_manager.py	列出、创建、移除和清理 worktree	python scripts/worktree_manager.py list
port_allocator.py	分配/检查/释放确定性端口区间；同步注册表	python scripts/port_allocator.py status
worktree_validator.py	验证 worktree 状态（陈旧、缺少分支、环境一致性、端口冲突、锁文件）	python scripts/worktree_validator.py --stale-days 14

参考资料

加载与任务匹配的参考资料——保持此文件简洁，按需查阅详细信息：

• references/setup-and-ports.md — git worktree 快速入门命令、确定性端口分配策略和 .worktree-ports.json 格式、端口冲突检测代码片段、完整的 setup-worktree.sh 脚本，以及按 worktree 配置的 Docker Compose 覆盖文件。创建 worktree 或配置端口/服务时阅读。
• references/cleanup-and-workflows.md — 安全清理脚本 cleanup-worktrees.sh、多 Agent 分配模式和规则、场景→操作决策矩阵，以及创建后的验证清单。自动执行清理或协调 Agent 时阅读。
• references/operations-playbook.md — 常见陷阱、最佳实践、故障排除表和成功标准。发布工作流前或诊断问题时阅读。

范围与限制

此技能涵盖：

• Git worktree 的生命周期：创建、列出、状态检查和移除
• 确定性端口分配，以及避免并行开发服务器发生冲突
• 环境文件同步和 Docker Compose 覆盖模式
• 多 Agent 工作区隔离策略和清理自动化

此技能不涵盖：

• Git 分支策略或合并冲突解决（请参阅 pr-review-expert 和 release-manager）
• 密钥轮换、保管库集成或凭据管理（请参阅 env-secrets-manager）
• CI/CD 流水线配置或自动化测试编排（请参阅 ci-cd-pipeline-builder）
• Monorepo 包管理、工作区链接或跨包依赖解析（请参阅 monorepo-navigator）

集成点

技能	集成方式	数据流
env-secrets-manager	Worktree 设置会复制包含由此技能管理的密钥的 .env 文件	.env 文件从主仓库流向每个 worktree；所有副本中的密钥引用保持一致
ci-cd-pipeline-builder	CI 流水线可以启动 worktree，以并行执行测试矩阵	流水线配置会为每个矩阵任务触发 setup-worktree.sh；端口分配可防止服务冲突
release-manager	发布分支会获得专用 worktree 用于稳定化，同时继续进行功能开发	发布 worktree 从发布分支创建；合并状态会驱动清理自动化
monorepo-navigator	在 Monorepo 设置中，worktree 必须遵循包边界和共享依赖	Worktree 创建会继承 Monorepo 根锁定文件；包级开发服务器使用分配的端口段
pr-review-expert	PR 审查可以在隔离的 worktree 中进行，并运行代码以供手动验证	审查者会在 PR 分支上创建 worktree，在分配的端口上运行开发服务器，并在审查后移除 worktree
tech-debt-tracker	过期的 worktree 和被放弃的分支会成为技术债务指标	清理脚本的输出会馈入债务跟踪；worktree 的存续时间和合并状态会影响优先级评分