# 子智能体工具指南

当你通过 `create_sub_agent`/`wait_sub_agent` 管理子智能体时，请遵循以下规则：

1. **何时创建**：当单个回复难以在时限内完成、需要长时间探索/编写大量文件或会阻塞主智能体上下文时，再考虑创建子智能体。特别是涉及大量信息搜集、网页提取、跨多篇资料的阅读与总结、需要输出结构化文件的任务，应该优先使用子智能体，避免主对话被海量搜索结果占满。子智能体适合“单一方向”的独立任务，比如按车企拆分调研、按章节拆分报告；不要让一个子智能体承担多个平行方向的需求。
2. **描述方式**：调用 `create_sub_agent` 前，先总结任务目标（summary）、详细分工（task），并指明交付目录（target_dir）以及需要一并提供的参考文件列表。任务描述要清晰、可执行，不要把问题交给子智能体自行理解。
3. **参考目录**：主智能体可将必要的文件列入 `reference_files`；这些文件会在子智能体的 `references/` 目录下以只读方式提供，适合提供需求文档、接口约束或已有实现片段。不要传递包含敏感信息或过于庞大的目录。
4. **交付目录要求**：子智能体只能在其 `deliverables/` 下输出成果，主智能体最终会把该目录复制到 `target_project_dir/子任务ID_deliverables`。交付目录必须包含：
   - `result.md`：用中文或中英双语写明任务完成情况、交付清单、风险与下一步建议。
   - 任务成果文件：按照主任务约定的路径/格式组织，必要时包含 README/使用说明。
5. **等待与跟进**：创建后使用 `wait_sub_agent` 轮询；如超时或失败，需要主动查看 `copied_path` 分析原因，再决定是否重试或人工补救。不要在子任务运行期间向其发送额外消息，它无法与主智能体实时通信。设置 `timeout_seconds` 时可参考：
   - 单/双次搜索即可完成的任务：180 秒；
   - 需要多轮搜索、整理多篇资料：300 秒；
   - 深度调研/多份长文总结：600 秒（上限依据配置）
6. **善后**：记录系统返回的 `system_message`，同步给用户；若交付不满足预期，可在主流程中补充说明或直接修改复制出的成果。

**拆分示例**  
- “调研比亚迪/吉利/奇瑞/长安/长城新能源品牌情况” → 建议为每家车企创建一个子智能体，各自总结销量与经营情况，主智能体负责合并。  
- “对 6 个 API 做差异分析” → 可按 API 或功能模块拆分，每个子智能体负责一组接口。  
- “阅读 20 篇行业报告并整理要点” → 可按主题或时间段划分，避免单个子智能体上下文爆炸。  
- “把 8 个用户反馈邮件整理成 FAQ” → 可按邮件批次或问题类型分配给不同子智能体，保证每份输出精简清晰。  
- “提取 3 份 PDF 报告的参数表并生成对比 Markdown” → 每个子智能体负责一份 PDF 的提取与结构化，再由主流程合并成总对比表。

牢记：主智能体与子智能体完全隔离，只能通过上述API交互。提供明确任务、参考和交付标准，才能让子智能体按预期产出可直接交付的结果。
