ProbeLabs Maid — Linter & Auto-Fix Cho Mermaid Diagram

Khi viết tài liệu kỹ thuật hoặc dùng AI (LLM / Coding Agents) sinh biểu đồ, lỗi cú pháp Mermaid là vấn đề rất phổ biến khiến biểu đồ bị vỡ (syntax error). probelabs/maid ra đời như một giải pháp linter siêu nhẹ, tốc độ mili-giây giúp phát hiện và tự động sửa các lỗi cú pháp Mermaid.

flowchart LR
    subgraph Input["Nguồn Mermaid Diagram"]
        AI["AI / LLM Agent sinh Mermaid"]
        Human["Developer viết Docs / Markdown"]
    end

    subgraph Maid["probelabs/maid Engine (~5MB)"]
        Parser["Mermaid AST & Syntax Validator"]
        Fixer["Rule-based Auto-Fix Engine"]
        Parser --> Fixer
    end

    subgraph Output["Kết Quả"]
        Clean["Diagram Hợp Lệ 100%"]
        Error["Báo Lỗi Rõ Ràng & Line Number"]
    end

    Input --> Maid
    Fixer -->|"Tự động sửa lỗi phổ biến"| Clean
    Fixer -->|"Báo lỗi nếu không thể tự fix"| Error

Vấn Đề Với Các Công Cụ Truyền Thống#

Thông thường, để kiểm tra một biểu đồ Mermaid trong CI/CD hoặc local, chúng ta phải cài đặt mermaid-cli (@mermaid-js/mermaid-cli).

flowchart TB
    subgraph Traditional["mermaid-cli Truyền Thống"]
        M1["Cài đặt Node + Puppeteer + Headless Chromium"]
        M2["Dung lượng tải về: ~1.7 GB"]
        M3["Khởi động Browser tốn vài giây"]
    end

    subgraph MaidApproach["probelabs/maid"]
        P1["Standalone Parser & Linter"]
        P2["Dung lượng siêu nhẹ: ~5 MB"]
        P3["Thực thi tức thì: < 50ms"]
    end

Các Lỗi Mermaid Phổ Biến Mà Maid Tự Động Sửa#

AI khi tạo biểu đồ Mermaid thường mắc các lỗi cú pháp như ký tự đặc biệt trong nhãn node chưa được đóng ngoặc kép, hoặc dùng sai mũi tên:

flowchart TD
    Err1["1. Ký tự ngoặc đơn/kép chưa escape<br/>node[Label (Chi tiết)]"] --> Fix1["Sửa thành: node['Label (Chi tiết)']"]
    Err2["2. Nhãn text trên mũi tên sai cú pháp<br/>A -- text --> B"] --> Fix2["Sửa thành: A -->|text| B"]
    Err3["3. Cú pháp subgraph hoặc class lỗi"] --> Fix3["Chuẩn hóa cú pháp AST"]

Cách Cài Đặt & Sử Dụng#

1. Chạy nhanh qua bunx#

Không cần cài đặt toàn cục, bạn có thể quét file Markdown bất kỳ:

# Quét kiểm tra cú pháp file README.md
bunx -y @probelabs/maid README.md

# Quét đệ quy toàn bộ thư mục docs
bunx -y @probelabs/maid docs/

2. Tự Động Sửa Lỗi (—fix)#

Để Maid tự động phát hiện và áp dụng bản sửa lỗi trực tiếp vào file:

bunx -y @probelabs/maid --fix src/content/blog/

3. Tích Hợp Vào Dự Án#

Cài đặt như một devDependency để kiểm tra trong CI/CD:

bun add -d @probelabs/maid
# hoặc
npm install -D @probelabs/maid

Cấu hình script trong package.json:

{
  "scripts": {
    "lint:mermaid": "maid docs/ src/",
    "lint:mermaid:fix": "maid --fix docs/ src/"
  }
}

Tích Hợp MCP Server Cho AI Coding Assistant#

probelabs/maid cung cấp sẵn Model Context Protocol (MCP) server. Điều này cho phép các Coding Agent (như Claude Code, Antigravity, Cursor) tự động validate biểu đồ ngay trong phiên lập trình trước khi lưu file.

sequenceDiagram
    autonumber
    actor User as Developer
    participant Agent as AI Coding Assistant
    participant MCP as Maid MCP Server
    participant Doc as Markdown File

    User->>Agent: "Tạo sơ đồ kiến trúc hệ thống"
    Agent->>Agent: Tạo mã Mermaid
    Agent->>MCP: Call tool: validate_mermaid(content)
    alt Có lỗi cú pháp
        MCP-->>Agent: {"valid": false, "fixed": "...", "errors": [...]}
        Agent->>Agent: Cập nhật mã Mermaid đã sửa
    else Hợp lệ
        MCP-->>Agent: {"valid": true}
    end
    Agent->>Doc: Ghi mã Mermaid hoàn chỉnh vào file
    Agent-->>User: "Đã tạo biểu đồ chuẩn 100%"

Cấu hình MCP (mcp_config.json):

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

Sử Dụng Programmatic (Node.js SDK)#

Bạn cũng có thể import thư viện vào mã nguồn ứng dụng để kiểm tra Mermaid diagram động:

flowchart LR
    Code["Raw Mermaid String"] --> SDK["Maid SDK: lint() / fix()"]
    SDK --> Result["Diagnostics Object<br/>&#123; valid: boolean, errors: [], fixedCode: string &#125;"]

import { lint, fix } from '@probelabs/maid';

const rawMermaid = `
flowchart LR
  A[User (Client)] --> B
`;

// 1. Kiểm tra lỗi
const diagnostics = await lint(rawMermaid);
if (!diagnostics.valid) {
  console.error('Phát hiện lỗi:', diagnostics.errors);
  
  // 2. Tự động sửa lỗi
  const fixed = await fix(rawMermaid);
  console.log('Mã sau khi sửa:\n', fixed.code);
}

Kết Luận#

probelabs/maid là công cụ không thể thiếu nếu bạn thường xuyên viết tài liệu kỹ thuật chứa Mermaid diagrams hoặc làm việc với AI agents:

• Siêu nhẹ & Nhanh: Loại bỏ hoàn toàn sự cồng kềnh của Chromium / Puppeteer.
• Tự sửa lỗi AI slop: Giảm thiểu tối đa lỗi render trên GitHub / website tài liệu.
• Sẵn sàng cho Agent: Hỗ trợ MCP server chuẩn hóa cho AI workflow.

Tài liệu tham khảo#

• probelabs/maid GitHub Repository ↗
• Mermaid Official Documentation ↗
• Model Context Protocol (MCP) Specification ↗