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

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--1" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
bash
cd đường/dẫn/đến/dự-án-của-bạn
```

**Ví dụ:**

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--2" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="5" data-line-number="5" data-line-start="5"><div class="line-content"></div></div></div></div></div></div>```bash
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

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--3" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
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

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--5" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
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

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--6" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>```bash
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:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--7" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"></div></div></div></div></div></div>```bash
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:

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--9" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5"><div class="font-sans text-sm text-ide-text-color opacity-60">  
</div><div class="flex flex-row gap-2 justify-end">  
</div></div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1">  
</div><div class="code-line" data-line-end="12" data-line-number="12" data-line-start="12"><div class="line-content"></div></div></div></div></div></div>```html
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 <span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">.gitignore</span></span></span>

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

<div id="bkmrk--11">  
</div><span class="inline-flex break-all leading-tight">.gitignore</span> 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

<div id="bkmrk--12">  
</div><span class="inline-flex break-all leading-tight">.gitignore</span> 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):

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--13" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="2" data-line-number="2" data-line-start="2"><div class="line-content"></div></div></div></div></div></div>```bash
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 <div>  
    </div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">.gitignore</span></span></span> 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
bash
ag-kit update
```

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--15" node="[object Object]"><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="1" data-line-number="1" data-line-start="1"><div class="line-content"></div></div></div></div></div></div>> ⚠️ **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

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-v%E1%BA%A5n-%C4%91%E1%BB%81-nguy%C3%AAn-nh%C3%A2n-g"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Vấn đề</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Nguyên nhân</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Giải pháp</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`npx: command not found`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Node.js chưa được cài đặt</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cài đặt Node.js từ nodejs.org</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">`ag-kit: command not found`</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cài đặt toàn cục chưa thành công</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Chạy lại `npm install -g @vudovn/ag-kit`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Thư mục `.agent/` đã tồn tại</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Đã cài đặt trước đó</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Thêm tham số `--force`: `ag-kit init --force`</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Script Python không chạy</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Python không có trong PATH</td><td class="px-3 py-2 leading-snug border border-gray-500/20">Cài lại Python với tùy chọn "Add to PATH"</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Slash commands không hiện</td><td class="px-3 py-2 leading-snug border border-gray-500/20">`.agent/` bị trong <div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">.gitignore</span></span></span></td><td class="px-3 py-2 leading-snug border border-gray-500/20">Dùng <div>  
</div><span class="context-scope-mention"><span class="inline-flex items-center gap-0.5 rounded-md align-middle text-sm font-medium transition-[opacity,background-color] cursor-pointer hover:bg-gray-500/20 select-text translate-y-[-1px]" draggable="true"><span class="inline-flex break-all leading-tight">.git/info/exclude</span></span></span> thay thế (xem Mục 5)</td></tr></tbody></table>

</div>---

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