diff --git a/agentskills/sub-agent-guide/SKILL.md b/agentskills/sub-agent-guide/SKILL.md index dbc75fd..d43fa71 100644 --- a/agentskills/sub-agent-guide/SKILL.md +++ b/agentskills/sub-agent-guide/SKILL.md @@ -81,27 +81,115 @@ sub_agent_results/refactor_auth/ # 按功能组织 - ❌ 使用绝对路径(必须是相对于项目根目录的相对路径) - ❌ 使用通用名称如 "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消息,用于通知你子智能体已经运行完成..." + +**何时使用:** +- ✅ 耗时任务(预计 > 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 消息 + +### 模式选择决策树 + +``` +任务预计耗时 < 1 分钟? +├─ 是 → 使用阻塞模式(run_in_background=false) +└─ 否 → 有多个并行任务? + ├─ 是 → 使用后台模式(run_in_background=true) + └─ 否 → 有其他工作可以先做? + ├─ 是 → 使用后台模式 + └─ 否 → 使用阻塞模式 +``` + ## 并行执行模式 创建多个子智能体时,确保它们的任务**完全独立**: ```python -# ✅ 好的并行:各自独立 -create_sub_agent(agent_id=1, task="生成模块 A 的文档", deliverables_dir="docs/module_a", ...) -create_sub_agent(agent_id=2, task="生成模块 B 的文档", deliverables_dir="docs/module_b", ...) +# ✅ 好的并行:各自独立,使用后台模式 +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", ...) -create_sub_agent(agent_id=2, task="搜索并整理 ChatGPT 最新模型信息", deliverables_dir="research/chatgpt", ...) -# 等两个都完成后,你再对比整合 +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", ...) -create_sub_agent(agent_id=2, task="分析后端鉴权实现", deliverables_dir="analysis/backend_auth", ...) - -# 等待所有完成 -wait_sub_agent(agent_id=1) -wait_sub_agent(agent_id=2) +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 @@ -167,10 +255,12 @@ create_sub_agent(agent_id=1, ...) # 失败了 ## 检查结果 -子智能体完成后,检查 `success` 字段和 `deliverables_dir`: +### 阻塞模式下 + +工具返回中直接包含结果: ```python -result = wait_sub_agent(agent_id=1) +result = create_sub_agent(agent_id=1, run_in_background=false, ...) if result["success"]: # 读取交付目录中的文件 @@ -182,9 +272,45 @@ else: # 考虑增加 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`:常规任务(文档生成、信息搜集、数据分析) @@ -194,4 +320,12 @@ else: ## 总结 -子智能体的本质是**并行执行完全独立的任务**。如果你发现自己在设计子智能体之间的协作流程,那可能不应该使用子智能体,而应该自己顺序执行这些步骤。 +子智能体的本质是**并行执行完全独立的任务**。 + +**关键要点:** +1. **执行模式选择**:快速任务用阻塞模式,耗时任务或并行任务用后台模式 +2. **后台模式下**:创建后继续工作或停止输出,系统会自动通知完成 +3. **任务独立性**:子智能体之间无法通信,确保任务完全独立 +4. **任务描述**:子智能体看不到对话历史,task 参数必须包含所有信息 + +如果你发现自己在设计子智能体之间的协作流程,那可能不应该使用子智能体,而应该自己顺序执行这些步骤。