# JXHelper — Công Cụ Tự Hành Võ Lâm Truyền Kỳ (100% Background Input)

Bộ công cụ tự động hóa thông minh dành cho Võ Lâm Truyền Kỳ (JX1), được thiết kế theo tiêu chuẩn kỹ thuật hiện đại, kế thừa triết lý kiến trúc từ **AutoPOE2**:
- **Không chiếm chuột & phím (100% Background Input)**: Chuột thật và bàn phím của người dùng hoàn toàn tự do, có thể lướt web, làm việc hoặc chơi nhiều acc cùng lúc.
- **Tự động về thành an toàn**: Kích hoạt Thổ Địa Phù ngầm định kỳ hoặc theo yêu cầu.
- **Tự động dùng Túi Đồ Nghề trong rương F4**: Mở F4 $\rightarrow$ Click phải Túi Đồ Nghề $\rightarrow$ Tự động bấm phím `1` chọn dòng 1 (Sửa toàn bộ trang bị) $\rightarrow$ Tự đóng thông báo.
- **Tự động quay lại bãi train bằng Thần Hành Phù**: Click phải Thần Hành Phù trong F4 $\rightarrow$ Gửi phím số chọn bãi luyện công $\rightarrow$ Dịch chuyển thẳng ra bãi cắm cọc không cần chạy bộ.
- **Giao diện chuẩn VLAuto**: Thân thiện, trực quan, cấu hình lưu tức thời (`config.json`), hỗ trợ nút bấm lấy tọa độ 3s một chạm.
- **Sạch sẽ 100% trước Windows Defender**: Không can thiệp driver, không hook bàn phím toàn cục, không inject DLL nhạy cảm.

---

## 1. Bản đồ Tài liệu Kỹ thuật (Living Docs SSoT)
* **[`AGENTS.md`](./AGENTS.md)**: Hiến pháp tác chiến, Master Invariant Matrix, quy tắc module hóa triệt để.
* **[`GEMINI.md`](./GEMINI.md)**: Mục lục điều hướng tác chiến cho AI Agent.
* **[`docs/README.md`](./docs/README.md)**: Sơ đồ luồng dữ liệu (Mermaid) và chu trình khép kín 3 tính năng.
* **[`SECURITY_AUDIT_2026-09-28.md`](./SECURITY_AUDIT_2026-09-28.md)**: Báo cáo kiểm tra bảo mật hệ sinh thái VCTK (5 giai đoạn, bằng chứng đầy đủ) + [`security-baseline/`](./security-baseline/README.md).

---

## 2. Cấu trúc Thư mục Dự án

```text
c:\Projects\JX\
├── AGENTS.md                  # SSoT: Hiến pháp & Bất biến hệ thống
├── GEMINI.md                  # Mục lục điều hướng
├── README.md                  # Tài liệu hướng dẫn sử dụng & tổng quan
├── docs/                      # Bản vẽ kiến trúc & Luồng nghiệp vụ
└── src/
    └── JXHelper/              # Dự án C# .NET 8 WinForms
        ├── Common/            # Hằng số Win32 & Delay tiêu chuẩn
        ├── Platform/          # Background Input qua Message Queue & Window Manager
        ├── Config/            # Quản lý cấu hình JSON SSoT
        ├── Core/              # BotBrain, BotState & ActionExecutor
        └── UI/                # Giao diện MainForm phong cách VLAuto
```

---

## 3. Hướng dẫn Khởi chạy & Sử dụng Một Chạm

### A. Chạy ứng dụng
Mở PowerShell tại thư mục dự án và chạy:
```powershell
dotnet run --project src/JXHelper/JXHelper.csproj
```
Hoặc mở trực tiếp file thực thi đã biên dịch:
```text
src\JXHelper\bin\Debug\net8.0-windows\JXHelper.exe
```

### B. Các bước thiết lập:
1. **Chọn cửa sổ Game:** Chọn cửa sổ JX từ danh sách thả xuống trên cùng (bấm *Quét lại (F5)* nếu vừa mở game).
2. **Cấu hình Về Thành:**
   - Chọn phím gán Thổ Địa Phù (mặc định: `Phím F8`).
   - Cài đặt chu kỳ tự động về thành (khuyến nghị $\ge 15 - 30$ phút để chắc chắn Túi Đồ Nghề đã hết thời gian hồi/cooldown).
   - Bấm nút **"Thử bấm Phù"** để kiểm tra phản hồi ngầm.
3. **Cấu hình Túi Đồ Nghề (Sửa đồ):**
   - Chọn phím mở rương (mặc định: `Phím F4`).
   - Bấm nút **"Lấy tọa độ (3s)"** $\rightarrow$ Rê chuột đến ô Túi Đồ Nghề trong túi game $\rightarrow$ Tool tự ghi nhận tọa độ $X, Y$.
   - Tích chọn: **"Bảng thoại: Tự bấm phím '1' chọn sửa toàn bộ"**.
   - Bấm nút **"Thử sửa đồ ngầm"** để kiểm chứng.
4. **Cấu hình Thần Hành Phù (Quay lại bãi):**
   - Tích chọn: **"Bật tính năng"**.
   - Bấm nút **"Lấy tọa độ (3s)"** của Thần Hành Phù $\rightarrow$ Rê chuột vào ô Thần Hành Phù trong rương F4.
   - Nhập chuỗi phím chọn menu bãi (ví dụ: `1` hoặc `1,2`).
   - Bấm nút **"Thử quay lại bãi"** để kiểm chứng.
5. **Bắt đầu:**
   - Bấm **"Lưu Cấu Hình"** $\rightarrow$ Bấm **[ BẮT ĐẦU ]**.
   - Chuột và bàn phím của bạn hoàn toàn tự do 100%.

---

## 4. Chế Độ Phát Triển Nâng Cao (Hot-Swap, Shared RAM & Live Telemetry)

Kế thừa kiến trúc tác chiến từ **AutoPOE2**, dự án trang bị bộ công cụ hỗ trợ vừa test vừa code song song:

### A. Vừa chạy Test vừa Sửa Code (Shadow Binary Hot-Swap)
Khi chạy qua chế độ Shadow Binary, tiến trình test chạy trên file sao chép độc lập (`runtime/JXHelper_Runtime.exe`). File gốc `JXHelper.dll` và `JXHelper.exe` **hoàn toàn không bị Windows khóa file**. Bạn có thể sửa code và chạy `dotnet build` bất kỳ lúc nào:
* **Khởi chạy Dev Supervisor:** Chạy file [`run_dev_shadow.bat`](file:///c:/Projects/JX/run_dev_shadow.bat) (hoặc `python scripts/dev_supervisor.py --run`).
* **Hot-Swap tự động:** Khi bạn gõ `dotnet build`, supervisor sẽ tự động phát hiện mã băm mới và reload chuyển giao an toàn!

### B. Kênh Chia Sẻ RAM Trực Tiếp (Shared Memory 0 I/O)
* **Kênh RAM:** `Local\JX_Helper_SHM_v1` (Struct chuẩn C# `JxTelemetryData`).
* **Xem trạng thái RAM live:** Chạy file [`watch_live_ram.bat`](file:///c:/Projects/JX/watch_live_ram.bat) (hoặc `python scripts/dev_supervisor.py --watch-shm`).
* Giúp Dev / AI Agent đọc tức thời: Trạng thái FSM, PID, số chu kỳ, thời gian đếm ngược, hành động gần nhất mà không cần I/O file, không làm chậm game.

### C. Kênh Nhật Ký Quá Khứ & Live Stream (Structured Log)
* **File lưu trữ:** `logs/telemetry.jsonl` (cấu trúc JSON) và `logs/actions.log` (văn bản).
* **Đọc stream thời gian thực:** Chạy file [`tail_live_logs.bat`](file:///c:/Projects/JX/tail_live_logs.bat) (hoặc `python scripts/dev_supervisor.py --tail`).
* Dữ liệu được mở với chế độ `FileShare.ReadWrite`, hỗ trợ phân tích dữ liệu lịch sử nhiều phiên mà không làm gián đoạn tool đang chạy.