Biên dịch system map tương tác với ak:diagram

Dùng ak:diagram khi bạn cần system map tương tác đã được validate hoặc editorial diagram. Skill biên dịch typed JSON IR cho architecture, workflow, sequence, dataflow và lifecycle, đồng thời vẫn render Mermaid, editorial template cũ và HTML đã chuẩn bị.

Chọn ak:diagram theo artifact

Dùng ak:diagram khi

• Bạn cần architecture, sequence, workflow, dataflow hoặc lifecycle map tương tác từ typed JSON.
• Bạn cần SVG, HTML self-contained, PNG hoặc video ngắn từ Mermaid hay editorial input.
• Bạn cần biên dịch cục bộ, xác định được, không CDN.

Chọn workflow khác khi

• Bạn muốn Mermaid source có thể review mà không có editorial framing. Dùng ak:mermaidjs-v11.
• Bạn cần editable canvas hoặc codebase auto-map. Dùng ak:excalidraw.
• Bạn cần khám phá và phân tích large graph. Dùng ak:graphify.
• Bạn đang quyết định visual explanation có hữu ích hay không. Bắt đầu với ak:preview.

Gọi Skill

Hoàn tất Làm quen, và xác nhận Engineer Kit đã được cài cho runtime cùng scope của bạn. Cung cấp input file, artifact mong muốn và có cho phép browser rendering, video capture hay dependency installation không.

/ak:diagram "Compile architecture.json to interactive HTML in ./build. Use preset classic and theme dark. Do not install dependencies."

/ak:diagram "Compile architecture.json to interactive HTML in ./build. Use preset classic and theme dark. Do not install dependencies."

$ak:diagram "Compile architecture.json to interactive HTML in ./build. Use preset classic and theme dark. Do not install dependencies."

Đây là Skill invocation flag:

Helper render.py / record.py đi kèm vẫn nhận --input, --title, --caption, --no-png, --no-svg, --dry-run, --snapshot-profile, --duration, --fps, --gif và --keep-frames. Các control helper đó không phải Skill invocation flag.

Chọn input tier

Typed IR là đường ưu tiên cho system map. HTML tương tác xác định được và tôn trọng prefers-reduced-motion: reduce.

Tách static rendering khỏi video recording

Static rendering helper luôn ghi <basename>.html và mặc định còn ghi:

• <basename>.png — screenshot 2× với animation được freeze ở final frame;
• <basename>.svg — chỉ khi trang đã render có SVG và có thể extract.

Control --no-png và --no-svg bỏ các output tương ứng. --dry-run ghi HTML mà không khởi động browser. HTML là animated surface; PNG là static frame đã freeze. SVG extraction serialize SVG đầu tiên được tìm thấy trong rendered DOM; bước này không bảo đảm mọi input đều có SVG hoặc page-level CSS, font, asset hay animation context vẫn hoạt động độc lập. Hãy kiểm tra static artifact đã extract.

Video là bước recording riêng trên HTML input. MP4 là default; --gif của recording helper chọn GIF được tạo bằng palette. Helper pause browser animation, tăng currentTime từng frame theo --duration và --fps được yêu cầu, chụp temporary PNG frame rồi dùng ffmpeg để ghép kết quả. Mermaid không có native animation primitive trong workflow này: animated Mermaid connector cần post-processing, còn HTML đã chuẩn bị có thể dùng tám bundled CSS connector effect. Các effect này freeze khi prefers-reduced-motion: reduce hoạt động.

Probe dependency mà không cài đặt

Yêu cầu Skill chạy bundled dependency probe trước rendering. Probe báo readiness và không bao giờ tự cài đặt. Probe kiểm tra:

HTML-only composition có thể tránh browser bằng --dry-run của helper. PNG hoặc SVG render qua browser cần Playwright và Chromium. Video cần thêm ffmpeg. Hãy coi cài đặt dependency còn thiếu là action riêng cần được duyệt.

Hiểu determinism và visible effect

Mermaid được pin, animation được freeze, browser setting cố định và frame stepping hỗ trợ output có thể tái lập với toolchain Chromium, font và ffmpeg cố định. Snapshot comparison từ chối browser hoặc font profile sai thay vì báo hash drift gây hiểu lầm. Ngoài profile đó, browser hoặc ffmpeg version, font substitution, label wrapping và Mermaid auto-layout có thể làm pixel, encoding hoặc hash thay đổi. Animated HTML vẫn động; PNG là một state đã freeze, còn MP4 hoặc GIF là frame sequence tường minh. Hãy ghi lại tool version thực sự được dùng.

Bundled Mermaid, template, style và effect là local, không cần CDN. Tuy nhiên, HTML do người dùng cung cấp có thể liên hệ network khi tham chiếu remote script, font, image hoặc asset khác. Skill không publish, upload, commit hay push artifact được tạo trừ khi workflow riêng được cho phép rõ ràng.

Kết quả đầy đủ báo input tier, type cùng variant đã chọn, exact output, dependency thực sự dùng, ranh giới static hoặc video, visual review, network activity, file bị overwrite và mọi renderer hoặc font-profile condition chưa được xác minh.