---
title: 可扩展性与自定义
description: 通过自定义子智能体、规则和 MCP 集成扩展 Verdent 的能力
---



### 你将学到什么

如何使用三种强大的可扩展方法来自定义和扩展 Verdent for VS Code：自定义子智能体、规则系统和 MCP 集成。

---

## 可扩展性概览

Verdent for VS Code 提供三种主要方法来扩展其能力并自定义行为：

1. **自定义子智能体** - 为特定领域任务创建专门的 AI 智能体
2. **规则系统** - 通过 VERDENT.md、AGENTS.md 和 plan_rules.md 引导行为
3. **MCP 集成** - 通过 Model Context Protocol 连接外部工具和服务

每种方法满足不同的自定义需求，并可组合使用以全面优化工作流。

---

## 方法一：自定义子智能体

### 概览

自定义子智能体是具有专用系统提示词、调用策略和任务特定专长的专门 AI 智能体。它们以项目特定的能力扩展 Verdent 内置的子智能体（`@Verifier`、`@Explorer`、`@Code-reviewer`）。

**存储位置：** `~/.verdent/subagents/`

### 创建自定义子智能体

**文件结构：**
```markdown
---
name: subagent-name
description: One-line purpose description
---
# System Prompt

[Behavior definition, personality, task interpretation approach]

Invocation policy (strict|flexible): Policy description

When to use:
- Scenario 1
- Scenario 2

When NOT to use:
- Avoid scenario 1
- Avoid scenario 2
```

**创建方法：**

**方法一：设置菜单**
1. 设置 → 子智能体
2. “创建新子智能体”
3. 定义名称、描述、系统提示词
4. 配置调用策略
5. 保存到 `~/.verdent/subagents/`

**方法二：直接创建文件**
1. 导航到 `~/.verdent/subagents/`
2. 创建 markdown 文件（例如 `security-reviewer.md`）
3. 添加 YAML frontmatter
4. 编写系统提示词和使用指南

### 自定义子智能体的使用场景

**特定领域专长：**
- **金融计算：** 税务合规、金融监管
- **医疗 HIPAA 合规：** 患者数据处理标准
- **密码学：** 安全实现最佳实践

**团队特定工作流：**
- **代码风格强制执行：** 超越 linter 规则的团队编码标准
- **文档一致性：** 确保文档遵循团队模板
- **依赖审计：** 对照已批准列表监控第三方包

**技术栈专家：**
- **React 性能优化：** 识别不必要的重新渲染
- **SQL 查询优化：** 分析并改进数据库性能
- **Docker 配置审查：** 验证容器化实践

**质量保证：**
- **测试覆盖率分析：** 识别未测试的代码路径
- **错误处理审查：** 确保全面的异常处理
- **日志标准强制执行：** 验证日志实践

### 示例：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
```

**用法：**
```
@api-documenter document the /api/users endpoints
```

### 示例：数据库迁移审查器

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

### 调用策略

**严格策略：**
- 子智能体仅在通过 @ 提及显式请求时运行
- 用户完全控制调用
- 最适合专门的、偶尔使用的子智能体

**灵活策略：**
- 允许基于任务模式检测自动调用
- 主智能体自动路由匹配的任务
- 最适合频繁使用、定义明确的子智能体

---

## 方法二：规则系统

### 概览

规则文件是引导 Verdent 行为、输出格式和决策的 Markdown 文档，无需修改代码。三种规则类型提供全面的自定义：

| 规则类型 | 作用范围 | 优先级 | 存储位置 |
|-----------|-------|----------|---------|
| **VERDENT.md** | 全局（所有项目） | 中 | `~/.verdent/VERDENT.md` |
| **AGENTS.md** | 项目特定（团队） | 最高 | 项目根目录 |
| **plan_rules.md** | Plan Mode 格式 | 独立 | `~/.verdent/plan_rules.md` |

### 规则优先级

当发生冲突时：
1. **AGENTS.md**（最高）- 项目规则覆盖用户偏好
2. **VERDENT.md**（中）- 在无项目冲突时应用
3. **默认行为**（最低）- Verdent 的内置默认值

**冲突示例：**
```
VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: 4-space indentation (project rules win)
```

### VERDENT.md（全局偏好）

**用途：** 适用于所有项目的个人编码风格和偏好

**示例：**
```markdown
# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases
- Include return types on all functions

## Code Organization
- One component per file
- Named exports instead of default exports
- Organize imports: external, internal, types

## Documentation
- TSDoc comments for public APIs
- Include @param and @returns tags

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly
```

**访问方式：** 设置 → 规则 → 用户规则

### AGENTS.md（项目规则）

**用途：** 团队范围的编码标准和项目特定约定

**示例：**
```markdown
# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to navigate
- Run `pnpm install --filter <project_name>` for dependencies
- Check package.json name field for correct package name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>`
- From package root: `pnpm test`
- Focus on one test: `pnpm vitest run -t "<test name>"`
- Fix all errors before merge

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing
```

**访问方式：** 项目根目录（纳入版本控制）

### plan_rules.md（Plan 自定义）

**用途：** 控制 Plan Mode 的输出格式和详细程度

**示例：**
```markdown
# Plan Rules

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes
```

**访问方式：** 设置 → 规则 → Plan 规则

### 规则编写最佳实践

**具体且有指导性：**
```
✓ Good: "Always use async/await for asynchronous operations"
✗ Vague: "Try to use modern JavaScript"
```

**逻辑化组织：**
- 在章节标题下分组相关规则
- 分离关注点（风格、测试、文档、安全）
- 跨文件使用一致的结构

**优先处理关键规则：**
- 将重要规则放在每节的最前面
- 对不可妥协的标准使用强调：`**NEVER** commit credentials`
- 聚焦于错误预防和安全

**测试有效性：**
- 开启新对话以验证规则的应用
- 根据智能体的实际行为优化规则
- 随项目演进更新规则

---

## 方法三：MCP 集成

### 概览

Model Context Protocol（MCP）通过连接外部工具、数据源和服务来扩展 Verdent。MCP 服务器充当 Verdent 与外部系统之间的桥梁。

**配置：** 通过 设置 → MCP 服务器 配置 `~/.verdent/mcp.json`

### MCP 能力

**外部系统访问：**
- 数据库查询工具（PostgreSQL、MySQL、MongoDB）
- 云服务 API（AWS、Azure、GCP）
- 项目管理（Jira、Linear、Asana）
- CI/CD 流水线（Jenkins、GitHub Actions）
- 监控服务（Datadog、New Relic）

**自定义工具开发：**
为专有系统创建 MCP 服务器：
- 内部 API 集成
- 遗留系统桥接
- 专门数据源
- 工作流自动化工具

### MCP vs. 自定义子智能体 vs. 规则

| 需求 | 最佳方法 | 原因 |
|------|-------------|-----|
| 专门的 AI 分析 | 自定义子智能体 | 需要基于自定义上下文的 AI 推理 |
| 编码标准强制执行 | 规则（AGENTS.md） | 简单的行为引导 |
| 外部数据库访问 | MCP 集成 | 需要连接外部系统 |
| 个人编码偏好 | 规则（VERDENT.md） | 全局行为自定义 |
| 团队约定 | 规则（AGENTS.md） | 共享的项目标准 |
| API 集成 | MCP 集成 | 外部服务交互 |
| Plan 格式自定义 | 规则（plan_rules.md） | Plan Mode 输出控制 |
| 领域专长（金融、医疗） | 自定义子智能体 | 专门知识应用 |

### 示例：组合使用三种方法

**场景：** 具有严格合规要求的全栈开发团队

**自定义子智能体：**
```markdown
---
name: compliance-auditor
description: Audits code for regulatory compliance (SOC2, HIPAA)
---
[System prompt for compliance checking]
```

**AGENTS.md（项目规则）：**
```markdown
## Security Standards
- All API endpoints must validate inputs
- Never log PII or credentials
- Encrypt sensitive data at rest and in transit

## Compliance
- Run @compliance-auditor before all PRs
- Document data retention policies in code comments
- Include audit trails for data access
```

**MCP 集成：**
- **合规数据库 MCP 服务器：** 对照合规规则检查操作
- **审计日志 MCP 服务器：** 记录所有敏感数据访问

**工作流：**
```
User: "Create endpoint for user profile updates"
Verdent: [Applies AGENTS.md rules]
         [Generates secure endpoint with validation]
         [Automatically invokes @compliance-auditor]
         [Uses MCP to log operation in audit system]
         Result: Compliant, secure, audited endpoint
```

---

## 可扩展性最佳实践

### 从简单开始，逐步扩展

**渐进式采用：**
1. **阶段一：** 从基本规则开始（VERDENT.md 或 AGENTS.md）
2. **阶段二：** 为重复的专门任务添加自定义子智能体
3. **阶段三：** 集成 MCP 以连接外部系统

### 策略性地组合方法

**协同示例：**

**规则 + 子智能体：**
- AGENTS.md 指定何时调用自定义子智能体
- 规则强制执行子智能体的建议被遵循

**规则 + MCP：**
- AGENTS.md 定义哪些 MCP 服务器被批准使用
- 规则指定何时需要外部数据访问

**子智能体 + MCP：**
- 自定义子智能体使用 MCP 工具访问外部系统
- 子智能体以专门的专长解读 MCP 结果

### 记录自定义内容

**团队文档：**
对于自定义子智能体和项目规则（AGENTS.md）：
- 记录非显而易见规则或子智能体的理由
- 提供正确用法的示例
- 包含故障排查指南
- 与代码一同纳入版本控制

**个人文档：**
对于 VERDENT.md 和个人子智能体：
- 为复杂规则添加注释说明理由
- 保持规则有序并及时更新
- 及时移除过时的规则

### 充分测试

**验证流程：**
1. 创建自定义内容（子智能体/规则/MCP 配置）
2. 开启新对话进行测试
3. 验证行为符合预期
4. 根据结果优化
5. 记录成功的模式

**常见测试场景：**
- 子智能体是否在预期时自动调用？
- 项目规则是否正确覆盖用户规则？
- MCP 服务器是否连接并执行操作？
- 组合方法是否在无冲突的情况下交互？

---

## 可扩展性故障排查

### 自定义子智能体问题

**子智能体未调用：**
- 检查调用策略（严格策略需要显式 @ 提及）
- 验证“何时使用”指南与你的请求匹配
- 确保文件位于 `~/.verdent/subagents/` 目录中
- 检查 YAML frontmatter 语法

**子智能体行为异常：**
- 检查系统提示词是否清晰
- 优化“何时使用”和“何时不使用”指南
- 使用显式 @ 提及测试以隔离行为
- 根据结果迭代系统提示词

### 规则冲突

**规则未被应用：**
- 检查规则优先级（AGENTS.md > VERDENT.md）
- 验证文件位于正确位置
- 开启新对话以测试全新应用
- 让规则更具体、更有指导性

**行为异常：**
- 查找同一文件中相互矛盾的规则
- 检查规则是否过于模糊
- 验证正在编辑的是正确的规则文件
- 使用明确的措辞（“始终”、“从不”、“优先”）

### MCP 集成问题

**连接失败：**
- 验证 `mcp.json` 语法
- 检查身份验证凭据
- 确保 MCP 服务器正在运行且可访问
- 验证网络连接

**工具调用问题：**
- 确认 MCP 服务器暴露了预期的工具
- 检查工具参数格式
- 查看 MCP 服务器日志以排查错误
- 独立测试 MCP 服务器

---

## 另请参阅

<CardGroup cols={2}>
  <Card title="子智能体管理" icon="users" href="/docs/verdent-for-vscode/agents-rules/subagent-management">
    详细的子智能体创建指南
  </Card>
  <Card title="规则系统" icon="book" href="/docs/verdent-for-vscode/agents-rules/rule-systems">
    完整的规则文档
  </Card>
  <Card title="MCP 集成" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    MCP 设置与配置
  </Card>
  <Card title="工具参考" icon="wrench" href="/docs/verdent-for-vscode/advanced-features/tool-reference">
    内置工具能力
  </Card>
</CardGroup>