Tạo sơ đồ kiến trúc động từ JSON với live-panel

live-panel làm gì

live-panel chuyển đổi một mô tả hệ thống JSON duy nhất thành sơ đồ kiến trúc động. Bố cục được giữ cố định trong khi các gói tin di chuyển dọc theo dây nối, nhật ký cuộn, bộ đếm thay đổi, thanh chuyển trạng thái và các trình kích hoạt bên cạnh lần lượt phát sáng.

Bạn có thể xuất kết quả thành MP4 H.264 cho các nền tảng như X và Xiaohongshu, hoặc giữ lại dưới dạng một trang web live tự chứa. Kho lưu trữ cũng hoạt động như một skill theo phong cách Claude Code thông qua tệp SKILL.md.

Ví dụ về các agent Codex đi kèm tái tạo diện mạo và chuyển động kiểu terminal của một video kiến trúc do @thedelost thực hiện. Kho lưu trữ cũng bao gồm một ví dụ kiến trúc AI sáng màu pastel và một hình ảnh trực quan hóa Airbnb.

Tính năng chính

• Sơ đồ được điều khiển bằng cấu hình và định nghĩa trong JSON.
• Chủ đề trực quan nền tối kiểu terminal và sáng màu pastel.
• Các giá trị đặt sẵn cho canvas 4:5, 3:4 và 1:1.
• Gói tin, đường dẫn, nhật ký, bộ đếm, đồng hồ đo, trình kích hoạt và thay đổi trạng thái động.
• Kết xuất xác định hoàn toàn dựa trên thời gian, không dùng thời gian đồng hồ thực, Math.random hoặc hoạt ảnh CSS.
• Xuất sang MP4 hoặc giữ lại trang HTML live đã tạo.
• Tự động kiểm tra khung hình để phát hiện tràn văn bản, chồng lấn và tính nhất quán khi tua đến vị trí bất kỳ.

Cài đặt các yêu cầu

live-panel sử dụng thư viện chuẩn của Python nên không yêu cầu gói pip. Hãy cài đặt các công cụ sau trước khi kết xuất:

• Python 3.8 trở lên.
• Chrome hoặc Chromium.
• ffmpeg.

Sau khi tải kho lưu trữ, hãy xác nhận rằng python3, Chrome hoặc Chromium và ffmpeg có sẵn trong PATH hệ thống. Theo mặc định, tập lệnh kết xuất sẽ tìm Chrome và ffmpeg trong PATH.

Kết xuất một ví dụ có sẵn

Hãy bắt đầu với cấu hình các agent Codex. Lệnh sau sẽ kết xuất cấu hình JSON thành tệp MP4:

python3 scripts/render.py --config examples/codex-agents/config.json --out out.mp4

Các cấu hình ví dụ cũng cho thấy dự án kết hợp vị trí cố định với các biến máy được tạo hoạt ảnh như thế nào. Các ví dụ dựng sẵn khác nằm trong examples/agent-architecture/ và examples/airbnb/.

Để giữ lại trang web đã tạo thay vì chỉ tạo video, hãy thêm --html-out:

python3 scripts/render.py \
  --config examples/codex-agents/config.json \
  --out out.mp4 \
  --html-out page.html

Mở tệp HTML kết quả bằng trình duyệt tương thích để xem hoạt ảnh live. Bạn cũng có thể điều khiển các tùy chọn đầu ra bằng những tham số như --width, --height, --duration, --fps, --chrome, --ffmpeg, --keep-frames, --audio và --crf.

Xác thực các khung hình đã kết xuất

Trước khi xuất bản một sơ đồ, hãy chạy trình kiểm tra khung hình:

python3 scripts/check_frames.py \
  --config examples/codex-agents/config.json \
  --out-dir frames \
  --repeat

Trình kiểm tra lấy mẫu khoảng 120 mốc thời gian, đo độ tràn văn bản và mức chồng lấn của các phần tử trong DOM, đồng thời ghi các tệp PNG đại diện. Với --repeat, công cụ sẽ tua đến vị trí khác với từng khung hình đã xuất rồi kết xuất lại để xác minh rằng kết quả giống hệt. Lệnh sẽ thoát với mã trạng thái 1 nếu phát hiện vấn đề.

Tạo sơ đồ của riêng bạn

1. Sao chép một trong các tệp cấu hình ví dụ.
2. Chỉnh sửa văn bản, số, màu sắc, vị trí và cài đặt hoạt ảnh.
3. Kết xuất cấu hình đã sao chép sang MP4 hoặc HTML.
4. Chạy check_frames.py và kiểm tra các tệp PNG đã tạo.
5. Điều chỉnh bố cục rồi lặp lại cho đến khi trình kiểm tra không còn báo lỗi.

Hầu hết tùy chỉnh được thực hiện trong tệp cấu hình. Kho lưu trữ lưu ý rằng bạn không cần sửa đổi assets/template.html để tạo sơ đồ thông thường.

Cấu hình canvas và chủ đề

Một cấu hình có thể chọn giá trị đặt sẵn cho canvas, thời lượng hoạt ảnh, tốc độ khung hình và thời gian chạy trước tùy chọn:

{
  "canvas": {
    "preset": "3:4",
    "duration": 28,
    "fps": 30,
    "preroll": 0
  },
  "theme": {
    "preset": "light-pastel",
    "colors": {
      "pk": "#f0575f"
    }
  }
}

Các giá trị đặt sẵn cho canvas gồm 4:5 ở kích thước 1200×1500 pixel, 3:4 ở kích thước 1080×1440 pixel và 1:1 ở kích thước 1080×1080 pixel. Giá trị terminal-dark sử dụng cửa sổ tối, kiểu chữ monospace và các hộp văn bản phân đoạn. Giá trị light-pastel sử dụng nền trắng, các hộp pastel bo góc, mũi tên SVG bo góc và hiệu ứng phát sáng nhẹ trên các mục đang hoạt động.

Vị trí trên canvas sử dụng pixel tuyệt đối. Vì vậy, cấu hình được biên soạn cho một tỷ lệ khung hình duy nhất. Mặc dù render.py --width và --height có thể đổi tỷ lệ đầu ra bằng cách thêm dải đen, một tỷ lệ khác thường yêu cầu sao chép cấu hình và định vị lại các hộp.

Mô tả các phần tử và chuyển động

Lược đồ cấu hình hỗ trợ nhiều loại phần tử trực quan:

• text dùng cho nhãn và văn bản độc lập.
• box dùng cho các vùng chứa, bao gồm màu nền, đường viền, bán kính góc, kiểu nét đứt, các mục theo từng dòng, thanh và các đoạn văn bản.
• line và path dùng cho dây nối và các kết nối.
• glyph và rule dùng cho ký hiệu và đường phân cách.
• flow dùng cho các gói dữ liệu di chuyển dọc theo một đường đa tuyến.
• tarrow dùng cho mũi tên kích hoạt.
• log dùng cho nội dung nhật ký cuộn hoặc thay đổi.

Các giá trị thay đổi được định nghĩa trong machines. Các loại máy khả dụng gồm counter, cycle, gauge, any_low, lane và triggers. Dùng các biến này để điều khiển trạng thái hiển thị thay vì thêm logic thời gian trực tiếp vào từng phần tử.

Các hộp, đường dẫn, luồng, đường kẻ và đoạn chạy có thể sử dụng điều kiện when và then. Ví dụ, điều kiện như {"var":"seq.i","in":[0,1,2]} có thể làm nổi bật một mục khi biến máy khớp với một trong các giá trị được liệt kê. Nhiều điều kiện được xử lý như một biểu thức AND.

Tìm hiểu về phát lại xác định

Trang được tạo ra cung cấp window.seek(t). Mọi hình ảnh đều là hàm thuần túy của giá trị thời gian t, còn các lựa chọn giả ngẫu nhiên sử dụng hàm băm số nguyên với seed cố định. Ở chế độ trình duyệt thông thường, requestAnimationFrame điều khiển hoạt ảnh. Khi kết xuất, trình xuất chuyển đến thời điểm của từng khung hình bằng seek(i/fps) rồi chụp lại kết quả.

Thiết kế này giúp các khung hình xuất ra có thể lặp lại. Đây cũng là lý do bạn nên sử dụng trình kiểm tra khung hình sau khi thay đổi phông chữ, vị trí hoặc điều kiện hoạt ảnh.

Cải thiện kiểu chữ và bố cục

Các tệp phông chữ không được đóng gói. Chủ đề terminal lần lượt dự phòng qua JetBrains Mono, IBM Plex Mono, DejaVu Sans Mono, Noto Sans Mono CJK SC và phông chữ monospace chung. Chủ đề pastel sáng sử dụng Noto Sans CJK SC, PingFang SC, Microsoft YaHei, Helvetica hoặc Arial, với Noto Serif CJK SC cho các tiêu đề lớn.

Để khớp gần hơn với các ví dụ, hãy cài đặt JetBrains Mono và các phông chữ Noto CJK. Biểu tượng emoji cũng cần một phông chữ emoji màu như Noto Color Emoji. Vì các phông chữ khác nhau có độ rộng ký tự khác nhau, hãy chạy lại check_frames.py mỗi khi thay đổi các phông chữ đã cài đặt.

Mẹo kết xuất hữu ích

• Dùng ví dụ gần nhất với phong cách hình ảnh bạn muốn làm điểm bắt đầu.
• Giữ tọa độ nhất quán với tỷ lệ canvas đã chọn.
• Dùng --keep-frames khi cần kiểm tra chính xác các hình ảnh được dùng để tạo video.
• Dùng --audio none khi không muốn có bản âm thanh.
• Điều chỉnh --crf khi cần kiểm soát chất lượng video được mã hóa.
• Chạy trình kiểm tra sau mỗi thay đổi đáng kể về bố cục, phông chữ hoặc cấu hình.
• Đối với Claude Code, đặt kho lưu trữ tại ~/.claude/skills/live-panel/ hoặc trong thư mục được trình tải kỹ năng của agent sử dụng.

Tín dụng và cấp phép

Mã được phát hành theo giấy phép MIT. Thiết kế hình ảnh được các agent Codex tái tạo trong ví dụ thuộc về @thedelost, còn đồ họa thông tin kiến trúc AI sáng thuộc về tác giả gốc, nhà sáng tạo Xiaohongshu 林纾. Các số liệu về Airbnb bắt nguồn từ những phát biểu của lãnh đạo Airbnb trong một cuộc phỏng vấn trên Latent.Space, còn các bộ đếm hoạt ảnh chỉ mang tính minh họa.

Kết luận

live-panel cung cấp một quy trình thực tế để chuyển đổi các mô tả hệ thống có cấu trúc thành đồ họa chuyển động hoàn thiện và có thể lặp lại. Sao chép một ví dụ, chỉnh sửa JSON, chọn canvas và chủ đề, kết xuất MP4 hoặc trang trực tiếp, rồi dùng trình kiểm tra khung hình xác định để phát hiện vấn đề bố cục trước khi xuất bản.