---
title: 子智能体管理
description: 了解并管理 Verdent 中的子智能体
---

子智能体是专门化的 AI 智能体，运行时拥有自己的自定义系统提示词、独立的上下文窗口和隔离的执行环境。它们处理由主智能体委派的特定任务，而不会污染主对话上下文。

**主要特性：**

- **隔离的上下文窗口：** 每个子智能体维护自己独立的上下文窗口。只有子智能体返回的最终结果才会占用主智能体上下文的空间，中间处理过程不会。
- **自定义系统提示词：** 每个子智能体都有专属的系统提示词，定义其行为、个性和任务解读方式。
- **自动任务委派：** 当检测到合适的任务类型时，主智能体会自动调用子智能体，类似于自动工具选择。
- **手动调用：** 用户可以使用 @-提及显式引用子智能体（`@Verifier`、`@Explorer`、`@Code-reviewer`）。

**两大类别：**
- **默认子智能体：** 内置（Verifier、Explorer、Code-reviewer）—— 即开即用，预先配置好。
- **自定义子智能体：** 用户创建，存储于 `~/.verdent/subagents/` —— 针对项目特定需求量身定制。

---

## 了解默认子智能体

Verdent for VS Code 包含三个内置的默认子智能体，它们预先配置好、即开即用，无需任何设置或配置。

<Tabs>
  <Tab title="@Verifier">
    **专长：** 快速代码检查与验证

    **能力：**
    - 验证代码逻辑
    - 检查语法正确性
    - 对照需求核验实现

    **用法：**
    在编码任务中引用：
    ```
    @Verifier check this authentication logic
    ```

    **最适用于：** 无需完整代码审查开销的快速验证
  </Tab>

  <Tab title="@Explorer">
    **专长：** 快速代码库探索与导航

    **能力：**
    - 按模式或名称查找文件
    - 搜索关键字/函数
    - 回答架构相关问题
    - 识别功能的实现位置

    **用法：**
    在涉及代码库的问题中自动调用，或显式请求时调用：
    ```
    @Explorer find all API endpoints
    ```

    **最适用于：**
    - 理解陌生的代码库
    - 定位具体实现
    - 架构分析

    **性能：** Token 高效，复杂搜索时可并行运行多个实例
  </Tab>

  <Tab title="@Code-reviewer">
    **专长：** 代码质量评估

    **能力：**
    - 主动扫描新增和修改的代码以发现安全漏洞
    - 识别可维护性问题
    - 检测性能问题

    **用法：**
    引用以进行质量检查：
    ```
    @Code-reviewer review this authentication flow
    ```

    **最适用于：**
    - 提交前审查
    - 在集成前发现问题
    - 确保代码质量标准
  </Tab>
</Tabs>

---

### 自动调用与手动调用

**自动选择的触发条件：**

主智能体基于任务模式识别自动选择子智能体：

**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** 按钮即可：
- 从可用子智能体中选择（默认和自定义）
- 显式将任务委派给所选子智能体
- 覆盖自动路由决策

**手动指定的好处：**
- **精确性：** 确保由确切的子智能体处理任务
- **覆盖：** 当多个子智能体都适用时，选择特定的子智能体
- **测试：** 显式验证自定义子智能体的行为
- **一致性：** 用同一个子智能体重复执行任务以获得一致结果

<Info>
自定义子智能体可能会根据其系统提示词调用策略中定义的“何时使用”指南被自动调用。关于触发模式配置的详细信息目前正在开发中。
</Info>

---

## 创建自定义子智能体

自定义子智能体让你能够创建针对项目特定需求、领域专长或团队工作流量身定制的专门化智能体。

### 创建方法

<Tabs>
  <Tab title="设置菜单">
    **推荐给初学者**

    1. 点击 **Settings** → **Subagents**
    2. 选择“Create new subagent”
    3. 定义子智能体的名称、描述和系统提示词
    4. 配置调用策略和使用指南
    5. 保存到 `~/.verdent/subagents/` 目录

    此方法提供带验证和有用提示的引导式界面来创建子智能体。
  </Tab>

  <Tab title="直接创建文件">
    **推荐给高级用户**

    1. 导航到 `~/.verdent/subagents/`
    2. 创建 markdown 文件（例如 `security-reviewer.md`）
    3. 添加包含 `name` 和 `description` 的 YAML frontmatter
    4. 编写定义行为的系统提示词
    5. 指定调用策略和“何时使用”指南

    此方法提供更多控制权，对熟悉文件结构的用户来说更快。

    <Tip>
    通过将自定义子智能体存储在 ~/.verdent/subagents/ 中，可以跨项目共享。它们将在所有工作区中可用。
    </Tip>
  </Tab>
</Tabs>

---

### 文件结构

自定义子智能体文件使用带 YAML frontmatter 的 Markdown 格式：

```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 2
```

**YAML 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
```

---

### 自定义子智能体示例

<Tabs>
  <Tab title="API 文档">
    ```markdown
    ---
    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 文档。
  </Tab>

  <Tab title="数据库迁移">
    ```markdown
    ---
    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
    ```

    **用例：** 在部署前识别有风险的数据库操作，防止生产事故。
  </Tab>

  <Tab title="无障碍">
    ```markdown
    ---
    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 应用在部署前满足无障碍标准。
  </Tab>
</Tabs>

---

### 自定义子智能体的常见用例

<Tabs>
  <Tab title="领域专长">
    **领域特定专长**

    - **金融计算：** 专精于税务合规、金融法规的子智能体
    - **医疗 HIPAA 合规：** 审查代码以符合患者数据处理标准
    - **密码学：** 对照最佳实践分析安全实现

    适用于对专业知识和监管约束有要求的行业。
  </Tab>

  <Tab title="团队工作流">
    **团队特定工作流**

    - **代码风格执行者：** 对照团队特定的编码标准（超出 linter 规则）进行检查
    - **文档一致性：** 确保文档遵循团队模板和语气
    - **依赖审计员：** 监控第三方包的使用是否符合批准列表

    强制执行团队约定，在协作项目中保持一致性。
  </Tab>

  <Tab title="技术栈">
    **技术栈专家**

    - **React 性能优化器：** 识别不必要的重渲染、memoization 机会
    - **SQL 查询优化器：** 分析并改进数据库查询性能
    - **Docker 配置审查员：** 验证容器化最佳实践

    在特定框架、语言或基础设施技术方面的深厚专长。
  </Tab>

  <Tab title="质量保证">
    **质量保证**

    - **测试覆盖分析器：** 识别未测试的代码路径，建议测试场景
    - **错误处理审查员：** 确保全面的异常处理
    - **日志标准执行者：** 验证用于调试和监控的日志实践

    自动化质量检查，以维持代码可靠性和可维护性标准。
  </Tab>

  <Tab title="合规">
    **合规与安全**

    - **GDPR 合规检查器：** 审查数据处理以满足隐私要求
    - **安全漏洞扫描器：** 针对框架特定问题的专门检测
    - **许可证合规审计员：** 检查依赖项的许可证兼容性

    确保在部署前符合法律、安全和许可要求。
  </Tab>

  <Tab title="项目特定">
    **项目特定需求**

    - **遗留代码现代化器：** 识别过时模式，建议现代替代方案
    - **迁移助手：** 指导框架或语言版本升级
    - **性能预算执行者：** 对照阈值监控打包体积、加载时间

    针对独特项目挑战和技术债务管理量身定制的自定义解决方案。
  </Tab>
</Tabs>

---

## 子智能体行为配置（AGENTS.md 模式）

虽然 AGENTS.md 主要用作项目规则文件（参见 [规则系统](/docs/verdent-for-vscode/agents-rules/rule-systems)），但它也可以定义项目特定的子智能体行为。

### 系统提示词设计原则

**具体且有指令性：**
定义确切的行为预期，而非笼统的指导。

<Tip>
系统提示词应具体且有指令性，“优化前先做性能分析”优于“尽可能尝试优化”。
</Tip>

**好的做法：**
```markdown
Analysis approach:
- Profile before optimizing
- Focus on algorithmic improvements
- Provide before/after benchmarks
```

**避免：**
```markdown
Try to optimize code when possible
```

**建立个性和语气：**
针对特定用途创建鲜明的“人设”：

```markdown
You are a performance optimization specialist.
```

**定义决策原则：**
指导子智能体如何处理权衡：

```markdown
When suggesting optimizations:
1. Measure first, optimize second
2. Prioritize readability over micro-optimizations
3. Only suggest changes with >10% performance improvement
```

**指定输出格式：**
控制结果的呈现方式：

```markdown
Output format:
- Markdown tables for endpoints
- Code examples in multiple languages
- Authentication flow diagrams
```

---

### 调用策略配置

**严格策略（Strict）：**
```markdown
Invocation policy (strict): Only run when explicitly requested.
```

适用于：
- 子智能体处理敏感操作（安全审查、数据库迁移）
- 用户应有意识地决定何时调用
- 自动调用可能造成干扰

**灵活策略（Flexible）：**
```markdown
Invocation policy (flexible): May auto-invoke based on task patterns.
```

适用于：
- 子智能体提供有用上下文且不造成干扰
- 自动调用能提升工作流效率
- 任务模式清晰可辨

**使用指南最佳实践：**

**“何时使用”部分：**
- 具体描述触发场景
- 包含应调用该子智能体的示例提示词
- 描述符合子智能体专长的任务特征

**“何时不使用”部分：**
- 显式列出排除项以防止不当调用
- 厘清与相关子智能体的边界
- 防止范围蔓延

---

## 任务路由与分发

Verdent 的多子智能体系统支持跨专门化智能体的并行任务执行，并具备自动路由和协调能力。

### 架构组件

**主智能体（编排器）：**
主智能体分析用户请求，拆解复杂任务，并将专门化的工作委派给合适的子智能体。它维护对话上下文并协调子智能体的结果。

**子智能体池：**
可被自动或手动调用的可用子智能体集合（默认和自定义）。每个子智能体独立运行，拥有隔离的上下文。

**自动任务路由：**
当主智能体检测到匹配子智能体专长的任务模式时，会自动分发工作：
- 代码库探索问题 → Explorer 子智能体
- 安全审查请求 → Code-reviewer 子智能体
- 验证检查 → Verifier 子智能体

**并行执行：**
多个子智能体可在复杂操作中并发运行。例如：Explorer 子智能体搜索代码库的同时，Code-reviewer 同步分析安全问题，从而更快交付结果。

<Note>
并行子智能体执行可加速复杂任务，Explorer 可以搜索的同时 Code-reviewer 同步分析。
</Note>

**结果合并：**
子智能体的输出返回给主智能体，由主智能体综合结果并向用户呈现统一的响应。

<Info>
关于子智能体执行调度、优先级、最大并发限制、错误处理和资源分配的详细信息目前正在开发中。如有具体的架构问题，请联系支持团队。
</Info>

---

## 子智能体监控

通过 Chat View 跟踪子智能体的使用和性能，Verdent 会在此显示子智能体的操作和结果。

### 监控方法

**Chat View 指示器：**
- 子智能体调用显示在对话历史中
- 进度指示器显示子智能体正在执行的时刻
- 结果明确标识由哪个子智能体提供输出

**子智能体输出部分：**
专用显示区，用于：
- 子智能体任务执行的结果
- 并行任务的进度指示器
- 任务完成时的合并摘要

**响应归属：**
Verdent 在响应中将发现归属于特定子智能体，清晰说明哪个智能体执行了哪项分析或搜索。

### 可见性与透明度

**操作透明度：**
Verdent 显示：
- 调用了哪个子智能体
- 调用是自动还是手动
- 任务委派原因
- 子智能体执行状态

**手动指定验证：**
当你使用 @-提及时，Verdent 会确认指定的子智能体正在处理任务，确保你的路由偏好得到尊重。

<Info>
增强的监控功能正在开发中，包括详细的执行日志、性能指标（执行时间、token 使用量）、历史调用跟踪、活动可见性设置和使用分析仪表板。
</Info>

---

## 另请参阅

<CardGroup cols={2}>
  <Card title="规则系统与行为指导" icon="sliders" href="/docs/verdent-for-vscode/agents-rules/rule-systems">
    通过用户规则、项目规则和计划规则配置 Verdent 行为
  </Card>
  <Card title="工具参考" icon="wrench" href="/docs/verdent-for-vscode/advanced-features/tool-reference">
    可用工具和能力的完整参考
  </Card>
</CardGroup>