集成工作流

你将学到什么

结合自定义子智能体、规则和 MCP 服务器，应对真实开发场景的实用集成工作流。

集成方式

方式	最适合	配置
自定义子智能体	AI 驱动的专项任务	`~/.verdent/subagents/*.md`
规则（AGENTS.md）	团队标准和行为	项目根目录 `AGENTS.md`
MCP 服务器	符合协议的外部工具	`.mcp.json`（项目根目录）

理念： 组合多种方式，打造贴合你需求的全面工作流。

常见集成模式

数据库开发工作流

技术栈： 迁移审查子智能体 + AGENTS.md 标准 + PostgreSQL MCP 服务器

子智能体：

---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations

AGENTS.md：

## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures

MCP： 用于查询执行、schema 检查、迁移校验的 PostgreSQL 服务器

工作流： 编写迁移 → @migration-reviewer 校验 → MCP 在预发环境测试 → PR 文档

带安全性的 API 开发

技术栈： 安全审计员 + AGENTS.md 规则 + 自定义 API 测试工具

组件：

子智能体： @api-security-auditor - 输入校验、SQL 注入、鉴权、限流
规则： 所有端点都需安全审查，公共 API 需限流
外部工具： 通过自定义集成进行自动化端点测试和安全扫描

结果： 在 PR 批准前自动进行安全审查。

API 测试和安全扫描工具可以通过自定义 MCP 服务器实现或其他集成方式来集成，具体取决于你的工具链。

前端可访问性

技术栈： 可访问性审计员 + WCAG 规则 + Lighthouse 集成

工作流：

Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score

Lighthouse 和其他可访问性工具可以通过自定义 MCP 服务器或 CI/CD 流水线集成，具体取决于你的工作流。

MCP 配置示例

理解 MCP

模型上下文协议（MCP） 是一种开放协议，标准化了应用程序如何向 LLM 提供上下文。MCP 服务器是实现该协议的可执行程序。它们不是数据库连接或 API 端点，而是运行并通过 JSON-RPC 2.0 通信的程序。

核心概念：

MCP 服务器：实现 MCP 协议的可执行程序（Node.js 包、Python 脚本等）
配置：告诉 Verdent 如何启动服务器（command + args）
通信：服务器处理自己的业务逻辑（查询、API 调用等）

基础设置

位置： 项目根目录下的 .mcp.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    }
  }
}

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

说明：

mcpServers - MCP 配置必需的顶层键
command - 要运行的可执行程序（对于 Node.js 包通常是 npx）
args - 传递给命令的参数（包名、连接字符串等）
env - 用于鉴权/配置的环境变量

多环境

{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}

最佳实践： 使用环境变量存储连接字符串，以保证凭据安全。MCP 服务器根据自身实现内部处理只读行为。请查阅具体服务器文档了解访问控制选项。

了解更多关于 MCP：

模型上下文协议规范
MCP 服务器注册表 - 浏览可用的 MCP 服务器
官方 MCP 服务器 - PostgreSQL、GitHub、Filesystem 等

工作区集成

项目专属配置

设置：

存放在项目根目录：.mcp.json
提交到版本控制以便团队共享
团队成员自动使用项目的 MCP 服务器

微服务示例：

{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}

对于 Kafka 等其他服务，你需要一个兼容的 MCP 服务器实现。官方 MCP 服务器注册表 mcp.so/servers 列出了可用的社区服务器。

团队协作

共享的 AGENTS.md 标准

提交到版本控制以实现团队范围内的一致性：

# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries

好处： 行为一致、标准被强制执行、自动质量门禁。

多智能体协调

复杂功能工作流

示例： 新的支付端点

1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR

结果： 完整审查的端点，应用了安全和数据库最佳实践。

集成最佳实践

渐进式采用

阶段 1： 基础规则

## Code Standards
- Use TypeScript strict mode
- Run tests before commit

阶段 2： 添加专项子智能体

## Code Review
- Run @security-reviewer before PR

阶段 3： 集成 MCP

## Database Access
- Use MCP postgres-staging for queries

策略性组合

组合	目的	示例
规则 + 子智能体	规则定义何时，子智能体进行分析	AGENTS.md：“用 @security-reviewer 审查”
规则 + MCP	规则指定使用哪个服务器，MCP 进行访问	AGENTS.md：“仅使用 db-staging”
子智能体 + MCP	子智能体使用 MCP 获取外部数据	安全审计员查询 API 端点

团队文档最佳实践

为团队记录集成时，应包括：

自定义子智能体：列出每个子智能体的名称、用途以及何时调用它
AGENTS.md 规则：记录规则并附上解释每条标准“为什么”的理由
MCP 服务器：描述每个服务器的用途、访问级别（只读/写入）以及何时使用
集成工作流：提供示例工作流，展示各组件如何协同工作
故障排查：记录你的配置特有的常见问题及其解决方案

将集成文档与你的 .mcp.json 和 AGENTS.md 文件一起提交，让新团队成员能快速了解你的配置。

故障排查

问题： 子智能体未在预期时被调用

检查：

位置：文件存在于 ~/.verdent/subagents/[name].md

YAML Frontmatter：语法有效，包含必需的 name 和 description 字段

调用策略：与使用方式匹配（strict 需要显式 @-提及）

描述：智能体的 description 准确描述了应何时使用该子智能体

重启：尝试重启 Verdent 以重新加载子智能体定义

常见原因：

子智能体文件名或 @-提及拼写错误
frontmatter 中 YAML 语法无效
子智能体的 description 与任务上下文不匹配

问题： AGENTS.md 规则未被应用

检查：

位置：文件位于项目根目录

语法：有效的 Markdown，无解析错误

指令风格：使用明确的命令（“始终使用……”而非“尝试……”）

会话：开启新对话以测试规则的全新应用

冲突：检查用户规则是否意外覆盖了项目规则

常见原因：

AGENTS.md 位于错误的目录（必须是项目根目录）
模糊的指令导致 AI 有不同解读
规则已应用但结果不如预期（需优化措辞）

问题： MCP 服务器无法启动或连接

检查：

语法：.mcp.json 包含有效的 JSON（使用 jq 校验）

结构：顶层存在必需的 mcpServers 键

服务器配置：每个服务器正确指定了 command 和 args

包：MCP 服务器包可访问（npx 自动下载包；-y 标志可跳过确认提示）

环境：env 对象中的变量已在你的 shell 中正确设置

权限：服务器可执行文件具有正确的执行权限

常见原因：

JSON 拼写错误（缺少逗号、括号未闭合）
args 数组中包名错误
缺少或不正确的环境变量
网络/防火墙阻止了 npx 包安装

调试步骤：

校验 JSON：cat .mcp.json | jq .
手动测试命令：npx -y @modelcontextprotocol/server-postgres "postgresql://..."
检查环境：echo $GITHUB_TOKEN
查看 Verdent 日志以获取具体的错误信息

另请参阅

可扩展性指南

完整的扩展方法概览

MCP 集成

模型上下文协议详情

View source

集成工作流

可扩展性指南

MCP 集成

On this page