blog.dopana

返回

在编写技术文档或使用 AI 编程助手(LLM / Coding Agents)生成图表时,Mermaid 语法错误经常导致渲染失败。probelabs/maid 是一款毫秒级响应、超轻量的 Mermaid 代码检查与校验工具(Linter),专门用于检测并自动修复 Mermaid 语法缺陷。

输出结果probelabs/maid 引擎 (~5MB)Mermaid 图表输入源"自动修复常见语法错误""无法修复时精确定位报错"AI / LLM Agent 生成的代码开发者编写的 Docs / MarkdownMermaid AST 与语法解析器基于规则的自动修复引擎100% 合法 Mermaid 图表清晰的错误报告与行号

传统工具面临的痛点#

以往在 CI/CD 或本地环境中验证 Mermaid 图表,通常依赖官方的 mermaid-cli(@mermaid-js/mermaid-cli)。

probelabs/maid传统的 mermaid-cli安装 Node + Puppeteer +Headless Chromium下载体积高达约 1.7 GB启动浏览器需数秒延迟独立 AST 解析器与 Linter体积极小:仅约 5 MB毫秒级执行:< 50ms
评估维度传统 mermaid-cliprobelabs/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. 节点文本包含括号未转义node[Label (详细信息)]修复为: node['Label (详细信息)']2. 箭头文字标签语法错误A -- text --> B修复为: A -->|text| B3. 错误的 subgraph 或 class 声明规范化 AST 结构输出

安装与使用方式#

1. 使用 npx 快速扫描#

无需全局安装,即可直接校验指定的 Markdown 文件或目录:

# 校验单个文件
npx -y @probelabs/maid README.md

# 递归检查 docs 文件夹
npx -y @probelabs/maid docs/
bash

2. 自动修复模式(—fix)#

让 Maid 自动修正语法错误并写回文件:

npx -y @probelabs/maid --fix src/content/blog/
bash

3. 项目集成#

将其作为开发依赖安装并在 CI/CD 中运行:

bun add -d @probelabs/maid
# 或
npm install -D @probelabs/maid
bash

配置 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 智能体可以在写盘前自动校验并修复图表代码。

[语法完全正确]alt[发现语法错误]12345678"生成系统架构图"生成原始 Mermaid 语法调用工具: validate_mermaid(content){"valid": false, "fixed": "...", "errors": [...]}采用自动修复后的 Mermaid 代码{"valid": true}写入经过验证的 Mermaid 代码"图表已生成且 100% 可正常渲染"开发者AI 编程助手Maid MCP ServerMarkdown 文件开发者AI 编程助手Maid MCP ServerMarkdown 文件

配置 MCP 服务(mcp_config.json):

{
  "mcpServers": {
    "maid": {
      "command": "npx",
      "args": ["-y", "@probelabs/maid", "--mcp"]
    }
  }
}
json

编程式调用(Node.js SDK)#

你也可以在应用中直接导入 SDK 进行动态检查:

原始 Mermaid 字符串Maid SDK: lint() / fix()诊断结果对象&{ valid: boolean, errors: [],fixedCode: string &}

总结#

probelabs/maid 是现代开发者和 AI 协同不可或缺的高效工具:

  • 轻量迅速:摆脱 1.7GB 的 Chromium 依赖,仅 5MB 且执行在毫秒级。
  • 专治 AI 幻觉:一键自动修复 LLM 生成的各类语法小问题。
  • Agent 友好:原生支持 MCP 协议,无缝接入 AI 编程助手生态。

参考文献#