LEARN CLAUDE CODE
S04: Subagent — 用上下文隔离保持主线清晰
这一课解决什么问题
到了 S03，Agent 可以规划和执行多步任务了。但有个新问题：messages[] 越来越胖。
假设你让 Agent 「重构 auth 模块」，它需要先去读 10 个文件理解代码结构。这 10 次 read_file 的完整结果全部堆在 messages[] 里——但主线任务真正需要的只是「auth 模块的接口设计如下：...」这样一句摘要。那些中间过程（几千行代码内容）白白消耗着宝贵的上下文窗口。
核心机制
┌────────────── 主 Agent ──────────────────────┐
│ │
│ messages = [system, user, ...] │
│ "帮我重构 auth 模块" │
│ │ │
│ │ 模型决定: "我需要先了解代码结构" │
│ │ │
│ ▼ │
│ ┌─── 子 Agent (独立上下文) ──────────┐ │
│ │ messages = [] ← 全新的空数组 │ │
│ │ system: "你是代码分析助手" │ │
│ │ task: "分析 src/auth/ 的代码结构" │ │
│ │ │ │
│ │ 循环 1: read_file(auth/index.ts) │ │
│ │ 循环 2: read_file(auth/types.ts) │ │
│ │ 循环 3: read_file(auth/middleware) │ │
│ │ ... 读了 10 个文件 ... │ │
│ │ 循环 N: end_turn → 输出摘要 │ │
│ │ │ │
│ │ return: "auth 模块包含 3 个核心 │ │
│ │ 接口: AuthProvider, Session, │ │
│ │ TokenManager..." │ │
│ └──────────────────────────────────────┘ │
│ │ │
│ ▼ 只有摘要进入主 messages[] │
│ messages.append(subagent_summary) │
│ │
│ 主 Agent 继续工作，上下文依然干净 │
└───────────────────────────────────────────────┘
对比：
无子 Agent: messages[] = 主任务 + 10个文件完整内容 ≈ 50,000 tokens
有子 Agent: messages[] = 主任务 + 一段摘要 ≈ 2,000 tokens
关键概念解释
- 上下文隔离子 Agent 有自己独立的 messages[] 数组，它的中间过程（工具调用、中间思考）不会污染主 Agent 的上下文。子 Agent 结束后，只有最终输出（摘要）被追加到主 Agent 的 messages[] 中。 — 核心价值：把「探索性工作」的中间垃圾隔离在子上下文里。
- 摘要返回子 Agent 的完整输出被压缩为一段简洁的摘要文本，只包含主 Agent 决策所需的关键信息。相当于你派下属去调研，他回来只给你汇报结论，不把所有原始资料堆你桌上。 — 信息密度最大化。主 Agent 拿到的是蒸馏后的精华。
对应到 Claude Code 官方的什么
AgentTool
Claude Code 的 AgentTool 就是这个机制的生产实现：
- 创建一个独立的子 Agent 实例，拥有自己的 messages[]
- 子 Agent 可以使用所有只读工具（不允许写操作，除非明确授权）
- 子 Agent 执行完毕后，将结果摘要返回给主 Agent
- 主 Agent 的 messages[] 中只出现摘要，中间过程全部丢弃
官方实现还有一个 maxTurns 限制，防止子 Agent 无限循环。
变更对比表
| 维度 | S03（单 Agent） | S04（主 + 子 Agent） |
|---|---|---|
| 上下文大小 | 所有中间过程堆积 | 只保留摘要，压缩比可达 25:1 |
| 信息质量 | 噪声多，关键信息被淹没 | 高密度摘要，直击要点 |
| 可处理任务规模 | 受上下文窗口限制 | 子 Agent 可独立处理大量文件 |
| 架构复杂度 | 单循环 | 嵌套循环（Agent 里跑 Agent） |
| 新增代码 | — | SubAgent 函数 + 独立 messages[] 管理 |
洞察：子 Agent 的本质是「用 API 调用成本换上下文空间」。子 Agent 的执行需要额外的 API 调用，但它释放了主 Agent 的上下文窗口，让主 Agent 能处理更大的任务。这是一种空间换时间（准确说是上下文空间换 API 调用）的策略。