# Báo Cáo Khai Thác Đặc Tả Kỹ Thuật (Specification Mining Report)
## Hệ Thống AI Agent, Chiến Hồn Tế Cốt (Feral Totem) & Máy Chủ Uy Quyền (Server Authority)

**Mã phân bổ**: `spec_miner_freeexile_ai_1`  
**Ngày thực hiện**: 2026-10-01T00:54:00Z  
**Mục tiêu**: Khai thác toàn diện hiện trạng mã nguồn, cấu trúc dữ liệu, cơ chế điều phối và ràng buộc kiến trúc của FreeExile nhằm phục vụ bước nhảy vọt AI Agent và Lộ trình 2026-2027.

---

## 1. OBSERVATION (Quan Sát Trực Tiếp Từ Mã Nguồn)

### 1.1. Cấu Trúc Dữ Liệu & Enums Cốt Lõi
Trực tiếp ghi nhận tại [`server/world/agent_orb_service.py`](file:///c:/Projects/FreeExile/server/world/agent_orb_service.py) và [`server/agent/`](file:///c:/Projects/FreeExile/server/agent/):

1. **`AgentOrbTier`** (`server/world/agent_orb_service.py:18-21`):
   ```python
   class AgentOrbTier(str, Enum):
       TIER_1 = "item_agent_orb_tier1"  # Sơ Cấp 2 Giờ (7,200s)
       TIER_2 = "item_agent_orb_tier2"  # Trung Cấp 8 Giờ (28,800s)
       TIER_3 = "item_agent_orb_tier3"  # Vô Song 24 Giờ (86,400s)
   ```
   - Thời lượng chuẩn hóa tại `ORB_DURATIONS: Dict[str, float]`: `{TIER_1: 7200.0, TIER_2: 28800.0, TIER_3: 86400.0}`.
   - Danh xưng hiển thị tại `ORB_NAMES: Dict[str, str]`: Sơ Cấp 2H ("Chiến Hồn Tế Cốt - Sơ Cấp"), Trung Cấp 8H ("Chiến Hồn Tế Cốt - Trung Cấp"), Vô Song 24H ("Hung Ma Tế Cốt - Vô Song").

2. **`DelegationSession`** (`server/world/agent_orb_service.py:38-58`):
   - Quản lý phiên uỷ thác runtime: `session_id: str`, `player_id: int`, `orb_id: str`, `start_timestamp_sec: float`, `total_duration_sec: float`, `remaining_duration_sec: float`, `stance: TacticalStance`, `llm_config: LLMProviderConfig`, `decision_core: AgentDecisionCore`.
   - Trạng thái vòng đời: `is_active: bool = True`, `is_offline: bool = False`, `is_expired: bool = False`.
   - Chỉ số thu hoạch: `exp_gained: int = 0`, `monsters_slain: int = 0`, `spirit_stones_looted: Dict[str, int] = field(default_factory=dict)`, `potions_consumed: int = 0`, `actual_active_time_sec: float = 0.0`.

3. **`DelegationHarvestReport`** (`server/world/agent_orb_service.py:60-71`):
   - Data class bất biến `@dataclass(slots=True, frozen=True)` đại diện cho báo cáo thu hoạch khi kết thúc phiên:
     `session_id: str`, `player_id: int`, `total_duration_sec: float`, `actual_active_time_sec: float`, `exp_gained: int`, `monsters_slain: int`, `spirit_stones_looted: Dict[str, int]`, `potions_consumed: int`, `reclaimed_timestamp: float`.

4. **`TacticalStance`** (`server/agent/agent_decision_core.py:26-31`):
   - `BALANCED`: Cân bằng giữa cày cấp, nhặt đồ và sinh tồn.
   - `AGGRESSIVE`: Truy sát quái vật liên tục, ưu tiên tối đa EXP.
   - `DEFENSIVE`: Cực kỳ cẩn trọng, rút lui né đòn khi máu thấp.
   - `TREASURE_HUNTER`: Ưu tiên nhặt Huyết Thạch quý hiếm trên hết.

5. **`AgentActionType`** (`server/agent/llm_provider_client.py:30-39`):
   - `IDLE`, `MOVE_TOWARDS`, `MOVE_AWAY`, `ATTACK_SKILL`, `DODGE`, `LOOT`, `USE_POTION`, `SWAP_WEAPON`.

### 1.2. Cơ Chế Tính Toán & Xác Thực EXP, Huyết Thạch, Trảm Quái
- **Cơ chế Server-Authoritative**: Toàn bộ biến động chỉ số không do client báo cáo; server cập nhật qua:
  - `AgentOrbService.record_monster_slain(player_id, exp=100)`: Tăng `monsters_slain += 1` và `exp_gained += exp`.
  - `AgentOrbService.record_loot_harvest(player_id, item_id, count=1)`: Ghi nhận số lượng Huyết Thạch (`spirit_stones_looted[item_id] += count`).
  - `AgentOrbService.record_potion_consumed(player_id, count=1)`: Ghi nhận tiêu hao đan dược.
- **Tiêu thụ & Xếp chồng thời gian**:
  - `activate_delegation()` trừ đúng 1 viên vật phẩm trong `inventories[player_id][orb_id]`. Trả về `None` nếu số lượng $\le 0$.
  - `extend_delegation()` cộng dồn trực tiếp thời gian vào phiên đang chạy mà không làm reset chỉ số thu hoạch (`session.total_duration_sec += extra_duration`, `session.remaining_duration_sec += extra_duration`).
- **Thu hồi quyền kiểm soát**:
  - `reclaim_control(player_id)`: Đóng session (`is_active = False`), tạo `DelegationHarvestReport` bất biến, chuyển vào `completed_reports` và giải phóng quyền điều khiển cho người chơi.

### 1.3. Cơ Chế Dòng Suy Nghĩ (Thought Streams) & Định Tuyến Nhà Cung Cấp LLM
1. **Kiến Trúc Não Kép (Dual-Layer Cognition Brain)**:
   - **Tầng Phản Xạ 30Hz Cục Bộ (`LOCAL_TACTICAL` / Heuristic 0ms)**:
     - Hiện thực tại `AgentDecisionCore.evaluate_tick_action()` và `LLMProviderClientRouter._heuristic_fallback()`.
     - Phản xạ sinh tồn khẩn cấp: Khi `hp_ratio < 0.25`, tự động kích hoạt `DODGE` (Huyễn Ảnh Bộ i-frame 250ms) nếu quái ở gần ($< 4.0\text{m}$), hoặc `USE_POTION` (Hoàn Hồn Đan) nếu ngoài tầm.
     - Tương khắc Ngũ Hành: Quái Thổ $\rightarrow$ xuất chiêu Mộc; Quái Hỏa $\rightarrow$ Thủy; Quái Kim $\rightarrow$ Hỏa; Quái Mộc $\rightarrow$ Kim; Quái Thủy $\rightarrow$ Thổ.
     - Tạo thought string tiếng Việt: `"Sinh mệnh nguy kịch (<25%). Kích hoạt Huyễn Ảnh Bộ né tránh sát thương tức thì!"`
   - **Tầng Chiến Lược Đa Mô Hình LLM (`LLMProviderClientRouter`)**:
     - Hỗ trợ 7 nhà cung cấp: `OPENROUTER`, `OPENAI`, `ANTHROPIC`, `GEMINI`, `DEEPSEEK`, `KIMI`, `LOCAL_TACTICAL`.
     - Cấu hình qua `LLMProviderConfig`: `timeout_sec = 2.0`, `temperature = 0.2`, `max_tokens = 256`.
     - Chuẩn hóa payload theo từng provider (Anthropic `/messages`, Gemini `responseMimeType="application/json"`, OpenAI JSON Object).
     - **Cơ chế Phục Hồi Tự Động (Zero-Latency Fallback)**: Khi Cloud LLM gặp lỗi mạng, timeout quá 2.0s hoặc JSON hỏng, router lập tức chuyển hướng sang `_heuristic_fallback()`, triệt tiêu hoàn toàn nguy cơ đứng hình nhân vật.
2. **Dòng Suy Nghĩ Trên Client UI**:
   - Client WebApp [`client/webapp/js/ui/agent_orb.js`](file:///c:/Projects/FreeExile/client/webapp/js/ui/agent_orb.js) kết nối qua `updateAgentThought(thought)`, hiển thị trực tiếp lên DOM `#agent-thought-stream` thuộc `#hud-agent-banner`, kèm nhãn nhà cung cấp và chiến thuật.

### 1.4. Ràng Buộc Kiến Trúc & Tiêu Chuẩn Kỹ Thuật 2026
- **GEMINI.md § 2.4 (Kiến Trúc Mùa Giải Song Thực Cảnh PoE2)**:
  - `Standard Realm` (Thái Hư Giới / Cõi Bị Lãng Quên): Vĩnh cửu, không bao giờ reset.
  - `Seasonal Challenge Realm` (Thiên Đạo Luân Hồi): Chu kỳ 3 tháng, khởi đầu tinh khôi (Cấp 1, 0 tiền, rương trống).
  - `Remove-Only Stash Tabs`: Rương mùa giải chuyển về Standard dạng chỉ rút (`is_remove_only = True`), cấm nạp (`deposit_item` ném `ValueError`), tự dọn dẹp khi rỗng (`is_prunable()`).
  - Phân vùng thực cảnh tuyệt đối: Ngăn chặn nhân vật Standard đi vào Map của Seasonal.
- **GEMINI.md § 2.5 (Chiến Hồn Tế Cốt Server-Authoritative)**:
  - Mọi lệnh di chuyển/xuất chiêu/nhặt đồ của Agent đều được đẩy vào `ServerEngineLoop.move_queue` và `skill_queue`, xác thực qua `MovementAuthorityEngine` và `CombatEngine`.
- **GEMINI.md § 2.7 (Khối Bảo Mật & Cổng Phủ Quyết Release)**:
  - Kiểm toán an ninh tự động qua `tools/security/run_independent_security_audit.py`. Quyền VETO bắt buộc nếu có lỗ hổng Critical/High.
- **GEMINI.md § 2.8 (ARPG Cá Nhân & Anti-VLTK Faction Siege)**:
  - $100\%$ trọng tâm vào hành trình cá nhân, không có tính năng công thành chiến, chiếm đất bang hội.
  - Bang hội gọn nhẹ: Kênh chat bang và Rương chung xác thực 2PC chống dupe.
- **GEMINI.md § 2.12 (Bản Đồ An Toàn & Sinh Quái PoE2)**:
  - `zone_player_hideout` và `zone_boundless_sanctuary` là Safe Haven thuần khiết 100%. `ZoneEngine.can_spawn_hostile_monsters(zone_id)` trả về `False`. Chỉ duy nhất Mộc Nhân Bất Hoại (`isDummy = True`) được tồn tại. Quái thù địch chỉ sinh ra ở ngoại vực (`OPEN_WORLD`, `DUNGEON_INSTANCE`, `SECRET_CHAMBER`).

---

## 2. LOGIC CHAIN (Chuỗi Suy Luận Kỹ Thuật)

1. **Từ Quan sát 1.1 & 1.2 $\rightarrow$ Kết luận về Kiến Trúc Authoritative**:
   - `AgentOrbService` không phụ thuộc vào client inputs để tính toán phần thưởng. Mọi hành vi diễn ra trực tiếp trên máy chủ qua `step_tick(dt)` tích hợp vào `ServerEngineLoop`. Do đó, không có nguy cơ hacker can thiệp bộ nhớ phía client để giả mạo số EXP hay Huyết Thạch nhặt được.
2. **Từ Quan sát 1.3 $\rightarrow$ Kết luận về Tách Rời Tải Tính Toán (Compute Isolation)**:
   - Tầng 30Hz World Loop chạy với ngân sách $33.33\text{ ms/tick}$. Các truy vấn Cloud LLM có độ trễ từ $500\text{ms}$ đến $2000\text{ms}$.
   - Việc `LLMProviderClientRouter` chạy bất đồng bộ ngoài loop và dự phòng tức thì bằng `_heuristic_fallback` (0ms) đảm bảo vòng lặp 30Hz không bao giờ bị nghẽn (zero tick stall).
3. **Từ Quan sát 1.4 $\rightarrow$ Kết luận về Ranh Giới Tích Hợp Hội Thoại & Co-op Tương Lai**:
   - Việc tích hợp giao tiếp ngôn ngữ tự nhiên (Natural Language Dialogue) với Chiến Hồn Tế Cốt BẮT BUỘC phải đi qua luồng dịch vụ xã hội tách biệt (như `ChatService` microservice qua WebSocket/QUIC) thay vì nhồi vào gói tin di chuyển/chiến đấu 30Hz của `ServerEngineLoop`.
   - Các chỉ thị chiến thuật từ hội thoại (ví dụ: "Đổi sang thế Tầm Bảo", "Ưu tiên đánh boss") sẽ được chuyển hóa thành các cập nhật trạng thái `session.stance` hoặc target mask bất đồng bộ an toàn.

---

## 3. CAVEATS (Vấn Đề Tồn Tại & Giới Hạn Nghiên Cứu)

1. **Chưa có File Schema Protobuf cho Agent Orb**: Hiện tại thư mục `proto/` chưa có `agent.proto` hay `totem.proto`. Giao tiếp giữa Client WebApp và Server về Agent Orb hiện đang dùng REST/JSON DTOs mô phỏng. Khi tiến lên bản phát hành C++20 / Metal, bắt buộc biên soạn `proto/agent.proto`.
2. **Uỷ Thác Ngoại Tuyến Mô Phỏng Toán Học (Headless Simulation vs Realtime Tick)**: Khi người chơi tắt máy (`is_offline = True`), máy chủ hiện tại vẫn duy trì cập nhật theo nhịp tick. Ở quy mô 1.000.000 CCU, việc tick 30Hz cho hàng trăm ngàn phiên offline trong bộ nhớ sẽ gây quá tải CPU; cần bổ sung thuật toán kết toán xác suất theo khối (Stochastic Batch Resolution / Monte Carlo Catch-up).
3. **Chưa Có Thực Thể Companion Đi Kèm (Visual Entity)**: Hiện tại Agent Orb chỉ là chế độ "lái tự động" (Autopilot) cho chính nhân vật của người chơi, chứ chưa phải một thực thể Đệ Tử/Thần Thú (Companion Spirit) độc lập đi song hành trong thời gian thực.

---

## 4. CONCLUSION (Đặc Tả Đột Phá Kỹ Thuật AI Agent 2026-2027)

Hệ thống AI Agent của FreeExile hiện tại đã có nền móng vững chắc với cấu trúc Não Kép, Server-Authoritative 30Hz, và quản lý phiên uỷ thác hoàn chỉnh. Để hiện thực hóa mục tiêu đột phá theo yêu cầu CEO và Roadmap 2026-2027, 3 cơ chế mở rộng cốt lõi cần được thiết kế:

### 4.1. Blueprint 1: Giao Tiếp Ngôn Ngữ Tự Nhiên Với Chiến Hồn (Natural Language Dialogue Channel)
- **Cơ chế**: Bổ sung kênh chat `ChatChannelType.COMPANION` vào `server/chat/chat_service.py` và `proto/chat.proto`.
- **Luồng xử lý**:
  1. Người chơi gõ lệnh: *"Chiến Hồn, máu dưới 40% hãy né, ưu tiên nhặt Huyết Hồn Thạch"*.
  2. `ChatService` gửi prompt tới Cloud LLM (DeepSeek/Gemini/Claude) qua background task.
  3. LLM trả về cấu trúc JSON Command: `{"set_stance": "TREASURE_HUNTER", "emergency_hp_threshold": 0.40}`.
  4. Server Engine cập nhật an toàn vào `session.decision_core` trong tick kế tiếp.

### 4.2. Blueprint 2: Chiến Hồn Xuất Khiếu - Đồng Hành Thời Gian Thực (Real-time Co-Op Companion)
- **Cơ chế**: Khi người chơi online, Chiến Hồn Tế Cốt có thể được triệu hồi thành một Phân Thần (Autonomous Spirit Actor) chiến đấu bên cạnh người chơi thay vì cướp quyền điều khiển nhân vật chính.
- **Thực thi uy quyền**: Phân Thần là một `CombatActor` độc lập trong `CombatEngine` và `Entity` trong `SpatialGrid`, tuân thủ bán kính bảo vệ (Leash distance $\le 15\text{m}$).

### 4.3. Blueprint 3: Mô Hình Dữ Liệu Cần Bổ Sung Trong `agent_orb_service.py`
```python
@dataclass(slots=True, frozen=True)
class CompanionDialogueMessage:
    message_id: str
    player_id: int
    timestamp_ms: int
    sender_type: str  # "PLAYER" | "TOTEM_SPIRIT"
    content: str
    extracted_intent: Optional[str] = None
    applied_parameters: Dict[str, Any] = field(default_factory=dict)

@dataclass(slots=True)
class CoOpCompanionEntity:
    companion_id: int
    owner_player_id: int
    orb_tier: AgentOrbTier
    element: FiveElements
    leash_radius_meters: float = 15.0
    teleport_threshold_meters: float = 25.0
    current_target_id: Optional[int] = None
```

---

## 5. FEATURES DISCOVERED & EDGE CASES

### Features Discovered
| # | Phân Loại | Tính Năng | Mô Tả Nghiệp Vụ | Dữ Liệu Đầu Vào (Inputs) | Dữ Liệu Đầu Ra (Outputs) | Cơ Chế Xử Lý Lỗi (Error Behavior) | Nguồn Phát Hiện |
|---|---|---|---|---|---|---|---|
| 1 | AI Delegation | `activate_delegation` | Tiêu hao 1 Agent Orb khởi tạo phiên uỷ thác tự hành | `player_id, orb_id, stance, llm_config` | `Optional[DelegationSession]` | Trả về `None` nếu số lượng Orb trong kho $\le 0$ | `agent_orb_service.py:97-140` |
| 2 | AI Delegation | `extend_delegation` | Cộng dồn thời gian uỷ thác mà không làm mất tiến trình | `player_id, orb_id` | `bool` (True/False) | Trả về `False` nếu phiên không tồn tại hoặc hết Orb | `agent_orb_service.py:142-158` |
| 3 | AI Delegation | `reclaim_control` | Đóng phiên uỷ thác, trả về báo cáo thu hoạch bất biến | `player_id` | `Optional[DelegationHarvestReport]` | Trả về `None` nếu không có phiên đang hoạt động | `agent_orb_service.py:211-232` |
| 4 | AI Cognition | `evaluate_tick_action` | Phản xạ cục bộ 30Hz: né đòn i-frame, tương khắc Ngũ Hành | `AgentPerceptionSnapshot` | `AgentActionPlan` | Mặc định chuyển về `IDLE` nếu không có mục tiêu | `agent_decision_core.py:193-279` |
| 5 | LLM Routing | `request_tactical_decision` | Định tuyến chiến thuật tới Cloud LLMs kèm timeout | `LLMProviderConfig, world_prompt` | `TacticalActionDecision` | Tự động kích hoạt `_heuristic_fallback()` khi lỗi | `llm_provider_client.py:251-311` |
| 6 | Server Authority | `step_tick` | Mô phỏng 30Hz 7 pha: i-frame, movement, combat, AOI | `dt: float = 0.0333` | `TickResult` | Kẹp vận tốc, chống speedhack qua rubberband | `server_engine_loop.py:124-196` |
| 7 | Anti-Cheat | `validate_and_reconcile_position` | Kiểm tra quãng đường di chuyển tối đa cho phép | `entity_id, claimed_x, claimed_y, dt` | `Tuple[bool, float, float]` | Ghi nhận điểm nghi vấn +10, kéo lùi vị trí | `movement_authority.py:60-88` |
| 8 | Zone Purity | `can_spawn_hostile_monsters` | Kiểm soát vùng an toàn (Safe Haven) theo chuẩn PoE2 | `zone_id: str` | `bool` | Trả về `False` nếu zone là Hideout hoặc Sanctuary | `zone_engine.py:103-111` |
| 9 | Seasonal Realm | `deposit_item` (Stash) | Ngăn chặn nạp đồ vào rương Chỉ Rút (Remove-Only) | `item: SeasonStashItem` | `None` | Ném `ValueError` nếu `is_remove_only == True` | `season_league_manager.py:57-63` |

### Edge Cases
| # | Tính Năng | Kịch Bản Thử Nghiệm (Input) | Hành Vi Quan Sát Thực Tế (Observed Behavior) |
|---|---|---|---|
| 1 | `activate_delegation` | Kích hoạt với `balance == 0` | Không trừ kho, không tạo session, trả về `None` sạch sẽ (`test_agent_orb_service.py:50`). |
| 2 | `extend_delegation` | Gia hạn phiên đã hết hạn (`is_active == False`) | Trả về `False`, giữ nguyên trạng thái kho đồ của người chơi. |
| 3 | `evaluate_tick_action` | Máu rơi xuống $< 25\%$ khi quái ở cự ly $3.5\text{m}$ | Kích hoạt `DODGE` tức thì (Huyễn Ảnh Bộ), miễn nhiễm sát thương 250ms (`test_agent_decision_core.py:76`). |
| 4 | `request_tactical_decision` | API Cloud LLM mất kết nối hoặc timeout $> 2.0\text{s}$ | Fallback sang Heuristic trong $< 0.1\text{ms}$, không gây giật lag nhịp tick của máy chủ. |
| 5 | `step_tick` | Hết thời gian uỷ thác (`remaining_duration_sec <= 0`) | Session tự động chuyển sang `is_active = False`, `is_expired = True`, ngừng nhận lệnh. |
| 6 | `can_spawn_hostile_monsters` | Truy vấn `zone_player_hideout` hoặc `zone_boundless_sanctuary` | Luôn trả về `False`, bảo đảm khu an toàn 100% không quái vật theo chuẩn PoE2. |
| 7 | `deposit_item` | Thử nạp đồ vào tab `is_remove_only = True` của Standard Realm | Ném `ValueError("Cannot deposit into Remove-Only stash tab")`, chặn đứng hành vi dupe/lạm dụng kho. |

---

## 6. VERIFICATION METHOD (Phương Pháp Kiểm Chứng Độc Lập)

Mọi kỹ sư và agent tiếp quản có thể kiểm chứng độc lập báo cáo này bằng các lệnh sau:

1. **Chạy toàn bộ unit test của AI Agent**:
   ```bash
   python -m pytest tests/unit/test_agent_orb_service.py tests/unit/test_agent_decision_core.py -v
   ```
   *Kỳ vọng*: 11/11 tests PASSED trong $< 0.5$ giây.

2. **Kiểm tra quy tắc vùng an toàn PoE2**:
   ```bash
   python -m pytest tests/unit/test_zone_monster_spawning_rules.py -v
   ```
   *Kỳ vọng*: Xác nhận 100% không sinh quái thù địch trong Hideout và Sanctuary.

3. **Kiểm toán vệ sinh tài liệu & mã nguồn**:
   ```bash
   python tools/lint/check_code_and_doc_hygiene.py --strict
   ```
   *Kỳ vọng*: Báo cáo `handoff.md` tuân thủ Soft Cap $\le 400$ dòng (Hard Cap $\le 600$ dòng).