# JX Automation Suite - Workspace Agent Rules & Guidelines (SSoT Kernel 2026)

## 1. Tư Duy Thống Soái Tác Chiến (Senior Orchestrator Mindset)
- **Vai trò**: Senior Orchestrator Agent (Kiến trúc sư Trưởng & Tổng Điều phối viên Hệ thống Tự hành JX).
- **Học thuyết Tác chiến Song song Kép (Dual-Track Operational Doctrine)**:
  * *Track 1 (Dev & Mock QA Track)*: Phát triển, kiểm thử unit test & logic FSM độc lập trong bộ nhớ, không cần mở game.
  * *Track 2 (Live Ops Track)*: Tương tác trực tiếp với tiến trình game thật (`vggame.exe` / `game.exe`) ngầm qua Windows Message Queue. Báo cáo trung thực trạng thái; **tuyệt đối cấm mạo nhận hoặc giả lập kết quả**.
- **Kỷ luật phát triển**: C# .NET 8 / WinForms hiện đại, Win32 Native API chuẩn xác, không DLL injection, sạch 100% với Windows Defender.

---

## 2. Bảng Tổng Hợp Mã Bất Biến Kiến Trúc (Master Invariant Matrix)

| Mã Bất Biến | Mô Tả Quy Tắc Cốt Lõi | Module Giám Sát |
| :--- | :--- | :--- |
| **INV-ANTI-HALLUCINATION-GUARD** | **CHẶN ĐỨNG ẢO GIÁC**: Script kiểm thử thực địa bắt buộc assert số lượng cửa sổ game thật (`Sword3 Class`). Thiếu dù 1 cửa sổ phải ném Fatal Error dừng ngay lập tức; cấm in log giả lập hay chụp desktop mạo nhận PASS. | `docs/anti_hallucination.md` |
| **INV-BG-INPUT-NO-HIJACK** | **BẤT BIẾN SINH TỬ**: 100% thao tác gửi qua `PostMessage` tới `HWND`. Cấm `SetCursorPos`, `mouse_event`, `SendInput`. Chuột và phím người chơi tự do 100%. | `BackgroundInput.cs` |
| **INV-FSM-SINGLE-OWNER** | Chỉ duy nhất 1 chủ sở hữu chu trình FSM. Cấm đa luồng gửi phím/click chồng chéo. | `CharacterFSM.cs` |
| **INV-TWO-FACTOR-WINDOW** | Xác thực cửa sổ 2 lớp: Tên tiến trình (`vggame.exe`) và Handle hợp lệ (`IsWindow(hWnd)`). | `WindowManager.cs` |
| **INV-SAFE-REPAIR-SEQUENCE** | Chuỗi sửa đồ: `Phù` $\rightarrow$ `Chờ nạp map (2.5s)` $\rightarrow$ `Mở F4` $\rightarrow$ `Click phải` $\rightarrow$ `Đóng F4`. | `ActionExecutor.cs` |
| **INV-CONFIG-INI-SSOT** | File cấu hình là nguồn chân lý duy nhất, hỗ trợ hot-sync và lưu tức thời từ UI. | `BotConfig.cs` |
| **INV-SUPERVISOR-SHADOW-EXEC** | Bot chạy trên Shadow Binary (`runtime/JXHelper_Runtime.exe`), không bao giờ khóa file nguồn khi build. | `scripts/dev_supervisor.py` |
| **INV-SHM-TELEMETRY-SSOT** | Trạng thái bot chia sẻ qua Memory-Mapped File (`Local\JX_Helper_SHM_v1`), đọc 0 I/O. | `SharedMemoryBridge.cs` |
| **INV-STRUCTURED-LOG-STREAM** | Mọi sự kiện ghi đồng thời vào `telemetry.jsonl` và `actions.log` (`FileShare.ReadWrite`). | `TelemetryLogger.cs` |
| **INV-LSP-FIRST-SEMANTICS** | Bắt buộc tra cứu symbol qua MCP `lsp-mcp` trước khi refactor. Cấm regex grep chay. | `lsp-mcp` |
| **INV-PER-CHAR-SECT-ISOLATION** | Mỗi nhân vật lưu cấu hình riêng (`config_{Char}.json`), môn phái và chiêu buff riêng biệt. Cấm ghi đè chiêu giữa các tab. | `BotConfig.cs`, `SkillScanner.cs` |
| **INV-NO-FKEY-COMBAT** | Cấm gán phím F1–F12 cho combat/buff vì sẽ bật bảng giao diện hệ thống. Ưu tiên Chuột phải ngầm. | `docs/autovlbs_integration.md` |
| **INV-NPC-TEXT-MATCH-FIRST** | 100% tương tác NPC đối soát theo từ khóa text động. Cấm dùng số thứ tự index cứng. | `docs/npc_dialog_runbook.md` |
| **INV-LIVE-FIELD-ACCEPTANCE** | Test mock chỉ là QA Track. Nghiệm thu bàn giao bắt buộc kiểm tra thực tế trên game thật theo runbook. | `LIVE_TESTING_RUNBOOK.md` |
| **INV-EMPIRICAL-VERIFIED** | Cấm báo cáo ảo giác. Chỉ xác nhận khi đã đối soát thực tế trên OS và log thực thi rõ ràng. | Toàn hệ thống |
| **INV-SKILL-TABLE-FIRST** | Chiêu thức trích xuất đúng Bảng Kỹ Năng F5 theo cấp. Cái Bang mặc định `Kháng Long Hữu Hối (cấp 50)`. | `docs/autovlbs_integration.md` |
| **INV-ACCOUNT-SSOT** | Danh sách tài khoản tập trung tại `config/accounts.json`, hỗ trợ import/export text hàng loạt. | `docs/multi_account_tactics.md` |
| **INV-SPOT-ANCHOR-LOCK** | `LockCurrentSpot = true` & `AttackRadius = 0`: Đứng yên tại chỗ quanh `(400, 300)` tại Nghiệt Long Động. | `docs/multi_account_tactics.md` |
| **INV-THAN-HANH-PHU-GATEWAY** | THP phân giải menu theo text: Thành thị $\rightarrow$ Dương Châu $\rightarrow$ Lưu điểm hồi sinh $\rightarrow$ Cổng Nghiệt Long Động. | `docs/multi_account_tactics.md` |
| **INV-NO-PLACEHOLDER-CREDS** | Cấm tự bịa tài khoản/mật khẩu. Bắt buộc dùng thông tin thật do người dùng cung cấp (`nguvansi`...). | `docs/multi_account_tactics.md` |
| **INV-PARTY-LEADER-DISPATCH** | Thiếu Lâm làm chủ PT, đánh bán kính 1000px; các thành viên bám sát cự ly 100px. | `docs/multi_account_tactics.md` |
| **INV-SEQUENTIAL-TELEPORT** | Dịch chuyển tuần tự: (1) Cái Bang $\rightarrow$ (2) Thiếu Lâm $\rightarrow$ (3) Nga My $\rightarrow$ (4) Ngũ Độc (delay nạp map 2.5s). | `docs/multi_account_tactics.md` |
| **INV-AUTO-UAC-ELEVATION** | Tự động kích hoạt UAC Administrator (`Verb = runas`, `requireAdministrator`) khi khởi động GUI. Chế độ CLI gắn console (`AttachConsole(-1)`) và ghi log `logs/cli_output.log`, tuyệt đối cấm silent fail nuốt lỗi. | `Program.cs`, `app.manifest` |
| **INV-STATIC-RAM-LOCAL-PLAYER** | Tên nhân vật lưu tại địa chỉ tĩnh `0x006DEC44`, cấp độ tại `0x006DEC66`. Đọc trực tiếp 0.001ms, triệt tiêu hoàn toàn việc quét brute-force 2GB RAM. | `CharacterNameResolver.cs` |
| **INV-TURBO-LEAN-LOGIN** | Chuỗi đăng nhập siêu tốc < 1.8s (dò cửa sổ 150ms, xóa ô 5ms, gõ phím 8ms, chọn slot $\rightarrow$ Enter 140ms), loại bỏ 100% lỗi Gateway server timeout làm rớt kết nối socket. | `AutoLoginEngine.cs` |
| **INV-DUAL-FACTOR-INGAME** | Định danh cửa sổ đã vào thế giới 2 tầng: RAM tĩnh + Pixel HUD (bình HP đỏ / MP xanh góc trái). Tuyệt đối cấm can thiệp hoặc gửi nhầm lệnh login vào tài khoản đang chơi, triệt tiêu bẫy "ngâm". | `CharacterNameResolver.cs`, `WindowManager.cs` |
| **INV-RAM-LIVE-PLAYER-STATS** | Định dạng cấu trúc Player Stats trong RAM: Sinh lực (HP) tại `[Base-0x18]`, Nội lực (Mana) tại `[Base-0x08]`, Thể lực (Stamina) tại `[Base+0x00]`, Thể lực tối đa tại `[Base+0x04]` với chữ ký bảo vệ `[43, 100, 0]` & `39`. Đọc O(1) qua cache 0.001ms. | `PlayerStatsReader.cs` |
| **INV-STATIC-RAM-MAP-ID** | ID Bản đồ hiện tại lưu tại địa chỉ tĩnh `0x006966CC` / `0x006966D0` trong `vggame.exe` (Lão Hổ Động ID 123, Nghiệt Long Động ID 182...). Đọc trực tiếp O(1) 0.001ms, tự động phân giải tên tiếng Việt và đường dẫn file `.map` qua `MapDatabase.cs`. | `MapDatabase.cs`, `PlayerStatsReader.cs` |
| **INV-RAM-LIVE-PLAYER-COORDS** | Tọa độ người chơi thực tế trong RAM lưu tại `[StaminaBase + 0x0270]` (X) và `[StaminaBase + 0x0274]` (Y) đơn vị engine pixel. Tọa độ HUD góc phải màn hình quy đổi chuẩn: `HudX = round(X / 256.0)`, `HudY = round(Y / 512.0)`. | `PlayerStatsReader.cs` |
| **INV-MAP-GRAPH-TOPOLOGY** | Cấu trúc file `.map` chuẩn gồm danh mục Waypoint `(X, Y, Type)` và bảng kề đồ thị topological `$`. Tự động tìm đường ngắn nhất (A* / BFS) phục vụ di chuyển, sửa đồ, mua thuốc và tuần tra bãi train. | `MapDatabase.cs` |
| **INV-VLHOOK-COMPAT-PATCH** | Lưu ý bảo toàn mã băm nguyên gốc `VLHookPr.dll` (`1F7D059401E48979CCA0B0D50FF00829`). Tuyệt đối cấm vá nhị phân trên client chạy VietGuard vì driver sẽ quét hash và kích hoạt bẫy "auto lạ" thoát game. Ưu tiên giải pháp Win32 `PostMessage` của JXHelper. | `_VLAuto/VLHookPr.dll` |
| **INV-MULTI-TIER-THP** | Cơ chế Thần Hành Phù đa tầng (chuỗi phím cách nhau bởi dấu phẩy, mặc định `2,5,4` cho Lão Hổ Động, `2,7,1` cho Nghiệt Long Động) hỗ trợ trọn vẹn menu Lua động của private server, tự động đóng F4 và chờ nạp map. | `ActionExecutor.cs`, `ThanHanhPhuExecutor.cs` |
| **INV-AUTO-SAVE-RESPAWN** | Tự động cố định điểm hồi sinh tại Dương Châu qua menu Thần Hành Phù (Phím 3) mỗi khi về thành hoặc qua nút 'Lưu rương', đảm bảo 100% khi tử vong hoặc bấm Phù (Phím 5) luôn tái sinh chuẩn tại Dương Châu. | `ActionExecutor.cs`, `ThanHanhPhuExecutor.cs` |
| **INV-NGUDOC-KIMYEN-CURSE** | Chuỗi bùa Ngũ Độc chuẩn Auto Kim Yến (Pre-Attack Curse Pipeline): Tung trọn bộ bùa (`U Hồn` $\rightarrow$ `Vạn Cổ` $\rightarrow$ `Thi Độc` $\rightarrow$ `Hóa Cốt`, delay 250ms) làm suy yếu mục tiêu trước khi chuyển sang chiêu công kích chính (`Bách Độc Xuyên Tâm`), chống spam lãng phí nhờ bộ đếm hiệu lực 15s và hỗ trợ lọc Boss. | `CombatEngine.cs`, `SupportSkillsForm.cs` |
| **INV-NEWBIE-BLOOD-POUCH** | Cơ chế mở Túi Máu Tân Thủ học từ Auto Kim Yến (`MoTuiThuoc`): Mở hành trang F4 $\rightarrow$ Click phải túi máu tại `(575, 345)` $\rightarrow$ Chuỗi menu `1,1` lấy Ngũ Hoa Ngọc Lộ Hoàn $\rightarrow$ Space xác nhận $\rightarrow$ Đóng F4; kích hoạt định kỳ (mặc định 60s) hoặc khẩn cấp khi HP < 65%, giữ dược phẩm đầy đủ 24/7 không cần về thành. | `ActionExecutor.cs`, `RecoveryEngine.cs`, `BotConfig.cs` |
| **INV-SMART-LEADER-FOLLOW** | Cơ chế bám sát và tự tìm acc chính thông minh (Smart Follow & Cross-Map Rejoin): Đọc tọa độ RAM thời gian thực, quy đổi vector đẳng cự màn hình (Isometric 2.5D: $isoX = (dx-dy)/2$, $isoY = (dx+dy)/4$), tự động kích hoạt Thần Hành Phù dịch chuyển xuyên map (`ExecuteTeleportToMapAsync`) khi acc phụ tử vong hồi sinh khác map với acc chính. | `CombatEngine.cs`, `PlayerStatsReader.cs`, `ThanHanhPhuExecutor.cs` |

---

## 3. Quy Chuẩn Module Hóa & Trần Tệp (Anti-Monolithic Policy)
- **Trần độ dài file (Ceiling)**: Một tệp không nên vượt quá **300 – 500 dòng**. Vi phạm SRP bắt buộc tách nhỏ.
- **Tách bạch Presentation Layer**: `MainForm.cs` chỉ trình bày UI và ủy quyền xuống `BotBrain` / `ActionExecutor`.
- **Hạt nhân dùng chung**: Toàn bộ hằng số Win32 nằm tại `src/Platform/NativeMethods.cs`.

---

## 4. Quy Trình Tác Chiến LSP-First
1. **Tiền Định vị**: Dùng `lsp_workspace_symbols` / `lsp_definition` để định vị file và dòng code.
2. **Đánh giá Tác động**: Dùng `lsp_references` tìm toàn bộ caller trước khi sửa chữ ký hàm.
3. **Hậu kiểm Ngữ nghĩa**: Dùng `lsp_diagnostics` kiểm tra 0 lỗi cú pháp/type sau khi sửa file C#.

---

## 5. Cổng Nghiệm Thu & Kỷ Luật Phát Triển (DoD)
- `lsp_diagnostics` báo cáo `No diagnostics found` trên các tệp C# can thiệp.
- `dotnet build` đạt kết quả `0 Warning(s), 0 Error(s)`.
- Không inject DLL, sạch 100% trước Windows Defender.
- Nghiệm thu thực địa có log thời gian thực và ảnh chụp màn hình game thật chứa nhân vật.

---

## 6. Bản Đồ Tài Liệu Mô-Đun Chuyên Biệt
Để chống tràn context, các hướng dẫn chi tiết được phân rã thành các tệp độc lập trong thư mục `docs/`:
- **Chống Ảo Giác & Hard Guardrail**: [`docs/anti_hallucination.md`](file:///c:/Projects/JX/docs/anti_hallucination.md)
- **Tích Hợp AutoVLBS & Bảng Kỹ Năng**: [`docs/autovlbs_integration.md`](file:///c:/Projects/JX/docs/autovlbs_integration.md)
- **Tác Chiến 4 Acc, Quản Lý Tài Khoản & THP**: [`docs/multi_account_tactics.md`](file:///c:/Projects/JX/docs/multi_account_tactics.md)
- **Khớp Text Hội Thoại NPC & Sổ Tay Test**: [`docs/npc_dialog_runbook.md`](file:///c:/Projects/JX/docs/npc_dialog_runbook.md) & [`LIVE_TESTING_RUNBOOK.md`](file:///c:/Projects/JX/LIVE_TESTING_RUNBOOK.md)