# AutoPOE2 — Telemetry Engine & Companion cho Path of Exile 2

> **Client:** Path of Exile 2 v0.5.5+ · **C++23** Hot Path 120 Hz + **Python 3.11** Cold Path  
> **Bản đồ tài liệu:** [`docs/README.md`](docs/README.md) · **Hiến pháp agent:** [`AGENTS.md`](AGENTS.md)  
> **Kiến trúc:** [Doc 50](docs/development/50_two_tier_asymmetric_hybrid_architecture_specification.md) · **Hàng đợi tự hành:** [Doc 61](docs/development/61_autonomy_gap_audit_and_next_development_basis.md)  
> **IPC:** [Doc 06](docs/development/06_binary_ipc_protocol_spec.md) — `PROTOCOL_VERSION 0x00050005`, `TelemetryPacket` **39 112 B** (không phải 4 MB)  
> Zoom/fog/camera: repo `Poe2VisualTool` — không nhúng DXGI vào Core.

Vòng Hideout → Map Device → TRAVERSE → map **CODE-PRESENT, chưa LIVE-VERIFIED**. XYZ đọc qua `PlayerFinder` 16 MB — **cấm** neo tĩnh `xyz_addr` / `0x290` / `0x540`. Nhân vật CI (`HP 1/1`): không Life Flask.

---

## 1. Kiến trúc

```mermaid
graph TB
    subgraph POE2_Client ["Path of Exile 2 (x64)"]
        GameMemory["RAM client"]
        GameLog["Client.txt"]
    end

    subgraph Tier1 ["Tier 1: AutoPOE2_Core.exe (C++23, 120Hz)"]
        MemReader["RPM: pointer chain + PlayerFinder"]
        Reflex["ReflexManager (flask CI/ES, dodge, chicken)"]
        OverlayCpp["Win32 overlay"]
        SHM["Seqlock TelemetryPacket 39112 B"]
        SPSC["SPSC 16 slot"]
        PanicCore["Panic: Pause / Ctrl+Shift+F12"]
    end

    subgraph Tier2 ["Tier 2: Python 3.11 companion"]
        ShmBridge["CoreShmBridge"]
        A3E["A3E (LinUCB local)"]
        Overlay["Control Center / HUD"]
        Trade["Trade / Gold / Discord"]
    end

    GameMemory -->|ReadProcessMemory| MemReader
    MemReader --> Reflex
    Reflex -->|KMBox / focus interlock| GameMemory
    MemReader --> OverlayCpp
    GameLog -->|FILE_SHARE_READ| SHM
    MemReader --> SHM
    SHM ==>|seqlock| ShmBridge
    ShmBridge --> Overlay
    ShmBridge --> A3E
    Overlay -->|OpCode 99| SPSC
    SPSC --> PanicCore
    Trade --> Overlay
```

Chi tiết module: Doc 50, Doc 29 (BotBrain), Doc 36 (skill), Doc 58 (CharacterFSM), [Doc 72](docs/development/72_hardware_safety_and_focus_interlock_specification.md) (focus interlock).

---

## 2. Hiện trạng ngắn (không nhân bản spec)

| Tầng | Có trong tree | Không tuyên bố |
|---|---|---|
| Reflex / vitals CI | LIVE-PROVEN đọc RAM + `--ci` | Full-auto farm như người |
| WASD / Map Device / loot walk-to | CODE-PRESENT (Doc 61 leftover) | LIVE-VERIFIED Hideout→TRAVERSE |
| HUD / trade / log | Companion Cold Path | Zero-memory “ToS-safe bot” khi Core RPM đang chạy |
| Visual FOV | Poe2VisualTool | `visual_mods` trong AutoPOE2 Core |

Nhân vật mục tiêu: [`character_target/README.md`](character_target/README.md) (BEONGUSI CI). Phím người chơi: [`.agents/skills/poe2-human-controls/SKILL.md`](.agents/skills/poe2-human-controls/SKILL.md).

---

## 3. Cây thư mục (rút)

```
AutoPOE2/
├── AGENTS.md                    # Hiến pháp agent
├── docs/                        # Bản đồ: docs/README.md
│   ├── development/             # Spec engine (index + archive/)
│   ├── assistant_tool/          # HUD / trade companion
│   ├── agent/                   # Playbook agent (không thay Doc 61)
│   ├── wiki/ play_guide/ research/
├── src/core/                    # C++23 Hot Path
├── src/assistant_tool/          # Python companion
├── src/agentic_engine/          # A3E local
├── src/common/                  # Kernel Python
├── tests/ tools/ scripts/
├── run_full_system.bat          # Launcher 1-click
└── CMakeLists.txt
```

---

## 4. Biên dịch & chạy

### 4.1. Yêu cầu

Windows 10/11 x64 · VS 2022 hoặc Clang 18+ (C++23) · CMake ≥ 3.25 · Python 3.11+ (`requirements.txt`).

### 4.2. Build Core

Trước khi build, tắt process đích (tránh `LNK1104`):

```powershell
cmd /c "taskkill /F /IM AutoPOE2_Core.exe >nul 2>&1 || exit 0"
cmd /c "taskkill /F /IM AutoPOE2_Tests.exe >nul 2>&1 || exit 0"
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
```

Binary: `bin/Release/AutoPOE2_Core.exe`, `AutoPOE2_Tests.exe`, `AutoPOE2_MemProbe.exe`.

### 4.3. Launcher

1. `run_full_system.bat` — UAC, venv, build nếu thiếu, Control Center.
2. Vào nhân vật trong POE2 → **F8** bật/tắt tự hành. Panic: **Pause** hoặc **Ctrl+Shift+F12** (không dùng F12 đơn — Steam screenshot).
3. Dev CLI ví dụ:

```powershell
.\bin\Release\AutoPOE2_Core.exe --move-mode wasd --autododge --autoflask --ci --wasd --move
```

`--ci` bắt buộc với Chaos Inoculation. `--flask-hp` không áp Life Flask khi `maxHP==1`. Town Portal = phím `.` (`VK_OEM_PERIOD`), không phải T.

Hotkey: F8/F6 master toggle · F11 recalibrate XYZ · F9 capture · F10 tactical overlay.

### 4.4. GGPK (chỉ đọc)

```powershell
python tools/extract_ggpk_to_db.py --catalog-only
python tools/extract_ggpk_to_db.py
```

Cần `tools/bin/libooz.dll` ([zao/ooz](https://github.com/zao/ooz)). Core 120 Hz không mở GGPK.

---

## 5. Kiểm thử

Không lấy số PASS cũ làm nghiệm thu phiên này. Chạy lại:

```powershell
cmake --build build --config Release --target AutoPOE2_Tests
ctest --test-dir build -C Release -V
pytest -m fast
```

Live: `python scripts/live_probe.py --all` khi client mở. Hàng đợi tự hành: Doc 61 §5 leftover + §7 DoD.

---

## 6. Pháp lý

RPM + KMBox/SendInput có thể vi phạm ToS GGG (Path of Exile 2). Dùng trên trách nhiệm người vận hành. Companion HUD (log + trade API) tách biệt Hot Path; chạy Core không biến HUD thành “zero-risk”.