# ĐẶC TẢ THIẾT KẾ & KỸ THUẬT: ĐỊNH HỒN THẦN CHÂU • UỶ THÁC AI AGENT ĐA MÔ HÌNH (MULTI-LLM AGENT ORB DELEGATION)
# DỰ ÁN FREEEXILE: DARK MARTIAL ASTRAL ARPG 2.5D

> **Phòng ban phụ trách**: Trưởng Bộ Phận Thiết Kế Hệ Thống (`lead_systems_designer`), Kiến Trúc Sư Server (`server_systems_architect`), Kiến Trúc Sư Tài Liệu (`lead_documentation_architect`), Giám Đốc An Ninh & Anti-Cheat (`security_anticheat_lead`).  
> **Phiên bản tài liệu**: 1.0.0-RELEASE  
> **Trạng thái thực thi**: Đã triển khai hoàn chỉnh (100% Green Test Suite, 118 unit tests passed).  
> **Áp dụng cho**: Server-Authoritative Loop, WebApp Mobile Simulator, iOS Metal Engine, Multi-LLM API Gateway.

---

## 1. BỐI CẢNH & TRIẾT LÝ THIẾT KẾ (DESIGN PHILOSOPHY & LORE)

Trong thế giới Cổ Võ Hắc Ám của `FreeExile`, tu sĩ đạt đến cảnh giới thâm sâu có thể ngưng tụ thần thức thành **Chiến Hồn Dã Tính** (Astral Avatar). Khi người chơi bận rộn công việc, học tập hoặc cần offline nghỉ ngơi, họ có thể sử dụng pháp bảo **Chiến Hồn Tế Cốt (Agent Orb)** để gửi gắm một đạo thần thức vào cơ thể nhân vật.

```
                  ┌────────────────────────────────────────┐
                  │        NGƯỜI CHƠI BẬN / OFFLINE        │
                  └───────────────────┬────────────────────┘
                                      │ Kích hoạt
                                      ▼
                        🔮 [ĐỊNH HỒN THẦN CHÂU]
                                      │
            ┌─────────────────────────┴─────────────────────────┐
            ▼                                                   ▼
┌───────────────────────┐                           ┌───────────────────────┐
│ TẦNG PHẢN XẠ CỤC BỘ   │                           │ TẦNG CHIẾN LƯỢC LLM   │
│ (30Hz Tick < 33.3ms)  │                           │ (Chu kỳ 3 - 5 giây)   │
├───────────────────────┤                           ├───────────────────────┤
│ • Né đòn i-frame <25% │◄──── Chỉ đạo chiến thuật ──│ • DeepSeek V3 / R1    │
│ • Nhặt Huyết Thạch     │     (Target Priority,     │ • OpenRouter Universal│
│ • Xuất chiêu khắc hệ  │      Stance, Route Plan)  │ • OpenAI GPT-4o       │
│ • Uống đan dược       │                           │ • Anthropic Claude 3.5│
└───────────┬───────────┘                           │ • Google Gemini 1.5   │
            │                                       │ • Moonshot AI Kimi    │
            ▼                                       └───────────────────────┘
┌───────────────────────────────────────────────────────────────────────────┐
│              SERVER-AUTHORITATIVE ENGINE & MOVEMENT AUTHORITY             │
│        (100% Xác thực chống hack, kiểm soát vị trí, sát thương, rương đồ) │
└───────────────────────────────────────────────────────────────────────────┘
```

### Điểm Đột Phá Khác Biệt:
1. **Không phải Auto-Clicker tầm thường**: Nhân vật được chỉ huy bởi mô hình trí tuệ nhân tạo lớn (LLMs hàng đầu thế giới: DeepSeek, OpenAI, Claude, Gemini, Kimi, OpenRouter) kết hợp Lõi phản xạ cơ học 0ms cục bộ (`LOCAL_TACTICAL`).
2. **Server-Authoritative Tuyệt Đối**: Mọi lệnh di chuyển, xuất chiêu, nhặt đồ đều đẩy qua hàng đợi thẩm định của Game Server (`MovementAuthorityEngine`, `CombatEngine`, `ConsignmentVault`). Cấm triệt để việc can thiệp bộ nhớ máy client.
3. **Tiếp Tục Chơi Khi Tắt Máy (True Offline Persistence)**: Server duy trì phiên phân thân ngay cả khi thiết bị di động của người chơi ngắt kết nối mạng hoặc tắt nguồn. Khi đăng nhập lại, người chơi nhận Báo Cáo Thu Hoạch Phân Thần (EXP, Huyết Thạch, Quái đã trảm).
4. **Kinh Tế Bản Vị Huyết Thạch Khép Kín**: Người chơi có thể chế tác Chiến Hồn Tế Cốt hoàn toàn từ Huyết Thạch nhặt trong game (Hắc Sơ Thạch + Huyết Hồn Thạch), không ép buộc nạp tiền.

---

## 2. PHÂN CẤP ĐỊNH HỒN THẦN CHÂU (AGENT ORB TIERS)

| Mã Định Danh Item | Tên Gọi Pháp Bảo | Thời Lượng | Nguồn Gốc Sở Hữu | Công Năng Đặc Biệt |
| :--- | :--- | :--- | :--- | :--- |
| `item_agent_orb_tier1` | **Chiến Hồn Tế Cốt - Sơ Cấp** | 2 Giờ (7,200s) | Rèn đúc (5 Khai Linh + 1 Hỗn Nguyên) hoặc Mua tại Hắc Thị Hoang Vực (200 Huyết Cổ Tệ) | Tự động di chuyển, đánh quái, khắc hệ Ngũ Hành, nhặt Huyết Thạch gần. |
| `item_agent_orb_tier2` | **Chiến Hồn Tế Cốt - Trung Cấp** | 8 Giờ (28,800s) | Rèn đúc (3 Hỗn Nguyên + 1 Thiên Mệnh) hoặc Mua tại Hắc Thị Hoang Vực (600 Huyết Cổ Tệ) | Kích hoạt tự động uống đan dược khi máu < 30%, né tránh Huyễn Ảnh Bộ i-frame 0.25s. |
| `item_agent_orb_tier3` | **Hung Ma Tế Cốt - Vô Song** | 24 Giờ (86,400s) | Rèn đúc (1 Huyết Ảnh Kính + 5 Thiên Mệnh) hoặc Mua tại Hắc Thị Hoang Vực (1,500 Huyết Cổ Tệ) | Tự động cất đồ quý vào Rương Ký Gửi Hắc Thị Hoang Vực, tối ưu hóa lộ trình săn Boss. |

---

## 3. KIẾN TRÚC ĐA MÔ HÌNH LLM (MULTI-LLM PROVIDER ARCHITECTURE)

Hệ thống cung cấp kết nối bất đồng bộ chuẩn Python 3.11 (`asyncio`, `mypy --strict`) tại [`server/agent/llm_provider_client.py`](file:///c:/Projects/FreeExile/server/agent/llm_provider_client.py):

```mermaid
flowchart LR
    A[Perception Snapshot] --> B[LLMProviderClientRouter]
    B -->|Provider: DEEPSEEK| C[DeepSeek API\ndeepseek-chat]
    B -->|Provider: OPENROUTER| D[OpenRouter Gateway\nopenrouter.ai/api/v1]
    B -->|Provider: OPENAI| E[OpenAI API\ngpt-4o-mini]
    B -->|Provider: ANTHROPIC| F[Anthropic Messages\nclaude-3-5-haiku]
    B -->|Provider: GEMINI| G[Google Gemini API\ngemini-1.5-flash]
    B -->|Provider: KIMI| H[Moonshot Kimi API\nmoonshot-v1-8k]
    B -->|Timeout >2s hoặc Offline| I[Local Tactical Reflex\n0ms Heuristic]
    C --> J[TacticalActionDecision]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K[ServerEngineLoop Queues]
```

### 3.1. Danh Sách Các Nhà Cung Cấp Hỗ Trợ:
1. **Lõi Phản Xạ Cục Bộ (`LOCAL_TACTICAL`)**:
   - Chạy 100% trên server/client nội bộ, độ trễ $0\text{ ms}$, không tốn token, không phụ thuộc internet ngoại vi.
   - Là chốt chặn an toàn (Circuit Breaker Fallback) khi các cloud API gặp sự cố.
2. **DeepSeek (`DEEPSEEK`)**:
   - Model mặc định: `deepseek-chat` / `deepseek-reasoner`.
   - Ưu thế: Tư duy chuỗi suy luận sâu (Chain-of-Thought), chi phí token cực thấp.
3. **OpenRouter Universal Gateway (`OPENROUTER`)**:
   - Model mặc định: `meta-llama/llama-3.3-70b-instruct` hoặc tùy biến người dùng.
   - Endpoint: `https://openrouter.ai/api/v1/chat/completions`.
4. **OpenAI (`OPENAI`)**:
   - Model: `gpt-4o-mini` / `gpt-4o`.
   - Chuẩn định dạng JSON Mode nghiêm ngặt.
5. **Anthropic Claude (`ANTHROPIC`)**:
   - Model: `claude-3-5-haiku-20241022` / `claude-3-5-sonnet`.
   - Endpoint Messages API với headers `x-api-key` và `anthropic-version: 2023-06-01`.
6. **Google Gemini (`GEMINI`)**:
   - Model: `gemini-1.5-flash` / `gemini-2.0`.
   - Response MIME type: `application/json`.
7. **Moonshot AI Kimi (`KIMI`)**:
   - Model: `moonshot-v1-8k` / `moonshot-v1-32k`.
   - Khả năng ngữ cảnh dài, xử lý nhật ký trận đánh nhiều giờ liên tục.

---

## 4. CHIẾN THUẬT TÁC CHIẾN (TACTICAL STANCES)

Người chơi có thể thiết lập 1 trong 4 phong cách chiến thuật khi kích hoạt Thần Châu:

| Chiến Thuật (Stance) | Biểu Tượng | Quy Tắc Ứng Xử Của Phân Thân | Ưu Điểm Nổi Bật |
| :--- | :---: | :--- | :--- |
| **Cương Mãnh (Aggressive)** | ⚔️ | Quét tìm và tiếp cận mọi quái vật trong bán kính 15m; ưu tiên dồn sát thương liên tục; chỉ né đòn khi máu < 15%. | Tốc độ cày cấp (EXP/giờ) và số quái hạ gục đạt mức cao nhất. |
| **Cân Bằng (Balanced)** | ⚖️ | Hài hòa giữa săn quái và nhặt đồ; tấn công quái đồng cấp, luân chuyển chiêu thức tương khắc Ngũ Hành; né đòn khi máu < 25%. | Khuyên dùng cho hầu hết bản đồ, an toàn và hiệu quả toàn diện. |
| **Tầm Bảo (Treasure Hunter)**| 💎 | Ưu tiên nhặt Huyết Hồn Thạch, Cổ Cốt Ấn ngay khi xuất hiện; bỏ qua quái vật nếu loot beam đang chiếu; giữ cự ly an toàn. | Thu hoạch tối đa Huyết Thạch phục vụ rèn đúc và bán trên sàn Kỳ Trân Các. |
| **Ẩn Nhẫn (Defensive)** | 🛡️ | Máu < 50% tự động lùi bước né tránh, dùng đan dược; kéo quái đơn lẻ ra xa bầy đàn; chỉ giao tranh khi thể trạng hoàn hảo. | Chống chết mất cấp độ tại các bản đồ quái cấp cao hoặc cõi Hỗn Độn. |

---

## 5. BÁO CÁO THU HOẠCH PHÂN THÂN (DELEGATION HARVEST REPORT)

Khi người chơi quay lại game và nhấn **"🛑 Thu Hồi Thần Niệm"**, hệ thống đóng phiên ủy thác và hiển thị bảng tổng kết:

```
┌────────────────────────────────────────────────────────────────┐
│           📜 BÁO CÁO THU HOẠCH PHÂN THÂN THẦN NIỆM             │
├────────────────────────────────────────────────────────────────┤
│ • Thời Gian Hoạt Động (Active Time): 01 giờ 45 phút 12 giây     │
│ • Yêu Ma Đã Trảm (Monsters Slain):   86 con                    │
│ • Tu Vi Lĩnh Ngộ (EXP Gained):       +48,200 EXP               │
│ • Đan Dược Đã Tiêu Thụ:             4 viên Hoàn Hồn Đan        │
├────────────────────────────────────────────────────────────────┤
│ 💎 LINH THẠCH & THẦN VẬT THU ĐƯỢC:                             │
│   ✨ Huyết Hồn Thạch (Primal Bloodstone): x6 viên            │
│   ⭐ Cổ Cốt Ấn (Ancient Bone Brand):          x2 viên            │
│   🔹 Hắc Sơ Thạch (Crude Flint):       x24 viên           │
└────────────────────────────────────────────────────────────────┘
```

---

## 6. SƠ ĐỒ TUẦN TỰ HOẠT ĐỘNG (SEQUENCE DIAGRAM)

```mermaid
sequenceDiagram
    autonumber
    actor Player as Người Chơi
    participant Client as WebApp Simulator / iOS Metal
    participant OrbService as AgentOrbService (Server)
    participant Core as AgentDecisionCore
    participant Router as LLMProviderClientRouter
    participant Engine as ServerEngineLoop

    Player->>Client: Nhấn [🔮 Thần Niệm Châu] -> Chọn DeepSeek + Stance Cân Bằng
    Client->>OrbService: activate_delegation(player_id, "item_agent_orb_tier1", stance, config)
    OrbService->>OrbService: Trừ 1 Thần Châu trong túi đồ, khởi tạo DelegationSession (7,200s)
    OrbService-->>Client: Xác nhận kích hoạt, hiển thị HUD Phân Thân & Luồng Suy Nghĩ
    
    loop Chu kỳ Fixed 30Hz Server Loop
        OrbService->>Core: step_tick(dt=0.033s)
        Core->>Engine: build_perception() (Vị trí, HP%, quái gần, loot beam)
        alt Cần quyết định chiến lược (Mỗi 3s)
            Core->>Router: request_tactical_decision(config, prompt)
            Router-->>Core: TacticalActionDecision (Target, Skill, Reasoning)
        end
        Core->>Engine: dispatch_plan_to_server() (Move / Attack / Dodge / Loot)
        Engine->>Engine: Authoritative verification (Tương khắc Ngũ Hành, i-frame)
    end

    Note over Player, Client: Người chơi ngắt kết nối (Offline) -> Server tiếp tục vận hành phân thân

    Player->>Client: Đăng nhập lại -> Nhấn [🛑 Thu Hồi Thần Niệm]
    Client->>OrbService: reclaim_control(player_id)
    OrbService-->>Client: DelegationHarvestReport (EXP, Huyết Thạch, Kills)
    Client->>Player: Hiển thị Modal Báo Cáo Thu Hoạch & Nhập Kho
```

---

## 7. KIỂM CHỨNG TỰ HÀNH & KẾT QUẢ TEST (TDD VERIFICATION)

Hệ thống đã trải qua chu trình kiểm thử tự hành TDD hoàn chỉnh:
- [`tests/unit/test_llm_provider_client.py`](file:///c:/Projects/FreeExile/tests/unit/test_llm_provider_client.py): 5/5 tests PASS (Định danh 7 providers, JSON parsing, timeout fallback, authorization headers).
- [`tests/unit/test_agent_decision_core.py`](file:///c:/Projects/FreeExile/tests/unit/test_agent_decision_core.py): 5/5 tests PASS (Perception snapshot, Ngũ Hành counter, low HP dodge reflex, treasure hunter loot priority).
- [`tests/unit/test_agent_orb_service.py`](file:///c:/Projects/FreeExile/tests/unit/test_agent_orb_service.py): 6/6 tests PASS (Khởi tạo session, trừ kho item, cộng dồn thời gian, offline persistence, harvest report).
- [`tests/unit/test_mobile_webapp_config.py`](file:///c:/Projects/FreeExile/tests/unit/test_mobile_webapp_config.py): 6/6 tests PASS (Kiểm chứng giao diện Modal, HUD banner, Multi-LLM options).
- **Tổng toàn bộ workspace**: **118/118 tests passed** ($100\%$ Green).