# TÀI LIỆU ĐẶC TẢ KỸ THUẬT: KHÉP KÍN CHU TRÌNH TỰ HÀNH ENDGAME, HẬU CẦN HÒM ĐỒ & PHỤC HỒI SỰ CỐ (AUTONOMOUS ENDGAME LOOP CLOSURE, STASH LOGISTICS & RESILIENCE SPECIFICATION)

> **Mã tài liệu**: `SPEC-ENDGAME-LOOP-CLOSURE-2026-P69`  
> **Mốc thời gian tham chiếu**: 17/09/2026  
> **Trạng thái**: [APPROVED FOR IMPLEMENTATION / SSoT 2026]  
> **Phạm vi**: `tools/autonomous_mapping_coordinator.py`, `src/assistant_tool/stash/`, `src/assistant_tool/autonomous_lifecycle.py`, `docs/development/`  
> **Tuân thủ**: Rule 1 (Hai Tầng C++/Python), Rule 3 (Living Docs), Rule 4 (Kiến Trúc Module Hóa), Rule 5 (100% Dữ Liệu Thật), Rule 7 (Chuẩn Người Chơi Thật & Non-Hijacking).

---

## 1. BỐI CẢNH & ĐỘNG LỰC PHÁT TRIỂN (CONTEXT & PROBLEM STATEMENT)

### 1.1. Hiện Trạng Vận Hành (Baseline Assessment)
Hệ thống AutoPOE2 đã hoàn thiện và kiểm chứng thành công các mắt xích cốt lõi:
- **Hot Path 120Hz (C++23)**: Sinh tồn CI/Life/ES/Ward, Walk-to-loot $\le 22\text{u}$, Pickit thị trường $\ge 1.0\text{ Chaos}$ với Hot-reload tức thì.
- **Cold Path (Python 3.11)**: Tiếp cận bệ đá Map Device 3D bằng WASD (Dwell $\ge 300\text{ms}$), click LMB mở bệ đá, chọn node Atlas thường (loại trừ đền thờ Well of Souls), Ctrl+Click nạp Waystone, click TRAVERSE và bước vào Portal.
- **Stage 1 đến Stage 6**: Đã chứng minh khả năng dọn map đơn lẻ và quay về Hideout an toàn qua phím `.` (`INV-KEY-PORTAL`).

### 1.2. Lỗ Hổng Khi Cày Tự Động Dài Hạn (The Multi-Map Autonomy Gap)
Khi chuyển từ chạy 1 map sang chạy liên tục nhiều map (`run_multi_map_loop`):
1. **Lỗ hổng Hậu cần (Logistics Gap)**: Sau khi kết thúc Stage 6 về Hideout, bot quay lại Stage 1 ngay lập tức. Ba lô chứa đầy đồ nhặt được từ map trước không được cất vào Hòm (Stash) hoặc bán (Vendor). Khi hết Waystone trong túi, hệ thống lập tức dừng lại với trạng thái `EXHAUSTED`.
2. **Lỗ hổng Mod Nguy Hiểm (Brick Map Mod Gap)**: Chưa có bước thẩm định các dòng thuộc tính nguy hiểm của Waystone (*Reflect Damage, Cannot Leech, Minus Max Resistances*). Kích hoạt map khắc chế sẽ khiến nhân vật tử trận liên tục.
3. **Lỗ hổng Phục hồi Tử trận (Death Recovery Gap)**: Khi nhân vật tử trận trong map (`movement_flags & 8`), hệ thống chưa có máy trạng thái tự động click *"Resurrect at Checkpoint / in Town"* và xử lý portal cũ.
4. **Lỗ hổng Định hướng Sương Mù (Fog Exploration Gap)**: Giai đoạn dọn map Stage 5 vẫn chạy theo bộ đếm thời gian (20–60s) kết hợp heatmap góc, chưa bám theo đường biên mở sương (Frontier Fog Exploration) của người chơi thật.

---

## 2. KIẾN TRÚC CHU TRÌNH TỰ HÀNH KHÉP KÍN TOÀN DIỆN (THE CLOSED-LOOP V2 PIPELINE)

Hệ thống nâng cấp quy trình 6 giai đoạn hiện tại thành **Quy trình 8 phân hệ khép kín tuần hoàn (Closed-Loop V2)**:

```mermaid
flowchart TD
    subgraph HIDEOUT_ROUTINE["Chu Trình Hậu Cần Tại Hideout (Cold Path)"]
        S0A["Stage 0A: Giám Định Nhanh<br/>The Hooded One (Opcode 8)"] --> S0B["Stage 0B: Thẩm Định Trang Bị<br/>WhatIsBetter & Lọc Đồ"]
        S0B --> S0C["Stage 0C: Cất Đồ Vào Hòm<br/>Auto-Stash (Currency, Gems, Runes)"]
        S0C --> S0D["Stage 0D: Rút Bổ Sung Waystone<br/>Rút từ Stash Map Tab nếu túi < 2 viên"]
    end

    subgraph MAP_ACTIVATION["Khởi Động & Kích Hoạt Bản Đồ"]
        S1["Stage 1: Precheck Túi & Craft Waystone<br/>Kiểm tra Mod Blacklist (Anti-Brick)"]
        S2["Stage 2: Tiếp Cận & Mở Map Device<br/>WASD Hold >= 300ms, Dynamic Zoom, Click LMB"]
        S3["Stage 3: Chọn Node & Nạp Waystone<br/>Lọc bỏ Well of Souls, Nạp Tablets, Click TRAVERSE"]
        S4["Stage 4: Vào Portal Chuyển Cảnh<br/>Click LMB vortex xanh, đối soát Client.txt"]
    end

    subgraph IN_MAP_LOOP["Vận Hành Chiến Đấu Trong Map (Hot Path 120Hz)"]
        S5["Stage 5: Dọn Map Theo Mép Sương<br/>Frontier Fog Exploration, CI Combat, Pickit >= 1C"]
        S6["Stage 6: Rút Lui An Toàn Về Hideout<br/>Clear quái 10u -> Phím '.' mở Portal -> Thoát"]
    end

    subgraph RESILIENCE_WATCHDOG["Giám Sát & Phục Hồi Sự Cố"]
        DEATH["Tử Trận: Click 'Resurrect in Hideout'<br/>Đóng cổng lỗi hoặc vào lại cứu vớt"]
        CRASH["Crash Game: Poe2ClientLauncher<br/>Tự khởi động lại & Đăng nhập"]
    end

    HIDEOUT_ROUTINE --> MAP_ACTIVATION
    MAP_ACTIVATION --> IN_MAP_LOOP
    IN_MAP_LOOP --> HIDEOUT_ROUTINE
    IN_MAP_LOOP -.->|Tử trận| DEATH
    DEATH --> HIDEOUT_ROUTINE
    CRASH -.-> HIDEOUT_ROUTINE
```

---

## 3. ĐẶC TẢ KỸ THUẬT CHI TIẾT TỪNG PHÂN HỆ MỚI

### 3.1. Phân Hệ Hậu Cần Hòm Đồ & Bổ Sung Waystone (Stage 0: Stash & Restock)
- **Tập tin đảm nhiệm**: `src/assistant_tool/stash/stash_orchestrator.py`, `tools/autonomous_mapping_coordinator.py`.
- **Cơ chế kích hoạt**:
  - Kích hoạt tự động sau khi kết thúc Stage 6 (về Hideout), hoặc khi phát hiện túi đồ có $\ge 20$ ô bị chiếm dụng, hoặc khi số lượng Waystone trong túi đồ $< 2$ viên.
- **Quy trình 4 bước**:
  1. **Di chuyển tới Stash**: Dùng WASD tiếp cận hòm đồ tại Shoreline Hideout $\le 18\text{u}$, `MoveMouseSmooth` tới tâm Hòm và Click LMB (`INV-KEY-NO-F-FOR-INTERACT`).
  2. **Quét & Phân loại Tabs**: `StashUiScanner` nhận diện danh sách tabs: `Currency`, `Fragments`, `Waystones`, `Dump/Quad`.
  3. **Cất đồ tự động (Auto-Deposit)**: Dùng `StashItemMatrix` quét toàn bộ túi đồ. Thực hiện `Ctrl + Click` với thời gian nghỉ ngẫu nhiên (jitter 60–120ms) để cất toàn bộ Currency, Runes, Essences, Splinters, Gems.
  4. **Rút Waystone (Auto-Withdraw)**: Nếu túi đồ có $< 2$ viên Waystone, tự động chuyển sang Tab `Waystones`, click lấy 2–3 viên Waystone thuộc Tier cấu hình chuyển vào hàng 1 của túi đồ.
  5. **Đóng Hòm đồ an toàn**: Gửi phím `Spacebar` (`VK_SPACE 0x20`) để đóng UI hòm đồ hoàn toàn (`INV-STASH-LOGISTICS-SAFE`).

---

### 3.2. Phân Hệ Thẩm Định & Lọc Mod Bản Đồ Nguy Hiểm (Brick Map Mod Filter)
- **Tập tin đảm nhiệm**: `src/assistant_tool/pickit/waystone_crafter.py`, `src/assistant_tool/modifier_filter.py`.
- **Mục tiêu**: Ngăn chặn 100% việc kích hoạt các bản đồ có mod khắc chế build Martial Artist / Monk CI.
- **Danh Mục Mod Cấm Tuyệt Đối (Blacklist / Brick Mods)**:
  - `Monsters reflect % of Physical Damage` (Khắc chế đòn đánh vật lý).
  - `Monsters reflect % of Elemental Damage` (Khắc chế sát thương nguyên tố).
  - `Cannot Leech Life / Mana / Energy Shield` (Triệt tiêu khả năng hồi phục sinh tồn).
  - `Players have -% maximum Resistances` (Gây đột tử trước sát thương nguyên tố).
  - `Players cannot regenerate Life, Mana or Energy Shield`.
- **Quy trình xử lý**:
  - Đọc thông tin Waystone qua Tooltip OCR / RAM Memory.
  - Nếu phát hiện Mod nằm trong Blacklist:
    - Nếu có `Orb of Scouring` + `Orb of Alchemy`: Tự động tẩy trắng và đập lại (Re-Roll).
    - Nếu không thể tẩy: Chuyển viên Waystone này sang ô cách ly trong túi và chọn viên Waystone an toàn tiếp theo.

---

### 3.3. Phân Hệ Tự Động Phục Hồi Khi Tử Trận (Death Recovery FSM)
- **Tập tin đảm nhiệm**: `tools/autonomous_mapping_coordinator.py`, `src/assistant_tool/core_shm_bridge.py`.
- **Cơ chế nhận diện**:
  - Đọc bitmask `PlayerTelemetryData.movementFlags & 8` (Bit 3 = DEAD).
  - Quét quang học phát hiện hộp thoại `"YOU HAVE DIED"` và nút `"RESURRECT IN HIDEOUT"`.
- **Hành vi xử lý**:
  1. Ngay lập tức giải phóng toàn bộ phím nhập liệu (`KEYUP` WASD, Space, Click).
  2. `_find_resurrect_button`: Tìm tọa độ trung tâm của nút *"RESURRECT IN HIDEOUT"*.
  3. Click LMB có chủ đích để hồi sinh về Hideout.
  4. Chờ 3.0s xác nhận khu vực `Client.txt` đã chuyển về `Shoreline Hideout`.
  5. Tự động ghi nhận Incident Dossier (`INCIDENT_DEATH_<TIMESTAMP>`).
  6. **Quyết định tiếp theo**: Nếu map hiện tại còn số cổng portal $> 0$ và thời gian cày map chưa quá 50%, bot sẽ tiếp tục bước vào cổng để dọn dẹp; nếu đã chết quá 2 lần trong cùng 1 map, hủy map và kích hoạt map mới.

---

### 3.4. Phân Hệ Điều Hướng Theo Mép Sương (Frontier Fog Exploration)
- **Tập tin đảm nhiệm**: `src/core/navigation/quest_navigator.cpp`, `src/core/navigation/terrain_grid.cpp`.
- **Bản chất kỹ thuật**:
  - Không dựa vào bộ đếm thời gian cố định.
  - Đọc ma trận ô địa hình đã khám phá (`Explored / Visible`) vs chưa khám phá (`Fog of War`).
  - Thuật toán **Frontier Search**: Tìm các cụm điểm ranh giới giữa vùng đã đi qua và vùng tối của bản đồ.
  - Hướng dẫn JPS Pathfinding dẫn đường nhân vật men theo các cụm Frontier này, đảm bảo mở sạch 95%+ diện tích bản đồ giống phong cách người chơi pro.
- **Tiêu chí hoàn tất map thực tế (4-Gate Commercial Map Clear Engine - SSoT 2026)**:
  - **Rào chắn sinh tử (Min Duration Guard)**: Bắt buộc thời lượng thực tế trong map phải đạt ít nhất $\ge 90\text{s}$ (`min_duration_sec = 90.0`). Triệt tiêu hoàn toàn anti-pattern kết thúc sớm giả tạo do số quái vật cục bộ $\le 30$.
  - Đạt khi thỏa mãn một trong các cổng kiểm định hợp lệ:
    1. **Cổng 1 (Boss Slain)**: Đã hạ gục Boss map chính (`m_bossSlain == True`) sau khi đã ở trong map $\ge 90\text{s}$.
    2. **Cổng 2 (Minimap Fog Coverage)**: Tỷ lệ mở sương mù Minimap đạt $\ge 85\%$ (`coverage_ratio >= 0.85`), hoặc thuật toán `MinimapFogExplorer` xác nhận không còn Frontier khả thi.
    3. **Cổng 3 (Traversed Distance & Core State)**: Quãng đường tuần tra tích lũy $\ge 1200\text{u}$ kết hợp Core Engine xác nhận `MAP_COMPLETED_PORTAL_OUT` (State 9) hoặc khu vực yên ắng kéo dài 25s sau khi đã tuần tra khắp bản đồ.
    4. **Cổng 4 (Hard Safety Cap)**: Thời lượng an toàn tối đa (240s – 300s) chống kẹt địa hình.

---

## 4. MA TRẬN BẤT BIẾN KIẾN TRÚC BỔ SUNG (NEW INVARIANTS)

| Mã Bất Biến | Mô Tả Quy Tắc | Module Giám Sát |
|---|---|---|
| **INV-MAP-LEGITIMATE-CLEAR-V2** | TUYỆT ĐỐI CẤM kết luận hoàn tất map khi mới đánh 1 con quái hoặc vào vùng vắng quái. Rào chắn CẤM THOÁT SỚM: Bắt buộc thỏa mãn đồng thời cả 3 trụ cột: (1) Thời gian trong map $\ge 90\text{s}$; (2) Quãng đường tuần tra $\ge 1200\text{u}$; (3) Mục tiêu cốt lõi: Mở sương Minimap $\ge 80\%$ HOẶC Map Boss đã bị tiêu diệt. | `MapClearEvaluator`, `AutonomousMapRunner`, `FrontierExplorationEngine`, `CharacterFSM` |
| **INV-STASH-LOGISTICS-SAFE** | Mọi tương tác Hòm đồ phải đóng UI bằng `Spacebar` (`VK_SPACE 0x20`) trước khi di chuyển sang Map Device. Tuyệt đối không để cửa sổ Stash mở khi click bệ đá. | `StashOrchestrator`, `AutonomousMappingCoordinator` |
| **INV-WAYSTONE-RESTOCK-MIN** | Duy trì tối thiểu 2 Waystones trong túi đồ. Nếu rỗng, BẮT BUỘC thực thi quy trình rút từ Stash Map Tab trước khi sang Stage 2. | `AutonomousMappingCoordinator::execute_stage1_precheck` |
| **INV-MAP-NO-BRICK** | TUYỆT ĐỐI CẤM bấm TRAVERSE nếu Waystone chứa mod trong Blacklist (Reflect, Cannot Leech). Bắt buộc Re-roll hoặc đổi Waystone khác. | `WaystoneAutoCrafter`, `AutonomousMappingCoordinator` |
| **INV-DEATH-RECOVERY-TIMEOUT** | Khi phát hiện cờ tử trận (`movement_flags & 8`), thực hiện click hồi sinh trong vòng $\le 5.0\text{s}$, không để nhân vật kẹt vĩnh viễn ở màn hình chết. | `AutonomousMappingCoordinator::execute_stage6_portal_return` |
| **INV-SAFE-PORTAL-CAST** | Trước khi bấm phím `.` mở Town Portal, bắt buộc kiểm tra khoảng cách quái gần nhất $\ge 10\text{u}$ để chống bị ngắt animation niệm cổng. | `AutonomousMapRunner`, `QuestNavigator` |
| **INV-CLIENT-CRASH-RECOVER** | Khi client game POE2 bị crash hoặc đóng đột ngột, Watchdog tự động kích hoạt `Poe2ClientLauncher` mở lại và chờ vào Hideout an toàn. | `Poe2ClientLauncher`, `AutonomousMappingCoordinator` |

---

## 5. KẾ HOẠCH TRIỂN KHAI THEO GIAI ĐOẠN (IMPLEMENTATION PHASES)

### Phase 1: Tích Hợp Hậu Cần Hòm Đồ & Rút Waystone Tự Động (P1 — Triển Khai Ngay)
- Gắn cờ `enable_stashing=True` làm mặc định trong `run_multi_map_loop`.
- Kết nối `StashOrchestrator` vào sau Stage 6 để tự động cất Currency/Loot.
- Trong Stage 1, nếu `not waystones_found`, tự động chuyển hướng gọi `execute_stage0_stash_routine` để rút Waystone từ Map Tab thay vì dừng lại (`EXHAUSTED`).

### Phase 2: Khóa Chặn Mod Bản Đồ Nguy Hiểm & Tự Động Re-roll (P2)
- Tích hợp hàm kiểm tra `is_brick_mod(text)` trước khi đặt Waystone vào khay.
- Thêm bước re-roll tự động nếu Waystone dính mod cấm.

### Phase 3: Nâng Cấp Frontier Fog Exploration & Watchdog Tự Mở Lại Game (P3)
- Kết nối bộ đọc Fog of War trong C++ Core Hot Path để điều hướng men sương.
- Hoàn thiện Watchdog phát hiện Client Crash để tự động khởi động lại qua `Poe2ClientLauncher`.