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.
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).
| Tiêu chí | mermaid-cli truyền thống | probelabs/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 browser | Vài mili-giây (In-memory AST) |
| Tính năng Auto-fix | Khô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:
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/bash2. 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/bash3. 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/maidbashCấu hình script trong package.json:
{
"scripts": {
"lint:mermaid": "maid docs/ src/",
"lint:mermaid:fix": "maid --fix docs/ src/"
}
}jsonTí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.
Cấu hình MCP (mcp_config.json):
{
"mcpServers": {
"maid": {
"command": "bunx",
"args": ["-y", "@probelabs/maid", "--mcp"]
}
}
}jsonSử 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:
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);
}typescriptKế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.