From c08c4ab141bf764dea51bb1f4c4e5545a05686b7 Mon Sep 17 00:00:00 2001
From: JOJO <1498581755@qq.com>
Date: Sat, 11 Jul 2026 20:40:27 +0800
Subject: [PATCH] =?UTF-8?q?docs(agentskills):=20=E6=9B=B4=E6=96=B0?=
 =?UTF-8?q?=E5=AD=90=E6=99=BA=E8=83=BD=E4=BD=93=E4=BD=BF=E7=94=A8=E6=8C=87?=
 =?UTF-8?q?=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 强调阻塞/后台模式的唯一判断标准是运行期间有没有别的事情要做
- 强调大范围搜索/调查前必须先自己进行浅层搜索
- 重写示例：国产开源智能体调研、程序 bug 定位
- 拆分后台模式场景：单个子智能体用阻塞，多个子智能体用后台并等待通知
---
 agentskills/sub-agent-guide/SKILL.md | 69 +++++++++++++++++-----------
 1 file changed, 42 insertions(+), 27 deletions(-)

diff --git a/agentskills/sub-agent-guide/SKILL.md b/agentskills/sub-agent-guide/SKILL.md
index c189750..f1d8d22 100644
--- a/agentskills/sub-agent-guide/SKILL.md
+++ b/agentskills/sub-agent-guide/SKILL.md
@@ -18,6 +18,7 @@ description: 子智能体使用指南。创建子智能体之前必须阅读此
 **适合（推荐）：**
 - **项目初期探索**：快速梳理目录结构、模块职责、运行方式，形成初步认知
 - **占用大量上下文的网络搜索和信息收集**：竞品调研、资料汇总、文档整理、新闻/资料比对
+  - **重要**：进行大范围搜索或调查前，必须先自己进行一次浅层搜索/调查，摸清关键词、主要来源和任务边界，再创建子智能体并给出精确指导。
 - **程序测试与验证**：执行测试命令、收集日志、汇总失败用例与错误模式
 - **并行独立的文档/分析任务**：生成说明文档、运行报告、排查清单
 
@@ -41,19 +42,19 @@ description: 子智能体使用指南。创建子智能体之前必须阅读此
 **好的示例：**
 
 ```
-# 信息搜集任务
-分析项目的前后端认证与鉴权实现：
-1. 查找所有与认证相关的代码文件（login, auth, jwt, session 等关键词）
-2. 分析前端如何存储和传递认证信息
-3. 分析后端如何验证和管理用户权限
-4. 整理成一份技术文档（auth_analysis.md），包含流程图和代码位置
+# 代码定位任务
+用户反馈了一个程序 bug：登录时偶尔报 500 错误。
+1. 先自己阅读项目结构，确认技术栈和登录相关模块位置
+2. 复现或定位错误触发条件，理解问题表现
+3. 创建子智能体：在 src/auth/、src/middleware/、src/api/login/ 等目录中查找可能导致 500 的代码路径
+4. 子智能体交付可疑文件列表和代码位置，生成 bug_location.md
 
 # 网络调研任务
-搜索并整理英伟达2025年的财报信息：
-1. 搜索英伟达2025年Q1-Q4财报
-2. 提取关键财务数据（营收、利润、增长率）
-3. 分析主要业务板块表现
-4. 生成结构化报告（nvidia_2025_report.md）
+用户要求调查国产开源智能体功能：
+1. 先自己进行一次浅层搜索，列出当前主要的国产开源智能体（如 AgentScope、DB-GPT、ModelScope-Agent 等）
+2. 根据初步结果，为每个候选智能体创建独立的子智能体，分别调研其功能特性、架构设计、适用场景
+3. 每个子智能体生成独立报告
+4. 最后由你整合对比，生成 overall_comparison.md
 
 # 系统信息收集
 收集当前计算机的硬件和系统信息：
@@ -126,9 +127,8 @@ create_sub_agent(
 - 你只需在收到通知后直接查看交付目录即可，系统会把所有必需信息一并带上。
 
 **何时使用：**
-- ✅ 耗时任务（预计 > 1 分钟）
-- ✅ 多个并行任务
-- ✅ 你有其他工作可以先做（回答用户问题、处理其他任务）
+- ✅ 需要同时创建多个子智能体
+- ✅ 创建后你有其他工作可以先做（回答用户问题、处理其他任务）
 
 **后台模式下你应该做什么：**
 
@@ -149,15 +149,25 @@ create_sub_agent(agent_id=2, task="...", run_in_background=true, ...)
 # 子智能体完成时会自动插入一条 system 消息通知你
 ```
 
-**情况 B：运行子智能体期间不需要做别的事情**
+**情况 B：运行子智能体期间不需要做别的事情，且只需要一个子智能体**
 ```python
-create_sub_agent(agent_id=1, task="大规模日志分析", run_in_background=true, timeout_seconds=1800)
+# 只有单个子智能体，且期间没有其他工作，直接使用阻塞模式
+create_sub_agent(agent_id=1, task="大规模日志分析", run_in_background=false, timeout_seconds=1800)
+
+# 等待工具返回后，直接读取交付目录处理结果
+```
+
+**情况 C：运行子智能体期间不需要做别的事情，但需要同时创建多个子智能体**
+```python
+# 多个子智能体同时运行，即使自己暂时没事做，也全部使用后台模式
+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, ...)
 
 # 告诉用户预计时间
-"我已启动子智能体进行日志分析，这个任务比较耗时，预计需要20-30分钟。系统会在完成后自动通知我，届时我会立即处理结果并回复你。"
+"我已启动2个子智能体并行分析认证与鉴权实现，预计需要10-15分钟。系统会在完成后自动通知我，届时我会立即整合结果并回复你。"
 
 # 然后停止工作和输出，等待系统通知
-# 子智能体运行完成后，系统会自动发送一条 user 消息通知你
+# 每个子智能体完成后，系统都会自动发送一条 user 消息通知你
 ```
 
 **重要提示：**
@@ -171,13 +181,15 @@ create_sub_agent(agent_id=1, task="大规模日志分析", run_in_background=tru
 ```
 任务预计耗时 < 1 分钟？
 ├─ 是 → 使用阻塞模式（run_in_background=false）
-└─ 否 → 有多个并行任务？
-    ├─ 是 → 使用后台模式（run_in_background=true）
-    └─ 否 → 有其他工作可以先做？
-        ├─ 是 → 使用后台模式
-        └─ 否 → 使用阻塞模式
+└─ 否 → 需要同时创建多个子智能体？
+    ├─ 是 → 使用后台模式（run_in_background=true），然后停止输出等待系统通知
+    └─ 否 → 创建后你有没有其他工作可以先做？
+        ├─ 是 → 使用后台模式（run_in_background=true），继续处理其他工作
+        └─ 否 → 使用阻塞模式（run_in_background=false）
 ```
 
+> **核心判断标准**：选择阻塞模式还是后台模式，**唯一标准是创建子智能体后你自己还有没有别的事情要做**，和子智能体本身被用来做什么任务无关。不要因为任务是“搜索”就一定用后台，也不要因为任务是“分析”就一定用阻塞。
+
 ## 并行执行模式
 
 创建多个子智能体时，确保它们的任务**完全独立**：
@@ -190,9 +202,12 @@ create_sub_agent(agent_id=2, task="生成模块 B 的文档", deliverables_dir="
 # 然后你可以继续做其他事情，或者停止输出等待通知
 
 # ✅ 好的并行：信息搜集
-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, ...)
-# 等系统自动通知两个都完成后，你再对比整合
+# 先自己浅层搜索，列出 3-5 个国产开源智能体
+# 然后为每个智能体创建独立的子智能体并行调研
+create_sub_agent(agent_id=1, task="调研 AgentScope 的功能特性、架构和适用场景", deliverables_dir="research/agentscope", run_in_background=true, ...)
+create_sub_agent(agent_id=2, task="调研 DB-GPT 的功能特性、架构和适用场景", deliverables_dir="research/dbgpt", run_in_background=true, ...)
+create_sub_agent(agent_id=3, task="调研 ModelScope-Agent 的功能特性、架构和适用场景", deliverables_dir="research/modelscope_agent", run_in_background=true, ...)
+# 等系统自动通知全部完成后，你再整合生成对比报告
 
 # ✅ 好的并行：系统调研
 create_sub_agent(agent_id=1, task="分析前端认证实现", deliverables_dir="analysis/frontend_auth", run_in_background=true, ...)
@@ -331,7 +346,7 @@ else:
 子智能体的本质是**并行执行完全独立的任务**。
 
 **关键要点：**
-1. **执行模式选择**：快速任务用阻塞模式，耗时任务或并行任务用后台模式
+1. **执行模式选择**：运行子智能体期间没有别的事情要做且只创建一个子智能体 → 阻塞模式；需要同时创建多个子智能体，或期间有其他工作可以先做 → 后台模式
 2. **后台模式下**：创建后继续工作或停止输出，系统会自动通知完成
 3. **任务独立性**：子智能体之间无法通信，确保任务完全独立
 4. **任务描述**：子智能体看不到对话历史，task 参数必须包含所有信息