Bản tiếng Anh:
SKILL.en.md
O que diagram — sơ đồ & biểu đồ faz?
Skill mỏng, có 2 script: scripts/mmd2png.py (Mermaid → PNG, local-only mặc định qua mmdc; remote chỉ khi chọn rõ) và scripts/chart.py (biểu đồ số liệu → PNG, matplotlib qua uv hoặc Python có sẵn). Nguồn nằm cạnh output, không ghi đè file có sẵn.
Bảng route theo nhu cầu
| Nhu cầu | Cách làm |
|---|---|
| Flowchart / sequence / class / state / ER / gantt / kiến trúc hệ thống | Mermaid → scripts/mmd2png.py (mặc định chỉ dùng mmdc local) |
| Biểu đồ cột / tròn / line từ số liệu thật | scripts/chart.py (matplotlib; uv có thể cần mạng nếu package chưa có trong cache) |
Sơ đồ nhúng báo cáo .report.docx | PNG +  trong .report.md, xuất docx theo skill paper và recipe doc |
| Sơ đồ ngoài khả năng Mermaid/matplotlib (3D, đồ hoạ tuỳ biến cao) | [N/A] — báo user rõ giới hạn, không bịa cách |
Quy tắc
- Output cạnh nguồn:
<tên_gốc>.diagram.png(ảnh) +<tên_gốc>.diagram.mmd(nguồn Mermaid, sửa được). Không ghi đè file nguồn. - Mermaid: viết vào
.mmd, renderpython3 scripts/mmd2png.py '<f>.mmd' '<f>.diagram.png'; nhãn sơ đồ theo ngôn ngữ người dùng nói. - Số liệu vẽ vào biểu đồ phải là số đo/thuật từ nguồn (nhãn
[fact]/[observed]); không vẽ số bịa. - Local-first, không gửi nguồn âm thầm: mặc định
mmd2png.pychỉ dùngmmdc; thiếu CLI/browser hoặc lỗi thì dừng và báo lý do, không gọi mạng. Càinpm i -g @mermaid-js/mermaid-clivà Chrome/Chromium. Chỉ khi người dùng/agent chọn rõ mới đặtMMD2PNG_BACKEND=remote(Kroki rồi mermaid.ink),krokihoặcink.chart.pyxử lý local;uv run --with matplotlibcó thể cần mạng để lấy package nếu chưa cài/cache, nên khi offline dùng Python có matplotlib sẵn hoặc cache đã chuẩn bị. - Verify trước khi giao:
mmd2png.pytự kiểm PNG magic + dung lượng ≥ 1 KB, ảnh JPEG từ remote được convert sang PNG thật bằng ImageMagick (thiếu converter → ghi<f>.jpg+ cảnh báo, không giả làm.png); khi nhúng báo cáo → kiểm lại bằngpdfinfo+pdftotextsau khi convert DOCX→PDF (ảnh hiển thị, không vỡ trang). - Kích thước: mỗi sơ đồ 1 ý, font đủ đọc; sơ đồ quá rộng → tách nhỏ thay vì để trình soạn thảo co cụm.
- Nhắc ngôn ngữ input — trả lời cùng ngôn ngữ người dùng nói.
scripts
scripts/mmd2png.py— Mermaid → PNG (local-only mặc định; remote opt-in quaMMD2PNG_BACKEND):python3 scripts/mmd2png.py '<f>.mmd' '<f>.diagram.png' [--scale 2] [--size 1600] [--theme forest]scripts/chart.py— số liệu CSV (2 cột: nhãn,giá trị) → PNG:uv run --with matplotlib python3 scripts/chart.py '<f>.csv' '<f>.diagram.png' <bar|pie|line>