XCode 并行任务

XCode 提供了多种并行执行任务的机制，让你可以同时处理多个工作项，显著提升开发效率。本章将介绍三种主要的并行化方案：Subagents（子代理）、Agent Teams（代理团队）和 Git Worktree（Git 工作树），帮助你根据不同的使用场景选择最合适的方式。

---

并行任务概述

| 机制 | 适用场景 | 协作方式 | 复杂度 | |------|----------|----------|--------| | Subagents | 专注型任务，只需关注结果 | 单向汇报（结果返回主代理） | 低 | | Agent Teams | 需要讨论与协作的复杂工作 | 多向通信（队友直接互发消息） | 中 | | Git Worktree | 多个任务需要隔离的代码环境 | 完全独立（各自的工作目录） | 中 |

> 选择建议： > - 只需并行处理、相互独立的子任务 → 使用 Subagents > - 需要多个 Agent 相互讨论、协调工作 → 使用 Agent Teams > - 多个任务需要操作同一仓库的不同分支 → 使用 Git Worktree

---

Subagents（子代理）

内置 Subagents

| Agent | 模型 | 工具 | 用途 | |-------|------|------|------| | Explore | Haiku（快速、低延迟） | 只读工具 | 文件发现、代码搜索、代码库探索 | | Plan | 继承主对话 | 只读工具 | 规划模式下的代码库研究 | | General-purpose | 继承主对话 | 所有工具 | 复杂研究、多步骤操作、代码修改 | | statusline-setup | Sonnet | — | 运行 /statusline 配置状态行 | | XCode Guide | Haiku | — | 解答 XCode 功能问题 |

调用 Subagent

方式一：自然语言

Use the test-runner subagent to fix failing tests

方式二：@-mention

@"code-reviewer (agent)" look at the auth changes

方式三：命令行启动

xcode --agent code-reviewer

前台与后台运行

前台 Subagent：阻塞主对话直到完成
后台 Subagent：并发运行，可按 Ctrl+B 切换

---

Agent Teams（代理团队）

Agent Teams 可以让你协调多个 XCode 实例一起工作。其中一个充当团队负责人（Leader），负责协调工作、分配任务并整合结果。其他成员各自独立工作，拥有各自的上下文窗口，同时还能直接相互沟通。

Subagents vs Agent Teams

| 特性 | Subagents | Agent Teams | |------|-----------|-------------| | 上下文 | 自己的上下文窗口；结果返回给调用者 | 自己的上下文窗口；完全独立 | | 通信 | 仅将结果汇报给主代理 | 队友之间直接互发消息 | | 协调 | 主代理负责管理所有工作 | 共享任务列表，支持自我协调 | | 最适合 | 只需关注结果的专注型任务 | 需要讨论与协作的复杂工作 | | Token 成本 | 较低：结果汇总回主上下文 | 较高：每位队友都是独立的 XCode 实例 |

简单来说：Subagent 是打工人向老板汇报，Agent Teams 是平等协作的项目组。

启用 Agent Teams

在 settings.json 中添加：

{
  "env": {
    "XCODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

或设置环境变量：

export XCODE_EXPERIMENTAL_AGENT_TEAMS=1

启动 Agent Team

启用后，用自然语言描述任务和团队结构：

Create an agent team to explore this from different angles:
one teammate on UX, one on technical architecture, one playing devil's advocate.

控制 Agent Team

显示模式

In-process：所有队友在主终端内运行，使用 Shift+Down 循环浏览队友
Split panes：每个队友获得自己的 tmux/iTerm2 窗格

指定队友数量和模型

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

任务分配

负责人可显式分配任务
队友可自我认领未分配、未阻止的任务
任务有三种状态：待处理、进行中、已完成

与队友交互

In-process：Shift+Down 循环浏览 → 输入消息 → Enter 查看 → Escape 中断
Split-pane：点击队友窗格直接交互

Agent Teams 架构

| 组件 | 角色 | |------|------| | Team Lead | 创建团队、生成队友并协调工作的主 XCode 会话 | | Teammates | 各自处理分配任务的独立 XCode 实例 | | Task List | 队友认领和完成的共享工作项列表 | | Mailbox | 代理之间通信的消息系统 |

存储位置：

Team config: ~/.xcode/teams/{team-name}/config.json
Task list: ~/.xcode/tasks/{team-name}/

---

Git Worktree 支持

什么是 Git Worktree

Git Worktree 是 Git 的一个功能，允许你在同一个仓库上挂载多个独立的工作目录。每个工作目录有自己的分支、自己的 HEAD、自己的暂存区，但共用同一个 .git 数据库（历史记录、对象存储）。

> 日常生活比喻："同一家公司（主仓库）有多个办公室（worktree），每个办公室有不同的团队（Agent），各自处理不同的项目（分支），但都共享公司的数据库（.git）和历史记录。"

使用 Git Worktree

命令行启动

# 创建 feature-auth 分支的工作树
xcode -w feature-auth
同时创建 tmux 会话
xcode -w feature-auth --tmux
使用传统 tmux
xcode -w feature-auth --tmux=classic

CLI 参数

| 参数 | 描述 | 示例 | |------|------|------| | --worktree, -w | 在隔离的 git worktree 中启动 XCode | xcode -w feature-auth | | --tmux | 为 worktree 创建 tmux 会话 | xcode -w feature-auth --tmux |

Worktree 创建位置：/.xcode/worktrees/

Subagent + Worktree 隔离

可以让自定义 Subagent 始终在自己的 worktree 中运行：

---
name: background-refactorer
description: Background refactoring agent
isolation: worktree
---

---

使用示例

示例一：并行代码审查

Use the security-reviewer subagent to check for security issues
Use the performance-reviewer subagent to analyze performance impact
Use the test-coverage subagent to validate test coverage

示例二：并行研究

Research the authentication, database, and API modules in parallel using separate subagents

示例三：多分支开发

# 终端 1：重构用户模块
xcode -w feature/user-refactor
终端 2：修复登录 bug
xcode -w bugfix/login-issue
终端 3：开发新功能
xcode -w feature/new-dashboard

示例四：链接 Subagent

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

---

最佳实践

Subagent 最佳实践

1. 保持专注：每个 Subagent 应有明确、单一的任务 2. 限制工具：根据任务需要限制 Subagent 的工具访问权限 3. 选择合适模型：简单任务使用 Haiku，复杂任务使用 Sonnet 或 Opus 4. 使用后台运行：长时间任务使用后台 Subagent，避免阻塞主对话 5. 恢复 Subagent：需要继续工作时，要求 XCode 恢复 Subagent

Agent Teams 最佳实践

1. 给队友足够的上下文：在生成提示中包含特定于任务的详细信息 2. 选择适当的团队规模：大多数工作流从 3-5 个队友开始 3. 适当调整任务大小：每个队友 5-6 个任务，保持生产力 4. 等待队友完成：告诉负责人等待队友完成任务后再进行 5. 从研究和审查开始：从不需要编写代码的任务开始 6. 避免文件冲突：分解工作使每个队友拥有不同的文件集 7. 监控和指导：检查进度，重定向不起作用的方法

Git Worktree 最佳实践

1. 每个任务一个 Worktree：避免在同一个 worktree 中处理多个不相关的任务 2. 使用 tmux 管理：同时运行多个 XCode 会话时，使用 tmux 便于切换 3. 清理不需要的 Worktree：任务完成后及时删除 worktree

---

故障排除

| 问题 | 解决方案 | |------|----------| | 队友未出现 | 检查任务是否足够复杂、tmux 是否安装 | | 过多权限提示 | 在权限设置中预批准常见操作 | | 队友在错误后停止 | 检查输出并给予额外指示或生成替代队友 | | 负责人提前关闭 | 告诉负责人继续或等待队友完成 | | 孤立的 tmux 会话 | 使用 tmux ls 和 tmux kill-session -t 清理 |