@mrtrinhvn/ag-kit 1.1.3 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtrinhvn/ag-kit",
-  "version": "1.1.3",
+  "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`.