# 14. QUY CHUẨN KỸ THUẬT, CHUẨN HÓA CHẤT LƯỢNG PHẦN MỀM & PHÒNG NGỪA HỒI QUY TOÀN DIỆN ## (Engineering Quality & Anti-Regression Master Protocol) > **Mã Tài Liệu**: `DOC-SPEC-QUALITY-ANTI-REGRESSION-20260907` > **Mốc Thời Gian Chuẩn Hóa**: `07/09/2026` > **Bối Cảnh Hệ Thống**: AutoPOE2 (C++23 Low-Latency Core Engine + Python 3.11 Passive Companion HUD / ShmBridge / AI Assistant) > **Phiên Bản Tham Chiếu**: Path of Exile 2 Standalone Engine (v0.5.5 / Early Access Q3-2026) > **Tiêu Chuẩn Áp Dụng**: Google Senior SWE Invariant Engineering Rigor & Claude 3.7 Sonnet / Opus Agentic Verification Standard > **Tài Liệu Căn Cứ**: `AGENTS.md`, `GEMINI.md`, `docs/development/01_system_architecture.md`, `vitals_calibration_architecture.md`, `13_commercial_bot_hp_detection_and_fast_activation_benchmark.md`, `Tham_Dinh/2026-09-07_17-31_bao_cao_tham_dinh_docs_vs_core_logic.md`. --- ## 1. PHÂN TÍCH NGUYÊN NHÂN GỐC RỄ CÁC LỖI LẶP ĐI LẶP LẠI (ROOT CAUSE ANALYSIS) Qua quá trình rà soát toàn diện codebase (`src/core/`, `src/assistant_tool/`), tài liệu kiến trúc (`docs/development/`) và các báo cáo thẩm định thực địa gần nhất, hệ sinh thái AutoPOE2 bộc lộ **8 mẫu lỗi lặp đi lặp lại (Recurring Bug Patterns)** và **3 Nguyên Nhân Gốc Rễ (Root Causes)** mang tính cấu trúc. ```mermaid graph TD subgraph Root Causes RC1["Tư Duy Chữa Cháy Tạm Thời
(Symptom Patching / Layered Heuristics)"] RC2["Thiếu Deterministic Pointer Traversal
(Lệ thuộc Differential 8GB RAM Scan)"] RC3["Thiếu Deterministic Mock Test Engine
(Không test được vòng đời Realtime)"] RC4["Văn Hóa Làm Việc Agent Cũ
(Code chay, Đoán bằng mắt, Doc Drift)"] end subgraph Recurring Bugs B1["HP/Mana/ES Calibrate Sai (2/250)"] B2["Quét RAM 8GB 100% CPU Khi Đổi Map"] B3["XYZ Mất Dấu Bắt Bước Đi 1-2 Bước"] B4["Phantom Monsters Đánh Vào Không Khí"] B5["Đảo Dấu Trục Y Phép Chiếu Isometric"] B6["Watchdog 5s Tự Sát Thay Vì Passive"] B7["Hot Path Vi Phạm Zero-Alloc & Zero-Syscall"] B8["Dead Config (Spirit +36, Max 2000, || true)"] end RC1 --> B3 RC1 --> B4 RC1 --> B8 RC2 --> B1 RC2 --> B2 RC2 --> B3 RC3 --> B1 RC3 --> B5 RC3 --> B6 RC4 --> B5 RC4 --> B6 RC4 --> B7 ``` ### 1.1. Danh Mục 8 Mẫu Lỗi Lặp Đi Lặp Lại Kinh Điển | # | Tên Lỗi & Biểu Hiện | Vị Trí Code Vi Phạm | Nguyên Nhân Kỹ Thuật Trực Tiếp | |---|---|---|---| | **1** | **Calibrate Vitals Dị Thường (HP 2/250, ES 125/0, Mana 2/256)**
Tool báo động giả, spam bình máu, đóng băng Failsafe, đầu độc `offsets.toml`. | `game_session.cpp:710–730`
`main.cpp:590–608`
`player_finder.cpp:18–34` | Fallback RVA `0x4434CE0` không kiểm tra semantic; nạp `player_addr` tin tưởng tuyệt đối mà không đối chiếu `expectedMaxHP`; giả định sai layout PoE 1 `{hp, maxHP, maxHP}` tại `+0, +4, +8`. | | **2** | **Quét RAM 8GB Ngốn 100% CPU Mỗi Lần Đổi Map**
Chuyển cảnh ngốn 15s–60s CPU 100%, gây nghẽn luồng, drop FPS và đơ giao diện. | `player_finder.cpp:16–34`
`game_session.cpp:528` | Quét vi sai brute-force toàn bộ 8GB Virtual Memory; lỗi trượt biên chunk (off-by-boundary) dòng 18–21 (`off += buf.size()` thiếu 12-byte overlap) bỏ sót struct vắt qua biên 1MB. | | **3** | **Mất Dấu XYZ Bắt Người Dùng Bước Đi (`WAITING_FIRST_STEP`)**
Hiện thông báo bắt bước đi 1–2 bước; kẹt cứng nếu AFK hoặc trong Grace Period bất tử. | `game_session.cpp:365–381`
`game_session.cpp:232–236`
`game_session.cpp:888` | Khi mất dấu 500ms (60 frames), tự gán `m_xyzAddr = 0` và chuyển sang `WAITING_FIRST_STEP`. Vá chắp vá bằng thread ngầm `keybd_event('W')` vi phạm nghiêm trọng khóa an toàn focus cửa sổ. | | **4** | **Quái Vật Ảo / Phantom Targets Đánh Vào Khoảng Không**
Đứng giữa bãi đất trống nhưng spam skill combo vào không khí, đổi hướng bất thường. | `entity_manager.cpp:441–500` | Khi chưa calibrate entity array (`m_entityArraySlot == 0`), quét 4MB RAM quanh player tìm 3 float liên tiếp rồi tự tạo quái ảo HP 100/100 (`name = "Hostile Monster"`). Rác đồ họa (vertex buffer, particles) bị biến thành quái vật! | | **5** | **Đảo Dấu Trục Y Trong Phép Chiếu Isometric**
Ở chế độ chuột, auto-quest đi lệch hướng dọc, auto-loot và kiting chạy theo hướng đối xứng ngược lại! | `quest_navigator.cpp:54` (`+`)
`reflex_manager.cpp:352` (`-`)
`loot_controller.cpp:299` (`-`) | Copy-paste code toán học isometric giữa các module mà không gom về một hàm dùng chung duy nhất (`WorldToScreen`). Dẫn đến xung đột dấu giữa navigation và combat reflex. | | **6** | **Watchdog Timeout 5s Giết Toàn Bộ Core Thay Vì Hạ Cấp Co-Pilot Passive**
Python HUD đơ/crash khiến C++ Core tự sát theo, làm mất cơ chế bảo vệ sinh tồn (Auto-Flask, Emergency Logout). | `main.cpp:772–779`
`01_system_architecture.md` §4.3 | Mâu thuẫn tài liệu: Docs cam kết mất heartbeat 3s sẽ chuyển sang Co-Pilot Passive; code thực tế đợi 5s rồi gọi `shm.RequestStop()` hủy luôn toàn bộ Core. | | **7** | **Vi Phạm Nguyên Tắc Hot Path 120Hz ("Zero-Alloc & Zero-Syscall")**
Tuyên bố "Zero Alloc, Zero Syscall" nhưng vòng lặp 120Hz liên tục bị giật lag micro-stutter. | `main.cpp:751–769`
`main.cpp:1087–1103`
`entity_manager.cpp:446` | Gọi 5 lần `GetAsyncKeyState` mỗi tick (~600 syscalls/giây); `sleep_for(500ms)` đóng băng Core khi nhấn F11; cấp phát heap hàng chục `std::string`/`std::vector` mỗi tick trong `overlay::SetLines` và entity fallback. | | **8** | **Cấu Hình Chết (Dead Config) & Logic Rác Trong GameSession**
Vô hiệu hóa cấu hình người dùng, điều kiện luôn đúng, log sai định dạng. | `game_session.cpp:282`
`game_session.cpp:661`
`game_session.cpp:670`
`game_session.cpp:707` | Gán cứng `m_spiritAddr = m_playerAddr + 36` và chặn `spMax <= 2000` làm hỏng cấu hình và build endgame; `if (ReadPosition(...) || true)` luôn đúng; in log `"[XYZ] 0x" + std::to_string(t)`; bỏ qua reset khi chết tại cùng map. | --- ### 1.2. Ba Nguyên Nhân Gốc Rễ Mang Tính Cấu Trúc (Structural Root Causes) 1. **Tư Duy Chữa Cháy Tạm Thời (Symptom Patching) & Tháp Heuristic Chồng Chất (Layered Fallbacks)**: - Thay vì giải quyết triệt để tại tầng kiến trúc, lập trình viên liên tục tạo ra các nhánh "fallback trên fallback": * Không đọc được XYZ $\rightarrow$ sinh ra nhánh `CAPTURING_STILL_BASELINE`. * Cần nhân vật di chuyển $\rightarrow$ thêm trạng thái `WAITING_FIRST_STEP`. * Người dùng không bước đi $\rightarrow$ thêm thread gõ phím 'W' mù quáng (`keybd_event`). * Phím 'W' làm mất focus $\rightarrow$ lại tính thêm cờ check focus... - Càng nhiều tầng heuristic vá víu, hệ thống càng phi tất định (non-deterministic), tạo ra hàng loạt edge-case mới triệt tiêu lẫn nhau. 2. **Thiếu Deterministic Pointer Traversal & Quá Lệ Thuộc Vào Differential Scanning**: - Các bot thương mại lớn (Exilebuddy, PoEHelper) sử dụng kiến trúc **Deterministic Pointer Traversal $O(1)$**: $$\text{GameController} \longrightarrow \text{InGameState} \longrightarrow \text{InGameData} \longrightarrow \text{LocalPlayer} \longrightarrow \text{Components}$$ Thời gian giải mã chỉ tốn **$< 0.001\text{ ms}$** qua 4–5 lần đọc bộ nhớ, đạt độ tin cậy 100% tại đúng frame đầu tiên kết thúc Loading Screen. - AutoPOE2 ban đầu tiếp cận theo tư duy dò bộ nhớ vi sai của Cheat Engine: quét toàn bộ RAM 8GB để tìm sự thay đổi float/int. Cách tiếp cận này vốn không ổn định trên một game hiện đại có bộ nhớ động và garbage collection phức tạp như POE2. Khi AOB pattern hoặc RVA tĩnh bị lệch, hệ thống lập tức sụp đổ về chế độ brute-force quét RAM. 3. **Thiếu Môi Trường Mock Test Độc Lập Cho Luồng Thời Gian Thực (Lack of Headless Mock Engine)**: - Bộ kiểm thử trước đây chỉ kiểm tra được các hàm toán học đơn lập trên struct đệm tĩnh (`SimulatedMemoryReader`). - Hoàn toàn thiếu Integration Mock Test mô phỏng vòng đời thực tế: Game khởi động $\rightarrow$ Đổi map $\rightarrow$ Tải màn hình $\rightarrow$ Grace Period $\rightarrow$ Agent disconnect $\rightarrow$ Đọc bộ nhớ lỗi $\rightarrow$ Phục hồi. - Do không có mock test cho các kịch bản ngoại lệ này, các đoạn mã chắp vá (hacky fallbacks) được đưa thẳng vào production mà không được kiểm chứng tự động. --- ## 2. QUY CHUẨN LẬP TRÌNH MỚI (NEW ENGINEERING QUALITY STANDARDS) ### 2.1. Cấm Triệt Để Heuristic Fallback Trong Core Engine (Zero-Tolerance Heuristic Policy) 1. **Nguyên Tắc Fail-Safe & Fail-Silent**: - Khi chưa giải mã được con trỏ bộ nhớ (chưa có `m_entityArraySlot` hoặc `m_xyzAddr == 0`), Core Engine **BẮT BUỘC PHẢI GIỮ IM LẶNG VÀ ĐỨNG YÊN AN TOÀN**. - Tuyệt đối cấm tạo thực thể giả (Fake Entity / Phantom Monsters) từ dữ liệu float ngẫu nhiên trong bộ nhớ. Radar hiển thị 0 quái vật tốt hơn gấp triệu lần việc tung chiêu vào khoảng không làm lộ hành vi bot. 2. **Triệt Tiêu Hoàn Toàn Thread Gõ Phím Rời Rạc Ngoài Luồng**: - Nghiêm cấm `std::thread([]() { keybd_event(...); }).detach()`. - Mọi lệnh điều khiển phần cứng (chuột, bàn phím) BẮT BUỘC phải đi qua lớp điều vận phần cứng trung tâm (`KMBoxNet`), tuân thủ 3 tầng bảo vệ: * Cờ cho phép di chuyển vật lý (`m_allowPhysicalMove` / `--move`). * Kiểm tra cửa sổ tiền cảnh (`KMBoxNet::IsGameWindowFocused()`). * Tự động đưa game lên tiền cảnh có kiểm soát (`EnsurePoe2WindowFocus()`). 3. **Cấm Monkey-Patching, Bypasses & Magic Numbers**: - Tuyệt đối cấm `|| true`, `if (true)`, comment out assertions, hoặc bỏ qua sanity check để "tiện việc test/debug". - Cấm hardcode số ma thuật: `totalGoldLooted += 150`, `spMax <= 2000`, `playerAddr + 36`. Mọi số liệu phải đọc trực tiếp từ bộ nhớ hoặc cấu hình rõ ràng. --- ### 2.2. Chuẩn Hóa Static Pointer Path Traversal $O(1)$ Theo Chuẩn Bot Thương Mại POE2 (2026) Hệ thống loại bỏ vĩnh viễn việc quét toàn bộ RAM 8GB và chuẩn hóa sang kiến trúc giải mã con trỏ tĩnh $O(1)$: ```mermaid graph LR subgraph Startup 1-Time AOB PE[".text Section (48MB)"] -->|10ms AOB Scan| RVA["Static RVA Offset"] RVA --> GC["GameController (.data)"] end subgraph Runtime O(1) Traversal [< 0.001 ms] GC -->|+0x100000| IGS["InGameState"] IGS -->|+0x120000| IGD["InGameData"] IGD -->|+0x110000| LP["LocalPlayer"] LP -->|+0x48| LC["LifeComponent
(HP, Mana, ES, Spirit)"] LP -->|+0x28| PC["PositionedComponent
(GridX, GridY, WorldX, WorldY)"] IGD -->|+0x200000| EM["EntityMap
(std::vector<Entity*>)"] end ``` #### Bảng Đối Soát Công Nghệ Truy Xuất Bộ Nhớ | Tiêu Chí Kỹ Thuật | Cơ Chế Cũ (Differential RAM Scan) | Chuẩn Nâng Cấp 2026 (Static Pointer Traversal $O(1)$) | |---|---|---| | **Thời gian kích hoạt khi load map** | 15.000 ms – 60.000 ms | **< 0.001 ms (Vài nano-giây)** | | **Mức tiêu thụ CPU** | 100% CPU trên toàn bộ các core | **~ 0.0% CPU** | | **Yêu cầu tương tác người dùng** | Bắt bước đi 1–2 bước (`WAITING_FIRST_STEP`) | **Zero-Touch 100% tự động** | | **Xử lý Grace Period** | Chờ click tay, AFK dẫn đến deadlock | **Micro-step tự động 15 units sau 300ms** | | **Độ tin cậy dữ liệu** | Dễ bắt nhầm float rác, trượt biên 12-byte | **Chính xác tuyệt đối 100% từ Struct Component** | #### Quy Trình Kích Hoạt Siêu Tốc Tại Mốc 400ms (Fast Activation Workflow) ```mermaid sequenceDiagram participant Game as POE2 Engine participant Sensor as Hybrid Area Listener participant Core as C++23 Core Engine participant KMBox as Hardware KMBoxNet Game->>Sensor: [LOADING SCREEN] Duration = 3.2s / IsLoading = false Sensor->>Core: OnZoneLoadingFinished() Event Note over Core: Mốc 0ms - 150ms: Chờ Heap Game ổn định Core->>Game: Đọc chuỗi con trỏ O(1) (GC -> IGS -> IGD -> LP) Note over Core: Mốc 150ms: HP, Mana, ES, XYZ sẵn sàng 100% Note over Core: Mốc 150ms - 300ms: Tính toán NavMesh & A* Path ngầm Core->>KMBox: Mốc 300ms: Phát xung Micro-Step (15 units) an toàn KMBox->>Game: Gửi phím W ngắn (45ms) có kiểm soát Focus Game-->>Core: Bùa bất tử Grace Period được giải trừ an toàn Note over Core: Mốc 400ms: Kích hoạt Combat/Loot/Quest Farm tự động! ``` --- ### 2.3. Chuẩn Hóa Headless Mock POE2 Memory Engine & Automated Testing Để triệt tiêu phụ thuộc vào game client thật và quyền Administrator Windows, kiến trúc kiểm thử được chuẩn hóa: 1. **Trừu Tượng Hóa Giao Diện `IMemoryReader`**: - `RPMReader`: Dành cho môi trường vận hành thực tế (Production) với game thật. - `HeadlessMockReader` / `SimulatedMemoryReader`: Chạy hoàn toàn tại **User-Mode** (`asInvoker`), cấp phát vùng nhớ giả lập 8MB/16MB. 2. **Khả Năng Tiêm Dữ Liệu & Giả Lập Kịch Bản Động**: - Tiêm cấu trúc `GameController`, `InGameState`, `LifeComponent`, `PositionedComponent`. - Giả lập hiện tượng chuyển map (Area Transition), nạp rác bộ nhớ (Heap Relocation), rơi kết nối IPC, và rớt máu đột ngột (< 28%). 3. **Bộ Công Cụ Kiểm Soát Chất Lượng (Quality Toolchain Integration)**: - **C++23 Clang-Tidy (`.clang-tidy`)**: Kiểm soát hiện đại hóa mã nguồn, phát hiện leak và vi phạm zero-alloc. - **AddressSanitizer (ASan)**: Tích hợp qua flag `-DENABLE_ASAN=ON` trong `CMakeLists.txt`. - **Python Pytest Suite**: Kiểm thử tự động 79 test cases bao gồm Mock IPC, Safety Interlock, Optical Sensor và Structured AI Agent. - **PowerShell One-Click Regression Runner (`scripts/run_regression_tests.ps1`)**: Chạy toàn bộ kiểm thử hệ thống chỉ với một câu lệnh duy nhất. --- ### 2.4. Nâng Cấp Kỹ Năng AI (Google GenAI SDK & Structured Outputs) - Loại bỏ hoàn toàn Regex parsing thô (`re.search(...)`) trong phân tích chat giao dịch và lập kế hoạch vĩ mô. - Khai thác tối đa Gemini 3.8 Flash SDK với **Pydantic Structured Outputs** (`MacroDecisionResult`, `TradeWhisperAnalysis`, `GameActionCommand`) đảm bảo 100% dữ liệu trả về chuẩn kiểu và an toàn trước prompt injection. --- ## 3. BỘ QUY TẮC NÂNG CẤP MỞ RỘNG CHO AGENTS.MD & GEMINI.MD (RULES 8, 9, 10, 11) Bốn quy tắc kỹ thuật nâng cấp sau đây đã được hợp nhất chính thức vào `AGENTS.md` và `GEMINI.md`: ```markdown ### QUY TẮC 8: Triệt Tiêu Sửa Lỗi Triệu Chứng (Root-Cause-First & Anti-Symptom Patching Protocol) - Cấm Monkey-Patching, bypass conditions (`|| true`), hardcode số ma thuật (`+= 150`, `spMax <= 2000`). - Cấm tự ý spawn thread gửi input vật lý ngoài kiểm soát của Focus Interlock. - Bắt buộc thực hiện Quy trình 4 bước RCA: 1. Tái hiện & Truy vết (Reproduce & Trace) 2. Phân tích Bất biến bị Vi phạm (Invariant Invalidation Analysis) 3. Tái cấu trúc Tận gốc (Structural Architectural Fix) 4. Khóa chặn bằng Invariant Assertion (Contract Enforcement) ### QUY TẮC 9: Cổng Kiểm Thử Đối Chiếu Nghiêm Ngặt Trước Khi Công Bố (Mandatory Verification Gate Before Done) - Nguyên tắc vàng: "Untested code is broken code." Cấm tư duy "Code chay / Đoán bằng mắt". - Cấm sao chép/tái sử dụng số liệu kiểm thử cũ. Bắt buộc trích xuất Raw Terminal Output thực tế trong phiên. - Môi trường Non-Admin: Bắt buộc chạy Mock Unit Tests hoặc verification scripts ở User-Mode. ### QUY TẮC 10: Hợp Đồng Đồng Bộ Tuyệt Đối Tài Liệu & Mã Nguồn (Zero-Drift Code-Doc Contract) - Nguyên tắc Single Source of Truth (SSoT): Tần số (Hz), độ trễ (ms), hotkeys, watchdog policy phải khớp 100% giữa docs và code. - Quy tắc Atomic Doc-Code Commit: Sửa logic code bắt buộc cập nhật tài liệu tương ứng đồng thời. - Phân biệt rõ hiện trạng và kế hoạch: Tính năng chưa cài đặt chỉ được ghi `[PLANNED]` hoặc `[DRAFT]`. ### QUY TẮC 11: Phòng Ngừa Hồi Quy Bằng Mock Harness Tự Động (Automated Regression Prevention via Mock Harness) - Thuật toán thuần túy (A*, Bézier, WorldToScreen, Vitals Sanitizer, SPSC Ring) phải chạy độc lập 100% trên Mock Harness ở User Mode. - Bug-Driven Regression Testing: Khi phát hiện lỗi logic, bắt buộc viết Unit Test tái hiện lỗi trước khi sửa code. - Tích hợp liên tục vào bộ kiểm thử tự động của dự án. ``` --- ## 4. LỘ TRÌNH CẢI THIỆN TỨC THÌ TRONG NGÀY HÔM NAY (07/09/2026) Hệ thống thiết lập lộ trình 4 giai đoạn triển khai ngay trong ngày 07/09/2026: ```mermaid gantt title LỘ TRÌNH CẢI THIỆN CHẤT LƯỢNG AUTOPOE2 (07/09/2026) dateFormat HH:mm axisFormat %H:%M section Phase 1: Clean-up Ban hành Chuẩn & Dọn dẹp Code Nguy hiểm :done, p1, 17:30, 18:30 section Phase 2: O(1) Traversal Khóa Cứng Static Pointer Traversal O(1) :active, p2, 18:30, 21:00 section Phase 3: Mock Harness Mở Rộng Headless Mock Integration Tests :p3, 21:00, 23:30 section Phase 4: Audit Daily 3:00 AM Automated System Audit :p4, 03:00, 03:30 ``` ### Chi Tiết Kế Hoạch Từng Giai Đoạn: 1. **Giai Đoạn 1 (Buổi Chiều 17:30 – 18:30): Dọn Dẹp Điểm Nóng Mã Nguồn (Critical Code Clean-up)**: - [x] Soạn thảo và ban hành tài liệu chuẩn hóa `14_engineering_quality_and_anti_regression_protocol.md`. - [x] Đồng bộ Quy tắc 8, 9, 10, 11 vào `AGENTS.md` và `GEMINI.md`. - [x] Gỡ bỏ triệt để fallback quét raw memory tạo quái ảo trong `src/core/memory/entity_manager.cpp` (chuẩn hóa FNV-1a hash Entity ID từ gridX, gridY, maxHP). - [x] Thống nhất dấu trừ trong phép chiếu Isometric dùng chung `common::WorldToScreenIsometric` (`quest_navigator.cpp`, `combo_manager.cpp`, `reflex_manager.cpp`, `loot_controller.cpp` và Python `sync_memory_snapshot.py`). - [x] Cập nhật Watchdog trong `src/core/main.cpp` chuyển sang Co-Pilot Passive khi timeout và tự động phục hồi khi Healthy (không tắt Core). - [x] Loại bỏ thread ngầm `keybd_event` trong `src/core/game_session.cpp`, thay bằng Micro-Step có kiểm soát focus (`EnsurePoe2WindowFocus()`, `m_allowPhysicalMove`, `KMBoxNet::SendKey`). - [x] Khắc phục triệt để lỗi trượt biên float 4-byte trong `PlayerFinder` (`kOverlap = 4`, bước nhảy an toàn, dedupe `.first != fAddr`). 2. **Giai Đoạn 2 (Buổi Tối 18:30 – 21:00): Triển Khai Dứt Điểm Chuỗi Con Trỏ Tĩnh $O(1)$**: - [ ] Khóa cứng chuỗi con trỏ `ModuleBase + 0x4434CE0 -> RootObject (+0x48 Life, +0x28 Positioned)`. - [ ] Vô hiệu hóa vĩnh viễn cơ chế quét RAM 8GB (`PlayerFinder::Scan`) khi load map mới. - [ ] Tích hợp Area Change Listener Hybrid (lắng nghe `Client.txt` + polling RAM `InGameState.IsLoading`). - [ ] Kiểm chứng thời gian giải mã vitals và tọa độ $< 0.001\text{ ms}$. 3. **Giai Đoạn 3 (Đêm 21:00 – 23:30): Mở Rộng Headless Mock Engine & Full Regression Test**: - [x] Bổ sung 3 bộ Unit Test hồi quy độc lập vào `tests/test_core.cpp` (Test 29: Isometric Invariants, Test 30: Chunk Overlap 12B/4B, Test 31: Watchdog Co-Pilot Passive). - [x] Chạy toàn bộ bộ kiểm thử hồi quy: `powershell -File .\scripts\run_regression_tests.ps1`. - [x] Đảm bảo 100% C++ Unit Tests (759/759 checks) và Python Pytest (79/79 tests) đều PASS, Ruff sạch, Mypy sạch. 4. **Giai Đoạn 4 (Rạng Sáng 03:00 Ngày 08/09/2026): Kiểm Toán Đồng Bộ Tự Động Định Kỳ**: - [ ] Kích hoạt Daily 3:00 AM Automated Audit theo đúng Quy tắc 7. - [ ] Đối chiếu chéo 100% tài liệu `docs/development/` với mã nguồn C++ Core và Python Companion. - [ ] Nghiệm thu Zero-Drift, xác nhận hệ sinh thái AutoPOE2 đạt chuẩn thương mại cao cấp. --- ## 5. BẢN CHỈNH SỬA CỤ THỂ (DIFF) CHO AGENTS.MD VÀ GEMINI.MD Dưới đây là nội dung diff chuẩn hóa đã được tích hợp đồng bộ vào cả `AGENTS.md` và `GEMINI.md`: ```diff --- a/AGENTS.md +++ b/AGENTS.md @@ -84,3 +84,51 @@ - Tự động phát hiện, báo cáo và hiệu chỉnh ngay lập tức mọi điểm mâu thuẫn hoặc lệch pha kỹ thuật, bảo đảm hệ thống luôn đồng bộ tuyệt đối 100%. +--- + +## 8. Triệt Tiêu Sửa Lỗi Triệu Chứng (Root-Cause-First & Anti-Symptom Patching Protocol) +- **Triết lý cốt lõi**: Tuyệt đối không chấp nhận các giải pháp vá tạm bợ (monkey-patching, band-aid fixes) che giấu triệu chứng mà không giải quyết nguyên nhân gốc rễ (root cause). Mọi bản vá chỉ làm dịu bề nổi mà để lại nợ kỹ thuật (technical debt) hoặc phá vỡ các bất biến hệ thống (invariants) đều bị coi là lỗi kỹ thuật nghiêm trọng. +- **Các hành vi bị CẤM TUYỆT ĐỐI**: + 1. *Cấm bypass điều kiện*: Không được thêm các điều kiện vô hiệu hóa kiểm tra kiểu `|| true`, `if (true)`, comment out assertions, hoặc bỏ qua sanity check để "tiện việc test/debug". + 2. *Cấm hardcode số ma thuật (magic numbers) & fake data*: Không gán số liệu ảo (như `totalGoldLooted += 150`, `spMax <= 2000`, offset cố định `+ 36`, fake entity HP 100/100) để qua mặt logic xác thực hoặc bù đắp cho module chưa hoàn thiện. + 3. *Cấm phá vỡ cơ chế an toàn / Focus Interlock*: Không được tự ý spawn thread rời rạc (ví dụ: `std::thread([]() { keybd_event(...); }).detach()`) để gửi input vật lý mà không thông qua interlock an toàn (`KMBoxNet::IsGameWindowFocused()`, `EnsurePoe2WindowFocus()`, flag `--move` / `allowPhysicalMove`). + 4. *Cấm đảo lộn thứ bậc phụ thuộc sinh tồn*: Không để crash hoặc lỗi ở tầng Cold Path (Python Companion HUD / GUI / Telemetry) kéo sập phản xạ sinh tồn độc lập của tầng Hot Path (C++ Core auto-flask / emergency logout). +- **Quy trình 4 bước bắt buộc khi sửa lỗi (Mandatory 4-Step RCA)**: + 1. **Tái hiện & Truy vết (Reproduce & Trace)**: Cô lập chính xác điều kiện kích hoạt lỗi, vẽ chuỗi gọi hàm (call graph) từ điểm phát sinh lỗi ngược về nguồn dữ liệu bẩn. + 2. **Phân tích Bất biến bị Vi phạm (Invariant Invalidation Analysis)**: Xác định rõ ràng bất biến kiến trúc (architectural invariant) nào bị phá vỡ (ví dụ: hệ trục tọa độ isometric không đồng nhất giữa các module, con trỏ bộ nhớ bị stale sau khi đổi map, v.v.). + 3. **Tái cấu trúc Tận gốc (Structural Architectural Fix)**: Viết lại hàm dùng chung duy nhất (Single Source of Logic - ví dụ `WorldToScreen(dx, dy)` chuẩn hóa), loại bỏ hoàn toàn các bản sao logic phân mảnh và mâu thuẫn. + 4. **Khóa chặn bằng Invariant Assertion (Contract Enforcement)**: Bổ sung `assert()`, `static_assert()`, hoặc exceptions kiểm tra tiền điều kiện/hậu điều kiện (preconditions/postconditions) để lỗi không bao giờ có cơ hội âm thầm vượt qua được nữa. + +--- + +## 9. Cổng Kiểm Thử Đối Chiếu Nghiêm Ngặt Trước Khi Công Bố (Mandatory Verification Gate Before Done) +- **Nguyên tắc vàng**: *"Untested code is broken code."* Không một nhiệm vụ nào được phép đánh dấu `[COMPLETED]` nếu chưa vượt qua cổng kiểm thử đối chiếu độc lập bằng lệnh thực thi thực tế (Raw CLI Test Output). +- **Cấm tư duy "Code chay / Đoán bằng mắt"**: + - Không bao giờ được suy đoán rằng "code trông chuẩn rồi thì chắc chắn sẽ chạy đúng". + - Không được dùng việc "biên dịch thành công (build pass)" làm bằng chứng thay thế cho "logic nghiệp vụ đúng (test pass)". + - Tuyệt đối cấm sao chép/tái sử dụng số liệu kiểm thử cũ từ phiên trước hoặc từ tài liệu cũ (như trích dẫn "610/610 PASS" hoặc "696/696 PASS" mà không chạy lệnh đo kiểm thực tế trong phiên hiện tại). +- **Quy định về Bằng chứng Thực thi trong Báo Cáo (Verification Evidence Criteria)**: + - Bắt buộc phải chạy test thông qua công cụ dòng lệnh (`run_command`). + - Phải trích xuất trực tiếp stdout/stderr của lệnh test thực tế vào báo cáo (bao gồm: lệnh đã gõ, thời gian thực thi, số lượng test case PASS/FAIL, bộ nhớ hoặc timing đo được). + - Khi môi trường thiếu quyền Admin (non-elevated) không thể chạy `AutoPOE2_Tests.exe` đầy đủ, BẮT BUỘC phải chạy Mock Unit Tests hoặc viết script verification cô lập chạy được ở User-mode để kiểm chứng toán học / logic trước khi báo cáo. + +--- + +## 10. Hợp Đồng Đồng Bộ Tuyệt Đối Tài Liệu & Mã Nguồn (Zero-Drift Code-Doc Contract) +- **Nguyên tắc Single Source of Truth (SSoT)**: Mã nguồn C++ / Python và tài liệu kiến trúc trong `docs/` là một thực thể thống nhất. Mọi sự sai lệch dù nhỏ nhất giữa tài liệu và code thực thi đều bị coi là lỗi nghiêm trọng (Zero Tolerance for Documentation Drift). +- **Các tiêu chuẩn đồng bộ bắt buộc**: + 1. *Tần số & Độ trễ (Frequencies & Latencies)*: Nếu code chạy ở chu kỳ 120Hz (~8.33ms), tài liệu KHÔNG ĐƯỢC ghi 200Hz (5ms). Mọi thông số thời gian phải phản ánh giá trị `constexpr` hoặc loop timer thực tế trong code. + 2. *Ánh xạ Phím & Hotkeys (Hotkey Bindings)*: Mọi thay đổi về phím bấm khẩn cấp hoặc phím chức năng (ví dụ: F11 chuyển từ Panic thành Calibrate XYZ, F12/Pause thành Panic Hotkey) phải được grep và cập nhật trên TOÀN BỘ các file tài liệu liên quan (`01_system_architecture.md`, `README.md`, `docs/wiki/`, v.v.). + 3. *Trạng thái Watchdog & Degrade Policy*: Cơ chế phục hồi khi timeout (ví dụ: Co-Pilot Passive vs Kill Core) trong code phải khớp 100% với kịch bản mô tả trong tài liệu. + 4. *Phân biệt Rõ Hiện Trạng vs Kế Hoạch*: Mọi tính năng chưa được cài đặt trong code thực tế chỉ được phép ghi trong docs dưới dạng `[PLANNED]` hoặc `[DRAFT]`. Tuyệt đối cấm viết tài liệu dạng "ước nguyện" (wishful thinking) trình bày như thể tính năng đã hoàn thiện trong khi code chưa hề có. +- **Quy tắc Atomic Doc-Code Commit**: + - Không có bất kỳ thay đổi logic nào được coi là hoàn tất nếu các tài liệu kỹ thuật liên quan chưa được sửa đổi đồng thời. Sub-agent tài liệu và sub-agent code phải bàn giao sản phẩm đồng bộ trong cùng một đợt cập nhật. + +--- + +## 11. Phòng Ngừa Hồi Quy Bằng Mock Harness Tự Động (Automated Regression Prevention via Mock Harness) +- **Thách thức thực tế**: Game client Path of Exile 2 là môi trường phụ thuộc cao (cần game chạy thật, cần quyền Administrator đọc Virtual Memory qua RPM, dễ bị hạn chế trong môi trường CI/Sandbox). +- **Yêu cầu bắt buộc về Mock Harness**: + 1. *Độc lập hoàn toàn với Client*: Tất cả các module thuật toán và xử lý dữ liệu thuần túy (như Coordinate Transform `WorldToScreen`, Pathfinder A*, Vitals Sanitizer, Humanized Bézier Curve, SPSC Ring Buffer, Loot Deduplication) BẮT BUỘC phải có **Mock/Simulated Test Harness** chạy độc lập 100% trong User Mode, không cần quyền Admin và không cần mở game thật. + 2. *Bug-Driven Regression Testing*: Mỗi khi một lỗi logic được phát hiện (ví dụ: lỗi đảo dấu trục Y giữa QuestNavigator và ReflexManager, lỗi trượt biên 12-byte khi quét memory chunk, lỗi dead-config của `m_spiritAddr`), BẮT BUỘC phải viết ngay một Unit Test case tái hiện đúng lỗi đó (reproduction test) trước khi sửa code, và đảm bảo test case này PASS sau khi sửa. + 3. *Tích hợp vào Bộ Kiểm Thử Tự Động*: Mọi regression test mới phải được đưa vào danh sách kiểm thử tự động của dự án (`AutoPOE2_Tests` hoặc `pytest`), bảo đảm lỗi không bao giờ có cơ hội tái phát trong bất kỳ bản build tương lai nào. ``` --- ## 6. KẾT LUẬN & ĐỀ XUẤT HÀNH ĐỘNG TIẾP THEO Tài liệu này xác lập ranh giới kỷ luật kỹ thuật mới cho toàn bộ hệ sinh thái AutoPOE2. Mọi sub-agent tham gia phát triển dự án từ thời điểm này bắt buộc phải tuân thủ nghiêm ngặt 11 Quy tắc của `AGENTS.md` và `GEMINI.md`, hướng tới mục tiêu xây dựng một phần mềm hỗ trợ chơi game đẳng cấp thương mại: an toàn tài khoản tuyệt đối, độ trễ cực thấp (< 0.001 ms), ổn định 100% và không bao giờ gặp lại các lỗi lặp đi lặp lại.