Figma Native — Evidence Engine cục bộ cho Figma bằng Rust

Tách biệt trách nhiệm

Kiến Trúc Tách Biệt Tuyệt Đối

Điểm mấu chốt của figma-native: Qwen không phải Planner. Qwen không cần nhớ lịch sử điều tra hay toàn bộ cấu trúc file lớn, chỉ tập trung dịch câu hỏi thành câu lệnh SQL SQLite chính xác.

1. ChatGPT (Planner)

Chiến lược & Quyết định

✓ Quyết định WHAT / WHY / decomposition
✓ Tạo tối đa 3 câu hỏi TSV cho round kế
✓ STOP investigation, dựng HTML/CSS và Asset Manifest

Đầu ra: questions_roundN.tsv • HTML/CSS • assets_*.tsv

2. Qwen Local (Coder)

Dịch sang SQL thuần túy

✓ Chỉ nhận case_id + question
✓ Dịch sang đúng 1 câu lệnh SQLite read-only
✓ Tự repair tối đa đúng 1 lần

Runtime: Qwen2.5-Coder-7B GGUF

3. Rust Engine

Thực thi, Guard & quản trị

✓ Bootstrap Figma API & chuẩn hóa SQLite
✓ SQL Guard: chặn triệt để mutating statements
✓ Materialize SVG + verify PNG theo Asset Manifest

Binary: dist/figma-native

4. SQLite canonical DB

Kho lưu trữ Snapshot & nguồn Evidence

✓ Lưu trọn vẹn nodes, layout, text, geometry
✓ Cố định Snapshot identity qua SHA-256
✓ Mở chế độ PRAGMA query_only=ON

Storage: figma-native.sqlite

Pipeline vòng đời

Quy Trình Hoạt Động End-to-End

Trong investigate, Round 1 là canonical document acquisition duy nhất; Round 2+ chạy SQLite-only. Sau STOP, assets là boundary riêng để materialize SVG và verify raster theo Asset Manifest.

1

Round 1: Bootstrap

Canonical document acquisition

Nhận URL Figma, kiểm tra HTTP 429 retry, phân giải cấu trúc cây JSON, nạp giao dịch vào SQLite, tính toán mã băm SHA-256 tạo Snapshot ID và kết xuất phần Profile tĩnh ban đầu vào evidence_bundle.md.

> figma-native investigate --url ... --db ... --evidence-out ...

2

Round 2+: TSV Cases

Qwen local & SQL read-only

Đọc tệp TSV chứa tối đa 3 câu hỏi. Qwen chạy cục bộ qua native llama.cpp chuyển sang SQL. Rust lọc qua SQL Guard, chạy với ngân sách thích ứng, tự sửa lỗi 1 lần nếu gặp lỗi kỹ thuật, và ghi nối tiếp chứng cứ.

> figma-native investigate --cases questions_round2.tsv

3

ChatGPT đánh giá & STOP

HTML/CSS + Asset Manifest

ChatGPT duyệt evidence. Khi đủ, thực hiện STOP, dựng HTML/CSS và xuất assets_<target>.tsv; nếu có raster manual thì xuất thêm assets_<target>_manual_verify.tsv.

HTML + CSS + Asset Manifest đã sẵn sàng

4

Asset Materialization

Deterministic & không cần AI

Rust đọc Asset Manifest đã chốt. figma_svg được batch qua một Tier-1 image request, validate rồi atomic write. browser_manual/png chỉ được kiểm tra pending_manual_export hoặc present_manual, không bị ghi đè.

> figma-native assets --manifest assets_target.tsv --root target-page

Trình diễn trực tiếp

Trình Mô Phỏng Điều Tra

Trực quan hóa cách dữ liệu được truy vấn và nối thêm vào Evidence Bundle qua từng Round.

GIAI ĐOẠN THU THẬP Bootstrap Figma URL & ingest vào SQLite

DB: figma-native.sqlite Snapshot: e82a9f14c012...

Đầu vào lệnh CLI & tham số

# Lệnh đã thực thi:

FIGMA_ACCESS_TOKEN='***' ./dist/figma-native investigate \
  --url 'https://figma.com/design/FILE_KEY/demo?node-id=0-1' \
  --db ./figma-native.sqlite \
  --evidence-out ./evidence_bundle.md

Các hành động Rust thực hiện:

• Parse file_key và node_id (1:2307)
• Gọi Figma API v1 với HTTP timeout 45s
• Ingest transaction vào SQLite (nodes, geometry, text...)
• Khởi tạo .figma-native-session.json

Trạng thái kỹ thuật: executed

Dữ liệu ghi vào Evidence Bundle (Markdown)

# Hồ sơ Database
- Nodes: tổng 512
  - FRAME: 236
  - TEXT: 211
  - VECTOR / Assets: 55
- Phạm vi Layout: 236 frame (Auto-layout, wrap, padding)
- Phạm vi Text: 211 node (font styles, character length)
- Provenance: SHA-256 e82a9f14c01258d4a97401bf
Bước tiếp theo: cung cấp questions_round2.tsv (tối đa 3 case)

Hồ sơ dữ liệu (Database Profile) giúp ChatGPT hiểu trước bức tranh toàn cảnh để lập danh sách câu hỏi điều tra chính xác nhất.

SQLite Schema chuẩn hóa

Cấu Trúc Bảng Chuẩn Hóa Của Figma

Tất cả chi tiết của bản thiết kế được phân bổ vào các bảng chi tiết với khóa chính kết hợp (snapshot_id, node_id), ngăn ngừa việc trộn lẫn dữ liệu giữa các phiên bản.

Bảng: nodes

Lưu trữ phả hệ node, quan hệ cha-con và thuộc tính chung của phần tử

PRAGMA foreign_keys=ON;

Cột	Kiểu	Mô tả & mục đích

Mẫu truy vấn minh họa

SELECT node_id, name, node_type, depth FROM nodes WHERE depth = 1 ORDER BY child_index ASC;

Điều kiện STOP thực dụng

Quy Tắc Dừng (STOP Gate) Thực Dụng

Mục tiêu không phải là tạo ra 100% bằng chứng vô hạn. Khi đủ evidence, workflow STOP investigation, dựng HTML/CSS và Asset Manifest; binary asset acquisition không phải lý do để tiếp tục query SQLite.

Bảng Kiểm Định Evidence (STOP Checklist) 0 / 8 hoàn thành

Đã xác định root/subtree cần dựng Tìm thấy frame cha chính (ví dụ Frame About node-id 1:2307)

Hierarchy chính đủ rõ Thứ tự các phần tử cha-con, cấp độ phân nhóm trong layout

Geometry của block chính đủ rõ Chiều rộng, chiều cao (ví dụ: Frame 1440x1788, Header 1440x164)

Layout/Spacing chính đủ rõ Auto-layout directions, gap, itemSpacing và padding

Text và Typography chính đủ rõ Font size, font weight, line-height và chuỗi ký tự hiển thị

Fills/Strokes/Effects cần thiết đủ rõ Mã màu nền, border radius (bo tròn góc), shadow cơ bản

Asset references/candidates đã được nhận diện Đã xác định semantic node, acquisition, format và target_path cần đưa vào Asset Manifest

Không còn technical failure chặn việc dựng Mọi query đều executed hoàn tất mà không gặp lỗi Guard

Trạng Thái Quyết Định Của ChatGPT

Khi đánh giá evidence bundle sau mỗi round điều tra:

TIẾP TỤC ĐIỀU TRA

Bằng chứng chưa đủ để dựng phiên bản đầu tiên của giao diện. Đang cần thêm thông tin về layout, cây thư mục hoặc typography.

Gợi ý kỹ thuật: Nếu sau khi render thử nghiệm phát hiện sai lệch (gap) cụ thể như sai màu sắc hoặc thiếu icon, chỉ mở thêm 1 Round mới nhắm trực diện vào gap đó thay vì truy vấn lại toàn bộ trang.

Assets sau giai đoạn investigation

Lấy Assets Đúng Từ Figma

Sau khi ChatGPT đã xác định đúng node và tạo Asset Manifest, phần lấy file asset trở nên rất đơn giản: SVG có thể tạo chính xác từ Figma bằng API, còn PNG được export thủ công từ trình duyệt theo đúng tên file đã khai báo. Bạn không cần để AI tự đoán lại asset ở bước này.

1

SVG: lấy trực tiếp bằng Figma API

Với asset có loại figma_svg/svg, figma-native assets dùng đúng node_id đã xác định trong investigation để yêu cầu Figma render SVG.

• Không tự vẽ lại SVG bằng AI.
• Không cần đoán path hoặc icon shape.
• File được ghi đúng target_path đã khai báo trong Asset Manifest.
• Nhiều SVG được gom vào một Tier-1 batch request.

2

PNG: export thủ công theo manifest

Với raster image, file assets_about_manual_verify.tsv đóng vai trò checklist: mỗi dòng cho biết chính xác node nào cần export và tên file nào phải lưu.

Mở Figma trong trình duyệt → chọn đúng node → Export PNG → lưu đúng target_path trong TSV → chạy verify.

Ví dụ: manifest khai báo assets/about-image.png thì file export phải có đúng tên và đúng path đó.

3

Muốn tiết kiệm API usage?

Bạn cũng có thể tự export SVG trực tiếp từ Figma bằng trình duyệt thay vì gọi Figma API. Đây là lựa chọn manual khi muốn giảm API usage hoặc không muốn dùng token cho bước materialization.

Khi làm theo cách này, vẫn nên giữ Asset Manifest làm nguồn chuẩn cho node_id, role và target_path. Luồng manual SVG nằm ngoài cơ chế browser_manual/png hiện tại.

CÁCH 1 — TỰ ĐỘNG LẤY SVG QUA FIGMA API

FIGMA_ACCESS_TOKEN='figd_...' ./dist/figma-native assets \
  --manifest ./output/assets_about.tsv \
  --root ./output/about-page

Lệnh này materialize các row figma_svg/svg và đồng thời báo những PNG nào vẫn đang chờ export thủ công.

CÁCH 2 — XÁC MINH PNG SAU KHI EXPORT TRÊN TRÌNH DUYỆT

./dist/figma-native assets \
  --manifest ./output/assets_about_manual_verify.tsv \
  --root ./output/about-page

Nếu tất cả PNG đã được lưu đúng tên và đúng path, trạng thái sẽ là present_manual. Bước verify này không cần Figma token và tạo 0 Figma API requests.

Tóm tắt

SVG tự động

Figma API → đúng node → đúng SVG → đúng filename.

PNG thủ công

Đọc manual TSV → export bằng browser → lưu đúng target_path → verify.

Tiết kiệm API

Có thể tự export cả SVG; Asset Manifest vẫn là mapping chuẩn để tránh sai node hoặc sai tên file.

CLI cho developer

Giao Diện Dòng Lệnh (CLI Reference)

Binary có hai nhóm workflow rõ rệt: investigate để thu thập evidence và assets để materialize Asset Manifest sau STOP.

ROUND 1: BOOTSTRAP Yêu cầu Figma token

Tải cấu trúc thiết kế từ Figma, chuẩn hóa vào SQLite và tạo static profile đầu tiên.

FIGMA_ACCESS_TOKEN='figd_...' ./dist/figma-native investigate \
  --url 'https://www.figma.com/design/FILE_KEY/page?node-id=0-1' \
  --db ./figma-native.sqlite \
  --evidence-out ./output/evidence_bundle.md

ROUND 2+: CHẾ ĐỘ CASE Hoàn toàn offline

Chỉ nhận tệp TSV chứa tối đa 3 câu hỏi; đường dẫn DB và Evidence được khôi phục tự động từ Session.

./dist/figma-native investigate \
  --cases ./output/questions_round2.tsv

ASSETS: MATERIALIZE SVG cần Figma token

Đọc canonical Asset Manifest, materialize toàn bộ SVG deterministic và append Asset Handoff.

FIGMA_ACCESS_TOKEN='figd_...' ./dist/figma-native assets \
  --manifest ./output/assets_about.tsv \
  --root ./output/about-page

ASSETS: XÁC MINH MANUAL 0 Figma requests

Sau khi export PNG thủ công, chạy manual-only manifest để xác nhận present_manual.

./dist/figma-native assets \
  --manifest ./output/assets_about_manual_verify.tsv \
  --root ./output/about-page

TIỆN ÍCH: SCHEMA Khám phá cấu trúc

In cấu trúc cơ sở dữ liệu rút gọn (compact Schema) ra màn hình để lập kế hoạch câu hỏi.

cargo run -- schema --db ./figma-native.sqlite

XÁC MINH: 119 TESTS Bảo đảm an toàn

Chạy test suite tích hợp gồm 119 test: kiểm tra SQL Guard, tính bất biến của snapshot và adaptive budget.

cargo test --manifest-path Cargo.toml

Guard & Bảo Mật

Cơ Chế Bảo Vệ SQL

Qwen có thể sinh mã SQL ngẫu nhiên, nhưng Rust đóng vai trò người gác cổng kiên cố với 2 lớp guard trước khi prepare statement.

Chặn toàn bộ mutation & DDL

Các từ khóa sau bị từ chối ngay lập tức: INSERT, UPDATE, DELETE, DROP, ALTER, ATTACH, VACUUM. Chỉ cho phép các mệnh đề SELECT và WITH RECURSIVE.

Deterministic Aggregate Guard

Ngăn chặn hành vi non-deterministic của SQLite khi câu lệnh gom nhóm aggregate vô tình chiếu các cột không nằm trong mệnh đề GROUP BY.

Adaptive Result Budget

Không bắt Qwen tự viết LIMIT. Rust tự động mở rộng trần dữ liệu: 128 dòng (32 KiB) → 512 dòng (128 KiB) → 2048 dòng (512 KiB) nếu bị tràn kết quả.

Evidence Engine cục bộ cho Figma bằng Rust & SQLite