---
title: 集成工作流
description: 将 Verdent 与外部工具和服务集成的实用模式
---



### 你将学到什么

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

---

## 集成方式

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

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

---

## 常见集成模式

### 数据库开发工作流

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

**子智能体：**
```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations
```

**AGENTS.md：**
```markdown
## 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 批准前自动进行安全审查。

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

---

### 前端可访问性

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

**工作流：**
```
Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score
```

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

---

## MCP 配置示例

### 理解 MCP

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

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

### 基础设置

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

<CodeGroup>
```json PostgreSQL Server
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    }
  }
}
```

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

```json Multiple Servers
{
  "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}"
      }
    }
  }
}
```
</CodeGroup>

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

### 多环境

```json
{
  "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 服务器根据自身实现内部处理只读行为。请查阅具体服务器文档了解访问控制选项。

<Tip>
**了解更多关于 MCP：**
- [模型上下文协议规范](https://modelcontextprotocol.io/specification)
- [MCP 服务器注册表](https://mcp.so/servers) - 浏览可用的 MCP 服务器
- [官方 MCP 服务器](https://github.com/modelcontextprotocol) - PostgreSQL、GitHub、Filesystem 等
</Tip>

---

## 工作区集成

### 项目专属配置

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

**微服务示例：**
```json
{
  "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"
      ]
    }
  }
}
```

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

---

## 团队协作

### 共享的 AGENTS.md 标准

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

```markdown
# 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：** 基础规则
```markdown
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
```

**阶段 2：** 添加专项子智能体
```markdown
## Code Review
- Run @security-reviewer before PR
```

**阶段 3：** 集成 MCP
```markdown
## Database Access
- Use MCP postgres-staging for queries
```

### 策略性组合

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

### 团队文档最佳实践

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

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

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

---

## 故障排查

<Tabs>
  <Tab title="子智能体问题">
    **问题：** 子智能体未在预期时被调用

    **检查：**

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

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

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

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

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

    ---

    **常见原因：**
    - 子智能体文件名或 @-提及拼写错误
    - frontmatter 中 YAML 语法无效
    - 子智能体的 `description` 与任务上下文不匹配
  </Tab>

  <Tab title="AGENTS.md 问题">
    **问题：** AGENTS.md 规则未被应用

    **检查：**

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

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

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

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

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

    ---

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

  <Tab title="MCP 服务器问题">
    **问题：** MCP 服务器无法启动或连接

    **检查：**

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

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

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

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

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

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

    ---

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

    ---

    **调试步骤：**
    1. 校验 JSON：`cat .mcp.json | jq .`
    2. 手动测试命令：`npx -y @modelcontextprotocol/server-postgres "postgresql://..."`
    3. 检查环境：`echo $GITHUB_TOKEN`
    4. 查看 Verdent 日志以获取具体的错误信息
  </Tab>
</Tabs>

---

## 另请参阅

<CardGroup cols={2}>
  <Card title="可扩展性指南" icon="puzzle-piece" href="/docs/verdent-for-vscode/advanced-features/extensibility">
    完整的扩展方法概览
  </Card>
  <Card title="MCP 集成" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    模型上下文协议详情
  </Card>
</CardGroup>