nested-subagents

嵌套子 Agent

生成一棵子 Agent 树，其中每个子 Agent 都可以继续生成子 Agent，最多深入 5 层。这样做的目的是管理上下文，而不是并行处理：每一层都会获得一个全新的上下文窗口，因此深度工作不会耗尽顶层 Agent 的上下文预算。

适用场景

• 问题可以分解为嵌套层级（研究 → 扩展 → 验证 → 综合），否则每一层的内容都会污染父级的上下文。
• 单个 Agent 的上下文窗口不足以容纳所有中间状态。
• 树的叶节点是不同的 subagent_type，需要各自专用的提示词（例如，一个叶节点使用 pii-detector，另一个使用 tester）。

如果扁平扇出（在一条消息中使用 Task × N）就足够了，请跳过此技能——嵌套会增加延迟。

步骤

1. 调用协调器——将 nested-coordinator 生成为顶层 Agent：

   Task({
     subagent_type: "nested-coordinator",
     name: "root-coordinator",
     description: "Decompose and delegate <problem>",
     prompt: "<problem statement, with constraints and expected output shape>"
   })
   

2. 协调器先进行分解——在调用任何 Task 之前，它会通过 TodoWrite 列出生成树。请先检查这棵树，再批准深度工作。

3. 子级生成子级——任何 nested-coordinator（或 YAML frontmatter 声明了 tools: [..., Task] 的其他 Agent）都可以调用 Task 来生成下一级。叶 Agent（其工具列表中不包含 Task）不能这样做。

4. 每一级都返回摘要——子级返回约 200 个 token 的结构化摘要，而不是完整记录。这样做的关键目的，是让父级的上下文保持干净。

5. 持久化树结构——每次生成 Agent 时，post-task 钩子都会将 parent_agent_id 和 depth 写入 AgentDB（ADR-147 P2）。运行结束后进行查询，以便归因成本并学习模式。

深度预算

来源	限制
Anthropic API	5 层（于 2026-06-09 宣布）
Ruflo 默认设置（pre-task 钩子）	4 层——设置一级保护余量，可在 claude-flow.config.json 中配置
严格模式环境变量	设置 CLAUDE_FLOW_STRICT_NESTING=true 以强制执行 Ruflo 上限

达到上限时，钩子会返回类型化的 NESTING_DEPTH_EXCEEDED 错误，并在负载中提供完整调用链，供父级决定是进行摘要、移交还是中止。

优势

• 每一级隔离上下文——顶层协调器看不到内部讨论；叶节点摘要会逐级向上传递。
• 更深入的委派，无需重复概括——避免了扁平扇出所迫使的“在第 1 层概括所有内容以便容纳”的反模式。
• 树形成本归因——parent_agent_id 血缘关系可准确统计每棵树的开销，而不只是每个 Agent 的开销。
• 可与 Ruflo 现有的编排器清晰对应——ruflo-sparc:sparc-orchestrator（5 个阶段 ≈ 5 层）、ruflo-goals:dossier-investigator（递归扩展实体）、v3-queen-coordinator（hierarchical-mesh 顶层）。

反模式（请勿这样做）

• **不要将 Task 传给叶 Agent。**叶节点不得生成子级。应直接在协调器下添加叶节点的 subagent_type。
• **不要用协调器包装 Tier-1 codemod。**Codemod（hooks_codemod）是深度为 0 的确定性转换——绝不要将它们放入生成树中。
• **不要为了“结构整洁”而嵌套。**过早增加嵌套层会增加延迟和成本，却不能节省上下文。如果一个 Agent 就能完成工作，就用一个 Agent。
• **不要让子级返回完整记录。**这会彻底破坏嵌套的目的。子级应返回结构化摘要。

相关内容

• Agent：ruflo-agent:nested-coordinator——编排器
• ADR-147——设计依据和四阶段推出计划
• ADR-144——授权传播将深度计数器作为 AuthScope.delegationDepth 共用
• ADR-099——dossier 调查器（递归并行研究）是典型的深度应用场景