子 agent 并行调研

子 agent 在隔离上下文中并行执行只读工具，然后向主对话返回摘要。

为什么需要子 agent？

重型调研任务（多文件分析、多轮推理）会快速消耗上下文 token。子 agent 将这些工作隔离：

主上下文：已用 50k tokens
  → 派生子 agent 进行调研
  → 子 agent：30k tokens 的探索（隔离）
  → 返回：500 token 摘要
  → 主上下文：仍为 50k tokens（无污染）

工作原理

派生子 agent

当 LLM 判断调研任务足够重时，会自动派生子 agent：

LLM："我需要在做修改前分析完整的 auth 模块"
  → 派生子 agent，任务："分析 auth 模块结构"
  → 子 agent 在隔离上下文中运行
  → 返回摘要："auth.py 有 3 个类，login 使用 JWT..."

只读执行

子 agent 只能使用只读工具：

允许	禁止
read_file	write_file
glob_files	edit_file
grep_content	execute_bash
locate_symbol
find_references

这确保子 agent 不能修改你的代码。

一次性使用

每个子 agent 是用完即焚的：

为特定任务创建
运行工具直到完成
返回简要摘要（to_brief）
上下文被丢弃——永不复用

与主对话的集成

子 agent 属于 harness（自主对话）范式：

主 harness 循环：
  → LLM 识别出重型调研任务
  → 调用 spawn_subagent 工具
  → 同时继续其他工作
  → 接收摘要
  → 用摘要指导下一步操作

子 agent 的摘要作为工具结果进入主上下文——与其他工具输出无异。

示例：多文件分析

用户："重构 auth 模块前，先分析所有相关文件"

LLM 决定派生子 agent：
  任务："分析所有与认证相关的文件：
         - 找出所有从 auth/ 导入的文件
         - 检查每个文件的依赖关系
         - 报告结构和耦合度"

子 agent 运行：
  1. grep_content("from.*auth") → 12 个文件
  2. 逐个 read_file → 检查导入
  3. locate_symbol("AuthService") → 3 个定义
  4. find_references("login") → 15 个引用

子 agent 返回摘要（500 tokens）：
  "Auth 模块：auth/ 下 5 个文件，被 12 个文件导入。
   AuthService 类在 3 处定义。
   login 函数有 15 个调用点。
   耦合最紧：routes/auth.py → services/auth.py"

主上下文收到摘要，无需子 agent 的中间探索过程。

并发执行

多个子 agent 可以并行运行：

LLM 同时派生 3 个子 agent：
  Agent 1：分析 auth 模块
  Agent 2：分析 user 模块
  Agent 3：分析数据库 schema

3 个并行运行 → 摘要到达 → LLM 综合分析

这大幅减少多区域调研的墙钟时间。

Effort 和 Client 共享

方面	行为
推理级别	跟随主对话（共享 effort_ref）
API client	与主对话共享连接池
Token 预算	独立——不消耗主上下文 token
上下文	完全隔离——绝不接触主消息历史

何时触发子 agent

LLM 自主决定何时派生子 agent。通常在以下场景：

触发条件	示例
大型代码库扫描	"分析 src/ 中所有文件"
深度依赖分析	"从入口点追踪完整调用链"
多文件对比	"比较 3 个模块的认证实现"
修改前调研	"重构前理解架构"

监控子 agent 活动

派生时状态栏显示：

🧠 medium  📊 12.4k tokens  🔍 [子agent] 分析 auth 模块...

完成后：

🔍 [子agent success] tokens=2.1k

总结

子 agent 是一种 token 效率机制。它让 LLM 进行重型调研而不污染你的主对话上下文。调研保持隔离，只有结论进入主流程。