# 15. Đặc Tả Nâng Cấp Công Nghệ & Bộ Công Cụ Kiểm Soát Chất Lượng (Technology Gap & Toolchain Upgrade Specification 2026)

> **Mã nhiệm vụ**: `TASK-UPGRADE-TECH-TOOLCHAIN-20260907`  
> **Mốc thời gian hệ thống**: 07/09/2026  
> **Bối cảnh chuẩn hóa**: AutoPOE2 (C++23 Core Engine + Python 3.11 Companion + Shared Memory IPC)  
> **Đơn vị chuyên trách**: Sub-Agent Nâng Cấp Công Nghệ & Chuỗi Công Cụ (Technology & Toolchain Upgrade Specialist)  
> **Tài liệu tham chiếu**: `AGENTS.md`, `GEMINI.md`, `13_commercial_bot_hp_detection_and_fast_activation_benchmark.md`, `14_engineering_rules_and_quality_gates.md`

---

## 1. Đánh Giá Khoảng Cách Công Nghệ (Technology Gap Analysis 2026)

Đối chiếu hiện trạng của AutoPOE2 với chuẩn công nghiệp của các bot thương mại POE2 (Exilebuddy, PoEHelper, Game-Changer, private auto-mappers) và các hệ thống C++23/Python 3.11 hiện đại trong năm 2026:

### 1.1. Kỹ thuật truy xuất bộ nhớ (Memory Access Paradigm)
* **Hiện trạng AutoPOE2**:
  * Khi vào map mới hoặc mất dấu `m_playerAddr` (`center == 0`), hệ thống kích hoạt quét vi sai toàn bộ Readable Memory Regions (8GB - 16GB) để tìm pattern triple `{X <= maxHP, maxHP, maxHP}`.
  * Tốn 15 - 60+ giây, CPU 100%, gây nghẽn luồng xử lý và giật lag game.
  * Đối với tọa độ XYZ, bắt buộc người dùng bước đi 1-2 bước để lọc vi sai float (`WAITING_FIRST_STEP`).
* **Chuẩn công nghiệp 2026**:
  * **Zero Full-RAM Scan**: Tuyệt đối không quét RAM 8GB khi chơi game.
  * **Static Pointer Path Traversal $O(1)$**: Chỉ quét AOB 1 lần duy nhất lúc khởi động trên phân vùng `.text` (48MB, ~10ms) để tìm con trỏ tĩnh `GameController` trong `.data`.
  * Tại runtime, giải mã chuỗi con trỏ:
    $$\text{GameController} \longrightarrow \text{InGameState} \longrightarrow \text{InGameData} \longrightarrow \text{LocalPlayer} \longrightarrow \text{Components}$$
  * Thời gian truy xuất: **< 0.001 ms (< 1 microsecond)** qua 4-5 lần đọc bộ nhớ trực tiếp.
  * Tọa độ XYZ và các chỉ số sinh tồn (HP, Mana, ES) sẵn sàng 100% ngay tại frame đầu tiên khi tắt loading screen mà không cần người dùng bước đi.

### 1.2. Môi trường Test giả lập (Headless Mock POE2 Memory Engine)
* **Hiện trạng AutoPOE2**:
  * Đã có `SimulatedMemoryReader` cơ bản với 8MB buffer cố định, mô phỏng `InGameState`, `PlayerState`, `EntityMap` đơn giản.
  * Chưa có mô hình chuỗi con trỏ nhiều cấp đầy đủ (`GameController -> InGameState -> InGameData -> LocalPlayer -> LifeComponent/PositionedComponent/BuffsComponent`).
  * Chưa giả lập đầy đủ kịch bản chuyển cảnh, Grace Period, hiệu ứng bất lợi (debuffs), và các chướng ngại vật địa hình động.
  * Một số test case trước đây phụ thuộc vào quyền Administrator hoặc tiến trình game thật.
* **Chuẩn công nghiệp 2026**:
  * **Headless Mock Engine hoàn chỉnh**: Chạy 100% ở User Mode (Non-Elevated, `asInvoker`), cho phép thực thi toàn bộ luồng nghiệp vụ C++ Core (PlayerFinder, Vitals, XYZ, Pathfinder, Combat, Looting, Auto-Login, TownQuest) mà không cần tiến trình `PathOfExile.exe` thật.
  * Khả năng tiêm kịch bản (Deterministic Scenario Injection): Mô phỏng tụt máu đột ngột, boss tung đòn, rơi vật phẩm giá trị, kẹt đường, ngắt kết nối mạng.

### 1.3. Bộ công cụ kiểm soát chất lượng (Quality & Verification Toolchain)
* **Hiện trạng AutoPOE2**:
  * C++23: Biên dịch bằng MSVC với flags `/W4 /permissive- /Zc:__cplusplus /utf-8 /GS /guard:cf`, nhưng chưa cấu hình Clang-Tidy (`.clang-tidy`), chưa tích hợp AddressSanitizer (`/fsanitize=address` / ASan) trong build system để phát hiện rò rỉ và tràn bộ nhớ.
  * Python 3.11: Đã có cấu hình `pyproject.toml`, 74 test cases pytest PASS. Tuy nhiên, `ruff` phát hiện 164 cảnh báo/lỗi định dạng và `mypy` phát hiện 56 lỗi type checking do thiếu chú thích kiểu nghiêm ngặt và trùng lặp package bases.
  * Thiếu kịch bản kiểm thử hồi quy 1-click chuẩn hóa: Các nhà phát triển phải chạy lệnh C++ và Python thủ công, rời rạc.
* **Chuẩn công nghiệp 2026**:
  * C++23 Quality Gate: `.clang-tidy` chuẩn hóa theo Google C++ Style & Modern C++23 Core Guidelines; AddressSanitizer (ASan) sẵn sàng qua cờ `-DENABLE_ASAN=ON`.
  * Python Quality Gate: Ruff linter & formatter tự động sửa lỗi (`--fix`), Mypy strict type checking không lỗi (`mypy --explicit-package-bases src`), Pytest coverage > 85%.
  * One-Click Regression Suite: Script `run_regression_tests.ps1` tự động điều phối toàn bộ chuỗi kiểm thử C++ và Python, đo lường thời gian thực thi và xuất báo cáo tổng hợp.

### 1.4. Nâng cấp kỹ năng AI (Gemini 3.8 Flash SDK & Structured Outputs)
* **Hiện trạng AutoPOE2**:
  * `src/assistant_tool/gemini_agent_bridge.py` đã ứng dụng Pydantic cho `ItemAppraisalResult`, nhưng hàm `plan_macro_strategy` vẫn nhận chuỗi văn bản tự do chưa qua xác thực schema.
  * Các module `discord_monitor.py` và `log_watcher.py` dựa trên biểu thức chính quy (regex: `re.search(r"(\d+)c")`) để phân tích giá cả và giao dịch, dễ bị lỗi khi format thay đổi hoặc gặp prompt injection.
  * Chưa tận dụng Native Tool/Function Calling của Gemini SDK để ra lệnh trực tiếp cho Core Engine.
* **Chuẩn công nghiệp 2026**:
  * Sử dụng Google GenAI SDK chuẩn năm 2026 với model `gemini-3.8-flash`.
  * Chuyển dịch toàn bộ cơ chế phân tích chat, whisper và chiến lược vĩ mô sang **Pydantic Structured Outputs** (`response_schema`).
  * Tích hợp **Native Tool Calling**: Mô hình AI trực tiếp gọi các công cụ điều khiển game đã định nghĩa (`send_game_command`, `use_flask`, `cast_skill`, `emergency_logout`, `filter_item`) một cách an toàn, có kiểm soát tham số nghiêm ngặt theo kiểu dữ liệu.

---

## 2. Kiến Trúc Môi Trường Test Giả Lập (Headless Mock POE2 Memory Engine)

```mermaid
graph TD
    subgraph MockEngine ["Headless Mock POE2 Memory Engine (User-Mode)"]
        BaseMem["Virtual Address Space (0x140000000 - 8MB / 16MB)"]
        StaticData[".data Section: Static Pointer GameController (0x140300000)"]
        InGameState["InGameState Struct (+0x100000)"]
        InGameData["InGameData / AreaInstance (+0x120000)"]
        LocalPlayer["LocalPlayer Entity (+0x110000)"]
        Components["Components: Life (+0x48), Positioned (+0x28), Buffs (+0x100)"]
        EntityMap["EntityMap Array (+0x200000: 512 Slots)"]
        TerrainGrid["Terrain Grid Map (Walkable / Blocked Matrix)"]
        
        BaseMem --> StaticData
        StaticData --> InGameState
        InGameState --> InGameData
        InGameData --> LocalPlayer
        LocalPlayer --> Components
        InGameData --> EntityMap
        InGameData --> TerrainGrid
    end

    subgraph CoreModules ["C++23 Core Modules (Tested Headlessly)"]
        PF["PlayerFinder (Pointer Traversal & Sanity)"]
        Vitals["Vitals Calibration (HP/Mana/ES)"]
        XYZ["XYZ Position & Movement Tracker"]
        Path["Pathfinder (A* & String Pulling)"]
        Combat["Combat & Combo Engine (Ice Strike & Boss Routine)"]
        Reflex["ReflexManager (Life Flask & Double Dodge)"]
        Loot["LootController (Item Filter & Auto-Loot)"]
        Login["AutoLogin & TownQuest Engine"]
    end

    MockEngine --> CoreModules
```

### 2.1. Cấu Trúc Thành Phần Giả Lập (Component Layout)
1. **Con trỏ tĩnh `.data` (`0x140300000`)**: Trỏ trực tiếp tới `InGameState`.
2. **`InGameState` (`+0x100000`)**:
   - `magic`: `0x50453247` ("PE2G")
   - `areaId`, `areaSeed`, `gameTick`
   - `inGameDataPtr`: Trỏ tới `InGameData` tại `+0x120000`
   - `playerStatePtr`: Trỏ tới `LocalPlayer` tại `+0x110000`
3. **`LocalPlayer` & Components**:
   - `LifeComponent (+0x48)`: `{currentHP, maxHP, reservedHP, currentMana, maxMana, currentES, maxES}`
   - `PositionedComponent (+0x28)`: `{gridX, gridY, worldX, worldY, worldZ, rotation}`
   - `BuffsComponent (+0x100)`: `{buffCount, buffMask: GracePeriod, FlaskActive, Frozen, Shocked}`
4. **`EntityMap` (`+0x200000`)**:
   - Mảng 512 con trỏ thực thể hỗ trợ spawn/despawn quái vật thường, quái Magic, Rare, Boss, vật phẩm rơi (Currency, Gear), Cổng dịch chuyển.

---

## 3. Kịch Bản Test Chống Hồi Quy (Regression Test Suite Scenarios)

Hệ thống kiểm thử chống hồi quy tự động bao gồm 5 kịch bản kiểm định đầu cuối (End-to-End Headless Scenarios):

| Kịch Bản | Mục Tiêu Kiểm Thử | Dữ Liệu Đầu Vào Giả Lập | Kỳ Vọng Đầu Ra (Pass Criteria) |
|---|---|---|---|
| **Scenario 1: Fast Activation & Grace Period** | Kiểm tra kích hoạt tức thời $O(1)$ và phá Grace Period tự động | Map loaded $\rightarrow$ Buff `grace_period` active $\rightarrow$ LocalPlayer tại tọa độ spawn | HP/Mana/XYZ đọc xong trong 0ms; Micro-step phát lệnh di chuyển sau 300ms; Buff bị phá an toàn. |
| **Scenario 2: Vitals Drop & Emergency Double-Dodge** | Kiểm tra phản xạ sinh tồn đa tầng khi tụt máu | HP giảm đột ngột từ 1250 về 250 (< 28%) trong 1 tick | ReflexManager kích hoạt Life Flask [1] + gửi phím Space/E né đòn + tính vector kiting ngược hướng quái vật. |
| **Scenario 3: Loot Sorting & Bag Capacity** | Kiểm tra nhặt đồ thông minh và lọc đồ rác | Spawn 3 vật phẩm: Mirror of Kalandra, Chaos Orb, Scroll of Wisdom | LootController ưu tiên Mirror $\rightarrow$ kiểm tra ô trống $\rightarrow$ di chuyển tới cự ly 35 đơn vị $\rightarrow$ click nhặt. |
| **Scenario 4: Monk Combat Routine & Boss Stagger** | Kiểm tra chuỗi combo chiêu thức và phản ứng stagger | Boss HP 6500, StaggerProgress tăng dần từ 0 lên 10000 | ComboManager tung 4 đòn Ice Strike $\rightarrow$ Boss stagger $\rightarrow$ kích hoạt Tempest Bell dứt điểm. |
| **Scenario 5: Pathfinder A* Around Complex Terrain** | Kiểm tra tìm đường qua ma trận mê cung và cửa đóng | Grid 64x64 với tường chéo và cửa hẹp | Thuật toán A* tìm đường ngắn nhất, Octile heuristic, String Pulling làm mịn, không cắt góc tường. |

---

## 4. Đặc Tả Tích Hợp Gemini 3.8 Flash Native Tool Calling & Pydantic

### 4.1. Định Nghĩa Tool Calling Trong Python
Thay vì để AI trả về văn bản tự do rồi dùng regex bóc tách, các hành động của AutoPOE2 được định nghĩa thành các hàm công cụ có kiểu dữ liệu rõ ràng:

```python
from pydantic import BaseModel, Field
from typing import Literal

class GameActionCommand(BaseModel):
    action_type: Literal["MOVE_TO", "CAST_SKILL", "USE_FLASK", "LOOT_ITEM", "EMERGENCY_LOGOUT", "PORTAL_TOWN"]
    target_x: float = Field(default=0.0, description="Tọa độ X thế giới")
    target_y: float = Field(default=0.0, description="Tọa độ Y thế giới")
    skill_slot: str = Field(default="", description="Phím tắt chiêu thức (Q, W, E, R, T, M1, M2)")
    flask_slot: int = Field(default=0, description="Slot bình thuốc (1-5)")
    reasoning: str = Field(description="Lý giải nguyên nhân kỹ thuật của quyết định")

class TradeOfferAnalysis(BaseModel):
    is_valid_trade: bool = Field(description="Tin nhắn có phải là lời mời giao dịch hợp lệ không")
    buyer_name: str = Field(description="Tên nhân vật người mua")
    item_requested: str = Field(description="Món đồ muốn mua")
    offered_currency: str = Field(description="Loại tiền tệ (Divine, Chaos, Exalted)")
    offered_amount: float = Field(description="Số lượng tiền tệ đề xuất")
    is_price_fair: bool = Field(description="Đánh giá giá đề xuất có khớp giá thị trường không")
    auto_response: str = Field(description="Câu phản hồi ngắn gọn chuẩn ngôn ngữ game thủ")
```

### 4.2. Lợi Ích Cốt Lõi So Với Regex
1. **Type Safety & Schema Validation**: Dữ liệu luôn tuân thủ 100% định dạng, loại bỏ hoàn toàn nguy cơ `AttributeError`, `ValueError` do regex không khớp.
2. **Kháng Prompt Injection**: AI nhận thức cấu trúc dữ liệu và lọc sạch các đoạn chat nguy hiểm giả mạo hệ thống.
3. **Multi-Step Tool Orchestration**: Gemini 3.8 Flash có thể gọi liên tiếp nhiều tool trong một lượt suy luận (ví dụ: `USE_FLASK` $\rightarrow$ `EMERGENCY_LOGOUT`).

---

## 5. Kế Hoạch Triển Khai & Kiểm Định (Implementation Roadmap)

1. **Giai đoạn 1**: Cấu hình `.clang-tidy` và kích hoạt cờ AddressSanitizer trong `CMakeLists.txt`.
2. **Giai đoạn 2**: Chuẩn hóa script `scripts/run_regression_tests.ps1` tích hợp toàn bộ kiểm thử C++ và Python.
3. **Giai đoạn 3**: Mở rộng `SimulatedMemoryReader` thành `HeadlessMockMemoryEngine` hỗ trợ đầy đủ chuỗi con trỏ tĩnh $O(1)$ và 5 kịch bản hồi quy.
4. **Giai đoạn 4**: Cập nhật `src/assistant_tool/gemini_agent_bridge.py` với Pydantic Structured Outputs và Tool Calling cho chiến lược vĩ mô.