Tóm tắt nhanh:
ak-diagrambiến mô tả hệ thống của bạn thành typed JSON IR rồi biên dịch offline ra reader HTML tương tác, file SVG hoặc mảnh HTML để nhúng. Phác thảo tay thì sangak-excalidraw, hình tĩnh để đăng thì sangak-tech-graph, Mermaid trong markdown thì sangak-mermaidjs-v11. Nó không cho bạn tự đặt toạ độ hay kéo thả nút.
Công khai: mình là maintainer của AgentKit và có quan hệ affiliate: link AgentKit trong bài là link affiliate, mua qua link này bạn được giảm 30%.
Tóm tắt
Dùng khi bạn cần sơ đồ kiến trúc, workflow, thứ tự gọi API, pipeline dữ liệu hoặc vòng đời trạng thái để đồng đội mở xem, chèn vào docs hay trình chiếu, và muốn sửa IR rồi biên dịch lại là có hình mới. Không cần khi bạn chỉ muốn phác thảo tay, một hình tĩnh để in hay đăng bài, hoặc một khối Mermaid nằm ngay trong markdown.
flowchart LR
A["Mô tả hệ thống hoặc file IR"] --> B["ak-diagram"]
B --> C["Reader HTML, SVG hoặc fragment"]
C --> D["Dừng: bạn mở, nhúng hoặc gửi file"]
A -.->|"Phác thảo tay"| E["ak-excalidraw"]
A -.->|"Hình tĩnh để đăng"| F["ak-tech-graph"]
A -.->|"Mermaid trong docs"| G["ak-mermaidjs-v11"]Bốn điều cần nắm:
| Khái niệm | Câu hỏi | Ví dụ |
|---|---|---|
| Kiểu sơ đồ | Thứ bạn muốn vẽ là loại nào trong 5 kiểu? | Gateway, auth, database là architecture. Duyệt release là workflow. Thứ tự gọi API là sequence. Pipeline ETL là dataflow. Trạng thái đơn hàng là lifecycle. |
| Typed JSON IR | Bạn khai gì, và cái gì máy tự lo? | Bạn khai gw role gateway ở layer 0, auth ở layer 1, db ở layer 2 và hai đường nối. Bộ biên dịch tự chia cột, giảm đường cắt nhau. |
| Đầu ra | Sơ đồ sẽ nằm ở đâu? | Gửi cho đồng đội mở bằng trình duyệt thì dùng HTML. Chèn vào docs hay slide thì dùng SVG. Đặt vào một trang HTML có sẵn thì dùng fragment. |
| Reader tương tác | Người xem file HTML làm được gì? | / tìm nút, bấm nút để làm mờ phần còn lại, R xem đường ngắn nhất, L lọc theo role, F trình chiếu, [ ] qua chương, M phát lại hiệu ứng. |
Đánh đổi cần biết: file Mermaid .mmd được vẽ offline bằng bộ Pele đóng gói kèm, nên trông khác hình Mermaid gốc. Chỉ khi Pele không đọc được sơ đồ hoặc máy không có node, trang ra mới tải Mermaid từ CDN và cần mạng.
Prompt mẫu (bản đồ kiến trúc):
/ak-diagram Vẽ kiến trúc của <tên app>: web client gọi API gateway,
gateway gọi auth service và order service, order service ghi vào PostgreSQL
và đẩy sự kiện vào queue cho worker gửi email. Tất cả nằm trong một VPC,
trừ nhà cung cấp email ở ngoài. Xuất file HTML.| Cờ | Để làm gì | Từ ak |
|---|---|---|
--format | Chọn loại file ra: html, svg hoặc fragment | 2.15.0 |
--preset | Chọn phong cách: classic, signal-flow, blueprint, editorial | 2.15.0 |
--theme | Nền sáng hoặc tối | 2.15.0 |
--out | Đường dẫn file ra | 2.13.0 |
Phần dưới đây là bản chi tiết: luồng chạy, 6 tình huống kèm prompt, giải thích từng cờ, lịch sử thay đổi theo bản ak và các lỗi hay vấp. Bản chi tiết và trang trực quan dành cho subscriber. Agent của bạn cũng tìm được trong đó qua MCP của portal.
Mở khi tài khoản có quyền subscriber
Bài này dành cho subscriber
Khi tài khoản có quyền, toàn bộ bài, bản visual tương tác và lệnh gọi từ agent đều mở.
- Đăng nhập hoặc tạo tài khoản modernEngineerQuyền đọc gắn với email tài khoản.
- Chọn gói trên trang Bảng giáGói 1, 3 hoặc 12 tháng, trả bằng chuyển khoản VietQR. Quyền đọc mở khoảng một phút sau khi tiền về.
- Hoặc nhập mã Facebook subscriberNgười ủng hộ trang qua Facebook nhận mã kích hoạt qua tin nhắn mỗi tháng.
Đã là subscriber? Đăng nhập để đọc.
Dùng bài này trong agent của bạn
Lấy API keyChép đoạn dưới, dán vào Claude Code, Codex hay agent bạn đang dùng. Agent đọc bài rồi đối chiếu với repo đang mở.
Đọc bài "ak-diagram: sơ đồ hệ thống tương tác, máy tự xếp bố cục" trên modernEngineer rồi áp dụng vào repo này.
1. Gọi tool content_get của MCP server modernengineer với locale "vi", slug "ak-diagram". Nếu chưa nối MCP server modernengineer, dừng lại và hướng dẫn tôi nối theo https://modernengineer.dev/vi/mcp.
2. Tóm tắt các bước chính của bài, chỉ ra bước nào áp dụng được cho repo này.
3. Đề xuất thay đổi cụ thể và hỏi tôi trước khi sửa file.Nối MCP cho Claude Code (một lần)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Đọc trọn bài qua MCP cần API key của tài khoản subscriber hoặc đã mua guide này. Không có quyền, agent sẽ chỉ đọc được phần mở đầu.
- Phiên bản
- v1.0.0
- Cập nhật
- 22/10/2026
- Giấy phép
- Bảo lưu mọi quyền
- Slug
- ak-diagram
