Trang 2.1: Yêu cầu hệ thống (Chi tiết về phiên bản Node.js >= 16 và Python >= 3.10).

1. Tóm tắt yêu cầu

Trước khi cài đặt Antigravity Kit, hãy đảm bảo máy tính của bạn đã đáp ứng các yêu cầu tối thiểu sau:

---

2. Node.js

Tại sao cần Node.js?

Công cụ dòng lệnh ag-kit được xây dựng trên nền tảng Node.js. Bạn cần Node.js để:

• Chạy lệnh npx @vudovn/ag-kit init để cài đặt bộ kit.
• Sử dụng lệnh ag-kit nếu cài đặt toàn cục.

Kiểm tra phiên bản Node.js

Mở Terminal (Command Prompt / PowerShell) và chạy:

cd đường/dẫn/đến/dự-án-của-bạn

Ví dụ:

# Windows
cd C:\Users\ten-ban\Projects\my-awesome-project

# macOS / Linux
cd ~/Projects/my-awesome-project

Bước 2: Chạy lệnh cài đặt

npx @vudovn/ag-kit init

npx sẽ tự động tải công cụ ag-kit về (tạm thời) và chạy lệnh khởi tạo. Bạn không cần cài đặt gì trước đó.

Bước 3: Chờ quá trình hoàn tất

Quá trình cài đặt sẽ tự động:

1. Kết nối với GitHub để tải phiên bản mới nhất.
2. Tạo thư mục .agent/ trong dự án của bạn.
3. Bơm toàn bộ 20 Agents, 36 Skills và 11 Workflows vào đó.

Khi hiển thị thông báo thành công, quá trình cài đặt đã hoàn tất.

---

3. Phương pháp 2: Cài đặt toàn cục (Global Install)

Phương pháp này phù hợp nếu bạn làm việc với nhiều dự án khác nhau và muốn dùng lệnh ag-kit từ bất kỳ đâu.

Bước 1: Cài đặt ag-kit lên toàn bộ máy

bash
npm install -g @vudovn/ag-kit

Lệnh này chỉ cần chạy một lần duy nhất trên máy tính của bạn.

Bước 2: Xác nhận cài đặt thành công

bash
cd đường/dẫn/đến/dự-án
ag-kit init

Bước 3: Khởi tạo vào từng dự án

Mỗi khi muốn tích hợp vào một dự án mới, di chuyển vào thư mục dự án đó và chạy:

bash


cd đường/dẫn/đến/dự-án
ag-kit init

4. Điều gì xảy ra sau khi cài đặt?

Sau khi cài đặt thành công, một thư mục .agent/ sẽ xuất hiện trong dự án của bạn với cấu trúc như sau:

your-project/
├── src/
├── package.json
├── ...
└── .agent/ ← Thư mục mới được tạo ra
├── ARCHITECTURE.md # Tài liệu kiến trúc tổng thể của Kit
├── AGENT_FLOW.md # Sơ đồ luồng hoạt động của các Agent
├── agents/ # 20 file cấu hình Specialist Agent
├── skills/ # 36 thư mục Knowledge Module (Skills)
├── workflows/ # 11 file quy trình làm việc (Workflows)
├── rules/ # Quy tắc hành vi toàn cục (GEMINI.md)
└── scripts/ # Script kiểm tra Python tổng thể

Từ thời điểm này, khi bạn mở dự án và bắt đầu trò chuyện với AI, nó sẽ tự động đọc các cấu hình trong thư mục .agent/ và hoạt động như một đội chuyên gia.

5. Quan trọng: Cấu hình .gitignore

Vấn đề

Nếu bạn đang dùng các trình soạn thảo AI như Cursor hoặc Windsurf, việc thêm .agent/ vào 

.gitignore sẽ khiến IDE không index được thư mục này. Hậu quả là các Slash Commands (như /plan, /debug) sẽ không xuất hiện trong dropdown gợi ý của chat.

 

Giải pháp được khuyến nghị

Không thêm .agent/ vào file 

.gitignore chung của dự án. Thay vào đó, thêm vào file local git exclude (chỉ áp dụng trên máy tính của bạn):

 

bash
#node Mở file local exclude
echo ".agent/" >> .git/info/exclude--version

CáchKết nàyquả giúp:hợp lệ phải hiển thị phiên bản >= 16.0, ví dụ: v20.11.0.

Cài đặt Node.js

Nếu chưa có, tải và cài đặt từ trang chính thức:

• ✅Khuyến Gitnghị: nodejs.org — Chọn phiên bản khôngLTS (Long Term Support) track thư mục .agent/ lên remote repository.
• ✅ IDE vẫn index được thư mục để Slashđảm Commandsbảo hoạtổn động.
• ✅ Thư mục .agent/ hoàn toàn cục bộ (local) và không ảnh hưởng đến 
  
  
  .gitignore chung.định.

Mẹo: Nên cài đặt phiên bản Node.js LTS mới nhất (hiện tại là Node.js 20.x LTS) để có sự tương thích tốt nhất với tất cả các gói npm hiện đại.

---

3. Python

Tại sao cần Python?

Các script kiểm tra chất lượng tự động của Antigravity Kit (checklist.py, verify_all.py) và nhiều script con trong từng Skill đều được viết bằng Python. Để các tính năng tự động hóa hoạt động, Python phải:

1. Được cài đặt trên máy tính.
2. Có thể gọi bằng lệnh python (hoặc python3) từ bất kỳ vị trí nào trong Terminal.

Kiểm tra phiên bản Python

python --version

Kết quả hợp lệ phải hiển thị phiên bản >= 3.10, ví dụ: Python 3.12.1.

Cài đặt Python (Windows)

Lưu ý:ý quan trọng (Windows): Nếu bạnbỏ muốnqua chiabước sẻtích cấuchọn hình"Add Python to PATH", lệnh python sẽ không được nhận dạng và các script kiểm tra của Kit sẽ không hoạt động. Bạn có thể khắc phục bằng cách gỡ cài đặt và cài lại Python với toàntùy chọn đó.

Cài đặt Python (macOS / Linux)

# macOS (dùng Homebrew)
brew install python3

# Ubuntu / Debian
sudo apt update && sudo apt install python3 python3-pip

4. Git

Tại sao cần Git?

• Lệnh ag-kit update dùng Git để tải phiên bản mới nhất của bộ độikit ngũtừ (khuyếnGitHub.
nghị
• Cho chophép các dự án nhóm), hãybạn commit thư mục .agent/ bình thường vào Git.repository Cáchcủa nàydự đảmán bảođể mọichia ngườisẻ trongcấu độihình với cả đội.

Kiểm tra phiên bản Git

bash
git --version

Kết quả hợp lệ ví dụ: git version 2.43.0.

Cài đặt Git

• Windows: Tải từ git-scm.com.
• macOS: Chạy brew install git hoặc cài Xcode Command Line Tools.
• Linux: sudo apt install git (Ubuntu/Debian) hoặc sudo dnf install git (Fedora).

---

5. Kiểm tra nhanh toàn bộ hệ thống

Chạy các lệnh sau để kiểm tra tất cả thành phần cùng lúc:

node --version   # Kiểm tra Node.js
npm --version    # Kiểm tra npm
python --version # Kiểm tra Python
git --version    # Kiểm tra Git

Nếu tất cả đều dùngtrả cùngvề mộtsố bộphiên Agent,bản Skillhợp vàlệ, Workflowhệ thống của bạn đã đượcsẵn thốngsàng nhất.để cài đặt Antigravity Kit.

---

6. CậpHệ nhậtđiều lênhành phiênđược bảnhỗ mớitrợ

Khi có phiên bản mới của Antigravity Kit,Kit bạntương cóthích thểvới cậptất nhật bằng lệnh:

bash
ag-kit update

⚠️ Cảnh báo: Lệnh update sẽ xóa và thay thế toàn bộ thư mục .agent/ bằng phiên bản mới nhất. Nếu bạn cócả các Workflowhệ hoặcđiều Agenthành tùyphổ chỉnh, hãy sao lưu trước khi cập nhật.biến:

---

7. Xử lý sự cố thường gặp

---

Bước tiếp theo: Sau khi đảm bảo đủ các yêu cầu trên, hãy chuyển sang Trang 2.2: Hướng dẫn cài đặt thành công, hãy đọc Trang 3.1: AI Agents và cơ chế định tuyến thông minhnhanh để hiểutiến cáchhành tậncài dụngđặt tốiAntigravity đaKit bộvào kit.dự án của bạn.