---
doc_id: "DOC-ADR-004"
title: "ADR 0004: Uỷ Thác Bản Năng: Lõi Phản Xạ 30Hz Cục Bộ Kết Hợp Multi-LLM"
category: "adr"
diataxis_type: "explanation"
status: "canonical"
version: "2026.1"
owner_role: "ai_agent_architect"
last_updated: "2026-09-29"
tags: ["adr", "ai-delegation", "war-soul-totem", "multi-llm", "offline-farming"]
related_code:
  - "server/agent/agent_decision_core.py"
  - "server/agent/llm_provider_client.py"
  - "tests/unit/test_agent_decision_core.py"
related_docs:
  - "docs/game_design/FREEEXILE_ORIGINAL_IP_AND_SYSTEMS.md"
  - "docs/architecture/GAME_ENGINE_ARCHITECTURE.md"
summary: "Quyết định kết hợp mô hình AI phân tầng: phản xạ thú tính cục bộ 30Hz (0ms) cho chiến đấu vi mô và Multi-LLM router không đồng bộ cho chiến thuật vĩ mô."
---

# ADR 0004: CHIẾN HỒN TẾ CỐT — LÕI PHẢN XẠ 30HZ CỤC BỘ KẾT HỢP MULTI-LLM

## 1. Bối Cảnh & Vấn Đề (Context)
Cơ chế **Chiến Hồn Tế Cốt (Feral War-Soul Totem)** cho phép người chơi khi bận rộn hoặc offline ủy thác nhân vật tự động săn mồi và sinh tồn trong Hoang Vực Lưu Đày.
Tuy nhiên, việc gửi mọi hành vi lên các mô hình ngôn ngữ lớn (LLMs) là bất khả thi vì:
1. Độ trễ suy luận LLM (500ms - 2000ms) quá chậm so với nhịp combat 30Hz (33.3ms/tick).
2. Chi phí API token bùng nổ khi nhân vật di chuyển và tung chiêu liên tục.
3. Rủi ro mất kết nối API khiến nhân vật đứng im và tử trận.

## 2. Các Phương Án Xem Xét (Considered Options)
1. **Thuần LLM Cho Mọi Quyết Định (Pure Cloud LLM)**:
   - *Ưu*: Hành vi thông minh, ứng biến phong phú.
   - *Nhược*: Không đáp ứng SLA 33ms; tốn kém hàng triệu USD token ở 1M CCU; thất bại hoàn toàn khi mạng lag.
2. **Thuần State Machine / Behavior Tree Đơn Giản (Pure Local Heuristic)**:
   - *Ưu*: Siêu nhanh (0ms), ổn định, chi phí 0 đồng.
   - *Nhược*: Hành vi máy móc, dễ bị quái vây bắt hoặc rơi vào bẫy địa hình lặp đi lặp lại; thiếu tính cá nhân hóa theo phong cách người chơi.
3. **Mô Hình Phân Tầng Kép (Hierarchical Hybrid AI Architecture)**:
   - **Tầng Vi Mô (Micro 30Hz - 0ms)**: Lõi Heuristic & Behavior Tree cục bộ trên server đảm nhận: né đòn (i-frame dodge), né vệt sát thương sàn (telegraph AoE), bấm bình máu khẩn cấp khi $HP < 35\%$, tự động thi triển combo võ học.
   - **Tầng Vĩ Mô (Macro Strategic Loop - Async)**: Multi-LLM Router (OpenRouter, OpenAI, Claude, Gemini, DeepSeek, Kimi) gọi nền mỗi $30 \to 60\text{ giây}$ để lập kế hoạch di chuyển, chọn tuyến đường, đánh giá túi đồ và quyết định rút lui khi gặp Boss quá sức.

## 3. Quyết Định Lựa Chọn (Decision)
**Chấp thuận Phương án 3: Kiến trúc Phân Tầng Kép (Local 30Hz Reflex + Async Multi-LLM Router).**

```mermaid
flowchart TD
    subgraph Combat30Hz ["Tầng 1: Lõi Phản Xạ Thú Tính Cục Bộ (30Hz - 0ms)"]
        Dodge["Né tránh đòn hiểm<br/>(i-frame dodge roll)"]
        Potion["Nuốt Huyết Thạch<br/>(Emergency Heal HP < 35%)"]
        Combo["Xả combo võ học<br/>(Primary & Finisher)"]
    end

    subgraph MacroLLM ["Tầng 2: Trí Tuệ Chiến Thuật Vĩ Mô (Async 30-60s)"]
        Router["Multi-LLM Provider Router<br/>(Gemini / Claude / GPT / DeepSeek)"]
        Strategy["Đánh giá chiến lược:<br/>- Chọn bãi quái cày cuốc<br/>- Phân loại trang bị nhặt được<br/>- Ra lệnh rút lui khi nguy cấp"]
    end

    MacroLLM -->|Chỉ thị chiến thuật| Combat30Hz
    Combat30Hz -->|Báo cáo chiến sự & Telemetry| MacroLLM
```

## 4. Hậu Quả & Đánh Đổi (Consequences)
- **Tích cực**:
  - Không bao giờ bị chết oan vì mạng lag (Lõi 30Hz chạy trực tiếp trên Server Authoritative Game Loop).
  - Tối ưu hóa chi phí token xuống mức tối thiểu (chỉ gọi 1 request mỗi 30-60s khi đổi khu vực).
  - Hỗ trợ đa dạng provider qua [llm_provider_client.py](file:///c:/Projects/FreeExile/server/agent/llm_provider_client.py).
- **Đánh đổi**:
  - Cần duy trì song song 2 luồng mã nguồn (Heuristic fallback và LLM planner).

## 5. Tham Chiếu Mã Nguồn (References)
- [agent_decision_core.py](file:///c:/Projects/FreeExile/server/agent/agent_decision_core.py)
- [llm_provider_client.py](file:///c:/Projects/FreeExile/server/agent/llm_provider_client.py)
- [test_agent_decision_core.py](file:///c:/Projects/FreeExile/tests/unit/test_agent_decision_core.py)