企业官网建设流程全解析

yome-agent 的子代理（Subagent）机制，是让主 Agent 在对话过程中自动"派生"出独立工作的子 Agent，把复杂任务拆解、并行调度、隔离执行。本文将带你快速看懂它的核心设计：Agent 工具注册、三级代理加载、隔离执行循环、防递归安全四大机制，并给出实践建议。

一、什么是 yome-agent 的子代理？

传统聊天式 AI 只有一个"大脑"，所有任务挤在同一段上下文里。yome-agent 的思路不同：主 Agent 拥有一个名为Agent的工具，当任务足够复杂（比如"调研整个代码库并总结架构"），主 Agent 会调用这个工具，派生一个带着独立对话历史的子 Agent 去干活，干完只把结论汇报回来。

它带来三个直接收益：

• ✅上下文隔离：子代理的探索过程不污染主会话，主 Agent 的 token 不被浪费
• ✅并行调度：一条消息里可以派发多个子代理同时工作
• ✅权限收敛：每个子代理可以配置自己的工具白名单、模型和最大轮数

核心实现集中在 src/subagent/ 目录，入口导出见 index.ts。

二、机制拆解 1：Agent 工具如何被注册进主循环

子代理不靠魔法触发，而是一个标准工具。在 src/agent.ts 的构造函数里，主 Agent 初始化时会执行registerTool(createAgentTool(config))，把Agent工具注册进工具表——从这一刻起，LLM 的工具列表里就多了一项"派生子代理"的能力。

createAgentTool定义在 src/subagent/agentTool.ts，它做三件事：

1. 动态生成工具描述：遍历当前所有可用代理，把每个代理的agentType、whenToUse（适用场景）、可用工具拼进描述里，让 LLM 自己判断"该不该派、派谁去"
2. 校验入参：只要求description（3~5 词的短描述）和prompt（完整任务说明）两个字段，subagent_type可选，缺省使用general-purpose
3. 执行派发：命中代理定义后调用runAgent()跑完整个子代理循环，最后把结果和 token 用量格式化返回

工具描述里还写入了"何时不该用"的约束（读单个文件、搜一个模式这种 1~2 步的事主 Agent 自己做），避免子代理被滥用。

三、机制拆解 2：子代理从哪里来？三级加载 + 优先级覆盖

子代理的定义是一个AgentDefinition（见 src/subagent/types.ts），包含：类型名、适用场景描述、工具白/黑名单、可预载的 skills、指定模型、最大轮数。它们来自三个地方，加载逻辑在 src/subagent/loadAgents.ts：

同名代理按项目 > 用户 > 内置的顺序覆盖（loadAgents.ts），这和你熟悉的其他工具链"就近配置优先"的思路一致。

自定义代理就是一个带 frontmatter 的 Markdown 文件，例如项目里放一个.yome/agents/reviewer.md：

--- name: reviewer description: 代码审查专家，只读不写 tools: [Read, Grep, Glob] model: your-fast-model maxTurns: 10 --- 你是一名严格的代码审查员……（正文即该子代理的 system prompt）

frontmatter 解析器在 parseFrontmatter，正文部分自动成为该子代理的系统提示词。注意：name 和 description 缺一不可，description 是主 Agent 决定"何时派它"的关键依据，写清楚比写花哨更重要。

内置的general-purpose代理定义在 src/subagent/builtinAgents.ts，拥有全部工具，适合多步调研类任务。

四、机制拆解 3：子代理如何被隔离执行

真正的执行引擎是 src/subagent/runAgent.ts 中的runAgent()，一次子代理生命周期的流程：

1. 配置合并：若代理定义了model，就生成一份只改了模型的配置，实现"不同代理用不同模型"
2. 工具过滤：按代理的白名单/黑名单裁剪可用工具（下文详述）
3. 预载 skills：若代理声明了skills，会把对应技能提示词预先注入对话开头（runAgent.ts）
4. 独立消息历史：从零开始建一个messages数组，主会话的任何上下文都不会带过去——所以 prompt 必须写得详尽
5. 循环执行：每轮调用 LLM，若返回 tool_use 就执行工具、把结果回灌，直到 LLM 给出纯文本结论或达到maxTurns（默认30轮，见 runAgent.ts）
6. 收尾：从最后一条 assistant 消息提取最终文本，连同 input/output token 统计一起返回给主 Agent

主 Agent 拿到的结果长这样：Agent "xxx" completed. / Tokens: N in / M out / （子代理的结论文本），之后由主 Agent 负责向用户转述。

防递归：一个不起眼但关键的设计

resolveAgentTools 在组装子代理工具表时，第一步就是把Agent工具本身剔除。这意味着子代理没有"再派生子代理"的能力，从架构上杜绝了无限递归派生、token 爆炸的可能。这是子代理机制能安全并行调度的前提。

五、动手实践：管理你的子代理

命令行里管理开关

在 yome 交互界面输入/subagents（命令注册见 src/ui/App.tsx），会弹出终端内的选择器（AgentPicker.tsx），用方向键 + Enter 即可启用/禁用任意代理。禁用状态持久化在~/.yome/disabled.json（逻辑见 src/toggleState.ts），下次启动依然生效。

写好 prompt 的三个要点

子代理是"零上下文"启动的，agentTool.ts 的工具说明里明确强调了：

• 📝交代背景：你在做什么、已经知道了什么、要找什么
• 🎯明确产出：说清楚是"只调研"还是"可以改代码"
• ⚡并行派发：一条消息里发起多个Agent工具调用，即可同时跑多个子代理（如一个查代码、一个查文档）

什么时候该用 / 不该用

六、总结

yome-agent 的子代理机制可以浓缩为一句话："Agent 是一个工具"——主 Agent 通过标准的Agent工具派生独立上下文的子代理，用三级配置决定"派谁"，用工具过滤和默认 30 轮上限决定"能干什么"，用剔除递归工具保证"不会失控"。想深入了解，建议按顺序阅读：

• 工具注册与描述：src/subagent/agentTool.ts
• 执行循环核心：src/subagent/runAgent.ts
• 加载与优先级：src/subagent/loadAgents.ts
• 内置代理示例：src/subagent/builtinAgents.ts