企业官网建设流程全解析

多AI团队并行开发不冲突：Agent Teams AI的Git Worktree分支策略详解

【免费下载链接】agent-teams-aiYou're the boss, agents are your team. They handle tasks on their own, message each other, and review each other's work. You just watch the kanban board and give high-level commands. Codex/Claude/OpenCode/Cursor/Grok/GitHub/Kiro/Z.AI/Xiaomi/MiniMax/Kimi(300+ models, 200+ LLM providers, free models no auth) Build your AI company with multiple teams项目地址: https://gitcode.com/gh_mirrors/cl/agent-teams-ai

让多个 AI 智能体团队同时改一个代码库，最怕的就是"互相踩踏"。Agent Teams AI 是一套多 AI 团队协作工具，你负责下高层指令、看看板，AI 团队自己领任务、互相发消息、互审代码。它的核心能力之一，就是基于 Git Worktree 的分支隔离策略：给每个队友分配独立的 worktree 检出目录和专属分支，让并行开发不再冲突。本文面向新手，详解这套 Git Worktree 分支策略的原理、启用条件和审查流程。

为什么多AI并行开发必然产生冲突

当你同时让 3 个 AI 队友修改同一个仓库时，传统做法下会发生这些问题：

• 文件覆盖：两个 AI 同时编辑policy.ts，后写的把先写的改动覆盖了
• 状态污染：lead 自己的工作区还没提交，队友的修改混进来，分不清谁改了什么
• 合并地狱：所有变更堆在同一个分支上，最后审查时一锅粥

Agent Teams AI 的思路很直接：一人一个 worktree，一人一个分支，物理隔离 + 逻辑隔离双保险。

三种并行策略：按团队规模选对模式

官方文档 git-worktree-strategy.md 给出了一张清晰的策略对照表：

💡核心建议：从简单开始。只有在真正可能出现并行编辑时才启用 worktree 隔离，而不是给每个任务都建一份检出——那样只会拖慢审查节奏。

什么时候该启用 Worktree 隔离

满足以下任意一条，就值得为 OpenCode 队友开启 worktree 隔离：

• ✅ 两个或更多队友可能同时编辑同一个仓库
• ✅ 某个任务会运行格式化工具、代码生成器或大范围测试
• ✅ 你希望每个队友的分支和 diff 彼此独立
• ✅ lead 工作区是"脏"的（有未提交改动），不该被队友直接动

反之，以下情况保持关闭即可：任务是只读的、只有一个队友在编辑、仓库还没被 Git 跟踪，或运行时路径不支持该隔离模式。

⚠️ 注意：Worktree 隔离目前仅适用于 OpenCode 成员，且项目必须已被 Git 跟踪。

自动化机制：每个队友一个专属分支

这套策略的底层实现在 TeamMemberWorktreeManager.ts 中，它会自动完成三件事，你完全不用手动敲 git 命令：

1️⃣ 生成确定性的专属分支名

分支名格式为agent-teams/<团队名>/<成员名>-<仓库哈希>，例如agent-teams/atlas/bob-a1b2c3d4e5。同一成员重复启动团队时，哈希保证分支名稳定，不会凭空产生一堆孤儿分支。

2️⃣ 独立的检出目录

每个成员拥有独立的 worktree 目录，按「项目名-仓库哈希/团队/成员」三级组织存放在应用数据目录的team-worktrees下，互不干扰。

3️⃣ 幂等与防冲突保护

代码中有一道关键防线：创建前会检查git worktree list，如果该分支已在别处被检出，直接报错拒绝（branch is already checked out elsewhere）；目录已存在时则校验它确实属于同一个 Git 仓库、且不在 detached HEAD 状态——队友上次做到哪条任务分支上，就原样保留。

前置条件检查：Git 状态预检服务

在真正创建 worktree 之前，TeamWorktreeGitService.ts 会做一轮体检，把常见坑提前拦下来：

• 项目路径必须是绝对路径且是真实存在的目录
• 项目必须是 Git 仓库（否则会提示 "Worktree isolation requires a Git repository"）
• 仓库必须有至少一次提交（HEAD 存在）。注意：它只会提醒你手动提交，绝不会自动帮你 commit

如果项目还不是仓库，服务也可以引导执行git init并创建初始提交，把"裸目录"变成可隔离的工作区。

分支卫生：开始并行开发前的30秒清单

在启动团队之前，花 30 秒确认状态：

1. 运行git status --short，看看主工作区是否干净
2. 运行git branch --show-current，确认当前分支
3. 主工作区有未提交改动也没关系——但要明确告诉智能体不要 revert 不相关文件，并把任务范围收窄

文档推荐了统一的分支命名风格：

agent/<团队或任务>/<简短用途>

例如agent/docs/mcp-guide、agent/review/task-log-filtering，一眼就能看出这条分支是谁、为哪个任务开的。

审查流程：完成不等于自动合并

隔离带来的最大收益是审查路径变干净了：每个 worktree 对应一个独立分支，diff 精简、变更范围聚焦。审查界面里可以按文件、按代码块逐个 Accept 或 Reject：

标准审查流程 5 步：

1. 看任务结果评论，确认智能体说明了变更范围和验证方式
2. 在审查 UI 中逐块检查任务 diff
3. diff 碰了不相关文件？→ 请求修改（request changes）
4. 测试/手动检查的风险等级与任务匹配后，再批准
5. 有意识地合并或应用变更

🚫 最重要的纪律：不要仅因任务完成就自动合并。"完成"只意味着智能体自认为准备好接受审查，不代表变更真的安全。

冲突处理策略：4种常见情形怎么办

即便做了隔离，并行团队仍会遇到摩擦。官方给出的处理对照表：

任务提示词的写法也直接影响冲突概率。一个好的提示词会指明允许的区域、敏感的边界、完成的证据，例如："在你的 worktree 中实现设置校验修复，编辑限定在 settings 目录内，不要碰 provider auth 和任务存储，完成前提交测试命令和结果。"更多示例见 team-brief-examples.md。

从简单开始，渐进式上隔离

总结这套 Git Worktree 分支策略的心法：

• 单一队友/只读任务→ 直接用主 worktree，别过度设计
• 连贯变更的团队→ 开一条功能分支，审查目标更清晰
• 多 OpenCode 队友并行编辑→ 启用 worktree 隔离，自动专属分支 + 独立 diff
• 任何情况→ 完成 ≠ 合并，审查永远由你把关

想进一步了解，可以阅读仓库内的策略研究笔记 research-worktrees.md（涵盖 per-teammate、per-task 等进阶隔离模式的设计权衡）、code-review.md（审查机制详解）以及 create-team.md（创建团队入门）。

让 AI 团队并行狂奔，你只管看板与合并——这正是 Agent Teams AI "你是老板，智能体是团队"的核心体验。

【免费下载链接】agent-teams-aiYou're the boss, agents are your team. They handle tasks on their own, message each other, and review each other's work. You just watch the kanban board and give high-level commands. Codex/Claude/OpenCode/Cursor/Grok/GitHub/Kiro/Z.AI/Xiaomi/MiniMax/Kimi(300+ models, 200+ LLM providers, free models no auth) Build your AI company with multiple teams项目地址: https://gitcode.com/gh_mirrors/cl/agent-teams-ai