在编写技术文档或使用 AI 编程助手(LLM / Coding Agents)生成图表时,Mermaid 语法错误经常导致渲染失败。probelabs/maid 是一款毫秒级响应、超轻量的 Mermaid 代码检查与校验工具(Linter),专门用于检测并自动修复 Mermaid 语法缺陷。
传统工具面临的痛点#
以往在 CI/CD 或本地环境中验证 Mermaid 图表,通常依赖官方的 mermaid-cli(@mermaid-js/mermaid-cli)。
| 评估维度 | 传统 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 时经常出现括号未加引号或连线标签语法错误:
安装与使用方式#
1. 使用 npx 快速扫描#
无需全局安装,即可直接校验指定的 Markdown 文件或目录:
# 校验单个文件
npx -y @probelabs/maid README.md
# 递归检查 docs 文件夹
npx -y @probelabs/maid docs/bash2. 自动修复模式(—fix)#
让 Maid 自动修正语法错误并写回文件:
npx -y @probelabs/maid --fix src/content/blog/bash3. 项目集成#
将其作为开发依赖安装并在 CI/CD 中运行:
bun add -d @probelabs/maid
# 或
npm install -D @probelabs/maidbash配置 package.json 中的脚本命令:
{
"scripts": {
"lint:mermaid": "maid docs/ src/",
"lint:mermaid:fix": "maid --fix docs/ src/"
}
}json为 AI 编程助手集成 MCP Server#
probelabs/maid 原生内置了 Model Context Protocol (MCP) 服务端。这使得 Claude Code、Antigravity 或 Cursor 等 AI 智能体可以在写盘前自动校验并修复图表代码。
配置 MCP 服务(mcp_config.json):
{
"mcpServers": {
"maid": {
"command": "npx",
"args": ["-y", "@probelabs/maid", "--mcp"]
}
}
}json编程式调用(Node.js SDK)#
你也可以在应用中直接导入 SDK 进行动态检查:
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);
}typescript总结#
probelabs/maid 是现代开发者和 AI 协同不可或缺的高效工具:
- 轻量迅速:摆脱 1.7GB 的 Chromium 依赖,仅 5MB 且执行在毫秒级。
- 专治 AI 幻觉:一键自动修复 LLM 生成的各类语法小问题。
- Agent 友好:原生支持 MCP 协议,无缝接入 AI 编程助手生态。