# 71. ĐẶC TẢ KIẾN TRÚC TÁC TỬ TỰ TIẾN HÓA & HỆ THỐNG TỰ SINH HARNESS (DOC 71)
## (Self-Evolving Autonomous Agent, Anomaly Self-Diagnosis, Auto-Harnessing & Closed-Loop Repair)

- **Mã tài liệu**: `SPEC-DOC-71-SELF-EVOLVING-AGENT-AND-AUTONOMOUS-HARNESS-20260918`
- **Mốc thời gian**: `18/09/2026` (Bối cảnh thực tế Q3/2026 — PoE2 Early Access v0.5.5+, C++23, Python 3.11.9)
- **Kế thừa & Tương thích**: Doc 50 (Two-Tier Asymmetric Architecture), Doc 61 (Autonomy Gap SSoT), Doc 66 (Agent Harness Governance), Doc 17 (Watcher & Mock Harness)
- **Trạng thái**: `[SSoT THIẾT KẾ & ĐIỀU PHỐI HEARTBEAT — SẴN SÀNG TRIỂN KHAI]`
- **Đối tượng áp dụng**: Senior Orchestrator Agent và toàn bộ 6 Domain Specialist Sub-Agents

---

## 1. TỔNG QUAN & TẦM NHÌN: CHUYỂN HÓA TỪ BOT SANG SELF-EVOLVING AGENT

### 1.1. Sự Khác Biệt Giữa Macro Bot vs Self-Evolving Game Agent
Hệ thống **AutoPOE2** hiện nay là một Co-Pilot kết hợp Bot FSM bán tự động mạnh mẽ (Hot Path 120Hz, Seqlock SHM 39KB, KMBox Net Bézier, PlayerFinder quét 16MB). Tuy nhiên, để đạt tới trạng thái **Tự hành hoàn toàn (Full Autonomy)** và **Tự nâng cấp bản thân (Self-Evolution)**, hệ thống cần chuyển hóa từ kiến trúc phản xạ thụ động sang mô hình **Tác tử Tự nhận thức & Tự tiến hóa (Self-Aware Self-Evolving Agent)**:

```mermaid
flowchart LR
    subgraph VONG_CU ["VÒNG LẶP TRUYỀN THỐNG (Tool/Bot)"]
        direction TB
        O1["Observe (Đọc RAM/OCR)"] --> D1["Decide (FSM tĩnh)"]
        D1 --> A1["Act (Click/WASD)"]
        A1 -. "Kẹt / Chết / Lỗi" .-> H1["Con người can thiệp & Debug"]
    end

    subgraph VONG_MOI ["VÒNG LẶP TIẾN HÓA TỰ TRỊ (Doc 71)"]
        direction TB
        O2["1. Observe (Đa cảm biến)"] --> D2["2. Decide (Mục tiêu & Kế hoạch)"]
        D2 --> A2["3. Act (KMBox Bézier)"]
        A2 --> S2["4. Sentinel (Soát 18 Invariants)"]
        S2 -- "Anomaly Detected" --> H2["5. Auto-Harness (Sinh Test Sandbox)"]
        H2 --> R2["6. Reflect & Evolve (Tự vá & Chỉnh tham số)"]
        R2 --> V2["7. Verify Gate (100% Pass)"]
        V2 --> D2
    end
```

### 1.2. Ba Định Lý Bất Biến Của Tác Tử Tự Tiến Hóa (Core Theorems)
1. **Định lý Phân Tầng Thời Gian Thực (Realtime Separation Theorem)**: Hot Path 120Hz (C++23) độc lập 100% về sinh tồn; các tác vụ tự suy luận, tự sinh test harness và tự vá code phải chạy bất đồng bộ tại Tier 3 (Meta Path) để **CPU dispatch trên Hot Path luôn < 0.5µs** (`INV-ACTUATOR-NON-BLOCKING`).
2. **Định lý Tái Hiện Tất Định (Deterministic Reproduction Theorem)**: Mọi sự cố, hành vi bất thường hoặc điểm nghẽn hiệu suất đều có thể đóng gói thành một Mock Test Case chạy 100% User-Mode độc lập không cần game thật và không cần quyền Admin (`INV-HARNESS-HEADLESS`).
3. **Định lý Cổng Nghiệm Thu Thực Nghiệm (Empirical Gate Theorem)**: Tuyệt đối cấm đưa bất kỳ bản vá tham số hoặc code mới nào vào vận hành nếu chưa chứng minh: **Fail trên test harness trước khi sửa $\implies$ Pass 100% trên test harness sau khi sửa $\land$ Pass toàn bộ regression suite** (Rule 5 & Rule 6).

---

## 2. KIẾN TRÚC MỞ RỘNG 3 TẦNG (THREE-TIER EVOLVING ARCHITECTURE)

Kế thừa kiến trúc 2 tầng của [Doc 50](50_two_tier_asymmetric_hybrid_architecture_specification.md), bổ sung **Tier 3 (Meta-Agent Path)** đóng vai trò là "Bộ não phản tư & phòng thí nghiệm sandbox":

```mermaid
flowchart TD
    subgraph TIER1 ["TIER 1: HOT PATH (120Hz - C++23)"]
        C1["ReflexManager (<10ms, Auto-Flask/Logout/Iframe)"]
        C2["BotBrain Arbiter (1 Action/Tick)"]
        C3["Hardware Actuator (KMBox Net, Bézier Curve)"]
        C4["SharedMemory Seqlock (39KB) + SPSC Ring Buffer"]
    end

    subgraph TIER2 ["TIER 2: COLD PATH (1-30Hz - Python 3.11)"]
        P1["Character Lifecycle FSM (Hideout / Map / Stash)"]
        P2["Map Coordinator & Stash Logistics"]
        P3["Vision OCR / Template Matcher"]
        P4["EventBus Decoupled Pub-Sub"]
    end

    subgraph TIER3 ["TIER 3: META-AGENT PATH (Async / Event-Driven - LLM & Sandbox)"]
        M1["Invariant Sentinel & Multimodal Flight Recorder"]
        M2["Auto-Harness Generator (Incident -> Pytest/C++ Harness)"]
        M3["Headless Mock Simulator (User-Mode Sandbox)"]
        M4["Reflex/Pickit Auto-Tuner & Strategy Evaluator (What-Is-Better)"]
        M5["Controlled Hot-Reload & Safe Patch Engine"]
    end

    TIER1 <== "Lock-Free Seqlock + SPSC Ring" ==> TIER2
    TIER2 -- "Anomaly Event / Flight Telemetry" --> TIER3
    TIER3 -. "Hot-Reload TOML/JSON Config" .-> TIER1
    TIER3 -. "Hot-Reload Python Modules / State" .-> TIER2
```

---

## 3. ĐẶC TẢ CHI TIẾT 4 PHÂN HỆ TỰ TRỊ

### Phân Hệ A: Tự Nhận Diện Vấn Đề (Self-Observation & Anomaly Detection)
Hệ thống giám sát liên tục thông qua 3 kênh cảm biến độc lập:
1. **Kênh Bất Biến Thời Gian Thực (Deterministic Invariants)**:
   - Vi phạm tọa độ: $\text{isMoving} = \text{true} \land (\Delta X^2 + \Delta Y^2 < 0.64) \text{ trong } > 500\text{ms} \implies$ `INV-XYZ-FROZEN` (kẹt địa hình).
   - Lệch pha cảm biến: $|Ratio_{\text{Optical}} - Ratio_{\text{RAM}}| > 0.25 \text{ trong } > 300\text{ms} \implies$ `INV-OPT-01` (trôi offset hoặc UI che khuất).
   - Lỗi cấu trúc bộ nhớ: $HP = 778 \land MaxHP = 778 \implies$ `INV-VIT-02` (đọc nhầm UI Marker).
   - Treo trạng thái FSM: FSM giữ nguyên một state $> 15.0\text{s}$ không chuyển tiếp $\implies$ `INV-FSM-DEADLOCK`.
2. **Kênh Hậu Kiểm Sự Cố (Blackbox Post-Mortem RCA)**:
   - Khi phát hiện `PlayerDeath`: Trích xuất 50 tick telemetry gần nhất từ `MultimodalFlightRecorder`.
   - Phân loại tự động:
     - `BURST_SLAM`: Mất $> 60\%$ EHP trong $< 500\text{ms}$.
     - `SWARM_OVERWHELM`: Số lượng quái vật áp sát $\ge 8$ cá thể.
     - `DOT_ATTRITION`: Mất máu từ từ do Poison/Bleed/Ground Effect mà không có hành động giải debuff.
3. **Kênh Đánh Giá Hiệu Suất Tự Hành (Drift & Efficiency Tracker)**:
   - Theo dõi tốc độ clear bản đồ (Map Clear Velocity): Nếu thời gian clear $> 180\text{s}$ hoặc lượng vàng/quặng thu thập được tụt $> 40\%$ so với mức chuẩn $\implies$ Cảnh báo `TACTICAL_INEFFICIENCY`.

---

### Phân Hệ B: Tự Động Hóa Sinh Test Harness (Self-Harnessing Pipeline)
Khi có bất kỳ sự cố Invariant nào được kích hoạt, hệ thống tự động thực hiện chuỗi quy trình khép kín:

```mermaid
sequenceDiagram
    autonumber
    participant Watcher as Realtime Watcher
    participant Recorder as Flight Recorder
    participant HarnessGen as Auto-Harness Generator
    participant Sandbox as Headless Test Sandbox
    participant Orchestrator as Senior Orchestrator

    Watcher->>Recorder: Kích hoạt Anomaly Trigger (0ms)
    Recorder->>Recorder: Lưu screenshot.png, raw_ram_dump.json, trace_ticks.json
    Recorder->>HarnessGen: Xuất incident_dossier.json vào debug_harness/incidents/
    HarnessGen->>HarnessGen: Phân tích cấu trúc lỗi & Sinh mã kiểm thử độc lập
    HarnessGen->>Sandbox: Tạo file tests/generated/test_incident_<id>.py
    HarnessGen->>Sandbox: Chạy lệnh: pytest tests/generated/test_incident_<id>.py
    Sandbox-->>HarnessGen: KẾT QUẢ: FAIL (Khẳng định tái hiện được lỗi 100% trong Sandbox)
    HarnessGen->>Orchestrator: Thông báo Dossier + Mã Test Reproduction sẵn sàng
```

- **Cấu trúc File Test Tự Sinh (`test_incident_<timestamp>.py`)**:
  ```python
  # Auto-generated by AutoHarnessGenerator from INCIDENT_20260918_...
  import unittest
  from src.assistant_tool.core_shm_bridge import CoreTelemetrySnapshot, PlayerTelemetry
  from src.agentic_engine.realtime_watcher import RealtimeWatcher
  from src.agentic_engine.invariant_sentinel import InvariantSentinel

  class GeneratedIncidentTest(unittest.TestCase):
      def setUp(self):
          self.dossier_data = load_incident_json("debug_harness/incidents/...")
          self.watcher = RealtimeWatcher(sentinel=InvariantSentinel())

      def test_reproduce_incident(self):
          # Nạp chính xác snapshot RAM từ hiện trường
          snapshot = build_snapshot_from_dossier(self.dossier_data)
          errors = self.watcher.process_telemetry(snapshot, is_moving=True)
          # Mục tiêu: Xác nhận hệ thống phát hiện chính xác mã lỗi
          self.assertIn(self.dossier_data["expected_error_code"], errors)
  ```

---

### Phân Hệ C: 3 Cấp Độ Tự Nâng Cấp Bản Thân (Self-Improvement Levels)

#### Cấp 1: Tự Hiệu Chuẩn Tham Số (Parametric Auto-Tuning) — Khả thi 100%
- Không sửa code; chỉ cập nhật file cấu hình TOML/JSON có kiểm soát:
  - **Reflex Auto-Tuning**: Chết do burst $\implies$ Tự động hạ ngưỡng `burst_dodge_threshold` từ 0.22 xuống 0.18; chết do quái vây $\implies$ tăng `kiting_distance` từ 35.0 lên 42.0.
  - **Dynamic Pickit Tuning**: Kho đồ đầy nhanh $\implies$ tự động tăng `min_value_chaos` từ 1.0 lên 2.5 dựa trên bảng giá POE2 Scout API ([Doc 68](68_poe2_market_pricing_and_dynamic_pickit_specification.md)).
  - **WASD Dwell Tuning**: Phát hiện xoay tại chỗ $\implies$ tự động tăng dwell từ 300ms lên 450ms.

#### Cấp 2: Tự Nâng Cấp Chiến Lược & Trang Bị (Strategic Evolution) — Khả thi 85%
- Tích hợp mô hình phản tư tại Tier 3:
  - **Đổi trang bị tối ưu (What-Is-Better Engine)**: Khi nhặt được trang bị Rare/Unique, đối chiếu chỉ số qua `WhatIsBetterEvaluator`. Nếu $\text{UtilityDelta} \ge +15.0$ và không vi phạm trần kháng 75% $\implies$ kích hoạt chu trình tự động thay đồ khi về Hideout.
  - **Đồ thị Tiến trình Atlas**: Tự động đánh giá các mod của Waystone trước khi cắm vào Map Device; tự động bỏ qua (blacklist) các map có mod chí tử đối với build (như Elemental Reflect hoặc No Mana Regen).

#### Cấp 3: Tự Sửa Lỗi Mã Nguồn Có Kiểm Soát (Controlled Code-Level Self-Repair) — Khả thi 60–70%
- Áp dụng độc quyền trên **Tầng Cold Path (Python 3.11)**:
  - Khi gặp lỗi parsing OCR hoặc logic tọa độ UI, Meta-Agent đọc mã nguồn liên quan, sinh patch thử nghiệm vào thư mục tạm `staging/`.
  - Chạy `pytest tests/generated/test_incident_<id>.py`. Nếu PASS, chạy tiếp toàn bộ regression suite (`pytest -m fast`).
  - Nếu tất cả các cổng nghiệm thu đều PASS $\implies$ gọi `importlib.reload()` áp dụng bản vá vào runtime mà không cần tắt game.
  - **Vùng Cấm Tuyệt Đối (Forbidden Surface)**: Cấm agent tự ý sửa mã nguồn phần cứng (`kmbox_net.*`), focus interlock, hoặc các hằng số an toàn cốt lõi trong Hot Path C++.

---

## 4. HỢP ĐỒNG ĐIỀU PHỐI HEARTBEAT TIẾP THEO (DISPATCH CONTRACT CHO ORCHESTRATOR)

Trong heartbeat tiếp theo, Senior Orchestrator sẽ phân rã nhiệm vụ và triệu hồi 3 Sub-Agents chuyên trách song song:

### 4.1. Task 1: Xây Dựng Bộ Sinh Kịch Bản Test Tự Động (Auto-Harness Generator)
- **Sub-Agent đảm nhiệm**: `qa_invariants_specialist`
- **Objective**: Tạo mới module `src/agentic_engine/auto_harness_generator.py`. Đọc dữ liệu từ `debug_harness/incidents/` và tự động sinh ra file test case `tests/generated/test_incident_<timestamp>.py` có khả năng chạy độc lập qua `pytest`.
- **Forbidden Surface**: `src/core/**`, `src/assistant_tool/ui/**`, `KMBoxNet.*`.
- **Merge Gate**: Sinh thành công test case từ file sự cố mẫu `debug_harness/LATEST_INCIDENT.json`; chạy lệnh `python -m pytest tests/test_harness_scenarios.py` trả về mã `0` (100% PASS).

### 4.2. Task 2: Khép Kín Vòng Lặp Tự Hiệu Chuẩn Phản Xạ & Tham Số (Reflex & Pickit Auto-Tuner)
- **Sub-Agent đảm nhiệm**: `python_systems_architect`
- **Objective**: Tích hợp `ReflexParameterTuner` và `WhatIsBetterEvaluator` vào luồng xử lý của `ControlCenter` / `AutonomousMappingCoordinator`. Khi nhân vật tử trận hoặc về Hideout, tự động đọc blackbox telemetry, ghi nhận tham số mới vào `captures/tuned_reflex_config.json` và bắn thông điệp IPC cập nhật xuống Core qua SPSC Ring Buffer.
- **Forbidden Surface**: `src/core/combat/reflex_manager.cpp` (giữ nguyên logic Hot Path, chỉ nhận config qua IPC/SHM).
- **Merge Gate**: Chạy unit test kiểm tra việc ghi và nạp cấu hình phản xạ không gây blocking; pytest pass trong `< 1.0s`.

### 4.3. Task 3: Đảm Bảo Hot-Path An Toàn Tuyệt Đối & Nhận Tham Số Dynamic Không Cần Khởi Động Lại
- **Sub-Agent đảm nhiệm**: `cpp_engine_specialist`
- **Objective**: Bổ sung hàm nạp lại tham số phản xạ động (`ReloadDynamicConfig`) trong `ReflexManager` và `BotBrain` từ cấu trúc SHM/IPC mà không cấp phát bộ nhớ động (`Zero Dynamic Allocation`) trong combat loop.
- **Forbidden Surface**: Bất kỳ lệnh gọi `new`, `malloc`, `std::vector::resize()` trong combat tick; không sửa giao diện KMBox hardware.
- **Merge Gate**: Biên dịch `AutoPOE2_Core.exe` và `AutoPOE2_Tests.exe` thành công; toàn bộ test domain `TestReflexManager` và `TestActuatorNonBlockingAndZeroHeap` đạt `100% PASS`.

---

## 5. MA TRẬN BẤT BIẾN BỔ SUNG (EXTENDED INVARIANTS)

| Mã Bất Biến | Tên Bất Biến | Quy Chuẩn Ràng Buộc | Module Giám Sát |
|---|---|---|---|
| **INV-HARNESS-HEADLESS** | Headless Mock Purity | Toàn bộ các test case tự sinh bắt buộc chạy 100% User-Mode, không cần quyền Administrator, không phụ thuộc cửa sổ game thật. | `AutoHarnessGenerator`, `SimulatedMemoryReader` |
| **INV-SELF-PATCH-ISOLATION** | Cold Path Only Self-Repair | Agent chỉ được phép tự sửa mã nguồn Python tại Tầng 2. Mọi can thiệp C++ Hot Path bắt buộc có sự phê duyệt của Orchestrator và tuân thủ kỷ luật `taskkill` pre-build. | `PatchEngine`, `SeniorOrchestrator` |
| **INV-CONFIG-HOTRELOAD-BOUNDS** | Parametric Safety Bounds | Tham số tự hiệu chuẩn không được vượt ngưỡng an toàn: $0.40 \le \text{FlaskHP} \le 0.85$, $0.12 \le \text{DodgeThreshold} \le 0.30$, $\text{KiteDistance} \le 60.0\text{u}$. | `ReflexParameterTuner`, `ReflexManager` |
| **INV-ROLLBACK-ON-REGRESSION** | Instant Staging Rollback | Bất kỳ bản vá tự động nào khiến số lượng test pass giảm hoặc phát sinh exception runtime trong 10s đầu tiên đều phải lập tức rollback về trạng thái trước đó. | `PatchEngine`, `WatchdogSupervisor` |