stack-diagram là gì?
stack-diagram là một kỹ năng tác nhân AI chuyển đổi mô tả bằng tiếng Anh tự nhiên về một ngăn xếp công nghệ thành sơ đồ kiến trúc. Thay vì phải tự đặt biểu tượng và vẽ kết nối, bạn chỉ cần mô tả các dịch vụ, mối quan hệ, giao thức và quy trình triển khai trong một câu hoặc đoạn văn ngắn.
Ví dụ, lời nhắc sau mô tả một ứng dụng web, API, các dịch vụ dữ liệu và quy trình triển khai:
Sơ đồ ngăn xếp của chúng tôi: Next.js và API Hono trên Vercel. Postgres trên Neon, xác thực bằng Clerk, thanh toán bằng Stripe. GitHub Actions thực hiện triển khai.
Kỹ năng này hoạt động với Claude Code, Codex, Cursor và các tác nhân khác hỗ trợ định dạng Agent Skills.
Tính năng chính
- Nhập bằng ngôn ngữ tự nhiên: Mô tả kiến trúc mà không cần viết cú pháp sơ đồ.
- Logo chính thức: Logo được lấy từ các nguồn như SVGL, Devicon, gilbarbara/logos, kho thương hiệu chính thức và gói AWS Architecture Icons.
- Định tuyến đường nối cẩn thận: Các đường nối được định tuyến quanh nhãn để mũi tên không chạy xuyên qua văn bản.
- Giao diện sáng và tối: Mỗi sơ đồ được hiển thị ở cả hai giao diện. Các ô logo vẫn giữ màu trắng để bảo toàn màu thương hiệu gốc.
- Nhiều định dạng đầu ra: Tạo tệp HTML độc lập, ảnh PNG, component React không phụ thuộc hoặc Artifact có thể chia sẻ.
- HTML di động: Phông chữ và logo được nhúng trực tiếp, giúp tệp HTML kết quả hiển thị mà không cần truy cập mạng.
Yêu cầu
Trước khi sử dụng kỹ năng, hãy đảm bảo môi trường của bạn cung cấp:
- Python 3.9 trở lên.
- Kết nối mạng trong khi tải logo.
- Playwright với Chromium khi xuất sơ đồ thành tệp PNG.
- Một tác nhân lập trình AI hoặc ứng dụng hỗ trợ kỹ năng.
Mặc dù HTML hoàn thiện có thể hoạt động ngoại tuyến, bạn vẫn cần kết nối mạng trong quá trình tạo vì logo được tải xuống lúc build thay vì được đóng gói cùng kỹ năng.
Cài đặt stack-diagram
Cài đặt trong tác nhân lập trình được hỗ trợ
Chạy lệnh sau từ terminal:
npx skills add caru-ini/stack-diagramLệnh này cài đặt kỹ năng cho các tác nhân hỗ trợ hệ sinh thái skills, bao gồm Claude Code, Codex và Cursor.
Cài đặt trong ứng dụng Claude
Đối với ứng dụng Claude chấp nhận kỹ năng tải lên, hãy mở bản phát hành mới nhất của dự án, tải xuống stack-diagram.zip và tải tệp ZIP đó lên dưới dạng kỹ năng.
Tạo sơ đồ kiến trúc đầu tiên
Sau khi cài đặt, hãy yêu cầu tác nhân vẽ ngăn xếp. Một lời nhắc hữu ích sẽ xác định các công nghệ chính, nơi chúng chạy và cách chúng tương tác.
Sơ đồ ngăn xếp của chúng tôi: Next.js và API Hono trên Vercel.
Postgres trên Neon, xác thực bằng Clerk, thanh toán bằng Stripe.
GitHub Actions thực hiện triển khai.Mô tả này cung cấp đủ thông tin để tác nhân thể hiện frontend, API, cơ sở dữ liệu, nhà cung cấp xác thực, nhà cung cấp thanh toán và quy trình triển khai.
Nêu rõ các mối quan hệ
Để có kết quả chính xác hơn, hãy thêm giao thức hoặc kiểu tương tác khi cần. Bạn có thể nêu rằng trình duyệt truy cập ứng dụng qua HTTPS, API truy vấn cơ sở dữ liệu qua SQL hoặc một dịch vụ thực hiện cuộc gọi RPC.
Vẽ người dùng truy cập Next.js trên Vercel qua HTTPS.
Next.js gọi API Hono qua RPC.
API truy vấn Neon qua SQL và sử dụng Clerk cho các phiên.
GitHub Actions triển khai ứng dụng.Dự án sẽ hiển thị kết quả và kiểm tra sơ đồ trước khi trả về, giúp ngăn các đường nối giao nhau với nhãn.
Công cụ phát triển sơ đồ
stack-diagram không chỉ giới hạn ở hạ tầng đám mây. Công cụ này cũng có thể trực quan hóa monorepo, công cụ cục bộ, trình chạy kiểm thử, hook commit, tích hợp liên tục và hoạt động xuất bản gói.
Vẽ công cụ monorepo của chúng tôi: workspace pnpm với Turborepo, Biome, Vitest và Lefthook. GitHub Actions chạy CI và xuất bản lên npm.
Kiểu lời nhắc này xác định phạm vi workspace, các công cụ hoạt động bên trong và hệ thống tự động bên ngoài chịu trách nhiệm cho CI và xuất bản.
Sơ đồ hóa một ứng dụng AI
Sơ đồ ứng dụng AI có thể kết hợp framework web, nhà cung cấp mô hình, cơ sở dữ liệu vector, tác vụ nền và nguồn nội dung. Hãy mô tả cả đường đi của yêu cầu tương tác lẫn mọi quy trình nạp dữ liệu theo lịch.
Vẽ chatbot tài liệu của chúng tôi: Next.js trên Vercel tìm kiếm Supabase pgvector và trả lời bằng Claude. Inngest đồng bộ Notion mỗi đêm.
Ở đây, lời nhắc phân biệt luồng hỏi đáp hướng đến người dùng với quy trình đồng bộ hóa diễn ra hằng đêm.
Sơ đồ hóa hạ tầng AWS
Đối với kiến trúc AWS, hãy nêu trực tiếp các dịch vụ và ranh giới mạng. stack-diagram sử dụng các biểu tượng kiến trúc chính thức của AWS.
Vẽ ứng dụng của chúng tôi trên AWS: CloudFront đứng trước S3 và ALB trong subnet công khai. Fargate, RDS và ElastiCache nằm trong subnet riêng tư.
Mô tả này thể hiện lớp định tuyến, bộ nhớ tĩnh, bộ cân bằng tải và sự phân tách giữa các subnet công khai và riêng tư.
Chọn định dạng đầu ra
Kết quả mặc định là một tệp HTML độc lập. Bạn cũng có thể yêu cầu trực tiếp một định dạng được hỗ trợ khác trong câu lệnh:
- HTML: Phù hợp nhất cho kho mã, tài liệu nội bộ và wiki. Phông chữ và logo được nhúng trong một tệp duy nhất.
- PNG: Hữu ích cho bản trình bày và tài liệu. Việc xuất PNG yêu cầu Playwright cùng Chromium.
- Thành phần React: Thành phần không phụ thuộc có thể tích hợp vào dự án React.
- Artifact: Phù hợp để xuất bản và chia sẻ qua Claude.
Tạo sơ đồ của ngăn xếp này dưới dạng một tệp HTML độc lập:
Next.js trên Vercel gọi một API Hono, API này lưu trữ dữ liệu trong Neon.Các tệp PNG và thành phần React được kết xuất từ cùng một tệp HTML nền tảng, giúp duy trì tính nhất quán giữa các định dạng đầu ra.
Sử dụng giao diện sáng và tối
Mỗi sơ đồ được kết xuất với giao diện sáng và tối. Các ô công nghệ vẫn giữ màu trắng để logo chính thức duy trì màu gốc, trong khi nhãn nhóm có thể chuyển sang logo thương hiệu phù hợp với giao diện tối.
Khi xuất bản đầu ra trong kho mã hoặc wiki, hãy giữ cả hai giao diện nếu người đọc có thể sử dụng các bảng màu giao diện khác nhau.
Mẹo nâng cao khi viết câu lệnh
Mô tả hướng di chuyển của lưu lượng
Danh sách sản phẩm cho biết ngăn xếp bao gồm những gì, nhưng ngôn ngữ chỉ hướng giải thích cách hệ thống hoạt động. Hãy sử dụng các động từ như gọi, truy vấn, phục vụ, xuất bản, triển khai và đồng bộ.
Nêu rõ ranh giới và vị trí
Cho biết các thành phần có dùng chung một môi trường triển khai, thuộc cùng một workspace hay nằm trong các subnet công khai và riêng tư. Những chi tiết này giúp sơ đồ nhóm đúng các thành phần liên quan.
Đưa vào lịch chạy và tự động hóa
Nếu một quy trình chạy hằng đêm, sau mỗi lần commit hoặc trong quá trình triển khai, hãy đưa thông tin đó vào. Điều này giúp phân biệt các quy trình nền với luồng yêu cầu chính.
Yêu cầu đúng định dạng đầu ra
Chỉ định đầu ra HTML, PNG, React hoặc Artifact khi định dạng HTML mặc định không phù hợp với nhu cầu của bạn. Để có kết quả dễ chia sẻ và hoạt động ngoại tuyến, hãy yêu cầu một tệp HTML độc lập.
Giữ nguyên tài sản thương hiệu
Dự án không đổi màu hoặc vẽ lại logo. Tên thương hiệu và logo vẫn là nhãn hiệu của các chủ sở hữu tương ứng, và sự hiện diện của chúng trong sơ đồ không hàm ý sự chứng thực.
Lưu ý về cấp phép
Mã nguồn và tài liệu của dự án sử dụng Giấy phép MIT. Các phông chữ đi kèm sử dụng SIL Open Font License 1.1. Logo không được đóng gói; chúng được tải xuống trong quá trình tạo từ các bộ sưu tập logo được hỗ trợ, AWS, Lucide hoặc các nguồn và kho lưu trữ thương hiệu chính thức.
Kết luận
stack-diagram cung cấp một cách nhanh chóng để biến mô tả kiến trúc ngắn gọn thành hình ảnh trực quan hoàn chỉnh với logo chính thức, tuyến kết nối dễ đọc, hỗ trợ giao diện và nhiều tùy chọn xuất. Hãy cài đặt skill, mô tả rõ ràng các thành phần và mối quan hệ, rồi yêu cầu định dạng đầu ra phù hợp với quy trình tài liệu hoặc chia sẻ của bạn.