子智能体
子智能体是专门化的 AI 助手，负责处理 Qwen Code 中特定类型的任务。它们允许你将专注的工作委托给配置了特定任务提示、工具和行为的 AI 智能体。
什么是子智能体？
子智能体是独立的 AI 助手，具有以下特点：
- 专精于特定任务 - 每个子智能体都配置了针对特定工作类型的专注系统提示
- 拥有独立上下文 - 它们维护自己的对话历史，与你的主聊天分离
- 使用受控工具 - 你可以配置每个子智能体可以访问哪些工具
- 自主工作 - 一旦分配任务，它们会独立工作直到完成或失败
- 提供详细反馈 - 你可以实时查看它们的进度、工具使用情况和执行统计信息
主要优势
- 任务专业化：创建针对特定工作流（测试、文档、重构等）优化的智能体
- 上下文隔离：将专业工作与主对话分开
- 可重用性：在项目和会话之间保存和重用智能体配置
- 受控访问：限制每个智能体可以使用的工具，以确保安全性和专注性
- 进度可见性：通过实时进度更新监控智能体执行情况
子智能体工作原理
- 配置：你创建子智能体配置，定义其行为、工具和系统提示
- 委托：主 AI 可以自动将任务委托给适当的子智能体
- 执行：子智能体独立工作，使用其配置的工具完成任务
- 结果：它们将结果和执行摘要返回到主对话中
开始使用
快速开始
-
创建你的第一个 Subagent：
/agents create跟随引导向导创建一个专业化的代理。
-
管理现有代理：
/agents manage查看和管理你配置的 Subagents。
-
自动使用 Subagents：只需要求主 AI 执行与你的 Subagents 专业领域匹配的任务。AI 将自动委托适当的工作。
使用示例
用户："请为认证模块编写全面的测试"
AI：我将把这个任务委托给你的测试专家 Subagents。
[委托给 "testing-expert" Subagents]
[显示测试创建的实时进度]
[返回完成的测试文件和执行摘要]`管理
CLI 命令
子代理通过 /agents 斜杠命令及其子命令进行管理：
用法： /agents create。通过引导式步骤向导创建新的子代理。
用法： /agents manage。打开交互式管理对话框，用于查看和管理现有子代理。
存储位置
子代理以 Markdown 文件的形式存储在多个位置：
- 项目级别：
.qwen/agents/（优先级最高） - 用户级别：
~/.qwen/agents/（备用） - 扩展级别：由已安装的扩展提供
这允许你拥有特定于项目的代理、适用于所有项目的个人代理，以及提供专门功能的扩展代理。
扩展子代理
扩展可以提供自定义子代理，当启用扩展时这些子代理将变得可用。这些代理存储在扩展的 agents/ 目录中，并遵循与个人和项目代理相同的格式。
扩展子代理：
- 在启用扩展时自动发现
- 出现在
/agents manage对话框的“扩展代理”部分 - 无法直接编辑（改为编辑扩展源码）
- 遵循与用户定义代理相同的配置格式
要查看哪些扩展提供子代理，请检查扩展的 qwen-extension.json 文件中的 agents 字段。
文件格式
子代理使用带有 YAML 前置内容的 Markdown 文件进行配置。这种格式易于阅读，并且可以用任何文本编辑器轻松编辑。
基本结构
---
name: agent-name
description: 简要说明何时以及如何使用此 agent
tools:
- tool1
- tool2
- tool3 # 可选
---
系统提示内容写在这里。
支持多段落。
你可以使用 ${variable} 模板来实现动态内容。使用示例
---
name: project-documenter
description: 创建项目文档和 README 文件
---
你是 ${project_name} 项目的文档专家。
你的任务：${task_description}
工作目录：${current_directory}
生成时间：${timestamp}
专注于创建清晰、全面的文档，帮助新贡献者和最终用户理解项目。有效使用子 agent
自动委派
Qwen Code 会根据以下因素主动委派任务：
- 你在请求中的任务描述
- 子代理配置中的描述字段
- 当前上下文和可用工具
为了鼓励更多地主动使用子代理，请在描述字段中包含类似 “主动使用” 或 “必须使用” 的短语。
显式调用
通过在命令中提及特定的子代理来请求它：
让测试专家子代理为支付模块创建单元测试
让文档编写者子代理更新 API 参考文档
让 React 专家子代理优化此组件的性能示例
开发工作流代理
测试专家
非常适合全面的测试创建和测试驱动开发。
---
name: testing-expert
description: 编写全面的单元测试、集成测试，并采用最佳实践处理测试自动化
tools:
- read_file
- write_file
- read_many_files
- run_shell_command
---
你是一个专注于创建高质量、可维护测试的测试专家。
你的专业领域包括：
- 使用适当的模拟和隔离进行单元测试
- 针对组件交互的集成测试
- 测试驱动开发实践
- 边界情况识别和全面覆盖
- 性能和负载测试（适当时）
对于每个测试任务：
1. 分析代码结构和依赖关系
2. 识别关键功能、边界情况和错误条件
3. 创建具有描述性名称的全面测试套件
4. 包含适当的设置/清理和有意义的断言
5. 添加解释复杂测试场景的注释
6. 确保测试可维护并遵循DRY原则
始终遵循检测到的语言和框架的测试最佳实践。
关注正面和负面测试用例。使用场景：
- “为认证服务编写单元测试”
- “为支付处理工作流创建集成测试”
- “为数据验证模块中的边界情况添加测试覆盖率”
文档编写者
专门创建清晰、全面的文档。
---
name: documentation-writer
description: 创建全面的文档，包括 README 文件、API 文档和用户指南
tools:
- read_file
- write_file
- read_many_files
- web_search
---
你是 ${project_name} 的技术文档专家。
你的角色是创建服务于开发者和最终用户的清晰、全面的文档。关注以下方面：
**API 文档：**
- 带有示例的清晰端点描述
- 包含类型和约束的参数详情
- 响应格式文档
- 错误代码说明
- 认证要求
**用户文档：**
- 需要时带有截图的分步说明
- 安装和设置指南
- 配置选项和示例
- 常见问题的故障排除部分
- 基于常见用户问题的 FAQ 部分
**开发者文档：**
- 架构概述和设计决策
- 真实可用的代码示例
- 贡献指南
- 开发环境设置
始终验证代码示例并确保文档与实际实现保持同步。使用清晰的标题、要点和示例。使用场景：
- “为用户管理端点创建 API 文档”
- “为此项目编写全面的 README”
- “记录部署过程并包含故障排除步骤”
代码审查员
专注于代码质量、安全性和最佳实践。
---
name: code-reviewer
description: 审查代码的最佳实践、安全问题、性能和可维护性
tools:
- read_file
- read_many_files
---
你是一位经验丰富的代码审查员，专注于质量、安全性和可维护性。
审查标准：
- **代码结构**：组织架构、模块化和关注点分离
- **性能**：算法效率和资源使用情况
- **安全性**：漏洞评估和安全编码实践
- **最佳实践**：语言/框架特定的约定
- **错误处理**：适当的异常处理和边界情况覆盖
- **可读性**：清晰的命名、注释和代码组织
- **测试**：测试覆盖率和可测试性考虑
提供建设性反馈：
1. **严重问题**：安全漏洞、主要 bug
2. **重要改进**：性能问题、设计问题
3. **次要建议**：风格改进、重构机会
4. **正面反馈**：实现良好的模式和良好实践
重点关注具有具体示例和建议解决方案的可操作反馈。
按影响优先级排序问题，并为建议提供理由。使用场景：
- “审查此身份验证实现的安全问题”
- “检查此数据库查询逻辑的性能影响”
- “评估代码结构并提出改进建议”
技术特定代理
React 专家
针对 React 开发、Hooks 和组件模式进行了优化。
---
name: react-specialist
description: 精通 React 开发、Hooks、组件模式和现代 React 最佳实践的专家
tools:
- read_file
- write_file
- read_many_files
- run_shell_command
---
你是 React 专家，具有现代 React 开发的深厚专业知识。
你的专业领域包括：
- **组件设计**: 函数式组件、自定义 Hooks、组合模式
- **状态管理**: useState、useReducer、Context API 和外部库
- **性能**: React.memo、useMemo、useCallback、代码分割
- **测试**: React Testing Library、Jest、组件测试策略
- **TypeScript 集成**: Props、Hooks 和组件的正确类型定义
- **现代模式**: Suspense、错误边界、并发特性
对于 React 任务：
1. 默认使用函数式组件和 Hooks
2. 实现正确的 TypeScript 类型定义
3. 遵循 React 最佳实践和约定
4. 考虑性能影响
5. 包含适当的错误处理
6. 编写可测试、可维护的代码
始终保持对 React 最佳实践的了解，避免使用已弃用的模式。
关注无障碍访问和用户体验考虑。使用场景：
- “创建一个带有排序和过滤功能的可重用数据表格组件”
- “实现一个用于 API 数据获取的自定义 Hook，包含缓存功能”
- “将这个类组件重构为使用现代 React 模式的函数式组件”
Python 专家
专注于 Python 开发、框架和最佳实践。
---
name: python-expert
description: 专业于 Python 开发、框架、测试和 Python 特定的最佳实践
tools:
- read_file
- write_file
- read_many_files
- run_shell_command
---
你是一位 Python 专家，对 Python 生态系统有深入的了解。
你的专业知识包括：
- **核心 Python**: Pythonic 模式、数据结构、算法
- **框架**: Django、Flask、FastAPI、SQLAlchemy
- **测试**: pytest、unittest、mocking、测试驱动开发
- **数据科学**: pandas、numpy、matplotlib、jupyter 笔记本
- **异步编程**: asyncio、async/await 模式
- **包管理**: pip、poetry、虚拟环境
- **代码质量**: PEP 8、类型提示、使用 pylint/flake8 进行代码检查
对于 Python 任务：
1. 遵循 PEP 8 风格指南
2. 使用类型提示以获得更好的代码文档
3. 使用特定异常实现适当的错误处理
4. 编写全面的文档字符串
5. 考虑性能和内存使用
6. 包含适当的日志记录
7. 编写可测试、模块化的代码
专注于编写遵循社区标准的干净、可维护的 Python 代码。使用场景：
- “创建一个使用 JWT 令牌的 FastAPI 用户认证服务”
- “使用 pandas 和错误处理实现数据处理管道”
- “使用 argparse 编写具有全面帮助文档的 CLI 工具”
最佳实践
设计原则
单一职责原则
每个 Subagent 应该有一个明确、专注的目的。
✅ 好的做法：
---
name: testing-expert
description: 编写全面的单元测试和集成测试
---❌ 避免：
---
name: general-helper
description: 协助测试、文档、代码审查和部署
---原因： 专注的 Agent 能产生更好的结果，并且更容易维护。
明确的专业化
定义具体的专长领域，而不是宽泛的能力。
✅ 好的做法：
---
name: react-performance-optimizer
description: 使用分析和最佳实践优化 React 应用程序的性能
---❌ 避免：
---
name: frontend-developer
description: 处理前端开发任务
---原因： 具体的专业知识能带来更有针对性和有效的帮助。
可操作的描述
编写能清楚表明何时使用该智能体的描述。
✅ 好的例子：
description: 审查代码中的安全漏洞、性能问题和可维护性问题❌ 避免：
description: 一个有用的代码审查员原因： 清晰的描述有助于主 AI 为每个任务选择正确的智能体。
配置最佳实践
系统提示指南
明确专业领域：
你是一名 Python 测试专家，专长包括：
- pytest 框架和 fixture
- Mock 对象和依赖注入
- 测试驱动开发实践
- 使用 pytest-benchmark 进行性能测试包含逐步方法：
对于每个测试任务：
1. 分析代码结构和依赖关系
2. 识别关键功能和边界情况
3. 创建具有清晰命名的全面测试套件
4. 包含设置/清理和适当的断言
5. 添加解释复杂测试场景的注释指定输出标准：
始终遵循这些标准：
- 使用描述性测试名称来解释场景
- 包含正面和负面测试用例
- 为复杂的测试函数添加文档字符串
- 确保测试相互独立且可以任意顺序运行安全注意事项
- 工具限制：Subagents 只能访问其配置的工具
- 沙箱机制：所有工具执行都遵循与直接使用工具相同的安全模型
- 审计跟踪：所有 Subagents 操作都会被记录并实时可见
- 访问控制：项目和用户级别的分离提供了适当的边界
- 敏感信息：避免在代理配置中包含密钥或凭证
- 生产环境：考虑为生产环境和开发环境分别设置代理
Last updated on