@mrtrinhvn/ag-kit 1.1.1 → 1.1.4

package/README.md

@@ -1,78 +1,75 @@
 # Antigravity Kit Core (`@mrtrinhvn/ag-kit`) 🚀
 
-A generic, institutional-grade AI programming framework for automating scaffolding, architecture, and coding directly inside your software projects. Inspired by the principles of `.agent` systems, carefully stripped of domain-specific constraints to adapt to any software development lifecycle.
+A generic, institutional-grade AI programming framework for automating scaffolding, architecture, and coding directly inside your software projects.
 
-## 📦 Quick Install
+## 📦 Quick Start
 
-The best way to initialize the AG-Kit in a new project is using `npx`:
+The best way to inject AG-Kit into any project is via `npx`:
 
 ```bash
-npx @mrtrinhvn/ag-kit init
-```
-
-> **Note**: This is the **recommended** method for remote machines as it avoids all `EACCES` permission issues.
+# 1. Khởi tạo bộ não (Inject .agent folder)
+npx @mrtrinhvn/ag-kit@latest init
 
-## 🛠 Global Usage & Commands
+# 2. Kiểm tra sức khỏe hệ thống (CDP, Ollama, Models)
+npx @mrtrinhvn/ag-kit@latest check
 
-You can also install it globally if you frequently create new projects:
-
-```bash
-npm install -g @mrtrinhvn/ag-kit
+# 3. Kiểm tra trạng thái và phiên bản
+npx @mrtrinhvn/ag-kit@latest status
 ```
 
-### 🛠 Local Development (Linking)
+---
 
-If you are developing Ag-Kit locally and want to use it globally without publishing to NPM:
+## 🛠 Lệnh CLI & Cách sử dụng
 
-1. Go to the Ag-Kit directory: `cd /home/tao/Projects/ag-kit`
-2. Run: `npm link` (This creates a global symlink)
-3. You can now use `ag-kit` anywhere!
+| Lệnh | Ý nghĩa | Chi tiết |
+|---|---|---|
+| `ag-kit init` | **Khởi tạo** | Cài đặt tủy não `.agent` và tạo file `.env` mẫu. |
+| `ag-kit check` | **Kiểm tra** | Quét cổng CDP (mặc định 9555), kiểm tra Ollama và AI Models. |
+| `ag-kit update` | **Cập nhật** | Nâng cấp Agents/Skills/Workflows mới nhất mà không làm mất dữ liệu Ký ức. |
+| `ag-kit status` | **Trạng thái** | Hiển thị rõ: Phiên bản Tool (CLI) và Phiên bản Core (Brain) đang dùng. |
 
-### ❌ Troubleshooting: EACCES Permission Error
+### ⚙️ Cấu hình Cổng (Custom Port)
 
-If you see `npm error code EACCES` when installing globally via network (`npm install -g`), use one of these:
+Mặc định AG-Kit quét cổng **9555** và **9222**. Nếu bạn muốn dùng một cổng riêng cho từng dự án (để tránh xung đột khi mở nhiều IDE), hãy sửa file `.env`:
 
-**Solution 1: Use sudo (For quick global install)**
-```bash
-sudo npm install -g @mrtrinhvn/ag-kit
+```env
+CDP_PORT=12345
 ```
+Lệnh `ag-kit check` sẽ tự động ưu tiên cổng này để kết nối với IDE.
 
-**Solution 2: Use npx (Recommended - No sudo needed)**
-```bash
-npx @mrtrinhvn/ag-kit <command>
-```
-npx sẽ tự động tải và chạy mà không cần quyền ghi vào thư mục hệ thống.
+---
+
+## 🏗 Cấu trúc hệ thống (.agent)
 
-**Solution 3: Local Development (For this machine)**
-Follow [NPM's guide](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) to change the global directory to your home folder.
+Sau khi chạy `init`, dự án của bạn sẽ có bộ khung tiêu chuẩn:
+
+- **`GEMINI.md`**: "Hiến pháp" tối cao của Agent, đảm bảo tư duy hệ thống và an toàn.
+- **`agents/`**: Các đặc vụ chuyên trách (Orchestrator, Frontend, Backend, Debugger).
+- **`skills/`**: Các thuật toán tác chiến (Clean code, TDD, React Expert, Rust Pro...).
+- **`workflows/`**: Các lệnh gõ tắt (slash commands) như `/create`, `/plan`, `/debug`.
+- **`knowledge/`**: Nơi lưu giữ giao thức v3 và các kiến thức tự chữa lành (`self-healing`).
 
 ---
 
-Then use the provided CLI anywhere:
+## 🔄 Cập nhật & Bảo trì
 
-| Command | Description |
-|---|---|
-| `ag-kit init` | Scaffolds the `.agent` framework (Agents, Skills, Workflows) into your current directory. |
-| `ag-kit check` | Verifies environment health (CDP, Tokens, Ollama, Models). |
-| `ag-kit update` | Pulls the latest rules and templates and safely overwrites the core `.agent` folders without breaking your custom `knowledge/` base. |
-| `ag-kit status` | Checks exactly which version of the AG-Kit is active in your current working directory. |
+Chúng tôi liên tục cập nhật các kỹ năng mới từ dự án `ag-orchestrator`. Để đảm bảo "bộ não" của bạn luôn thông minh nhất:
 
-## 🧠 What's Inside the Brain?
+```bash
+# Luôn dùng @latest để lấy những tinh hoa mới nhất từ NPM
+npx @mrtrinhvn/ag-kit@latest update
+```
+
+---
 
-Running `ag-kit init` injects the following core architecture into your project:
+## ❌ Xử lý lỗi thường gặp (Troubleshooting)
 
-- **`GEMINI.md`**: The supreme constitution (Tier 0 Rules) ensuring the Agent always thinks systematically, acts safely, and never hallucinates code.
-- **`agents/`**: Core personas taking specialized roles (e.g., `orchestrator`, `frontend-specialist`, `backend-specialist`, `debugger`).
-- **`skills/`**: Tactical operational algorithms spanning from `clean-code` and `tdd-workflow` to `python-patterns` and `nextjs-react-expert`.
-- **`workflows/`**: Pre-defined step-by-step instructions (slash commands) like `/create`, `/plan`, `/brainstorm`, and `/debug`.
-- **`scripts/`**: CI/CD automation checkers like `lint_runner.py` and `security_scan.py`.
+**1. Lỗi phiên bản không khớp (Version ghosting):**
+Nếu `status` báo phiên bản cũ hơn bản trên NPM, đó là do cache của `npx` hoặc bạn đã cài global. 
+- Cách giải quyết: Luôn thêm `@latest` sau tên gói hoặc chạy `sudo npm install -g @mrtrinhvn/ag-kit@latest`.
 
-## ⚙️ How It Works
-The AG-Kit is designed to be injected into an AI IDE or a custom Agent workspace.
-1. The AI reads `GEMINI.md` first.
-2. It assumes the persona of the relevant specialist in `agents/`.
-3. It selectively loads specific techniques from `skills/` based on context.
-4. It continuously documents important technical learnings in `knowledge/`.
+**2. Lỗi EACCES (Quyền truy cập):**
+Nếu cài global bị báo lỗi quyền, hãy dùng `npx` (Khuyên dùng) hoặc dùng `sudo`.
 
 ---
 *Built with ❤️ to enforce Institutional-Grade Software Standards.*

package/bin/cli.js

@@ -73,7 +73,22 @@ program.command('init')
     const srcAgent = path.join(TEMPLATE_DIR, '.agent');
     if (!fs.existsSync(TARGET_AGENT_DIR)) {
       copyRecursiveSync(srcAgent, TARGET_AGENT_DIR);
+      // Ghi lại version vào .agent/.version
+      fs.writeFileSync(path.join(TARGET_AGENT_DIR, '.version'), pkg.version);
       console.log('\x1b[32m✅ Đã cài ráp thành công thư mục .agent vào Project!\x1b[0m');
+      
+      // Khởi tạo .env nếu chưa có
+      const envPath = path.join(process.cwd(), '.env');
+      if (!fs.existsSync(envPath)) {
+        fs.writeFileSync(envPath, 'CDP_PORT=9555\n');
+        console.log('\x1b[34mℹ️  Đã tạo file .env mẫu với CDP_PORT=9555\x1b[0m');
+      } else {
+        const envContent = fs.readFileSync(envPath, 'utf-8');
+        if (!envContent.includes('CDP_PORT=')) {
+          fs.appendFileSync(envPath, '\nCDP_PORT=9555\n');
+          console.log('\x1b[34mℹ️  Đã thêm cấu hình CDP_PORT=9555 vào file .env hiện tại\x1b[0m');
+        }
+      }
     } else {
       console.log('\x1b[33m⚠️ Thư mục .agent đã tồn tại. Hãy dùng lệnh "update" để cập nhật.\x1b[0m');
     }
@@ -102,6 +117,8 @@ program.command('update')
     });
 
     migrateLegacyMemories();
+    // Cập nhật version vào .agent/.version
+    fs.writeFileSync(path.join(TARGET_AGENT_DIR, '.version'), pkg.version);
     console.log('\x1b[32m✅ Cập nhật thành công 100% Cấu trúc kỹ năng siêu cấp!\x1b[0m');
   });
 
@@ -182,15 +199,22 @@ program.command('status')
   .action(() => {
     console.log('\x1b[36m📊 Trạng thái AG-Kit trong dự án hiện tại:\x1b[0m');
     if (fs.existsSync(TARGET_AGENT_DIR)) {
-      console.log('\x1b[32m✅ Trạng thái: Đã Cài Đặt (Active)\x1b[0m');
-      console.log(`📁 Đường dẫn : ${TARGET_AGENT_DIR}`);
+      console.log('\x1b[32m✅ Trạng thái  : Đã Cài Đặt (Active)\x1b[0m');
+      console.log(`📁 Đường dẫn    : ${TARGET_AGENT_DIR}`);
+      
+      const vPath = path.join(TARGET_AGENT_DIR, '.version');
+      if (fs.existsSync(vPath)) {
+        const installedVersion = fs.readFileSync(vPath, 'utf-8').trim();
+        console.log(`🧠 Bản cài đặt  : v${installedVersion}`);
+      } else {
+        console.log(`🧠 Bản cài đặt  : Không rõ (Legacy)`);
+      }
+
+      console.log(`🏷  Bản Tool     : v${pkg.version}`);
       
-      try {
-          const pJson = require('../package.json');
-          console.log(`🏷  Phiên bản : v${pJson.version}`);
-      } catch (e) {}
     } else {
-      console.log('\x1b[31m❌ Trạng thái: Chưa có gì. Gõ "ag-kit init" để Setup.\x1b[0m');
+      console.log('\x1b[31m❌ Trạng thái  : Chưa có gì. Gõ "ag-kit init" để Setup.\x1b[0m');
+      console.log(`🏷  Bản Tool     : v${pkg.version}`);
     }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtrinhvn/ag-kit",
-  "version": "1.1.1",
+  "version": "1.1.4",
   "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
   "main": "index.js",
   "bin": {

package/template/.agent/knowledge/model-switching-vfs.md

@@ -0,0 +1,22 @@
+# Tiết Kiệm Token & Quản Lý Mô Hình (Model & VFS Knowledge)
+
+## 1. Cơ Chế Tiết Kiệm Token
+Trong môi trường điều khiển từ xa (Telegram), việc tối ưu hóa token là cực kỳ quan trọng để duy trì hiệu suất và chi phí.
+
+### VFS (Virtual File System)
+- **Tác dụng**: Giảm 98% lượng token khi khám phá mã nguồn.
+- **Cách hoạt động**: Thay vì đọc toàn bộ file, AI sử dụng công cụ `vfs` để chỉ lấy chữ ký (signatures) của hàm và lớp.
+- **Quy tắc**: Phải luôn sử dụng `vfs` trước khi dùng `grep` hoặc đọc file đầy đủ. (Xem `GEMINI.md`).
+
+## 2. Chiến Lược Lựa Chọn Mô Hình (Model Strategy)
+Hệ thống sử dụng cơ chế "Phân tầng độ khó" để chọn model:
+
+| Độ khó | Tác vụ | Mô hình khuyến nghị | Lý do |
+| :--- | :--- | :--- | :--- |
+| **Thấp** | Giải thích code, Refactor nhỏ, Chat thông thường | **Ollama (Local)** | Không tốn quota, phản hồi nhanh cho tác vụ đơn giản. |
+| **Trung bình** | Fix lỗi, Thêm tính năng mới | **Gemini 3 Flash** | Cân bằng giữa chi phí và độ thông minh. |
+| **Cao** | Thiết kế kiến trúc, Debug lỗi phức tạp | **Claude 3.5 Sonnet / Gemini 1.5 Pro** | Độ chính xác cao nhất cho các vấn đề hóc búa. |
+
+## 3. Tích Hợp Local Model (Ollama)
+- Bot kết nối trực tiếp với Ollama API tại `http://localhost:11434`.
+- Người dùng có thể chọn dùng model local qua lệnh `/model` để "đóng băng" quota Google khi không cần thiết.

package/template/.agent/skills/lazy-gravity/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: lazy-gravity
+description: Cross-platform remote operation patterns for Antigravity, based on the LazyGravity project.
+---
+
+# Vận Hành Đa Nền Tảng (LazyGravity Patterns)
+
+LazyGravity tập trung vào việc quản lý nhiều dự án và phiên làm việc từ xa một cách an toàn và linh hoạt.
+
+## Các Đặc Điểm Chính
+
+1. **Project Discovery**: Tự động quét các thư mục trong Workspace để cho phép người dùng chuyển đổi dự án từ xa qua lệnh `/project`.
+2. **Session Management**: Quản lý lịch sử hội thoại (Past Conversations), cho phép chọn lại phiên cũ để tiếp tục làm việc.
+3. **Auto-Accept Flow**: Tích hợp cơ chế tự động nhấn "Accept" cho các file edit nếu người dùng bật chế độ `/autoaccept`.
+
+## Quản Lý Dự Án (Remote Switching)
+
+- Sử dụng `WorkspaceService` để liệt kê các thư mục con.
+- Khi người dùng chọn dự án, bot sẽ cung cấp thông tin hoặc tự động restart target sang dự án mới (nếu được cấp quyền).
+
+## Phân Loại Mô Hình (Model Categorization)
+- Phân tách rõ ràng giữa **Cloud Models** (Google Gemini, Claude) và **Local Models** (Ollama).
+- Ưu tiên Local Models cho các yêu cầu giải thích hoặc refactor nhỏ để tiết kiệm quota Cloud.

package/template/.agent/skills/remoat-integration/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: remoat-integration
+description: Patterns for controlling AI code editors from Telegram, based on the Remoat project.
+---
+
+# Kỹ Thuật Điều Khiển Editor Từ Xa (Remoat Integration)
+
+Kỹ thuật này cho phép điều khiển Antigravity hoặc bất kỳ Editor nào hỗ trợ CDP (Chrome DevTools Protocol) thông qua Telegram.
+
+## Nguyên Tắc Cốt Lõi (Remoat Strategy)
+
+1. **Bridge qua CDP**: Không can thiệp vào mã nguồn của Editor. Sử dụng CDP để Inject Prompt và Monitor Response.
+2. **Single Brain Architecture**: Bot Telegram chỉ đóng vai trò "lễ tân", nhận lệnh và chuyển tiếp cho Editor. Editor là "bộ não" thực hiện công việc.
+3. **Wait for Generate**: Sử dụng DOM Observation để biết khi nào AI trong Editor đang suy nghĩ hoặc đã hoàn thành.
+
+## Các Tập Lệnh Đặc Trưng
+
+- `/screenshot`: Chụp ảnh màn hình Editor để kiểm tra kết quả trực quan.
+- `/stop`: Dừng khẩn cấp quá trình sinh code của AI.
+- `/mode`: Chuyển đổi giữa chế độ `fast` (flash models) và `plan` (pro models).
+
+## Cấu Hình Hạ Tầng
+- Yêu cầu Editor mở cổng debug: `--remote-debugging-port=9555`.
+- Sử dụng `.env` để quản lý `IDE_PORT` đồng nhất với script khởi động.

package/template/.agent/skills/telegram-agentic-gateway/SKILL.md

@@ -61,20 +61,27 @@ Mỗi Topic/Chat trên Telegram sẽ sinh ra 1 File Ký ức lưu Context. Bắt
 
 ---
 
-## PHẦN E: KIẾN TẠO HẠ TẦNG & HƯỚNG DẪN ÔNG CHỦ (User Setup Instructions)
-Khi bạn (AI) code xong cái `TelegramGateway` cho dự án, nghĩa vụ của bạn CƯƠNG QUYẾT phải xuất ra một bảng hướng dẫn `Markdown` dặn dò Ông Chủ (User) cách thiết lập Telegram để chọn 1 trong 2 chế độ chơi:
+## PHẦN E: GIAO DIỆN PREMIUM (awesome-grammY Aesthetics)
+Một Gateway chuyên nghiệp phải có UI/UX tinh tế:
+1. **Header & Divider**: Sử dụng các thẻ `<b>` và ký tự ngăn cách (e.g. `━━━━━`) để tạo khối thông tin rõ ràng.
+2. **Status Mapping**: Sử dụng emoji trực quan cho trạng thái (✅ Online, 🚨 Offline, 🛡️ Protected).
+3. **Categorized Menus**: Nhóm các nút bấm theo chức năng (Hệ thống, AI, Dự án).
+4. **Short Callback Data**: Vì Telegram giới hạn callback data là 64 bytes, hãy sử dụng `shortIdMap` để lưu trữ Title dài và map chúng với một mã ngắn (e.g. `sess_a1b2`).
 
-1. **Chế Độ Bệnh Viện Đa Khoa (Group Multi-Topics - Khuyên dùng):**
-   - Hướng dẫn User tạo 1 Group Telegram mới.
-   - Thêm con Bot vào Group và cấp quyền Admin.
-   - **ĐẶC BIỆT QUAN TRỌNG:** Nhắc User phải vào Cài đặt Group (Group Settings) -> Bật tính năng **"Topics"** (Diễn đàn). 
-   - Giải thích cho User: Mỗi khi có 1 "Bệnh nhân" (Lỗi/Tính năng mới), User tạo một cái Topic mới trong Group đó. Bot sẽ phân luồng Ký ức cực mượt theo từng Topic.
+---
 
-2. **Chế Độ Phòng Khám Tư (Private Single Chat):**
-   - Hướng dẫn User chỉ cần nhấp vào Bot và nhắn tin trực tiếp (DM).
-   - Nhắc User dùng lệnh `/forget` nếu muốn đổi chủ đề để tránh Bot bị chập Ký ức.
+## PHẦN F: KIẾN TẠO HẠ TẦNG & HƯỚNG DẪN (User Setup)
+Khi triển khai, hãy hướng dẫn User:
+1. **Tạo Nhóm (Group with Topics)**: 
+   - Tạo Group Telegram. Thêm Bot làm Admin.
+   - Bật **"Topics"** trong cài đặt nhóm.
+   - Mỗi dự án hoặc tính năng lớn nên là 1 Topic riêng để cô lập ký ức.
+2. **Cấu Hình .env**: Giải thích rõ các token:
+   - `TELEGRAM_BOT_TOKEN`: Lấy từ @BotFather.
+   - `ALLOWED_USER_IDS`: Bảo mật, chỉ cho phép chủ nhân điều khiển.
+   - `IDE_PORT`: Cổng CDP của Antigravity (thường là 9555).
 
 ---
 
 ## TỔNG KẾT TRIỂN KHAI
-*(Ghi chú cho AI)*: Khi code Node.js/Python cho bot, bạn TỰ ĐỘNG đăng ký toàn bộ 7 lệnh này vào Bot Menu (`bot.setMyCommands(...)` trong Telegram API) để User chỉ việc gõ dấu `/` là Menu gợi ý hiện ra đầy đủ và chuyên nghiệp!
+*(Ghi chú cho AI)*: Luôn tích hợp VFS (`GEMINI.md`) để tiết kiệm token khi thực hiện code discovery từ xa thông qua Bot.

package/template/GEMINI.md

@@ -0,0 +1,35 @@
+# 🚀 Antigravity Core Rules
+
+> This file defines the core operational rules for the AI Agent in this workspace.
+
+---
+
+## 🛠️ TOKEN SAVING: VFS PROTOCOL (MANDATORY)
+
+**You MUST use `vfs` for code discovery before using `grep` or reading entire files.**
+
+### Why use VFS?
+`vfs` extracts logical signatures (functions, classes, types) without reading the bodies. This saves up to 98% of tokens compared to raw file reads.
+
+### Usage Protocol
+1. **Locate**: Use `vfs search` or `vfs <path>` to find the logical structure.
+2. **Review**: Analyze the signatures returned by `vfs`.
+3. **Read**: Only read the specific line ranges identified via `vfs`.
+
+### Commands
+- **CLI**: `vfs . -f <function_name>`
+- **MCP**: Use the `vfs` MCP tool if available.
+
+---
+
+## 🤖 MODEL SELECTION
+
+- **Simple Tasks**: Prefer local Ollama models (e.g., `nemotron`, `llama3`) to save cloud budget.
+- **Complex Tasks**: Use high-tier models (e.g., `Claude 3.5 Sonnet`, `Gemini 1.5 Pro`).
+
+---
+
+## 🧹 CLEAN CODE
+- Write self-documenting code.
+- Avoid over-engineering.
+- Follow the patterns defined in `.agent/skills/clean-code`.