Subagent · 上下文隔离与派发
"派活给小弟"看起来是 multi-agent 范式，但真正的关键收益是上下文隔离——让主 loop 不被子任务的细节淹没。
Core Curriculum
Level 2 · 工程判断
阅读时间 · 21 分钟
练习 · 建议必做
低波动
Last reviewed · 2026-04-22
你将学会什么
- 理解《Subagent / 上下文隔离与派发》在 agent harness / coding agent 学习路径里的核心作用。
- 能用本页给出的判断法区分“概念、机制、边界、代价”。
- 知道这页内容之后会在哪一章被复用到源码阅读或动手实践里。
学习前提
建议先读《Virtual Filesystem / 上下文卸载》；如果你是跳读，至少先看本章索引与本页 TL;DR。
这页在课程中的位置
课程中段的能力层，用来回答“一个 harness 为什么需要这些补丁”。
本页 1 句话结论
"派活给小弟"看起来是 multi-agent 范式，但真正的关键收益是 上下文隔离 ——让主 loop 不被子任务的细节淹没。
带走的判断法
先看失败模式，再看能力补丁；能力不是越多越好，而是要能对症下药。
Source Policy
课程主线：稳定能力抽象 + 官方机制 + 跨框架共性。
TL;DR
- Subagent 不是"为了模拟人类协作"，是为了上下文隔离。一个子任务跑下来可能产生 30 条 message——如果在主 loop 里跑，主 loop 直接被淹没；派给 subagent 跑，主 loop 只看到 1 条摘要。
- 机制：暴露一个
task 工具，参数是 (instruction, context_to_pass)。tool 实现内部启动一个新的 agent loop，用独立 context 跑完，把结果摘要作为 tool 返回回灌到主 loop。
- 它和 multi-agent group chat 是不同范式——subagent 是主从、单向、隔离；group chat 是平等、双向、共享。前者更稳，后者更灵活。多数 production agent 选前者。
- 4 个关键设计点：① 传什么给子；② 子能用哪些工具；③ 子返回什么形态；④ 子失败时怎么处理。每一条选错都会让 subagent 退化成"额外开销但不解决问题"。
1. 没有它会怎样：主 loop 被子任务淹没
设想 Claude Code 接到任务："看 src/ 下所有 .ts 文件，找出所有用了 deprecated API 的地方，整理一份清单。"
没有 subagent 时：
- 主 loop 第 1-3 轮：grep + glob 找文件，定位到 80 个 .ts 文件。
- 第 4-83 轮：逐个 read 每个文件 + grep 关键字 + 写笔记——这 80 轮的 read 输出全部留在主 loop 的 message 历史里。
- 到第 80 个文件时，message 历史已经有几千条 tool message，模型的注意力分散，开始漏检或对最后几个文件给出过分详细分析。
- 第 84 轮要写汇总清单时——它已经"看不见"前 60 个文件的发现了。
有 subagent 时：
- 主 loop 第 1-3 轮：grep + glob 找出 80 个文件。
- 主 loop 第 4 轮：调用
task 派一个 subagent："你的任务是 read 这 20 个文件，找 deprecated API 用法，返回清单。"
- Subagent 在独立 context 跑 20 几轮，跑完只返回一行摘要 + 一份结构化清单。
- 主 loop 重复 4 次，总共派 4 个 subagent 跑完 80 个文件。主 loop 始终只有十几条 message。
- 第 8 轮主 loop 整理 4 份清单输出最终结果——清晰、不漏、可重放。
2. 主 loop 视角对比 · 可切换
切换看同一任务的主 loop 上下文差异（任务跑完时）：
3. 内部最小实现（30 行）
# task 工具：参数 = 子任务指令 + 必要 context；返回 = 子 agent 的最终摘要
def task_tool(state, instruction: str, context: str = "",
al
