Quarto to Word (quarto-2-word)

Bộ skill và hệ thống công cụ hỗ trợ AI Agent tạo tài liệu Docx từ Quarto (.qmd) bám sát 100% template mẫu Docx bất kỳ, tích hợp vòng lặp so sánh ảnh trang trực quan (Visual Diff).

---

📂 Cấu Trúc Dự Án

quarto-2-word/
├── .agents/skills/            # Skill pack định dạng cho Multica / AI agents
│   ├── docx-template-to-qmd/  # Skill tái tạo tài liệu bám mẫu Docx
│   └── qmd-from-golden/       # Skill sinh tài liệu từ mẫu vàng .qmd
├── .claude/skills/            # Skill pack tương thích Claude Code
├── docs/                      # Tài liệu tra cứu và cẩm nang
│   ├── openxml-cookbook.md    # Cẩm nang ranh giới năng lực & catalog recipe OpenXML
│   └── skill-authoring-flow.md# Taxonomy 7 loại văn bản & flow viết skill
├── goldens/                   # Registry các mẫu vàng đã kiểm chứng
│   └── registry.md
├── tools/                     # Bộ công cụ so sánh trực quan & CLI helper
│   ├── q2w.py                 # CLI helper scaffold mẫu vàng & build 1 lệnh (Mới)
│   ├── docx2png.py            # Chuyển Docx -> PDF -> PNG
│   ├── compare_pages.py       # So sánh SSIM, Pixel diff, Heat map, Side-by-side
│   ├── openxml_core.py        # Module lõi thao tác OpenXML thuần Python
│   └── render_and_compare.sh  # Script tự động hóa 1 lệnh (Render -> Diff)
├── quarto-homework/           # Pipeline mẫu: Phiếu bài tập Toán 7 (Thương hiệu)
├── quarto-demo/               # Pipeline mẫu: Văn bản hành chính VN (Nghị định 30)
├── quarto-homework-so-thap-phan/ # Tài liệu mới sinh từ mẫu vàng
└── e2e/                       # Nghiệm thu độc lập End-to-End
    └── REPORT.md

---

🚀 Các Tính Năng Chính

1. CLI Helper 1 Lệnh (tools/q2w.py): Tự động hóa toàn diện các thao tác cho AI Agent và lập trình viên: tra cứu mẫu vàng (list-goldens), nhân bản bộ khung (init), biên dịch kèm hậu xử lý (build), và so sánh ảnh trực quan (diff).
2. Vòng lặp so sánh thị giác (Visual Diff Loop): Chụp ảnh từng trang docx do .qmd render ra so với docx mẫu, đo chỉ số SSIM + Pixel difference để tinh chỉnh liên tục.
3. Cẩm nang & Module lõi OpenXML (tools/openxml_core.py): Can thiệp sâu và chuẩn hóa các thành phần vượt quá khả năng mặc định của Pandoc (Header/Footer nâng cao, viền câu hỏi, OMML, chống ngắt khối...).
4. Mẫu vàng (Golden Templates): Kho lưu trữ các template đã chuẩn hóa để nhân bản nhanh tài liệu mới trong 1 lượt chạy.

---

⚡ Hướng Dẫn Nhanh Với CLI tools/q2w.py

# 1. Liệt kê các mẫu vàng trong registry:
python3 tools/q2w.py list-goldens

# 2. Khởi tạo tài liệu mới từ mẫu vàng:
python3 tools/q2w.py init homework-math7 ./my-new-homework "PHIẾU BÀI TẬP TOÁN 7 - ĐẠI SỐ"

# 3. Biên dịch Quarto sang DOCX kèm tự động kích hoạt script Polish OpenXML:
python3 tools/q2w.py build ./my-new-homework/homework.qmd

# 4. So sánh trực quan thị giác giữa file render và template:
python3 tools/q2w.py diff ./my-new-homework/homework.qmd ./my-new-homework/homework_template.docx --mode template

---

🛠️ Yêu Cầu Môi Trường

• quarto >= 1.10.x
• pandoc >= 3.x
• libreoffice / soffice & pdftoppm (cho tính năng render ảnh docx2png)
• python3 (kèm Pillow cho công cụ so ảnh cơ bản; scikit-image, numpy trong tools/.venv cho phân tích SSIM chuyên sâu)