---
name: sub-agent-guide
description: 子智能体使用指南。创建子智能体之前必须阅读此技能。子智能体仅用于并行处理独立的“非代码编写”任务（如项目初步探索、网络搜索与信息收集、程序测试执行）。关键限制：子智能体之间无法通信，看不到主对话历史。严格禁止将子智能体用于项目代码编写、代码修改、重构或实现功能。
---

# 子智能体使用指南

## 核心原则

**一个子智能体 = 一个完整的独立任务**

子智能体拥有完整工具能力，但与主智能体和其他子智能体完全隔离。它们看不到你的对话历史，无法互相通信，只能通过文件系统共享信息。

**硬性限制：子智能体严格禁止用于项目代码编写/修改。**

## 何时使用

**适合（推荐）：**
- **项目初期探索**：快速梳理目录结构、模块职责、运行方式，形成初步认知
- **占用大量上下文的网络搜索和信息收集**：竞品调研、资料汇总、文档整理、新闻/资料比对
- **程序测试与验证**：执行测试命令、收集日志、汇总失败用例与错误模式
- **并行独立的文档/分析任务**：生成说明文档、运行报告、排查清单

**不适合：**
- 任务之间需要频繁协调（子智能体无法互相通信）
- 简单快速的任务（创建子智能体有开销）
- 需要你参与决策的任务（子智能体是自主运行的）
- 任何项目代码编写、代码修改、代码重构、功能实现任务（必须由主智能体处理）
- 任何会直接改动项目源码的开发工作

## 任务描述的艺术

子智能体看不到你的对话历史，task 参数是它收到的唯一指令。

**关键要素：**
1. **明确的目标** - 要做什么，产出什么
2. **清晰的范围** - 操作哪些文件/目录
3. **具体的交付物** - 生成什么文件，放在哪里
4. **完成标准** - 什么算完成

**好的示例：**

```
# 信息搜集任务
分析项目的前后端认证与鉴权实现：
1. 查找所有与认证相关的代码文件（login, auth, jwt, session 等关键词）
2. 分析前端如何存储和传递认证信息
3. 分析后端如何验证和管理用户权限
4. 整理成一份技术文档（auth_analysis.md），包含流程图和代码位置

# 网络调研任务
搜索并整理英伟达2025年的财报信息：
1. 搜索英伟达2025年Q1-Q4财报
2. 提取关键财务数据（营收、利润、增长率）
3. 分析主要业务板块表现
4. 生成结构化报告（nvidia_2025_report.md）

# 系统信息收集
收集当前计算机的硬件和系统信息：
1. CPU 架构、型号、核心数
2. GPU 型号、显存、驱动版本
3. 内存大小、系统版本
4. 保存为 system_info.md
```

**避免：**
- ❌ "帮我分析一下认证代码" - 太模糊
- ❌ "如果发现问题请告诉我" - 子智能体无法与你交互
- ❌ "先做 A，然后等我确认再做 B" - 子智能体是一次性执行的

## 交付目录设计

`deliverables_dir` 必须是**不存在的新目录**，子智能体会把所有成果放在这里。

**命名建议：**
```
sub_agent_results/task_description/  # 清晰描述任务
sub_agent_results/module_a_docs/     # 按模块组织
sub_agent_results/test_auth_report/  # 按测试/报告组织
```

**避免：**
- ❌ 使用已存在的目录（会报错）
- ❌ 使用绝对路径（必须是相对于项目根目录的相对路径）
- ❌ 使用通用名称如 "output" "result"（多个子智能体会冲突）

## 执行模式：阻塞 vs 后台

子智能体有两种执行模式，通过 `run_in_background` 参数控制：

### 阻塞模式（run_in_background=false，默认）

**行为：**
- 创建子智能体后，你会**停止输出**，等待它完成
- 完成后结果直接在工具返回中给出，继续你的工作
- 不会有额外的系统通知消息

**何时使用：**
- ✅ 快速任务（预计 < 1 分钟）
- ✅ 需要立即使用结果的任务
- ✅ 单个子智能体，没有其他并行工作

**示例：**
```python
# 快速信息搜集，立即需要结果
create_sub_agent(
    agent_id=1,
    summary="搜索 Python 3.12 新特性",
    task="搜索并整理 Python 3.12 的主要新特性，生成 python312.md",
    deliverables_dir="research/python312",
    run_in_background=false,  # 阻塞等待
    timeout_seconds=300
)
# 工具返回后，你可以立即读取 research/python312/python312.md
```

### 后台模式（run_in_background=true）

**行为：**
- 创建子智能体后，工具**立即返回**，你可以继续做其他事情
- 子智能体在后台运行，完成后系统会**自动插入一条 user 消息**通知你
- 你会在对话中看到类似："这是一句系统自动发送的user消息，用于通知你子智能体已经运行完成..."

**完成通知机制说明：**
- 后台子智能体完成的通知是系统自动插入的 user/system 消息，不依赖手动调用 `wait_sub_agent` 或其它轮询接口。
- 你只需在收到通知后直接查看交付目录即可，系统会把所有必需信息一并带上。

**何时使用：**
- ✅ 耗时任务（预计 > 1 分钟）
- ✅ 多个并行任务
- ✅ 你有其他工作可以先做（回答用户问题、处理其他任务）

**后台模式下你应该做什么：**

**情况 A：运行子智能体期间需要做别的事情**
```python
# 创建多个后台任务
create_sub_agent(agent_id=1, task="...", run_in_background=true, ...)
create_sub_agent(agent_id=2, task="...", run_in_background=true, ...)

# 立即告诉用户并继续其他工作
"我已经启动了2个子智能体在后台并行工作，预计需要10-15分钟。在等待期间，我可以先帮你处理其他事情。"

# 然后你可以：
# - 回答用户的其他问题
# - 处理其他任务
# - 阅读代码、分析问题
# - 运行其他工具
# 子智能体完成时会自动插入一条 system 消息通知你
```

**情况 B：运行子智能体期间不需要做别的事情**
```python
create_sub_agent(agent_id=1, task="大规模日志分析", run_in_background=true, timeout_seconds=1800)

# 告诉用户预计时间
"我已启动子智能体进行日志分析，这个任务比较耗时，预计需要20-30分钟。系统会在完成后自动通知我，届时我会立即处理结果并回复你。"

# 然后停止工作和输出，等待系统通知
# 子智能体运行完成后，系统会自动发送一条 user 消息通知你
```

**重要提示：**
- 系统会自动处理通知，你只需要在收到通知消息后处理结果即可
- 如果你正在执行工具调用，系统会延迟通知，避免打断你的工作流
- 通知类型取决于你是否继续工作：继续工作时收到 system 消息，停止输出时收到 user 消息
- 后台完成由上述系统通知负责，不要再依赖 `wait_sub_agent` 或类似的手动等待流，系统会在能插入消息时自动通知你。

### 模式选择决策树

```
任务预计耗时 < 1 分钟？
├─ 是 → 使用阻塞模式（run_in_background=false）
└─ 否 → 有多个并行任务？
    ├─ 是 → 使用后台模式（run_in_background=true）
    └─ 否 → 有其他工作可以先做？
        ├─ 是 → 使用后台模式
        └─ 否 → 使用阻塞模式
```

## 并行执行模式

创建多个子智能体时，确保它们的任务**完全独立**：

```python
# ✅ 好的并行：各自独立，使用后台模式
create_sub_agent(agent_id=1, task="生成模块 A 的文档", deliverables_dir="docs/module_a", run_in_background=true, ...)
create_sub_agent(agent_id=2, task="生成模块 B 的文档", deliverables_dir="docs/module_b", run_in_background=true, ...)
# 告诉用户："已启动2个子智能体并行生成文档，预计10分钟完成。系统会在完成后自动通知我。"
# 然后你可以继续做其他事情，或者停止输出等待通知

# ✅ 好的并行：信息搜集
create_sub_agent(agent_id=1, task="搜索并整理 Claude 最新模型信息", deliverables_dir="research/claude", run_in_background=true, ...)
create_sub_agent(agent_id=2, task="搜索并整理 ChatGPT 最新模型信息", deliverables_dir="research/chatgpt", run_in_background=true, ...)
# 等系统自动通知两个都完成后，你再对比整合

# ✅ 好的并行：系统调研
create_sub_agent(agent_id=1, task="分析前端认证实现", deliverables_dir="analysis/frontend_auth", run_in_background=true, ...)
create_sub_agent(agent_id=2, task="分析后端鉴权实现", deliverables_dir="analysis/backend_auth", run_in_background=true, ...)
# 系统会在每个完成时发送通知，你可以逐个处理或等全部完成
```

```python
# ❌ 不好的并行：需要协作
create_sub_agent(agent_id=1, task="收集日志", ...)
create_sub_agent(agent_id=2, task="基于子智能体1的日志结论生成报告", ...)  # 依赖子智能体1的结果
# 子智能体2不知道子智能体1什么时候完成，无法协调
```

## 常见陷阱

### 1. 期望子智能体协作

❌ **错误：**
```python
create_sub_agent(agent_id=1, task="收集 A 类日志并通知子智能体2")
create_sub_agent(agent_id=2, task="等待子智能体1完成，然后汇总 B 类报告")
```

子智能体之间无法通信。如果任务有依赖，应该：
- 方案1：顺序执行（等第一个完成后再创建第二个）
- 方案2：让一个子智能体完成整个流程

### 2. 忘记子智能体看不到对话历史

❌ **错误：**
```python
# 你在对话中说："我们要排查认证流程问题"
create_sub_agent(task="按照我们讨论的方案排查认证流程")
```

✅ **正确：**
```python
create_sub_agent(task="""
排查 src/auth/ 目录认证流程：
- 梳理认证相关入口、调用链和关键配置
- 运行现有测试并记录失败项
- 生成诊断报告（auth_diagnosis.md）
- 不允许修改任何项目源码
""")
```

### 3. 超时时间设置不当

子智能体超时后会被强制终止，已完成的工作可能丢失。

**经验值：**
- 文档生成：600-900 秒
- 信息搜集/网络调研：900-1800 秒
- 大规模分析：1800-3600 秒

宁可设置得长一些，也不要让子智能体因超时而前功尽弃。

### 4. agent_id 重复使用

同一对话中，每个 agent_id 只能使用一次。如果子智能体失败需要重试，必须使用新的 agent_id。

```python
create_sub_agent(agent_id=1, ...)  # 失败了
# ❌ create_sub_agent(agent_id=1, ...)  # 会报错
# ✅ create_sub_agent(agent_id=2, ...)  # 使用新的 ID
```

## 检查结果

### 阻塞模式下

工具返回中直接包含结果：

```python
result = create_sub_agent(agent_id=1, run_in_background=false, ...)

if result["success"]:
    # 读取交付目录中的文件
    deliverables = result["deliverables_dir"]
    # 处理生成的文件...
else:
    # 检查失败原因
    if result["status"] == "timeout":
        # 考虑增加 timeout_seconds 重试
    else:
        # 查看 result["message"] 了解失败原因
```

### 后台模式下

等待系统自动插入的通知消息：

**如果你继续工作**，会收到 system 消息：
```
✅ 子智能体1 任务摘要：搜索 Python 3.12 新特性 已完成。

调用了15次
阅读了8次文件
编辑了2次文件
搜索了3次内容
查看了5个网页
运行了2个指令

运行了245秒

已搜索并整理 Python 3.12 的主要新特性...

交付目录：research/python312
```

**如果你停止输出**，会收到 user 消息：
```
这是一句系统自动发送的user消息，用于通知你子智能体已经运行完成

子智能体1 (搜索 Python 3.12 新特性) 已完成任务。

已搜索并整理 Python 3.12 的主要新特性...

运行了245秒

交付目录：research/python312
```

收到通知后，读取交付目录中的文件并处理结果。

## thinking_mode 选择

- `fast`：常规任务（文档生成、信息搜集、数据分析）
- `thinking`：需要深度推理的任务（架构设计、复杂算法分析、安全审计）

大多数情况下使用 `fast` 即可。

## 总结

子智能体的本质是**并行执行完全独立的任务**。

**关键要点：**
1. **执行模式选择**：快速任务用阻塞模式，耗时任务或并行任务用后台模式
2. **后台模式下**：创建后继续工作或停止输出，系统会自动通知完成
3. **任务独立性**：子智能体之间无法通信，确保任务完全独立
4. **任务描述**：子智能体看不到对话历史，task 参数必须包含所有信息

如果你发现自己在设计子智能体之间的协作流程，那可能不应该使用子智能体，而应该自己顺序执行这些步骤。