XCode 子代理（Subagent）
在 XCode 中，你可以创建 专门的 AI 子代理（Subagent），用于处理特定类型的任务，从而获得更好的上下文隔离、更强的约束控制和更高的执行效率。
子代理运行在 独立的上下文窗口 中，每个子代理都可以拥有独立的系统提示、指定的模型、明确的工具访问权限、独立的权限模式，以及跨会话的持久记忆。当 XCode 判断你的请求符合某个子代理的描述时，会自动将任务委托给它，由子代理独立完成后返回结果。
> 子代理只接收自身的系统提示和基础环境信息（如工作目录）， 不会继承完整的 XCode 系统提示，这保证了行为的纯净和可控。
---
为什么要使用子代理
子代理的核心价值在于 隔离 + 专业化，主要体现在以下几个方面：
保留主对话上下文：把探索、日志分析等"重任务"放到子代理中，主对话只接收结论摘要，不被大量中间输出淹没。研究表明，并行运行三个子代理分析 5 万行项目约需 45 秒，而串行执行需要 3 分钟。
强制执行约束：通过工具白名单或黑名单限制子代理的能力，例如只读分析、禁止执行危险命令。
行为专业化：为特定领域（代码审查、调试、数据分析）设计专用 AI，在系统提示中明确指出代理的能力边界，避免不必要的调用。
控制成本：将简单任务交给 Haiku，将复杂分析交给 Sonnet，通过环境变量 XCODE_SUBAGENT_MODEL 统一设置所有子代理使用的模型。
跨项目复用：用户级子代理一次配置，所有项目可用。
---
子代理 vs 多代理
| 对比项 | 子代理（Subagent） | 多代理（Multi-agent） | |--------|-------------------|----------------------| | 运行范围 | 在单个 XCode 会话内启动，处理子任务后返回结果 | 多个 XCode 会话并行或串行运行，通常由编排器管理 | | 上下文 | 独立上下文窗口，与主对话隔离 | 各会话上下文完全独立 | | 嵌套 | 子代理不能再创建子代理（需嵌套时使用 Skills） | 可由编排器协调多层级任务 | | 适用场景 | 聚焦子任务、大量输出隔离、专业分析 | 全功能开发流水线（设计 → 实现 → 测试 → 发布） |
---
内置子代理
1、Explore（探索代理）
用于只读搜索与分析代码库。模型默认使用 Haiku（速度快、延迟低），只开放只读工具（不能 Edit / Write）。当 XCode 需要查看代码但不修改代码时，会自动使用 Explore 代理。支持不同探索深度： quick、 medium、 very thorough。
2、Plan（规划代理）
在计划模式下收集代码库信息，帮助 XCode 理解项目结构，为后续方案制定积累上下文。只开放只读工具，在不产生嵌套代理的前提下安全地收集规划所需信息。
3、General-purpose（通用代理）
用于复杂、多步骤任务，开放全部工具，继承主对话的模型。适合"看 + 改 + 推理"的综合场景，以及需要多步骤代码修改的任务。
4、其他内部代理
| 代理名称 | 说明 | |----------|------| | Bash | 在独立上下文中运行 Shell 命令 | | statusline-setup | 配置终端状态栏显示 | | XCode Guide | 解答 XCode 使用相关问题 |
---
创建你的第一个子代理
1、打开子代理管理界面
在 XCode 中执行以下命令，打开完整的子代理管理界面：
/agents
该界面提供所有子代理管理能力：查看全部可用代理（内置 / 用户级 / 项目级 / 插件）、创建新代理、编辑已有代理，以及在同名冲突时查看哪个版本实际生效。
2、选择创建用户级子代理
在界面中选择 Create new agent，然后选择 Project (.xcode/agents/)，代理文件会保存到当前目录的 .xcode/agents/ 目录下，如果选择 ~/.xcode/agents/ 目录，则对所有项目生效。
3、描述代理的职责
我们可以直接用自然语言告诉 XCode 这个代理要做什么，XCode 会自动生成系统提示和初始配置。例如：
一个代码改进代理，扫描项目文件，
针对可读性、性能和最佳实践提出建议，
并给出改进示例。
生成完成后，按 e 键可以手动编辑所有配置内容。
4、配置工具权限与模型
- 只做代码审查 → 仅勾选只读工具（Read / Grep / Glob）
- 需要修改代码 → 保留 Edit / Write 工具
- 模型推荐选择 Sonnet，分析能力与执行速度较为均衡
- 选择 User：在 ~/.xcode/agent-memory/ 建立持久记忆，跨所有项目积累经验
- 选择 None：不保留学习成果，每次任务从零开始
5、选择记忆范围（可选）
6、使用刚创建的代理
使用 code-improver 子代理为此项目提出改进建议
代理会在独立上下文中运行，完成后将结果摘要返回给主对话。
---
子代理的作用范围
| 存放位置 | 作用范围 | 优先级 | |----------|----------|--------| | CLI --agents 标志 | 仅当前会话 | 最高 | | .xcode/agents/ | 当前项目 | 高 | | ~/.xcode/agents/ | 所有项目（全局） | 中 | | 插件 agents | 插件作用域 | 最低 |
---
配置文件结构
每个子代理配置文件由两部分组成：YAML frontmatter（元数据与配置）和 Markdown 正文（系统提示）。
---
name: code-reviewer
description: Reviews code for quality, best practices, and security issues.
Invoke when the user asks to review, audit, or check code quality.
tools: Read, Grep, Glob
model: sonnet
permissionMode: default
memory: project
---You are a senior code reviewer.
Analyze code and provide actionable feedback organized by severity: Critical / Major / Minor.
Update your agent memory with recurring patterns, conventions, and known issues you discover.
完整字段说明
| 字段 | 是否必填 | 说明 | |------|---------|------| | name | 必填 | 唯一标识，小写字母 + 连字符 | | description | 必填 | 决定 XCode 何时自动调用此代理，务必写清楚使用场景 | | tools | 可选 | 工具白名单；设置后只能使用列出的工具，MCP 工具也会被排除 | | disallowedTools | 可选 | 工具黑名单；继承主对话全部工具，但排除列出的工具（MCP 工具保留） | | model | 可选 | 指定模型：haiku / sonnet / opus / inherit | | permissionMode | 可选 | 权限行为控制 | | memory | 可选 | 持久记忆范围：user / project / local | | background | 可选 | 设为 true 时，该代理始终以后台方式运行 | | isolation | 可选 | 设为 worktree 时，在临时 git worktree 中运行 | | skills | 可选 | 在此代理启动时自动加载的 Skills 列表 | | hooks | 可选 | 生命周期钩子：SubagentStart / SubagentStop / PreToolUse / PostToolUse |
---
权限模式
| 模式 | 行为 | 适用场景 | |------|------|----------| | default | 正常权限提示，每次操作前询问用户 | 通用场景，推荐默认值 | | acceptEdits | 自动接受文件编辑，无需每次确认 | 频繁改动文件的代理 | | dontAsk | 自动拒绝未授权操作，不中断执行流程 | 严格只读场景 | | bypassPermissions | 跳过所有权限检查，直接执行 | 仅限完全可信的自动化环境 | | plan | 只读规划模式，不执行任何写操作 | 方案制定、架构分析 |
---
持久记忆（Memory）
| 范围值 | 存储位置 | 适用场景 |
|--------|----------|----------|
| user | ~/.xcode/agent-memory/
---
worktree 隔离模式
设置 isolation: worktree 后，子代理会在临时 git worktree 中运行，与主仓库完全隔离。适合：
---
后台运行（Background）
| 运行方式 | 行为 | 限制 | |----------|------|------| | 前台（Foreground） | 阻塞主对话直到完成，权限提示和澄清问题会实时传给用户 | 无特殊限制 | | 后台（Background） | 并行执行，不打断主对话；启动前会预先确认所需权限 | 无法使用 MCP，无法进行交互式澄清；权限不足时任务失败 |
控制方式：
Ctrl + B：将当前运行的子代理切换到后台Ctrl + F（按两次确认）：终止所有后台代理background: true：始终以后台方式运行如需彻底禁用后台任务功能：
export XCODE_DISABLE_BACKGROUND_TASKS=1
---
生命周期钩子（Hooks）
| 钩子事件 | 触发时机 | 典型用途 | |----------|----------|----------| | SubagentStart | 子代理启动时 | 记录启动日志、初始化环境 | | SubagentStop | 子代理任务完成时 | 记录结果、触发下游任务、发送通知 | | PreToolUse | 工具调用前 | 校验操作合法性，退出码为 2 时可阻止该工具调用 | | PostToolUse | 工具调用后 | 格式化输出、生成变更记录 |
---
典型使用模式
1、隔离高输出任务
使用子代理运行所有测试，只返回失败的测试和根因分析
2、并行研究
并行使用子代理分别分析认证模块、数据库模块和 API 模块，汇总后给出整体架构建议
3、串联子代理流水线
先用 code-reviewer 找出问题，再用 optimizer 子代理修复这些问题
串联工作流的设计原则：每个代理只做一件事，并通过清晰的"输入 → 处理 → 输出 → 交接信号"定义接口。
4、并行代码审查
同时启动 style-checker、security-scanner、test-coverage 三个子代理并行审查，
将审查时间从数分钟压缩到数十秒
---
最佳实践
description 怎么写
工具权限设计（最小权限原则）
单一职责
并行 vs 串行的选择