# Brainstorm: Tích hợp Kiến trúc Đa Tác tử và Triết lý Wise Teacher vào Antigravity (AWKit)

## Lịch sử Hiệu chỉnh (Revision History)

| Phiên bản | Ngày | Người thực hiện | Nội dung thay đổi |
| :--- | :--- | :--- | :--- |
| v1.0 | 2026-06-14 | Antigravity Orchestrator | Khởi tạo tài liệu gộp thống nhất cả 3 nghiên cứu: Wise Teacher, Fable 5 Multi-Agent và Antigravity Subagents. |

---

## Tóm tắt Điều hành (Executive Summary)

Tài liệu này đề xuất phương án tối ưu hóa toàn diện Antigravity (AWKit) bằng cách kết hợp:
1. **Triết lý giảng dạy cuốn chiếu (Wise Teacher):** Đảm bảo user nắm vững Vấn đề (Problem), Giải pháp (Solution), và Bối cảnh (Broader Context).
2. **Kiến trúc đa tác tử phân lớp (Manager-Workers-Critic-Safety Router):** Chống "Context Rot" và tối ưu hóa hiệu năng theo mô hình của Fable 5.
3. **Cơ chế Subagents của Antigravity:** Tận dụng tối đa built-in `research` và các custom sub-agents để thực thi an toàn, cô lập ngữ cảnh và nâng cao hiệu quả làm việc.

---

## 1. Triết lý Giảng dạy Cuốn chiếu (Wise Teacher Protocol)

Phương pháp này chuyển đổi hoạt động của Antigravity từ "chỉ bàn giao code" sang "chuyển giao tri thức sâu sắc" cho con người một cách cuốn chiếu (Incremental Learning).

```mermaid
graph TD
    A[Bắt đầu Mục tiêu] --> B[User tự trình bày hiểu biết - Restatement]
    B --> C[AI phân tích & lấp đầy lỗ hổng kiến thức]
    C --> D[Quiz kiểm tra bằng AskUserQuestion]
    D -->|Sai/Chưa hiểu sâu| C
    D -->|Đã Master| E[Đánh dấu hoàn thành mục trong checklist]
```

### 3 Trụ cột Kiến thức Bắt buộc:
- **The Problem (Vấn đề):** Tại sao vấn đề tồn tại, các nhánh hướng đi để giải quyết.
- **The Solution (Giải pháp):** Tại sao chọn phương án này, quyết định thiết kế và edge cases.
- **Broader Context (Bối cảnh rộng):** Tác động lâu dài của thay đổi đối với toàn bộ hệ thống.

### Cơ chế Tương tác:
- **Proactive Restatement:** Buộc user tự tóm tắt trước để AI dò tìm lỗ hổng kiến thức thực tế.
- **Adaptive Explanations (ELI5 / ELI14 / ELII):** Giải thích linh hoạt từ mức cực kỳ đơn giản (cho khái niệm trừu tượng) tới mức chuyên sâu (cho logic mã nguồn chi tiết).
- **Interactive Quizzing:** Sử dụng tool `AskUserQuestion` để tạo các câu đố trắc nghiệm (đảo lộn đáp án, ẩn kết quả cho tới khi nộp bài).

---

## 2. Kiến trúc Điều phối Đa Tác tử (Multi-Agent Control Plane)

Dựa trên nghiên cứu về Fable 5 và các tài liệu chính thức từ OpenAI/Google, chúng ta cần tránh việc dồn mọi log thô vào một luồng chat duy nhất (gây ra **Context Rot**). Thay vào đó, thiết lập một Control Plane phân lớp:

```mermaid
graph TD
    Manager[Manager / Synthesizer] -->|1. Phân loại & Định tuyến| Router[Safety Router / Classifier]
    Manager -->|2. Phân rã nhiệm vụ| Workers[Bounded Specialists / Workers]
    Workers -->|3. Trả kết quả tóm tắt| Critic[Critic / Verifier Pass]
    Critic -->|4. Phản biện & Đối chiếu| Manager
    Manager -->|5. Cập nhật| Ledger[External Work Ledger]
```

### Các Thành phần Cốt lõi:
1. **Manager (Trình điều phối):** Giữ bối cảnh điều hành chính, phân rã công việc và tổng hợp kết quả cuối cùng.
2. **Workers (Tác tử chuyên biệt):** Chỉ thực hiện các tác vụ đọc-ghi trong ranh giới được chỉ định, chỉ trả về **Structured Summary JSON** thay vì log thô.
3. **Critic / Verifier:** So chéo kết quả, phát hiện mâu thuẫn, ngăn ngừa việc AI "chốt quá sớm" vào các giả thuyết sai (early commitment).
4. **Safety Router:** Nhận diện các tác vụ nguy cơ cao (cyber, database write) để định tuyến sang degraded mode hoặc kích hoạt cổng phê duyệt (Approval Gate).
5. **External Work Ledger:** Sổ ghi chép trạng thái ngoài model (lưu tại `.brain/session.json`) giúp khôi phục ngữ cảnh (resumable state) trên mọi họ mô hình (Claude, GPT, Gemini).

---

## 3. Hiện thực hóa bằng Cơ chế Subagents của Antigravity

Chúng ta ứng dụng trực tiếp tài liệu hướng dẫn của Google Antigravity 2.0 để cấu trúc các vai trò trên:

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant Manager as Manager (Orchestrator)
    participant Research as Research Agent (Built-in)
    participant Critic as Critic Agent (Custom)

    User->>Manager: Yêu cầu task COMPLEX
    Manager->>Research: invoke_subagent (Quét codebase cô lập)
    Research-->>Manager: Trả về Structured Summary JSON (Idle)
    Note over Manager: Xây dựng giải pháp
    Manager->>Critic: invoke_subagent (Yêu cầu review chéo)
    Critic-->>Manager: Trả về Báo cáo lỗi tiềm ẩn & phản biện (Idle)
    Note over Manager: Điều chỉnh giải pháp hoàn thiện
    Manager->>User: Trình bày giải pháp cuối cùng kèm minh chứng
```

### Cách thức Triển khai cụ thể:
- **Tận dụng Built-in `research`:** Dùng cho mọi tác vụ tìm kiếm codebase hoặc đọc file lớn. Session tìm kiếm thô sẽ tự giải phóng khi subagent hoàn thành, giữ cho context chính cực sạch.
- **Định nghĩa Custom `critic` qua `define_subagent`:**
  - Thiết lập `system_prompt` hướng tới việc rà soát lỗi logic, stress-test các giả thuyết.
  - Cấu hình **Read-Only** tools để bảo vệ codebase khỏi việc ghi đè vô ý.
- **Định nghĩa Custom `safety-router`:** Phân loại các hành động có side-effect (ví dụ: mutated file, write database, outbound network). Sử dụng tính năng interruption của Antigravity để dừng luồng và xin phê duyệt từ user (Approval Boundary).
- **Giao tiếp qua Tin nhắn (Inter-Agent Messaging):** Tận dụng trạng thái `Idle` và cơ chế thức tỉnh khi nhận tin nhắn để duy trì các sub-agents chạy ngầm trong suốt phiên làm việc, tránh khởi tạo lại nhiều lần gây hao phí token.

---

## 4. Kịch bản Kiểm thử & Đánh giá (Verification Cases)

| Kịch bản | Cách thức thực thi | Tiêu chí Đạt (Pass Criteria) |
| :--- | :--- | :--- |
| **Deep Research & Code Review** | Manager spawn `research` để tìm codebase, sau đó spawn 2 `critic` song song để review độc lập. | Báo cáo cuối đầy đủ bằng chứng, không lẫn log thô của `research`. |
| **Approval Boundary Test** | Thực thi một câu lệnh ghi đè file nhạy cảm. | Hệ thống bắt buộc phải kích hoạt `safety-router`, tạm dừng tiến trình và hiển thị yêu cầu Approve rõ ràng cho User. |
| **Wise Teacher Checkpoint** | Kích hoạt `/teach` sau một gate lớn. | Tạo thành công checklist học tập tại `.brain/teach_checklist.md`, hỏi user restate và đặt câu hỏi qua `AskUserQuestion`. |