ruflo nested-leaf嵌套生成树最底层的最小权限叶子Agent 模板实战指南【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/rufloruflo 在plugins/ruflo-agent插件中提供了一整套面向 Claude Code 原生嵌套子代理nested subagents能力的 Agent 模板。nested-leaf是这套体系中的叶子节点模板——它位于整棵生成树的底层只被赋予一个聚焦任务并且故意不授予Task工具从而构成 ADR-147 所要求的最小权限边界least-privilege boundary。本文以该模板为核心讲解叶子的职责契约、强制返回结构、为何禁止叶子再派生以及它与nested-coordinator/nested-researcher/nested-reviewer等编排者模板的配合方式并结合仓库中的 ADR 与源码给出可验证的底层依据。为什么需要叶子嵌套子代理的上下文管理动机嵌套子代理的出发点不是并行而是上下文管理。Claude Code 2.1.169 引入的嵌套能力让每个子代理拥有独立的上下文窗口子代理自己还能再派生子代理最深可达 5 层Anthropic API 上限。与扁平扇出相比嵌套的最大价值在于每一层都获得全新的上下文窗口顶层指令永远不需要阅读内层对话只有叶子返回的结构化摘要向上爬升父级上下文因此保持干净。扁平扇出flat fan-outTask× N 一次调用多个子代理只卸载一层上下文lead 仍要读完所有摘要嵌套子代理nested sub-agents每层可以在自己上下文填满之前把更深的工作委托给新的窗口——这正是 ruflo 最深的编排者ruflo-goals:dossier-investigator、ruflo-sparc:sparc-orchestrator、v3-queen-coordinator此前遇到的瓶颈。nested-leaf就是这个模型中的最小工作单元树的底部。它不做任何派生只完成一项被分配的任务并返回结构化摘要。nested-leaf 模板的核心内容plugins/ruflo-agent/agents/nested-leaf.md的完整 frontmatter 如下--- name: nested-leaf description: Leaf-worker template for nested spawn trees — performs one focused task and returns a structured summary. Deliberately does NOT have the Task tool (least-privilege boundary) model: haiku tools: - Read - Grep - Glob - Bash ---注意三个关键点model: haiku叶子只做单一聚焦工作用轻量模型即可成本最低tools仅包含Read、Grep、Glob、Bash这是最小工具集足够读取、搜索和操作文件但没有Task没有任何Task工具这是整个模板的设计灵魂也是与编排者模板最本质的区别。叶子的三条行为准则模板正文明确了叶子的行为边界只做一项被分配的任务。父级用Task派生你时只给一个单一、有边界的任务你只做这件事。不做探索式展开。如果工作本身需要扇出父级应该派生多个叶子而不是让一个叶子自己再扇出。返回结构化摘要而非完整对话记录约 150–300 tokens。嵌套的全部意义在于保持父级上下文干净——如果返回大段散文这次派生就是浪费。强制的返回结构LEAF_RESULT模板规定叶子必须返回如下形状LEAF_RESULT task: verbatim task your parent gave you status: success | partial | failed result: the actual answer/output, concise evidence: - file:line or command:output notes: one line max — anything the parent needs to know that isnt in result各字段的语义字段含义说明task父级给的原样任务文本便于父级与摘要对应避免歧义status执行状态三选一success/partial/failedresult实际答案/产出要求简洁evidence证据列表必须是file:line或command:output形式可验证notes附加说明最多一行放 result 之外父级必须知道的信息这个形状与nested-coordinator中每个子节点应返回约 200 tokens 的结构化摘要而不是工具调用日志的要求完全一致——结构化摘要就是嵌套通信的最小协议。为什么叶子不能有 Task 工具模板给出了三层理由这也是 ADR-147 P1 的核心决策1. 成本归因会被破坏在 Claude Code 2.1.169 中嵌套生成的运行时门控是hasTaskTool它在派生时刻根据父级的工具列表逐次计算。如果父级把Task传给了你你就会继承它。一旦树中的叶子偷偷派生AgentDB 里会出现看似扁平的派生日志、实际是嵌套的真实树——每份成本报告都会少算。2. 深度预算被无意识地消耗Tier-1 叶子只是想查一下就悄悄派生会静默消耗父级根本没有预算的层级。嵌套深度是有限资源Anthropic API 5 层ruflo 默认 4 层必须被有意使用。3. 混淆代理confused-deputy风险按照 ADR-144 授权传播每次派生都携带父级的AuthScope。叶子如果能派生就可能以原始主体从未授权的方式延长作用域链。ADR-144 规定作用域是单调递减的每一跳只能减少工具/服务器绝不能增加。叶子再派生意味着作用域链条上多了一环不可控的传播。因此模板明确规定如果叶子真的需要派生不要自己派生而是带着followups说明返回给父级——父级拥有Task工具由它决定是否派生后续任务。源码级的门控证据ADR-147 对 2.1.169 二进制的实证分析见 v3/docs/adr/ADR-147-nested-subagent-depth-integration.md确认了以下事实运行时门控是布尔值hasTaskTool从父级工具列表在派生时刻计算不是深度计数器也不是环境变量探测实验显示即使 YAML 声明了tools: [Task, Read, Grep, Glob, TodoWrite, Bash]6 个工具派生子代理实际只继承Read, Grep, Glob, Bash这 4 个——Task和TodoWrite被运行时剥离且在--permission-mode bypassPermissions、--allowedTools显式授权等各种模式下行为一致结论是YAML 的tools:字段确实被加载器接受并传播恰好 4/6 生效Task被剥离属于硬编码或服务端 denylist。这意味着当 denylist 解除时ruflo 的 agent 文件无需任何代码改动即可激活嵌套。这从底层印证了nested-leaf只声明Read / Grep / Glob / Bash的写法是声明式正确的——叶子模板从一开始就按最小权限设计与运行时的实际行为一致。深度预算与防护嵌套体系如何约束叶子嵌套体系有一套完整的深度预算机制详见 nested-subagents SKILL来源上限Anthropic API5 层2026-06-09 宣布ruflo 默认pre-task钩子4 层——保留一层余量可在claude-flow.config.json中配置严格模式环境变量CLAUDE_FLOW_STRICT_NESTINGtrue强制执行 ruflo 上限当达到上限时pre-task钩子返回类型化的NESTING_DEPTH_EXCEEDED错误payload 中携带完整链父级可据此决定是汇总、移交还是中止。这个守卫正是 ADR-147 P3 的设计默认 4 层比 Anthropic 的 5 层少一层保证 ruflo 的拒绝先于 API 的拒绝触发且错误信息更清晰。叶子作为第 N 层时其自身深度已由整条链决定它不需要、也不应该感知深度——这是父级nested-coordinator通过current_depthN传参管理的。何时使用 / 何时不使用模板自身给出了明确的使用边界适用场景编写一个应当位于树底部的新专家 agent以本模板为起点把nested-leaf改名为你的专家名称需要在一个没有编排职责的 agent 中显式强制最小权限。不适用场景agent 需要协调子任务——改用nested-coordinatoragent 由人类用户顶层直接调用而非由父 agent 派生——改用普通平铺 agent 定义如coder、tester等。与编排者模板的配合整棵生成树的形状nested-leaf不是孤立文件它属于plugins/ruflo-agent/agents/下完整的一套 9 个 agent 模板编排者拥有Task负责派生nested-coordinator.md、nested-queen.md、nested-queen-researcher.md、nested-queen-reviewer.md、nested-researcher.md、nested-reviewer.md叶子无Task只做事nested-leaf.md、nested-queen-leaf.md另有独立专家模板wasm-specialist.md编排者的代表 nested-coordinator 的 frontmatter 是--- name: nested-coordinator description: Orchestrator that spawns nested sub-agents (up to depth5) via Claude Codes native Task tool — for deep delegation where context isolation matters more than throughput model: sonnet tools: - Task - Read - Grep - Glob - TodoWrite - Bash ---两者对比一目了然维度nested-coordinatornested-leaf角色编排者树的中间/顶部叶子树的底部模型sonnethaiku是否拥有Task✅ 是❌ 否额外工具TodoWrite先规划树再派生无工作方式分解 → 规划 → 派生 → 汇总执行单个任务 → 返回结构化摘要在nested-coordinator的派生规范中叶子正是它必须遵守的禁止把Task传给叶子约束的另一面coder、tester、pii-detector、security-auditor、aidefence-guardian等叶子 agent 被明确禁止派生。如果树的叶子需要工作编排者直接通过它们的既有subagent_type派生而不是以防万一再派一个nested-coordinator。nested-leaf模板提到的可配对编排者还包括nested-researcher/nested-reviewer以及ruflo-core:coder/ruflo-core:tester见 plugins/ruflo-core/agents/coder.md这些同级叶子——它们拥有各自的专门提示词当角色匹配时优先使用它们只有没有现成叶子匹配时才使用本模板作为起点。实践路径如何把模板落成你的叶子 Agent基于上述设计落地一个叶子 agent 的推荐流程复制模板以plugins/ruflo-agent/agents/nested-leaf.md为起点复制为你的专家名例如pii-detector.md、test-runner.md改写 frontmatter更新name与descriptionmodel保持轻量haiku 级别工具列表保持Read / Grep / Glob / Bash绝不添加Task——这是最小权限边界的声明式保证改写正文职责保留只做一件事、不做探索、返回 LEAF_RESULT三条准则把task语义替换为你的专家职责接入编排树由nested-coordinator或其他声明了tools: [Task, ...]的编排者通过Task({subagent_type: 你的叶子名, ...})派生它遵守深度预算叶子本身不感知深度深度由父级通过current_depthN传递、由pre-task钩子与CLAUDE_FLOW_STRICT_NESTINGtrue强制约束。关联设计文档与验证手段ADR-147 嵌套子代理深度集成本模板的设计依据含四阶段滚动方案P1 仅编排者拥有Task→ P2 从parent_agent_id持久化生成树 → P3 深度感知守卫 → P4 文档与模板对齐以及 2.1.169 的实证分析ADR-144 授权传播AuthScope.delegationDepth与嵌套深度共享同一计数器解释叶子再派生会延长授权链的风险ADR-099 Dossier Investigator递归并行研究的教科书用例——树形递归深挖正是嵌套体系的目标场景验证脚本scripts/probe-nested-spawn-depth.mjs是递归深度探针运行输出见docs/probes/nested-spawn-depth-*.txt在每次 Claude Code CLI 升级后应首先重跑一旦返回CAP OBSERVED at depthN即意味着嵌套运行时已激活P2/P3 随之解锁插件烟测plugins/ruflo-agent/scripts/smoke.sh是插件契约12 项结构检查可验证 agent 文件声明正确。理解nested-leaf本质上就是理解嵌套子代理体系的安全底线树的深度是预算叶子的职责是执行而非派生最小权限是声明在 YAML 里的、而不是运行时祈祷来的。把这套模板放进你的编排树底部你的深层委托才能在上下文隔离、成本归因与授权安全三个维度上同时成立。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ruflo nested-leaf：嵌套生成树最底层的“最小权限叶子“Agent 模板实战指南
ruflo nested-leaf嵌套生成树最底层的最小权限叶子Agent 模板实战指南【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/rufloruflo 在plugins/ruflo-agent插件中提供了一整套面向 Claude Code 原生嵌套子代理nested subagents能力的 Agent 模板。nested-leaf是这套体系中的叶子节点模板——它位于整棵生成树的底层只被赋予一个聚焦任务并且故意不授予Task工具从而构成 ADR-147 所要求的最小权限边界least-privilege boundary。本文以该模板为核心讲解叶子的职责契约、强制返回结构、为何禁止叶子再派生以及它与nested-coordinator/nested-researcher/nested-reviewer等编排者模板的配合方式并结合仓库中的 ADR 与源码给出可验证的底层依据。为什么需要叶子嵌套子代理的上下文管理动机嵌套子代理的出发点不是并行而是上下文管理。Claude Code 2.1.169 引入的嵌套能力让每个子代理拥有独立的上下文窗口子代理自己还能再派生子代理最深可达 5 层Anthropic API 上限。与扁平扇出相比嵌套的最大价值在于每一层都获得全新的上下文窗口顶层指令永远不需要阅读内层对话只有叶子返回的结构化摘要向上爬升父级上下文因此保持干净。扁平扇出flat fan-outTask× N 一次调用多个子代理只卸载一层上下文lead 仍要读完所有摘要嵌套子代理nested sub-agents每层可以在自己上下文填满之前把更深的工作委托给新的窗口——这正是 ruflo 最深的编排者ruflo-goals:dossier-investigator、ruflo-sparc:sparc-orchestrator、v3-queen-coordinator此前遇到的瓶颈。nested-leaf就是这个模型中的最小工作单元树的底部。它不做任何派生只完成一项被分配的任务并返回结构化摘要。nested-leaf 模板的核心内容plugins/ruflo-agent/agents/nested-leaf.md的完整 frontmatter 如下--- name: nested-leaf description: Leaf-worker template for nested spawn trees — performs one focused task and returns a structured summary. Deliberately does NOT have the Task tool (least-privilege boundary) model: haiku tools: - Read - Grep - Glob - Bash ---注意三个关键点model: haiku叶子只做单一聚焦工作用轻量模型即可成本最低tools仅包含Read、Grep、Glob、Bash这是最小工具集足够读取、搜索和操作文件但没有Task没有任何Task工具这是整个模板的设计灵魂也是与编排者模板最本质的区别。叶子的三条行为准则模板正文明确了叶子的行为边界只做一项被分配的任务。父级用Task派生你时只给一个单一、有边界的任务你只做这件事。不做探索式展开。如果工作本身需要扇出父级应该派生多个叶子而不是让一个叶子自己再扇出。返回结构化摘要而非完整对话记录约 150–300 tokens。嵌套的全部意义在于保持父级上下文干净——如果返回大段散文这次派生就是浪费。强制的返回结构LEAF_RESULT模板规定叶子必须返回如下形状LEAF_RESULT task: verbatim task your parent gave you status: success | partial | failed result: the actual answer/output, concise evidence: - file:line or command:output notes: one line max — anything the parent needs to know that isnt in result各字段的语义字段含义说明task父级给的原样任务文本便于父级与摘要对应避免歧义status执行状态三选一success/partial/failedresult实际答案/产出要求简洁evidence证据列表必须是file:line或command:output形式可验证notes附加说明最多一行放 result 之外父级必须知道的信息这个形状与nested-coordinator中每个子节点应返回约 200 tokens 的结构化摘要而不是工具调用日志的要求完全一致——结构化摘要就是嵌套通信的最小协议。为什么叶子不能有 Task 工具模板给出了三层理由这也是 ADR-147 P1 的核心决策1. 成本归因会被破坏在 Claude Code 2.1.169 中嵌套生成的运行时门控是hasTaskTool它在派生时刻根据父级的工具列表逐次计算。如果父级把Task传给了你你就会继承它。一旦树中的叶子偷偷派生AgentDB 里会出现看似扁平的派生日志、实际是嵌套的真实树——每份成本报告都会少算。2. 深度预算被无意识地消耗Tier-1 叶子只是想查一下就悄悄派生会静默消耗父级根本没有预算的层级。嵌套深度是有限资源Anthropic API 5 层ruflo 默认 4 层必须被有意使用。3. 混淆代理confused-deputy风险按照 ADR-144 授权传播每次派生都携带父级的AuthScope。叶子如果能派生就可能以原始主体从未授权的方式延长作用域链。ADR-144 规定作用域是单调递减的每一跳只能减少工具/服务器绝不能增加。叶子再派生意味着作用域链条上多了一环不可控的传播。因此模板明确规定如果叶子真的需要派生不要自己派生而是带着followups说明返回给父级——父级拥有Task工具由它决定是否派生后续任务。源码级的门控证据ADR-147 对 2.1.169 二进制的实证分析见 v3/docs/adr/ADR-147-nested-subagent-depth-integration.md确认了以下事实运行时门控是布尔值hasTaskTool从父级工具列表在派生时刻计算不是深度计数器也不是环境变量探测实验显示即使 YAML 声明了tools: [Task, Read, Grep, Glob, TodoWrite, Bash]6 个工具派生子代理实际只继承Read, Grep, Glob, Bash这 4 个——Task和TodoWrite被运行时剥离且在--permission-mode bypassPermissions、--allowedTools显式授权等各种模式下行为一致结论是YAML 的tools:字段确实被加载器接受并传播恰好 4/6 生效Task被剥离属于硬编码或服务端 denylist。这意味着当 denylist 解除时ruflo 的 agent 文件无需任何代码改动即可激活嵌套。这从底层印证了nested-leaf只声明Read / Grep / Glob / Bash的写法是声明式正确的——叶子模板从一开始就按最小权限设计与运行时的实际行为一致。深度预算与防护嵌套体系如何约束叶子嵌套体系有一套完整的深度预算机制详见 nested-subagents SKILL来源上限Anthropic API5 层2026-06-09 宣布ruflo 默认pre-task钩子4 层——保留一层余量可在claude-flow.config.json中配置严格模式环境变量CLAUDE_FLOW_STRICT_NESTINGtrue强制执行 ruflo 上限当达到上限时pre-task钩子返回类型化的NESTING_DEPTH_EXCEEDED错误payload 中携带完整链父级可据此决定是汇总、移交还是中止。这个守卫正是 ADR-147 P3 的设计默认 4 层比 Anthropic 的 5 层少一层保证 ruflo 的拒绝先于 API 的拒绝触发且错误信息更清晰。叶子作为第 N 层时其自身深度已由整条链决定它不需要、也不应该感知深度——这是父级nested-coordinator通过current_depthN传参管理的。何时使用 / 何时不使用模板自身给出了明确的使用边界适用场景编写一个应当位于树底部的新专家 agent以本模板为起点把nested-leaf改名为你的专家名称需要在一个没有编排职责的 agent 中显式强制最小权限。不适用场景agent 需要协调子任务——改用nested-coordinatoragent 由人类用户顶层直接调用而非由父 agent 派生——改用普通平铺 agent 定义如coder、tester等。与编排者模板的配合整棵生成树的形状nested-leaf不是孤立文件它属于plugins/ruflo-agent/agents/下完整的一套 9 个 agent 模板编排者拥有Task负责派生nested-coordinator.md、nested-queen.md、nested-queen-researcher.md、nested-queen-reviewer.md、nested-researcher.md、nested-reviewer.md叶子无Task只做事nested-leaf.md、nested-queen-leaf.md另有独立专家模板wasm-specialist.md编排者的代表 nested-coordinator 的 frontmatter 是--- name: nested-coordinator description: Orchestrator that spawns nested sub-agents (up to depth5) via Claude Codes native Task tool — for deep delegation where context isolation matters more than throughput model: sonnet tools: - Task - Read - Grep - Glob - TodoWrite - Bash ---两者对比一目了然维度nested-coordinatornested-leaf角色编排者树的中间/顶部叶子树的底部模型sonnethaiku是否拥有Task✅ 是❌ 否额外工具TodoWrite先规划树再派生无工作方式分解 → 规划 → 派生 → 汇总执行单个任务 → 返回结构化摘要在nested-coordinator的派生规范中叶子正是它必须遵守的禁止把Task传给叶子约束的另一面coder、tester、pii-detector、security-auditor、aidefence-guardian等叶子 agent 被明确禁止派生。如果树的叶子需要工作编排者直接通过它们的既有subagent_type派生而不是以防万一再派一个nested-coordinator。nested-leaf模板提到的可配对编排者还包括nested-researcher/nested-reviewer以及ruflo-core:coder/ruflo-core:tester见 plugins/ruflo-core/agents/coder.md这些同级叶子——它们拥有各自的专门提示词当角色匹配时优先使用它们只有没有现成叶子匹配时才使用本模板作为起点。实践路径如何把模板落成你的叶子 Agent基于上述设计落地一个叶子 agent 的推荐流程复制模板以plugins/ruflo-agent/agents/nested-leaf.md为起点复制为你的专家名例如pii-detector.md、test-runner.md改写 frontmatter更新name与descriptionmodel保持轻量haiku 级别工具列表保持Read / Grep / Glob / Bash绝不添加Task——这是最小权限边界的声明式保证改写正文职责保留只做一件事、不做探索、返回 LEAF_RESULT三条准则把task语义替换为你的专家职责接入编排树由nested-coordinator或其他声明了tools: [Task, ...]的编排者通过Task({subagent_type: 你的叶子名, ...})派生它遵守深度预算叶子本身不感知深度深度由父级通过current_depthN传递、由pre-task钩子与CLAUDE_FLOW_STRICT_NESTINGtrue强制约束。关联设计文档与验证手段ADR-147 嵌套子代理深度集成本模板的设计依据含四阶段滚动方案P1 仅编排者拥有Task→ P2 从parent_agent_id持久化生成树 → P3 深度感知守卫 → P4 文档与模板对齐以及 2.1.169 的实证分析ADR-144 授权传播AuthScope.delegationDepth与嵌套深度共享同一计数器解释叶子再派生会延长授权链的风险ADR-099 Dossier Investigator递归并行研究的教科书用例——树形递归深挖正是嵌套体系的目标场景验证脚本scripts/probe-nested-spawn-depth.mjs是递归深度探针运行输出见docs/probes/nested-spawn-depth-*.txt在每次 Claude Code CLI 升级后应首先重跑一旦返回CAP OBSERVED at depthN即意味着嵌套运行时已激活P2/P3 随之解锁插件烟测plugins/ruflo-agent/scripts/smoke.sh是插件契约12 项结构检查可验证 agent 文件声明正确。理解nested-leaf本质上就是理解嵌套子代理体系的安全底线树的深度是预算叶子的职责是执行而非派生最小权限是声明在 YAML 里的、而不是运行时祈祷来的。把这套模板放进你的编排树底部你的深层委托才能在上下文隔离、成本归因与授权安全三个维度上同时成立。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考