在编写技术文档或使用 AI 编程助手（LLM / Coding Agents）生成图表时，Mermaid 语法错误经常导致渲染失败。probelabs/maid 是一款毫秒级响应、超轻量的 Mermaid 代码检查与校验工具（Linter），专门用于检测并自动修复 Mermaid 语法缺陷。
flowchart LR
subgraph Input["Mermaid 图表输入源"]
AI["AI / LLM Agent 生成的代码"]
Human["开发者编写的 Docs / Markdown"]
end
subgraph Maid["probelabs/maid 引擎 (~5MB)"]
Parser["Mermaid AST 与语法解析器"]
Fixer["基于规则的自动修复引擎"]
Parser --> Fixer
end
subgraph Output["输出结果"]
Clean["100% 合法 Mermaid 图表"]
Error["清晰的错误报告与行号"]
end
Input --> Maid
Fixer -->|"自动修复常见语法错误"| Clean
Fixer -->|"无法修复时精确定位报错"| Error
传统工具面临的痛点#
以往在 CI/CD 或本地环境中验证 Mermaid 图表，通常依赖官方的 mermaid-cli（@mermaid-js/mermaid-cli）。
flowchart TB
subgraph Traditional["传统的 mermaid-cli"]
M1["安装 Node + Puppeteer + Headless Chromium"]
M2["下载体积高达约 1.7 GB"]
M3["启动浏览器需数秒延迟"]
end
subgraph MaidApproach["probelabs/maid"]
P1["独立 AST 解析器与 Linter"]
P2["体积极小：仅约 5 MB"]
P3["毫秒级执行：< 50ms"]
end
| 评估维度 | 传统 mermaid-cli | probelabs/maid |
|---|---|---|
| 包体积 | ~1.7 GB（依赖 Chromium / Puppeteer） | ~5 MB（零重量级浏览器依赖） |
| 执行速度 | 启动需 2-5 秒 | 几毫秒（纯内存 AST 解析） |
| 自动修复（Auto-Fix） | 不支持（仅能渲染或报错） | 支持（自动修复 LLM 常见语法疏漏） |
| AI 协同（MCP） | 无 | 原生集成 Model Context Protocol (MCP) Server |
Maid 自动修复的常见 Mermaid 错误#
AI 生成 Mermaid 时经常出现括号未加引号或连线标签语法错误：
flowchart TD
Err1["1. 节点文本包含括号未转义<br/>node[Label (详细信息)]"] --> Fix1["修复为: node['Label (详细信息)']"]
Err2["2. 箭头文字标签语法错误<br/>A -- text --> B"] --> Fix2["修复为: A -->|text| B"]
Err3["3. 错误的 subgraph 或 class 声明"] --> Fix3["规范化 AST 结构输出"]
安装与使用方式#
1. 使用 npx 快速扫描#
无需全局安装，即可直接校验指定的 Markdown 文件或目录：
# 校验单个文件
npx -y @probelabs/maid README.md
# 递归检查 docs 文件夹
npx -y @probelabs/maid docs/2. 自动修复模式（—fix）#
让 Maid 自动修正语法错误并写回文件：
npx -y @probelabs/maid --fix src/content/blog/3. 项目集成#
将其作为开发依赖安装并在 CI/CD 中运行：
bun add -d @probelabs/maid
# 或
npm install -D @probelabs/maid配置 package.json 中的脚本命令：
{
"scripts": {
"lint:mermaid": "maid docs/ src/",
"lint:mermaid:fix": "maid --fix docs/ src/"
}
}为 AI 编程助手集成 MCP Server#
probelabs/maid 原生内置了 Model Context Protocol (MCP) 服务端。这使得 Claude Code、Antigravity 或 Cursor 等 AI 智能体可以在写盘前自动校验并修复图表代码。
sequenceDiagram
autonumber
actor User as 开发者
participant Agent as AI 编程助手
participant MCP as Maid MCP Server
participant Doc as Markdown 文件
User->>Agent: "生成系统架构图"
Agent->>Agent: 生成原始 Mermaid 语法
Agent->>MCP: 调用工具: validate_mermaid(content)
alt 发现语法错误
MCP-->>Agent: {"valid": false, "fixed": "...", "errors": [...]}
Agent->>Agent: 采用自动修复后的 Mermaid 代码
else 语法完全正确
MCP-->>Agent: {"valid": true}
end
Agent->>Doc: 写入经过验证的 Mermaid 代码
Agent-->>User: "图表已生成且 100% 可正常渲染"
配置 MCP 服务（mcp_config.json）：
{
"mcpServers": {
"maid": {
"command": "npx",
"args": ["-y", "@probelabs/maid", "--mcp"]
}
}
}编程式调用（Node.js SDK）#
你也可以在应用中直接导入 SDK 进行动态检查：
flowchart LR
Code["原始 Mermaid 字符串"] --> SDK["Maid SDK: lint() / fix()"]
SDK --> Result["诊断结果对象<br/>{ valid: boolean, errors: [], fixedCode: string }"]
import { lint, fix } from '@probelabs/maid';
const rawMermaid = `
flowchart LR
A[User (Client)] --> B
`;
// 1. 语法检查
const diagnostics = await lint(rawMermaid);
if (!diagnostics.valid) {
console.error('检测到错误:', diagnostics.errors);
// 2. 自动修正
const fixed = await fix(rawMermaid);
console.log('修复后的代码:\n', fixed.code);
}总结#
probelabs/maid 是现代开发者和 AI 协同不可或缺的高效工具：
- 轻量迅速：摆脱 1.7GB 的 Chromium 依赖，仅 5MB 且执行在毫秒级。
- 专治 AI 幻觉：一键自动修复 LLM 生成的各类语法小问题。
- Agent 友好：原生支持 MCP 协议，无缝接入 AI 编程助手生态。