子智能体管理
了解并管理 Verdent 中的子智能体
子智能体是专门化的 AI 智能体，运行时拥有自己的自定义系统提示词、独立的上下文窗口和隔离的执行环境。它们处理由主智能体委派的特定任务，而不会污染主对话上下文。
主要特性：
- 隔离的上下文窗口： 每个子智能体维护自己独立的上下文窗口。只有子智能体返回的最终结果才会占用主智能体上下文的空间，中间处理过程不会。
- 自定义系统提示词： 每个子智能体都有专属的系统提示词，定义其行为、个性和任务解读方式。
- 自动任务委派： 当检测到合适的任务类型时，主智能体会自动调用子智能体，类似于自动工具选择。
- 手动调用： 用户可以使用 @-提及显式引用子智能体（
@Verifier、@Explorer、@Code-reviewer）。
两大类别：
- 默认子智能体： 内置（Verifier、Explorer、Code-reviewer）—— 即开即用，预先配置好。
- 自定义子智能体： 用户创建，存储于
~/.verdent/subagents/—— 针对项目特定需求量身定制。
了解默认子智能体
Verdent for VS Code 包含三个内置的默认子智能体，它们预先配置好、即开即用，无需任何设置或配置。
专长： 快速代码检查与验证
能力：
- 验证代码逻辑
- 检查语法正确性
- 对照需求核验实现
用法： 在编码任务中引用：
@Verifier check this authentication logic最适用于： 无需完整代码审查开销的快速验证
专长： 快速代码库探索与导航
能力：
- 按模式或名称查找文件
- 搜索关键字/函数
- 回答架构相关问题
- 识别功能的实现位置
用法： 在涉及代码库的问题中自动调用，或显式请求时调用：
@Explorer find all API endpoints最适用于：
- 理解陌生的代码库
- 定位具体实现
- 架构分析
性能： Token 高效，复杂搜索时可并行运行多个实例
专长： 代码质量评估
能力：
- 主动扫描新增和修改的代码以发现安全漏洞
- 识别可维护性问题
- 检测性能问题
用法： 引用以进行质量检查：
@Code-reviewer review this authentication flow最适用于：
- 提交前审查
- 在集成前发现问题
- 确保代码质量标准
自动调用与手动调用
自动选择的触发条件：
主智能体基于任务模式识别自动选择子智能体：
Explorer 子智能体：
- 关于代码库结构的问题（“架构是什么？”、“X 在哪里实现？”）
- 文件搜索请求（“找出所有……的文件”、“显示与……相关的组件”）
- 代码导航查询（“身份验证如何工作？”、“什么调用了这个函数？”）
Code-reviewer 子智能体：
- 安全审查请求（“审查安全漏洞”、“检查 SQL 注入风险”）
- 代码质量评估提示（“分析代码质量”、“识别可维护性问题”）
- 提交前审查场景（呈现代码变更时隐式触发）
Verifier 子智能体：
- 验证请求（“验证这段逻辑”、“检查这个实现是否正确”）
- 语法和正确性检查（“这段代码能工作吗？”、“验证身份验证流程”）
手动指定：
用户可以使用 @-提及覆盖自动路由：
@Explorer find all authentication-related files
@Code-reviewer review the security of login flow
@Verifier check validation logic in middleware添加子智能体按钮： 点击输入框中的 Add Subagent 按钮即可：
- 从可用子智能体中选择（默认和自定义）
- 显式将任务委派给所选子智能体
- 覆盖自动路由决策
手动指定的好处：
- 精确性： 确保由确切的子智能体处理任务
- 覆盖： 当多个子智能体都适用时，选择特定的子智能体
- 测试： 显式验证自定义子智能体的行为
- 一致性： 用同一个子智能体重复执行任务以获得一致结果
自定义子智能体可能会根据其系统提示词调用策略中定义的“何时使用”指南被自动调用。关于触发模式配置的详细信息目前正在开发中。
创建自定义子智能体
自定义子智能体让你能够创建针对项目特定需求、领域专长或团队工作流量身定制的专门化智能体。
创建方法
推荐给初学者
- 点击 Settings → Subagents
- 选择“Create new subagent”
- 定义子智能体的名称、描述和系统提示词
- 配置调用策略和使用指南
- 保存到
~/.verdent/subagents/目录
此方法提供带验证和有用提示的引导式界面来创建子智能体。
推荐给高级用户
- 导航到
~/.verdent/subagents/ - 创建 markdown 文件（例如
security-reviewer.md） - 添加包含
name和description的 YAML frontmatter - 编写定义行为的系统提示词
- 指定调用策略和“何时使用”指南
此方法提供更多控制权，对熟悉文件结构的用户来说更快。
通过将自定义子智能体存储在 ~/.verdent/subagents/ 中，可以跨项目共享。它们将在所有工作区中可用。
文件结构
自定义子智能体文件使用带 YAML frontmatter 的 Markdown 格式：
---
name: subagent-name
description: Brief description of specialization
---
# System Prompt
[Behavior definition, personality, interpretation style]
Invocation policy (strict): Only run if explicitly requested.
When to use:
- Specific scenario 1
- Specific scenario 2
When NOT to use:
- Avoid scenario 1
- Avoid scenario 2YAML Frontmatter（必填）：
name：用于 @-提及的子智能体标识符description：子智能体用途的一行描述
系统提示词部分： 定义子智能体行为的 Markdown 内容：
- 个性和语气
- 任务解读方式
- 输出格式偏好
- 决策原则
调用策略（必填）：
Invocation policy (strict|flexible): Policy description- strict： 仅在用户显式请求时调用
- flexible： 允许基于任务模式自动调用
使用指南：
When to use the [name] agent:
- Bullet list of scenarios for invocation
When NOT to use:
- Bullet list of scenarios to avoid自定义子智能体示例
---
name: api-documenter
description: Generates comprehensive API documentation from code
---
# System Prompt
You are an API documentation specialist.
Documentation approach:
- Extract endpoints, parameters, and responses from code
- Generate OpenAPI/Swagger specifications
- Include usage examples and error codes
- Document authentication requirements
Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams
Invocation policy (strict): Only run when explicitly requested.
When to use:
- User requests API documentation generation
- Need to document REST/GraphQL endpoints
- Creating developer guides
When NOT to use:
- Inline code comments
- User-facing documentation用例： 通过分析路由处理器、控制器和 schema 定义，自动生成全面的 API 文档。
---
name: migration-reviewer
description: Reviews database migrations for safety and correctness
---
# System Prompt
You are a database migration safety specialist.
Review checklist:
- Check for destructive operations (DROP, DELETE without WHERE)
- Verify reversible migrations (up/down compatibility)
- Identify potential data loss scenarios
- Validate index creation strategies
- Check for blocking operations on large tables
Risk assessment:
- Categorize migrations: low/medium/high risk
- Recommend staging environment testing for high-risk changes
- Suggest rollback procedures
Invocation policy (strict): Only run when explicitly requested.
When to use:
- User creates or modifies migration files
- Pre-deployment migration review
- Investigating migration failures
When NOT to use:
- Schema design from scratch
- Query optimization用例： 在部署前识别有风险的数据库操作，防止生产事故。
---
name: a11y-auditor
description: Audits frontend code for accessibility compliance
---
# System Prompt
You are an accessibility compliance specialist (WCAG 2.1 Level AA).
Audit criteria:
- Semantic HTML structure
- ARIA labels and roles
- Keyboard navigation support
- Color contrast ratios
- Screen reader compatibility
- Focus management
Report format:
- Issues categorized by severity (critical/major/minor)
- WCAG guideline references
- Code examples showing fixes
- Testing recommendations
Invocation policy (flexible): May auto-invoke for UI component reviews.
When to use:
- User creates/modifies UI components
- Pre-deployment accessibility checks
- Compliance audits
When NOT to use:
- Backend API code
- Build configuration files用例： 确保 Web 应用在部署前满足无障碍标准。
自定义子智能体的常见用例
领域特定专长
- 金融计算： 专精于税务合规、金融法规的子智能体
- 医疗 HIPAA 合规： 审查代码以符合患者数据处理标准
- 密码学： 对照最佳实践分析安全实现
适用于对专业知识和监管约束有要求的行业。
团队特定工作流
- 代码风格执行者： 对照团队特定的编码标准（超出 linter 规则）进行检查
- 文档一致性： 确保文档遵循团队模板和语气
- 依赖审计员： 监控第三方包的使用是否符合批准列表
强制执行团队约定，在协作项目中保持一致性。
技术栈专家
- React 性能优化器： 识别不必要的重渲染、memoization 机会
- SQL 查询优化器： 分析并改进数据库查询性能
- Docker 配置审查员： 验证容器化最佳实践
在特定框架、语言或基础设施技术方面的深厚专长。
质量保证
- 测试覆盖分析器： 识别未测试的代码路径，建议测试场景
- 错误处理审查员： 确保全面的异常处理
- 日志标准执行者： 验证用于调试和监控的日志实践
自动化质量检查，以维持代码可靠性和可维护性标准。
合规与安全
- GDPR 合规检查器： 审查数据处理以满足隐私要求
- 安全漏洞扫描器： 针对框架特定问题的专门检测
- 许可证合规审计员： 检查依赖项的许可证兼容性
确保在部署前符合法律、安全和许可要求。
项目特定需求
- 遗留代码现代化器： 识别过时模式，建议现代替代方案
- 迁移助手： 指导框架或语言版本升级
- 性能预算执行者： 对照阈值监控打包体积、加载时间
针对独特项目挑战和技术债务管理量身定制的自定义解决方案。
子智能体行为配置（AGENTS.md 模式）
虽然 AGENTS.md 主要用作项目规则文件（参见 规则系统），但它也可以定义项目特定的子智能体行为。
系统提示词设计原则
具体且有指令性： 定义确切的行为预期，而非笼统的指导。
系统提示词应具体且有指令性，“优化前先做性能分析”优于“尽可能尝试优化”。
好的做法：
Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks避免：
Try to optimize code when possible建立个性和语气： 针对特定用途创建鲜明的“人设”：
You are a performance optimization specialist.定义决策原则： 指导子智能体如何处理权衡：
When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement指定输出格式： 控制结果的呈现方式：
Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams调用策略配置
严格策略（Strict）：
Invocation policy (strict): Only run when explicitly requested.适用于：
- 子智能体处理敏感操作（安全审查、数据库迁移）
- 用户应有意识地决定何时调用
- 自动调用可能造成干扰
灵活策略（Flexible）：
Invocation policy (flexible): May auto-invoke based on task patterns.适用于：
- 子智能体提供有用上下文且不造成干扰
- 自动调用能提升工作流效率
- 任务模式清晰可辨
使用指南最佳实践：
“何时使用”部分：
- 具体描述触发场景
- 包含应调用该子智能体的示例提示词
- 描述符合子智能体专长的任务特征
“何时不使用”部分：
- 显式列出排除项以防止不当调用
- 厘清与相关子智能体的边界
- 防止范围蔓延
任务路由与分发
Verdent 的多子智能体系统支持跨专门化智能体的并行任务执行，并具备自动路由和协调能力。
架构组件
主智能体（编排器）： 主智能体分析用户请求，拆解复杂任务，并将专门化的工作委派给合适的子智能体。它维护对话上下文并协调子智能体的结果。
子智能体池： 可被自动或手动调用的可用子智能体集合（默认和自定义）。每个子智能体独立运行，拥有隔离的上下文。
自动任务路由： 当主智能体检测到匹配子智能体专长的任务模式时，会自动分发工作：
- 代码库探索问题 → Explorer 子智能体
- 安全审查请求 → Code-reviewer 子智能体
- 验证检查 → Verifier 子智能体
并行执行： 多个子智能体可在复杂操作中并发运行。例如：Explorer 子智能体搜索代码库的同时，Code-reviewer 同步分析安全问题，从而更快交付结果。
并行子智能体执行可加速复杂任务，Explorer 可以搜索的同时 Code-reviewer 同步分析。
结果合并： 子智能体的输出返回给主智能体，由主智能体综合结果并向用户呈现统一的响应。
关于子智能体执行调度、优先级、最大并发限制、错误处理和资源分配的详细信息目前正在开发中。如有具体的架构问题，请联系支持团队。
子智能体监控
通过 Chat View 跟踪子智能体的使用和性能，Verdent 会在此显示子智能体的操作和结果。
监控方法
Chat View 指示器：
- 子智能体调用显示在对话历史中
- 进度指示器显示子智能体正在执行的时刻
- 结果明确标识由哪个子智能体提供输出
子智能体输出部分： 专用显示区，用于：
- 子智能体任务执行的结果
- 并行任务的进度指示器
- 任务完成时的合并摘要
响应归属： Verdent 在响应中将发现归属于特定子智能体，清晰说明哪个智能体执行了哪项分析或搜索。
可见性与透明度
操作透明度： Verdent 显示：
- 调用了哪个子智能体
- 调用是自动还是手动
- 任务委派原因
- 子智能体执行状态
手动指定验证： 当你使用 @-提及时，Verdent 会确认指定的子智能体正在处理任务，确保你的路由偏好得到尊重。
增强的监控功能正在开发中，包括详细的执行日志、性能指标（执行时间、token 使用量）、历史调用跟踪、活动可见性设置和使用分析仪表板。