高级功能
可扩展性与自定义
通过自定义子智能体、规则和 MCP 集成扩展 Verdent 的能力
你将学到什么
如何使用三种强大的可扩展方法来自定义和扩展 Verdent for VS Code：自定义子智能体、规则系统和 MCP 集成。
可扩展性概览
Verdent for VS Code 提供三种主要方法来扩展其能力并自定义行为：
- 自定义子智能体 - 为特定领域任务创建专门的 AI 智能体
- 规则系统 - 通过 VERDENT.md、AGENTS.md 和 plan_rules.md 引导行为
- MCP 集成 - 通过 Model Context Protocol 连接外部工具和服务
每种方法满足不同的自定义需求，并可组合使用以全面优化工作流。
方法一：自定义子智能体
概览
自定义子智能体是具有专用系统提示词、调用策略和任务特定专长的专门 AI 智能体。它们以项目特定的能力扩展 Verdent 内置的子智能体（@Verifier、@Explorer、@Code-reviewer）。
存储位置： ~/.verdent/subagents/
创建自定义子智能体
文件结构：
---
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创建方法：
方法一：设置菜单
- 设置 → 子智能体
- “创建新子智能体”
- 定义名称、描述、系统提示词
- 配置调用策略
- 保存到
~/.verdent/subagents/
方法二：直接创建文件
- 导航到
~/.verdent/subagents/ - 创建 markdown 文件（例如
security-reviewer.md） - 添加 YAML frontmatter
- 编写系统提示词和使用指南
自定义子智能体的使用场景
特定领域专长：
- 金融计算： 税务合规、金融监管
- 医疗 HIPAA 合规： 患者数据处理标准
- 密码学： 安全实现最佳实践
团队特定工作流：
- 代码风格强制执行： 超越 linter 规则的团队编码标准
- 文档一致性： 确保文档遵循团队模板
- 依赖审计： 对照已批准列表监控第三方包
技术栈专家：
- React 性能优化： 识别不必要的重新渲染
- SQL 查询优化： 分析并改进数据库性能
- Docker 配置审查： 验证容器化实践
质量保证：
- 测试覆盖率分析： 识别未测试的代码路径
- 错误处理审查： 确保全面的异常处理
- 日志标准强制执行： 验证日志实践
示例：API 文档生成器
---
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示例：数据库迁移审查器
---
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 |
规则优先级
当发生冲突时：
- AGENTS.md（最高）- 项目规则覆盖用户偏好
- VERDENT.md（中）- 在无项目冲突时应用
- 默认行为（最低）- 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（全局偏好）
用途： 适用于所有项目的个人编码风格和偏好
示例：
# 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（项目规则）
用途： 团队范围的编码标准和项目特定约定
示例：
# 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 的输出格式和详细程度
示例：
# 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 输出控制 |
| 领域专长（金融、医疗） | 自定义子智能体 | 专门知识应用 |
示例：组合使用三种方法
场景： 具有严格合规要求的全栈开发团队
自定义子智能体：
---
name: compliance-auditor
description: Audits code for regulatory compliance (SOC2, HIPAA)
---
[System prompt for compliance checking]AGENTS.md（项目规则）：
## 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 accessMCP 集成：
- 合规数据库 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可扩展性最佳实践
从简单开始，逐步扩展
渐进式采用：
- 阶段一： 从基本规则开始（VERDENT.md 或 AGENTS.md）
- 阶段二： 为重复的专门任务添加自定义子智能体
- 阶段三： 集成 MCP 以连接外部系统
策略性地组合方法
协同示例：
规则 + 子智能体：
- AGENTS.md 指定何时调用自定义子智能体
- 规则强制执行子智能体的建议被遵循
规则 + MCP：
- AGENTS.md 定义哪些 MCP 服务器被批准使用
- 规则指定何时需要外部数据访问
子智能体 + MCP：
- 自定义子智能体使用 MCP 工具访问外部系统
- 子智能体以专门的专长解读 MCP 结果
记录自定义内容
团队文档： 对于自定义子智能体和项目规则（AGENTS.md）：
- 记录非显而易见规则或子智能体的理由
- 提供正确用法的示例
- 包含故障排查指南
- 与代码一同纳入版本控制
个人文档： 对于 VERDENT.md 和个人子智能体：
- 为复杂规则添加注释说明理由
- 保持规则有序并及时更新
- 及时移除过时的规则
充分测试
验证流程：
- 创建自定义内容（子智能体/规则/MCP 配置）
- 开启新对话进行测试
- 验证行为符合预期
- 根据结果优化
- 记录成功的模式
常见测试场景：
- 子智能体是否在预期时自动调用？
- 项目规则是否正确覆盖用户规则？
- MCP 服务器是否连接并执行操作？
- 组合方法是否在无冲突的情况下交互？
可扩展性故障排查
自定义子智能体问题
子智能体未调用：
- 检查调用策略（严格策略需要显式 @ 提及）
- 验证“何时使用”指南与你的请求匹配
- 确保文件位于
~/.verdent/subagents/目录中 - 检查 YAML frontmatter 语法
子智能体行为异常：
- 检查系统提示词是否清晰
- 优化“何时使用”和“何时不使用”指南
- 使用显式 @ 提及测试以隔离行为
- 根据结果迭代系统提示词
规则冲突
规则未被应用：
- 检查规则优先级（AGENTS.md > VERDENT.md）
- 验证文件位于正确位置
- 开启新对话以测试全新应用
- 让规则更具体、更有指导性
行为异常：
- 查找同一文件中相互矛盾的规则
- 检查规则是否过于模糊
- 验证正在编辑的是正确的规则文件
- 使用明确的措辞（“始终”、“从不”、“优先”）
MCP 集成问题
连接失败：
- 验证
mcp.json语法 - 检查身份验证凭据
- 确保 MCP 服务器正在运行且可访问
- 验证网络连接
工具调用问题：
- 确认 MCP 服务器暴露了预期的工具
- 检查工具参数格式
- 查看 MCP 服务器日志以排查错误
- 独立测试 MCP 服务器