# Playbook agent (`docs/agent/`)

> **Không thay hiến pháp.** Đọc [`AGENTS.md`](../../AGENTS.md) và [Doc 61](../development/61_autonomy_gap_audit_and_next_development_basis.md) trước. Nhân vật: [`character_target`](../../character_target/README.md).  
> File trong thư mục này = tactics / A3E / control playbook. Cấm đánh LIVE-VERIFIED vòng farm từ đây.

---

## 1. TẦM NHÌN & TÔN CHỈ HOẠT ĐỘNG (AGENT MANIFESTO)

Antigravity không chỉ đơn thuần là một trợ lý ảo trả lời câu hỏi, mà đóng vai trò là một **Tổng Chỉ Huy Tác Chiến (Autonomous Tactical Commander)**. Agent sở hữu đầy đủ khả năng:
1. **Quan sát (Perceive)**: Trích xuất dữ liệu viễn trắc thời gian thực qua Shared Memory (120Hz (~8.33ms)), đọc nhật ký client (`Client.txt`, fallback `LatestClient.txt`), và phân tích thị giác máy tính qua ảnh chụp màn hình (`captures/`).
2. **Quyết định (Decide)**: Đánh giá tình huống chiến trường, phát hiện mối đe dọa sát thương bộc phát (Burst Damage), lựa chọn mục tiêu chiến dịch (Campaign Roadmap), và thẩm định giá trị trang bị theo chuẩn Meta.
3. **Hành động (Act)**: Trực tiếp điều phối C++ Core Engine thông qua vòng đệm lệnh IPC (Command Ring Buffer), điều khiển bàn phím/chuột qua Win32 API hoặc phần cứng KMBox B+ Pro, và tự động xử lý rớt mạng/đăng nhập lại.

---

## 2. DANH MỤC TÀI LIỆU TRONG THƯ MỤC `docs/agent/`

| Tệp tài liệu | Nội dung chi tiết |
|---|---|
| [`architecture.md`](./architecture.md) | Kiến trúc 2 phân tầng chuyên biệt: Từ vi phản xạ sinh tồn C++23 (120Hz) đến Bộ não chiến lược Antigravity AI & A3E Engine (Python 3.11). |
| [**SPEC 61 Thẩm định lỗ hổng tự hành**](../development/61_autonomy_gap_audit_and_next_development_basis.md) | **SSoT 16/09/2026**: vì sao chưa chơi được như người; hàng đợi GAP-1…7. Đọc **trước** khi sửa F8 / Map Device / WASD / combat. |
| [**SPEC 50 Kiến trúc 2 tầng Hot/Cold Path**](../development/50_two_tier_asymmetric_hybrid_architecture_specification.md) | Đặc tả kiến trúc bất đối xứng 2026: C++23 120Hz DOD + Python 3.11 EDA 30Hz. |
| [**SPEC 29 BotBrain / Pickit / Farm loop**](../development/29_botbrain_priority_fsm_pickit_and_closed_farming_loop.md) | Hợp đồng implement full-auto (P0–P5) và bộ lọc Pickit DSL. |
| [`pro_player_tactics.md`](./pro_player_tactics.md) | Giáo trình chiến thuật Pro Player: Vũ đạo combo đánh Boss, cơ chế di chuyển thả diều (Kiting), danh sách đen map mod T16, và quy tắc bảo toàn EXP. |
| [`autonomous_control_playbook.md`](./autonomous_control_playbook.md) | Cẩm nang điều khiển thực chiến: Hướng dẫn chi tiết cách Antigravity khởi chạy, giám sát, thẩm định đồ và tự phục hồi hệ thống khi có sự cố. |
| [**`05_agentic_self_learning_engine.md`**](./05_agentic_self_learning_engine.md) | **Đặc tả Động cơ Tự học Trực tuyến & Ra quyết định (A3E Engine)**: Thuật toán Contextual Bandit LinUCB không phụ thuộc thư viện ngoài, vòng đời 4 bước xử lý Item Chưa Giám Định (Scroll of Wisdom vs The Hooded One), hàm đa mục tiêu Pareto giải đáp "What is better", và bộ tự chỉnh phản xạ / rút kinh nghiệm tử trận. |

---

## 3. SƠ ĐỒ VÒNG LẶP ĐIỀU KHIỂN TỰ CHỦ & TỰ HỌC (AUTONOMOUS LEARNING & DECISION LOOP)

```mermaid
flowchart TD
    subgraph SENSOR [1. TẦNG CẢM BIẾN (PERCEPTION)]
        A1[Shared Memory Telemetry: HP, ES, Mana, XYZ, Radar]
        A2[LogSensor: Client.txt events]
        A3[ScreenCapturer: Burst Damage PNG + JSON]
        A4[BlackboxRecorder: 120 Ticks Circular Telemetry]
    end

    subgraph BRAIN [2. BỘ NÃO CHIẾN LƯỢC & TỰ HỌC A3E (DECISION & LEARNING)]
        B1{Đánh Giá Nguy Hiểm & Contextual State}
        B2[LinUCB Contextual Bandit: Lựa chọn Hành động Tối ưu]
        B3[WhatIsBetterEvaluator: Pareto Multi-Objective Score]
        B4[ItemLifecycleManager: Unidentified 4-Stage Pipeline]
        B5[Dynamic Reflex Tuner & Reflection Critic: Học từ Tử trận]
    end

    subgraph ACTUATOR [3. TẦNG THỰC THI (ACTION)]
        C1[Command Ring Buffer: Di chuyển, Nhặt đồ, Đăng nhập]
        C2[Reflex Engine: Instant Flask, Iframe Spacebar]
        C3[Hardware KMBox / Win32 Input]
        C4[Transparent Overlay & Control Center HUD]
    end

    SENSOR --> BRAIN
    BRAIN --> ACTUATOR
    ACTUATOR -->|Phản hồi trạng thái & Telemetry| SENSOR
    SENSOR -->|Reward Feedback & Post-Mortem| B5
    B5 -->|Hiệu chỉnh Ngưỡng Phản xạ & LinUCB Policy| B2
```