# GEMINI CONTEXT & ARCHITECTURAL SITEMAP: THẬP NGŨ NIÊN (THE FIFTEEN SPRINGS)

> **Identity & Scope**: Đây là tệp ngữ cảnh kiến trúc hệ thống dành cho Gemini. Cung cấp sơ đồ định tuyến tài nguyên, phân vai module, và cẩm nang tra cứu lệnh nhanh cho quy trình sản xuất điện ảnh AI 3 giờ (180 phút).

---

## 1. PROJECT METADATA & BẢN QUYỀN
- **Tên dự án & Nhãn hiệu bảo hộ**: **THẬP NGŨ NIÊN** (Đầy đủ: **THẬP NGŨ NIÊN: ĐOẠN TRƯỜNG KÝ** / Quốc tế: **THE FIFTEEN SPRINGS** / **FIFTEEN AUTUMNS**).
- **Tác giả kiêm Chủ sở hữu IP**: **NGUYỄN SĨ SƠN** (Sinh ngày: 08/08/1990, CCCD: 031090010018).
- **Nguyên tác văn học**: *Đoạn Trường Tân Thanh - Truyện Kiều* (Đại thi hào Nguyễn Du, Public Domain).
- **Định dạng sản xuất**: 6 Tập x 30m (Full Feature), 18 Phân tập x 10m, 12 Phân đoạn x 5m, Shorts 1m (9:16 dọc).
- **Công nghệ lõi**: Gemini Banana (Imagen 3 Keyframes) + Muse2API Gateway (FastAPI OpenAI-compatible `http://127.0.0.1:18610/v1`) & Muse.ai Video Engine + PureScale 4K UHD.

---

## 2. SƠ ĐỒ ĐIỀU HƯỚNG TÀI LIỆU DỰ ÁN (DOCUMENTATION SITEMAP)

| Phân Vùng | Đường Dẫn | Vai Trò & Tài Liệu Trọng Tâm |
| :--- | :--- | :--- |
| **Chỉ thị Hệ thống** | [`AGENTS.md`](file:///C:/Projects/KieuStory/AGENTS.md) | Bộ quy chuẩn kỹ thuật, chỉ thị tự động hóa render Muse2API, bảo toàn âm thanh và safety gate. |
| **Muse2API Reference** | [`MUSE_API_AGENT_GUIDE.md`](file:///C:/Projects/KieuStory/MUSE_API_AGENT_GUIDE.md) | **Đặc tả kỹ thuật Muse2API Gateway**: Cổng REST API OpenAI-compatible (`http://127.0.0.1:18610/v1`), pooling tài khoản tự động, endpoints video/image/chat. |
| **Tổng quan Dự án** | [`README.md`](file:///C:/Projects/KieuStory/README.md) | Giới thiệu dự án, kiến trúc tổng thể, trạng thái sản xuất và thông báo sở hữu trí tuệ. |
| **Project Bible** | [`00_Project_Bible/`](file:///C:/Projects/KieuStory/00_Project_Bible/README.md) | Sổ tay đạo diễn: [MASTER_BIBLE.md](file:///C:/Projects/KieuStory/00_Project_Bible/MASTER_BIBLE.md), [CHARACTER_BIBLE.md](file:///C:/Projects/KieuStory/00_Project_Bible/CHARACTER_BIBLE.md) (32 nhân vật), [ENVIRONMENT_BIBLE.md](file:///C:/Projects/KieuStory/00_Project_Bible/ENVIRONMENT_BIBLE.md), [SAFETY_GUIDELINES.md](file:///C:/Projects/KieuStory/00_Project_Bible/SAFETY_AND_MONETIZATION_GUIDELINES.md), [TIMELINE_AND_AGING.md](file:///C:/Projects/KieuStory/00_Project_Bible/TIMELINE_AND_AGING_MATRIX.md), [CINEMATIC_AUDIO.md](file:///C:/Projects/KieuStory/00_Project_Bible/CINEMATIC_AUDIO_PIPELINE.md). |
| **Kịch bản Nguồn** | [`01_Scripts_And_Episodes/`](file:///C:/Projects/KieuStory/01_Scripts_And_Episodes/) | Kịch bản văn xuôi trường thiên 60.000 từ, nguyên tác 3.254 câu lục bát, cấu trúc 30m và 10m. *(Bảo lưu nguyên vẹn)* |
| **Kịch bản Phân cảnh** | [`FilmMaker/`](file:///C:/Projects/KieuStory/FilmMaker/README.md) | Phân cảnh điện ảnh 6 tập Hollywood format ([INDEX_VA_DANH_MUC_CANH_QUAY.md](file:///C:/Projects/KieuStory/FilmMaker/INDEX_VA_DANH_MUC_CANH_QUAY.md), TAP_01 đến TAP_06). *(Bảo lưu nguyên vẹn)* |
| **Bộ Prompt AI** | [`02_AI_Prompts/`](file:///C:/Projects/KieuStory/02_AI_Prompts/) | Dữ liệu prompt JSON sinh ảnh (`gemini_banana_prompts.json`), video (`muse_ai_video_prompts.json`), nhạc Suno. *(Bảo lưu nguyên vẹn)* |
| **Storyboards** | [`03_Storyboards/`](file:///C:/Projects/KieuStory/03_Storyboards/README.md) | Bảng phân cảnh chi tiết theo shot cho các cảnh cao trào ([Ep01_Gia_Bien_Storyboard.md](file:///C:/Projects/KieuStory/03_Storyboards/Ep01_Gia_Bien_Storyboard.md)). |
| **Tài Nguyên Sản Xuất** | [`04_Assets/`](file:///C:/Projects/KieuStory/04_Assets/) | Kho tài nguyên nhân vật theo mô hình Character-Centric (`characters/<group>/<character>/`) tích hợp chân dung master/720p, turnaround sheets & views crop; keyframes & tail frames (`keyframes/`), raw & master videos (`videos/`), bằng chứng IP (`archive/`). |
| **Pipeline Tự Động Hóa** | [`05_Production_Pipeline/`](file:///C:/Projects/KieuStory/05_Production_Pipeline/README.md) | Cỗ máy điều phối sản xuất (`production_orchestrator.py`), đa worker (`multi_worker_orchestrator.py`), quản lý tập (`episode_manager.py`), audio master (`audio_continuity_engine.py`). |
| **Không Gian Tác Nghiệp Theo Tập** | [`episodes/`](file:///C:/Projects/KieuStory/episodes/README.md) | **Đơn vị sản xuất mô-đun hóa độc lập 6 Tập (`ep01` .. `ep06`)**: Mỗi tập chứa riêng `screenplay.md`, `prose.md`, `prompts/muse_prompts.json`, `manifest.json`, `storyboards/`. **Agent chỉ nạp tập cần làm để chống loãng context.** |
| **Thư Mục Xuất Bản** | [`06_Exports/`](file:///C:/Projects/KieuStory/06_Exports/) | Video Master hoàn thiện các tập 30m, 5m và shorts 1m 9:16 dọc. |
| **Hồ Sơ Bản Quyền** | [`license/`](file:///C:/Projects/KieuStory/license/README.md) | Hồ sơ Cục Bản quyền tác giả (`01_`), Cục Sở hữu trí tuệ (`02_`), Hợp đồng thỏa thuận nội bộ & AI terms (`03_`), cẩm nang nộp thực tế ([CHECKLIST.md](file:///C:/Projects/KieuStory/license/CHECKLIST_NOP_HO_SO_THUC_TE.md)). |

---

## 3. CẨM NANG THAO TÁC NHANH (QUICK REFERENCE RUNBOOK)

```bash
# 1. Báo cáo tiến độ sản xuất theo 6 Tập độc lập:
python "05_Production_Pipeline\episode_manager.py" --status

# 2. Xem chi tiết tiến độ hoặc các shot của 1 Tập cụ thể:
python "05_Production_Pipeline\production_orchestrator.py" --status --episode ep01
python "05_Production_Pipeline\production_orchestrator.py" --list-shots ep01_scene02

# 3. Đồng bộ 2 chiều giữa từng tập và file Master:
python "05_Production_Pipeline\episode_manager.py" --sync-to-master

# 4. Kiểm tra sức khỏe Muse2API Gateway & Account Pool:
python "05_Production_Pipeline\muse_api_client.py" --health

# 5. Render 1 shot đơn lẻ (Ưu tiên Muse2API Gateway, tự động chuỗi Head-Tail):
python "05_Production_Pipeline\run_shot.py" --shot ep01_scene02_shot04 --engine muse_api
python "05_Production_Pipeline\production_orchestrator.py" --render-shot ep01_scene02_shot04

# 6. Render tự động toàn bộ 1 Cảnh theo chuỗi Head-Tail và tự động ghép Master:
python "05_Production_Pipeline\production_orchestrator.py" --batch-scene ep01_scene02

# 7. Ghép nối các shot thành Master Scene (bảo toàn 100% âm thanh AAC qua FFmpeg):
python "05_Production_Pipeline\production_orchestrator.py" --concat-scene ep01_scene02

# 8. Master âm thanh chuẩn YouTube Green Dollar (-14 LUFS) kết hợp BGM:
python "05_Production_Pipeline\production_orchestrator.py" --master-audio ep01_scene02 --bgm "04_Assets/audio_sfx/scene01_bgm.m4a"

# 9. Render Song Song Đa Phiên / Phân phối Hàng đợi Cảnh:
python "05_Production_Pipeline\multi_worker_orchestrator.py" --dispatch-queue   # Phân phối song song Scene Queue (Work-Stealing)
python "05_Production_Pipeline\multi_worker_orchestrator.py" --episode ep01     # Render song song toàn bộ cảnh trong Tập 1

# 10. Trích xuất góc nhìn Character Turnaround Sheet (Skill `cinema-shot`):
python tools/manage_turnaround_sheets.py --status
python tools/manage_turnaround_sheets.py --crop thuy_van_maiden_16yo --view portrait
python tools/manage_turnaround_sheets.py --crop thuy_kieu_maiden_16yo --view front
```

---

## 4. QUY TẮC CỐT TỬ CẦN NHỚ (GOLDEN RULES)
1. **Cô Lập Ngữ Cảnh Từng Tập (Zero Dilution & Zero Overlap)**: Khi Agent/Worker làm việc với Tập N, CHỈ ĐƯỢC nạp thư mục `episodes/ep{N}/`. Tuyệt đối không nạp kịch bản, prompt của các tập khác để tránh tràn context và xung đột dữ liệu.
2. **Động cơ Muse2API Gateway (Ưu tiên số 1 - Zero-Browser Friction)**: Toàn bộ quá trình render video Muse.ai được điều phối tự động qua cổng **Muse2API Gateway** (`http://127.0.0.1:18610/v1` - API Key tại `c:\Projects\Muse2API\data\api_key`). Gateway tự động giải quyết xoay vòng bể tài khoản (Account Pool Round-Robin/LRU) và xử lý anti-bot ngầm, triệt tiêu hoàn toàn lỗi crash trình duyệt hay khóa file lockfile. Browser session (`agent-browser --session muse`) chỉ sử dụng làm tầng dự phòng cuối cùng (fallback) khi gateway không khả dụng.
3. **Cô Lập Thư Mục Tải Về**: Mỗi worker tải file vào `04_Assets/temp_downloads/w<id>` thông qua `AGENT_BROWSER_DOWNLOAD_PATH` hoặc nhận trực tiếp stream MP4 từ Muse2API để triệt tiêu race condition.
4. **Bảo Toàn Head-Tail Chaining Nội Bộ**: Chỉ song song cấp Scene/Episode; trong cùng 1 Scene bắt buộc tuần tự (Tail Frame shot trước mã hóa base64 làm Start Frame shot sau).
5. **Audio Guard Trong Prompt**: Bắt buộc có hậu tố cấm nhạc nền, cấm tạp âm điện tử; chỉ cho phép foley, ambience và thoại.
6. **Cấm Concat Bằng OpenCV**: Bắt buộc dùng FFmpeg `filter_complex concat` (`[v][a]`) để giữ nguyên âm thanh của Muse.ai.
7. **Bảo Tồn Bằng Chứng IP**: Không xóa bất kỳ bản nháp hay render thử nghiệm nào; luôn chuyển vào `04_Assets/archive/`.
8. **Quy Chuẩn Critic Gate & Bảo Vệ Ngân Sách**: Hỗ trợ 4 tầng kiểm duyệt (`File-Bridge Host Agent`, `Antigravity SDK`, `Google GenAI`, `Offline Heuristic OpenCV/FFprobe`). Khi chạy không có API key hoặc hết hạn mức, ưu tiên File-Bridge Queue (`04_Assets/critic_queue/`) và Offline Heuristic để đảm bảo 100% tự động khép kín, 0 phụ thuộc cloud key. Ngân sách đám mây được khóa cứng ở mức $1.00 USD (`CRITIC_MAX_BUDGET_USD=1.00`).
9. **Chuẩn Hóa Quy Trình Bấm Máy Với Skill `cinema-shot`**: Trước khi bấm máy bất kỳ shot nào, BẮT BUỘC tuân thủ chu trình 6 bước của skill `cinema-shot`: Đối chiếu kho Character Turnaround Model Sheet 4 góc nhìn nằm trong từng thư mục nhân vật (`04_Assets/characters/<group>/<character>/`), trích xuất đúng góc nhìn `portrait`/`front`/`profile` vào thư mục `views/`, khóa chặt Closed Lips Guard (khẩu hình đóng khi có V.O./ngâm thơ) và Audio Guard (-14 LUFS).
10. **Kiến Trúc Điều Phối Lai (Hybrid Dual-Engine Video Routing)**:
   - **Muse2API Gateway Engine (`--engine muse_api` / `--engine muse`)**: Tự động gán cho shot Cảnh toàn (Wide Shot, Aerial, Establishing), đại cảnh hành động phức tạp cần độ phân giải 1280x720 10s và âm thanh foley tự nhiên tích hợp sẵn qua REST API bất đồng bộ.
   - **Gradio LTX-Video API (`--engine gradio_ltx`)**: Tự động gán cho shot Cận cảnh (Close-Up, MCU, CU, ECU), đặc tả chi tiết (bàn tay, ánh mắt, giọt lệ, chén trà), hoặc nháp chuyển động Previs. Chạy headless qua `gradio_client`, 0 VNĐ ($0.00), tốc độ 25s, giải phóng hoàn toàn trình duyệt.
   - **Tự động phân luồng (`--engine auto`)**: `classify_shot_engine()` trong `run_shot.py` và `production_orchestrator.py` tự động phân bổ: Close-Up -> `gradio_ltx`, Wide/Action -> `muse_api` (kèm fallback đa tầng).
11. **Quy Chuẩn Tự Động Hóa Điện Ảnh Chuẩn FlowKit (FlowKit Autonomous Engineering Pipeline)**:
   - **Zero-Waste Contact Sheet Tiling Engine (`contact_sheet_engine.py`)**: Tính toán ước số chính xác `(cols_eff, rows_eff)` sao cho `cols_eff * rows_eff == n_frames`. Triệt tiêu 100% các ô đen rác (unfilled black cells), dập tắt hoàn toàn hiện tượng Vision LLM bị ảo giác lỗi màn hình đen. Đóng dấu timestamp badge trực quan `[T=X.Xs | #Frame N]`.
   - **Danh Mục 14 Lỗi Video AI & Tường Lửa Hard Caps (`antigravity_critic_gate.py`)**: Phân tầng 14 lỗi (5 Critical: `character_drift`, `breed_swap`, `role_reversal`, `brand_logo_text`, `character_count_drift`; 5 High: `camera_drift`, `object_morph`, `reverse_motion`, `human_hands_limbs`, `scale_break`; 4 Minor: `lighting_jitter`, `micro_blur`, `background_warp`, `color_shift`). Khi phát hiện Critical: ép cứng `character_consistency <= 0.30`, `overall_score <= 0.59`, `approved = False`, `suggested_action = "RETAKE_SHOT"`. Khi phát hiện High: ép cứng `overall_score <= 0.74`, `approved = False`. Triệt tiêu hoàn toàn sự khoan dung thiên vị của LLM.
   - **Vòng Lặp Tự Sửa Lỗi Tự Hành (Diagnostic Prompt Healing - `prompt_healer.py`)**: Tự động phát hiện vector lỗi và tiêm chính xác các liệu pháp kháng lỗi (anti-drift, locked-camera, anatomy-guard) từ `ERROR_THERAPY_CATALOG` vào `motion_prompt` trước khi render lại; giới hạn cứng `MAX_HEALING_CYCLES = 2`; bảo toàn 100% Audio Guard và Closed Lips Guard ở cuối prompt.
   - **Công Thức Nhịp Điệu Cú Máy 3 Hồi & Tách Rời Camera (`prompt_healer.py`)**: Chuẩn hóa prompt theo cấu trúc thời gian 3 nhịp: `[Beat 1 (0-3s) - Thiết lập]`, `[Beat 2 (3-6s) - Kịch tính & Cảm xúc]`, `[Beat 3 (6-10s) - Lắng đọng & Nối tiếp]` kết hợp tách riêng câu lệnh `[Chuyển động Camera]` độc lập.
   - **Hậu Kỳ Tự Động Smart Trim & Khớp Giọng Đọc (`audio_continuity_engine.py`)**: Dynamic Head Trim (`-ss 1.0`) tự động phát hiện và cắt bỏ 1 giây đầu tĩnh (24 frames diff < 1.5). Narrator Fitting tự động đo đạc và khớp video theo độ dài thoại + 0.3s buffer an toàn. Smart Stitching áp dụng `xfade` (0.5s) cho `CONTINUOUS_TAKE` và hard cut cho `CINEMATIC_CUT`, chuẩn hóa đầu ra -14.0 LUFS EBU R128 stereo 48kHz.