Trang 2.2: Hướng dẫn cài đặt nhanh (Sử dụng lệnh npx).

1. Trước khi bắt đầu

Đảm bảo các yêu cầu hệ thống đã được đáp ứng (tham khảo Trang 2.1: Yêu cầu hệ thống):

• ✅ Node.js >= 16.0
• ✅ Python >= 3.10 (trong PATH)
• ✅ Git

---

2. Phương pháp 1: Cài đặt nhanh bằng npx (Khuyến nghị)

Đây là cách nhanh nhất và đơn giản nhất để bắt đầu. Bạn không cần cài bất kỳ thứ gì lên toàn bộ máy tính.

Bước 1: Di chuyển vào thư mục dự án

Mở Terminal và di chuyển vào thư mục gốc của dự án bạn muốn cài đặt:

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

Ví dụ:

bash
# 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

bash
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
ag-kit --version

Nếu hiển thị số phiên bản, cài đặt toàn cục đã thành công.

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
# Mở file local exclude
echo ".agent/" >> .git/info/exclude

Cách này giúp:

• ✅ Git không track thư mục .agent/ lên remote repository.
• ✅ IDE vẫn index được thư mục để Slash Commands hoạt động.
• ✅ Thư mục .agent/ hoàn toàn cục bộ (local) và không ảnh hưởng đến 
  
  
  .gitignore chung.

Lưu ý: Nếu bạn muốn chia sẻ cấu hình Kit với toàn bộ đội ngũ (khuyến nghị cho các dự án nhóm), hãy commit thư mục .agent/ bình thường vào Git. Cách này đảm bảo mọi người trong đội đều dùng cùng một bộ Agent, Skill và Workflow đã được thống nhất.

---

6. Cập nhật lên phiên bản mới

Khi có phiên bản mới của Antigravity Kit, bạn có thể cập 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 Workflow hoặc Agent tùy chỉnh, hãy sao lưu trước khi cập nhật.

---

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

---

Bước tiếp theo: Sau khi cài đặt thành công, hãy đọc Trang 3.1: AI Agents và cơ chế định tuyến thông minh để hiểu cách tận dụng tối đa bộ kit.