Tạo diagram dựa trên bằng chứng với ak:tech-graph

Dùng ak:tech-graph để tạo technical diagram có chất lượng xuất bản dưới dạng SVG chỉnh sửa được và PNG độ phân giải cao. Skill biến mô tả hệ thống đã duyệt thành node, relationship, semantic arrow cùng layout, validate SVG, render cục bộ và báo cáo cả hai artifact.

Chọn ak:tech-graph cho visual artifact bền vững

Dùng ak:tech-graph khi

• Bạn cần architecture, data-flow, sequence, process, UML, ER, network hoặc agent-memory diagram để xuất bản.
• Cặp SVG và PNG tĩnh hữu ích hơn inline diagram definition.
• Ý nghĩa arrow, grouping, label và visual style phải review được.
• Bạn muốn render structured JSON fixture qua template đi kèm.

Chọn workflow khác khi

• Bạn cần diagram inline nhanh trong documentation. Dùng Mermaid workflow của project.
• Bạn cần raw source được đóng gói để phân tích. Dùng ak:repomix.
• Bạn cần repository fact trước khi vẽ. Dùng ak:scout và coi source, configuration, test cùng current docs là evidence của diagram.
• Bạn cần image không phải technical graph. Dùng image hoặc preview workflow phù hợp.

Chuẩn bị bằng chứng và renderer

Trước khi bắt đầu:

• Hoàn thành Làm quen và xác nhận Engineer Kit đã được cài cho đúng runtime cùng scope.
• Cung cấp audience, diagram type, component, boundary, relationship, flow direction, label, style mong muốn và output destination.
• Với hệ thống hiện có, xác định primary source chứng minh từng node và edge: code, manifest, schema, deployment configuration, test hoặc official architecture docs. Ghi assumption thay vì vẽ chúng như fact.
• Xác minh rsvg-convert có sẵn. Tool này đến từ librsvg và cần cho PNG export.
• Xác nhận destination chứa được cả SVG và PNG; publication hoặc upload nằm ngoài lần chạy trừ khi được duyệt riêng.

Chạy Skill

/ak:tech-graph "Tạo data-flow diagram từ authentication docs và deployment config hiện tại. Hiện browser, gateway, auth service, session store và audit sink; ghi nhãn mọi payload cùng assumption; style 1; ghi ./artifacts/auth-flow.svg và PNG."

/ak:tech-graph "Tạo data-flow diagram từ authentication docs và deployment config hiện tại. Hiện browser, gateway, auth service, session store và audit sink; ghi nhãn mọi payload cùng assumption; style 1; ghi ./artifacts/auth-flow.svg và PNG."

$ak:tech-graph "Tạo data-flow diagram từ authentication docs và deployment config hiện tại. Hiện browser, gateway, auth service, session store và audit sink; ghi nhãn mọi payload cùng assumption; style 1; ghi ./artifacts/auth-flow.svg và PNG."

Skill nhận diagram type hoặc system description và không công bố mode flag. Style 1, Flat Icon, là mặc định; style 2–7 chọn Dark Terminal, Blueprint, Notion Clean, Glassmorphism, Claude Official hoặc OpenAI Official.

Chọn generation path

Khi không có custom path, deliverable theo source là ./[derived-name].svg và ./[derived-name].png. PNG export mặc định rộng 1920 pixel. Template generator hỗ trợ structure architecture, flowchart, data-flow, sequence, comparison, timeline, mind-map, agent, memory, use-case, class, state-machine, ER và network-topology.

Hiểu các giai đoạn của lần chạy

1. Skill thiết lập factual scope. Nó tách component cùng flow có source khỏi abstraction được yêu cầu và assumption chưa giải quyết.
2. Skill phân loại diagram. Type quyết định layer, lifeline, cardinality, state, actor hoặc layout semantic khác.
3. Skill chọn style. Style reference tương ứng cung cấp color, typography, shape, spacing và arrow convention.
4. Skill lập graph. Node, edge, group, port, legend, label và routing corridor được bố trí trước khi tạo tệp.
5. Skill ghi và validate SVG. Validation kiểm tra XML, tag balance, quote, marker reference, collision arrow đơn giản, closing tag và renderer compatibility khi tool có sẵn.
6. Skill export và review PNG. rsvg-convert tạo raster artifact; runtime đọc được image kiểm tra overlap, clipped text, crossing cùng legend placement, rồi sửa và render lại khi cần.
7. Skill báo evidence và tệp. Kết quả nêu cả hai path, validation, source basis, assumption và mọi giới hạn visual review.

Giữ diagram chính xác và an toàn

• SVG và PNG là persistent file. Xác nhận trước khi ghi đè artifact hiện có hoặc ghi ngoài project boundary.
• Generation cùng rendering theo source chạy cục bộ, không cần provider, credential, network call hay paid service. Cài librsvg, đọc remote source hoặc publish output là effect riêng cần duyệt.
• Không nhúng secret, private hostname, customer data, internal URL hoặc credential vào label, metadata, file name hay screenshot.
• Tránh external font import; chúng có thể làm lỗi local rendering và thêm network dependency. Giữ font cùng SVG resource self-contained.
• Bỏ validation hoặc visual review làm giảm chất lượng evidence. Nếu không đọc được image, báo rằng visual correctness chưa được kiểm tra.

Xác minh kết quả

Kết quả hoàn chỉnh gồm graph specification dựa trên source, exact SVG cùng PNG path, diagram type và style, render width, validator result, visual review statement và unresolved assumption. Kiểm tra mọi label vừa khung, arrow nối vào edge của component, crossing rõ nghĩa, legend giải thích nhiều flow type và output vẫn đọc được ở kích thước đích.

Regression suite đi kèm render một fixture cho mỗi style, validate SVG và export PNG khi có rsvg-convert. Nó chứng minh coverage của generator cùng style, không chứng minh factual accuracy của diagram mới.

Khắc phục sự cố hoặc tiếp tục

Biết các giới hạn hiện tại

• Skill không tự khám phá architecture hoặc dependency graph; nó cần description được cung cấp hoặc project inspection đã duyệt.
• Shell validation chỉ bắt một tập structural và routing problem có giới hạn; không thay visual inspection hay accessibility review.
• Runtime phụ thuộc graph complexity và revision cycle. Template render đơn giản chạy cục bộ và nhanh; diagram xuất bản dày có thể cần nhiều vòng inspect và rerender.
• Stable và beta đóng package generator, fixture, style cùng validation workflow ak:tech-graph giống nhau.