blog.dopana

Quay lại

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.

Kết Quảprobelabs/maid Engine (~5MB)Nguồn Mermaid Diagram"Tự động sửa lỗi phổ biến""Báo lỗi nếu không thể tự fix"AI / LLM Agent sinh MermaidDeveloper viết Docs /MarkdownMermaid AST & SyntaxValidatorRule-based Auto-Fix EngineDiagram Hợp Lệ 100%Báo Lỗi Rõ Ràng & LineNumber

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).

probelabs/maidmermaid-cli Truyền ThốngCài đặt Node + Puppeteer +Headless ChromiumDung lượng tải về: ~1.7 GBKhởi động Browser tốn vài giâyStandalone Parser & LinterDung lượng siêu nhẹ: ~5 MBThực thi tức thì: < 50ms
Tiêu chímermaid-cli truyền thốngprobelabs/maid
Dung lượng~1.7 GB (kèm Chromium / Puppeteer)~5 MB (Zero heavy browser)
Tốc độ2-5 giây khởi động headless browserVài mili-giây (In-memory AST)
Tính năng Auto-fixKhông (chỉ render ảnh / báo lỗi)Có (Tự sửa lỗi cú pháp phổ biến của AI)
Tích hợp AI (MCP)Không hỗ trợCó sẵn MCP Server cho Agent

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:

1. Ký tự ngoặc đơn/kép chưaescapenode[Label (Chi tiết)]Sửa thành: node['Label (Chitiết)']2. Nhãn text trên mũi tên sai cúphápA -- text --> BSửa thành: A -->|text| B3. Cú pháp subgraph hoặcclass lỗiChuẩ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/
bash

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/
bash

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
bash

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

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

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.

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

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

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

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:

Raw Mermaid StringMaid SDK: lint() / fix()Diagnostics Object&{ valid: boolean, errors: [],fixedCode: string &}

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#