@mrtrinhvn/ag-kit 1.1.3 → 1.1.5

package/README.md

@@ -4,8 +4,14 @@ A generic, institutional-grade AI programming framework for automating scaffoldi
 
 ## 📦 Quick Start
 
-The best way to inject AG-Kit into any project is via `npx`:
+The best way to inject AG-Kit into any project is via `npx`. Bạn có thể chạy trực tiếp để vào **Menu tương tác**:
 
+```bash
+# DASHBOARD - Menu chọn tất cả tác vụ (Khuyên dùng)
+npx @mrtrinhvn/ag-kit@latest
+```
+
+Hoặc chạy các lệnh đơn lẻ:
 ```bash
 # 1. Khởi tạo bộ não (Inject .agent folder)
 npx @mrtrinhvn/ag-kit@latest init
@@ -23,6 +29,7 @@ npx @mrtrinhvn/ag-kit@latest status
 
 | Lệnh | Ý nghĩa | Chi tiết |
 |---|---|---|
+| `ag-kit` | **Dashboard** | (Không tham số) Mở menu chọn tương tác cực kỳ tiện lợi. |
 | `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. |
@@ -66,7 +73,8 @@ npx @mrtrinhvn/ag-kit@latest update
 
 **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`.
+- Cách giải quyết: Luôn thêm `@latest` sau tên gói (`npx @mrtrinhvn/ag-kit@latest`) hoặc cập nhật bộ não bằng lệnh `ag-kit update`.
+- Giờ đây, các lệnh `init` và `status` sẽ tự động phát hiện và nhắc bạn chạy `update` nếu phát hiện lệch phiên bản.
 
 **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`.

package/bin/cli.js

@@ -90,7 +90,18 @@ program.command('init')
         }
       }
     } 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');
+      console.log('\x1b[33m⚠️ Thư mục .agent đã tồn tại.\x1b[0m');
+      const vPath = path.join(TARGET_AGENT_DIR, '.version');
+      if (fs.existsSync(vPath)) {
+        const installedVersion = fs.readFileSync(vPath, 'utf-8').trim();
+        if (installedVersion !== pkg.version) {
+          console.log(`\x1b[35m👉 Phát hiện phiên bản cũ (v${installedVersion}). Hãy dùng lệnh "ag-kit update" để cập nhật lên v${pkg.version}.\x1b[0m`);
+        } else {
+          console.log('\x1b[34mℹ️  Bạn đang sử dụng phiên bản khớp với bộ công cụ (v${pkg.version}).\x1b[0m');
+        }
+      } else {
+        console.log('\x1b[35m👉 Hãy dùng lệnh "ag-kit update" để đồng bộ cấu trúc mới.\x1b[0m');
+      }
     }
 
     console.log('\x1b[35m\n🎉 Hoàn tất! Vui lòng copy luật GEMINI vào file GEMINI.md của dự án nếu chưa có.\x1b[0m');
@@ -127,6 +138,12 @@ program.command('check')
   .action(async () => {
     const { execSync } = require('child_process');
     console.log('\x1b[36m🔍 Đang kiểm tra hệ sinh thái Antigravity...\x1b[0m');
+    
+    if (!fs.existsSync(TARGET_AGENT_DIR)) {
+      console.log('\x1b[31m❌ Hệ thống chưa được khởi tạo. Thư mục .agent không tồn tại.\x1b[0m');
+      console.log('\x1b[35m👉 Hãy chạy "ag-kit init" trước khi thực hiện kiểm tra này.\x1b[0m');
+      return;
+    }
 
     // 1. Check .env
     const envPath = path.join(process.cwd(), '.env');
@@ -203,8 +220,9 @@ program.command('status')
       console.log(`📁 Đường dẫn    : ${TARGET_AGENT_DIR}`);
       
       const vPath = path.join(TARGET_AGENT_DIR, '.version');
+      let installedVersion = '0.0.0';
       if (fs.existsSync(vPath)) {
-        const installedVersion = fs.readFileSync(vPath, 'utf-8').trim();
+        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)`);
@@ -212,10 +230,41 @@ program.command('status')
 
       console.log(`🏷  Bản Tool     : v${pkg.version}`);
       
+      if (installedVersion !== pkg.version) {
+        console.log('\n\x1b[33m⚠️  CẢNH BÁO: Phiên bản bộ não (.agent) đang lệch với bộ công cụ (ag-kit)!\x1b[0m');
+        console.log(`\x1b[35m👉 Hãy chạy "ag-kit update" để đồng bộ ngay.\x1b[0m`);
+      }
+      
     } 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ì.\x1b[0m');
+      console.log('\x1b[35m👉 Gõ "ag-kit init" để biến thư mục này thành một Agentic Workspace!\x1b[0m');
       console.log(`🏷  Bản Tool     : v${pkg.version}`);
     }
   });
 
-program.parse(process.argv);
+
+if (process.argv.length <= 2) {
+  const inquirer = require('inquirer');
+  console.log('\x1b[35m\n🧠 ANTIGRAVITY KIT - BẢNG ĐIỀU KHIỂN TÁC VỤ\x1b[0m');
+  inquirer.prompt([
+    {
+      type: 'list',
+      name: 'action',
+      message: 'Chọn một tác vụ để thực hiện:',
+      choices: [
+        { name: '🚀 Khởi tạo (init) - Cài đặt .agent', value: 'init' },
+        { name: '🔄 Cập nhật (update) - Nâng cấp bộ não', value: 'update' },
+        { name: '🔍 Kiểm tra (check) - Test môi trường', value: 'check' },
+        { name: '📊 Trạng thái (status) - Xem version', value: 'status' },
+        new inquirer.Separator(),
+        { name: '❌ Thoát', value: 'exit' }
+      ]
+    }
+  ]).then(answers => {
+    if (answers.action !== 'exit') {
+      program.parse([process.argv[0], process.argv[1], answers.action]);
+    }
+  });
+} else {
+  program.parse(process.argv);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtrinhvn/ag-kit",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
   "main": "index.js",
   "bin": {
@@ -29,6 +29,7 @@
     "package.json"
   ],
   "dependencies": {
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "inquirer": "^8.2.5"
   }
 }

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`.