diff --git a/agentskills/sub-agent-guide/SKILL.md b/agentskills/sub-agent-guide/SKILL.md index ca1c9a14..350a8725 100644 --- a/agentskills/sub-agent-guide/SKILL.md +++ b/agentskills/sub-agent-guide/SKILL.md @@ -1,6 +1,6 @@ --- name: sub-agent-guide -description: 子智能体使用指南。创建子智能体之前必须阅读此技能。子智能体仅用于并行处理独立的“非代码编写”任务(如项目初步探索、网络搜索与信息收集、程序测试执行)。关键限制:子智能体之间无法通信,看不到主对话历史。严格禁止将子智能体用于项目代码编写、代码修改、重构或实现功能。**如果运行模式为多智能体模式,禁止阅读并参考该 skill。** +description: 子智能体使用指南。创建子智能体之前必须阅读此技能。子智能体用于并行处理独立任务(项目探索、网络搜索与信息收集、程序测试执行等)。代码修改视情况而定:一般性代码编写由主智能体完成;大规模、重复性高、边界与任务明确的代码修改可由子智能体承担,但必须明确工作范围防止冲突,最终由主智能体验证。关键限制:子智能体之间无法通信,看不到主对话历史。**如果运行模式为多智能体模式,禁止阅读并参考该 skill。** --- # 子智能体使用指南 @@ -11,7 +11,19 @@ description: 子智能体使用指南。创建子智能体之前必须阅读此 子智能体拥有完整工具能力,但与主智能体和其他子智能体完全隔离。它们看不到你的对话历史,无法互相通信,只能通过文件系统共享信息。 -**硬性限制:子智能体严格禁止用于项目代码编写/修改。** +**代码修改纪律(视情况而定)** + +子智能体**不是**代码编写的主力——一般性代码编写、重构、功能实现仍由主智能体承担。但当任务**同时满足**以下条件时,**允许子智能体修改核心代码**: + +1. **大规模、重复性高**:改动量大或模式重复(如批量迁移、统一错误处理、机械式重构),交给子智能体执行效率远高于主智能体逐文件处理 +2. **边界与任务明确**:任务描述清楚指定要操作的文件/目录范围,无歧义 +3. **范围防冲突**:与主智能体、其他子智能体的工作范围不重叠 +4. **最终验证**:子智能体的智能程度取决于用户配置的模型,其改动**必须由主智能体审查验证**(读 diff / 跑测试),不能直接信以为真 + +**禁止场景(不可放宽):** +- 修改任务描述明确范围之外的文件 +- 影响面不可控的架构级改动、跨模块协调 +- 子智能体无法自主验证正确性的改动 ## 何时使用 @@ -21,13 +33,14 @@ description: 子智能体使用指南。创建子智能体之前必须阅读此 - **重要**:进行大范围搜索或调查前,必须先自己进行一次浅层搜索/调查,摸清关键词、主要来源和任务边界,再创建子智能体并给出精确指导。 - **程序测试与验证**:执行测试命令、收集日志、汇总失败用例与错误模式 - **并行独立的文档/分析任务**:生成说明文档、运行报告、排查清单 +- **大规模、重复性高的代码修改**:批量迁移、统一错误处理、机械式重构等边界明确的任务(任务描述必须精确指定文件/目录范围,完成后审查验证改动) **不适合:** - 任务之间需要频繁协调(子智能体无法互相通信) - 简单快速的任务(创建子智能体有开销) - 需要你参与决策的任务(子智能体是自主运行的) -- 任何项目代码编写、代码修改、代码重构、功能实现任务(必须由主智能体处理) -- 任何会直接改动项目源码的开发工作 +- 边界模糊、影响面不可控的代码修改(必须先由主智能体划定范围) +- 需要跨模块协调或反复验证的架构级改动 ## 任务描述的艺术 @@ -71,17 +84,19 @@ description: 子智能体使用指南。创建子智能体之前必须阅读此 ## 交付目录设计 -`deliverables_dir` 必须是**不存在的新目录**,子智能体会把所有成果放在这里。 +`deliverables_dir` 可以**留空**:留空时系统自动在 `.astrion/sub_agent_results/` 下创建(如 `agent_1`,撞名自动加后缀),并把最终路径作为工具结果返回。该目录是运行时内部目录,不进入 git 版本控制。 -**命名建议:** +显式传入时:必须是相对项目根目录的**不存在的新目录**,已存在会报错。 + +**命名建议**(显式传入时,用清晰描述任务的相对路径): ``` -sub_agent_results/task_description/ # 清晰描述任务 -sub_agent_results/module_a_docs/ # 按模块组织 -sub_agent_results/test_auth_report/ # 按测试/报告组织 +research/python312/ # 清晰描述任务 +docs/module_a/ # 按模块组织 +analysis/frontend_auth/ # 按功能分析组织 ``` **避免:** -- ❌ 使用已存在的目录(会报错) +- ❌ 传入已存在的目录(会报错) - ❌ 使用绝对路径(必须是相对于项目根目录的相对路径) - ❌ 使用通用名称如 "output" "result"(多个子智能体会冲突) @@ -251,7 +266,7 @@ create_sub_agent(task=""" - 梳理认证相关入口、调用链和关键配置 - 运行现有测试并记录失败项 - 生成诊断报告(auth_diagnosis.md) -- 不允许修改任何项目源码 +- 本任务为只读诊断,不修改任何文件 """) ``` @@ -286,7 +301,7 @@ create_sub_agent(agent_id=1, ...) # 失败了 result = create_sub_agent(agent_id=1, run_in_background=false, ...) if result["success"]: - # 读取交付目录中的文件 + # 读取交付目录中的文件(显式传入或自动创建的路径都在这里) deliverables = result["deliverables_dir"] # 处理生成的文件... else: diff --git a/prompts/sub_agent/system.txt b/prompts/sub_agent/system.txt index 48bd81b9..0f2dddca 100644 --- a/prompts/sub_agent/system.txt +++ b/prompts/sub_agent/system.txt @@ -24,6 +24,13 @@ - 你的工作范围应该与其他子智能体不重叠 - 不要修改任务描述之外的文件 +## 代码修改纪律(视情况而定) +- 你有完整的读写工具,主智能体可能分配给你修改核心代码的任务(典型:大规模、重复性高、边界明确的工作) +- 允许修改代码的前提:任务描述明确划定了文件/目录范围,且改动面在该范围之内 +- 修改前先阅读相关代码,理解上下文再动手;只做任务要求的改动,不顺手扩大改动面 +- 修改完成后,在 finish_task 的 summary 中列出改动清单(文件、改动点),由主智能体审查验证 +- 任务未指定代码修改时,保持只读分析,不要擅自改动代码 + ## 效率性 - 直接开始工作,不要过度解释 - 合理使用工具,避免重复操作