Trang 2.3: Cài đặt toàn cục (Global Install) và cấu hình biến môi trường PATH.

1. Cài đặt toàn cục là gì?

Cài đặt toàn cục (Global Install) có nghĩa là bộ công cụ ag-kit được cài đặt ở cấp độ toàn bộ hệ thống thay vì chỉ trong một dự án cụ thể. Sau khi cài toàn cục, bạn có thể gõ lệnh ag-kit từ bất kỳ thư mục nào trên máy tính.

---

2. Cài đặt toàn cục lên hệ thống

Bước 1: Mở Terminal với quyền phù hợp

• Windows: Mở PowerShell hoặc Command Prompt (không cần quyền Admin nếu npm được cài bình thường).
• macOS/Linux: Mở Terminal thông thường.

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

bash
npm install -g @vudovn/ag-kit

-g là tham số báo cho npm biết đây là cài đặt toàn cục (global).

Bước 3: 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 (ví dụ: 2.0.2), cài đặt đã thành công.

Bước 4: Khởi tạo cho từng dự án

Mỗi khi cần dùng cho một dự án mới, chỉ cần:

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

---

3. Biến môi trường PATH là gì và tại sao quan trọng?

PATH là một biến môi trường của hệ thống. Nó chứa danh sách các thư mục mà hệ điều hành sẽ tự động tìm kiếm khi bạn gõ một lệnh trong Terminal.

Ví dụ dễ hiểu: Khi bạn gõ ag-kit init, hệ điều hành sẽ duyệt qua từng thư mục trong biến PATH để tìm xem có file thực thi tên ag-kit ở đâu không. Nếu tìm thấy → chạy. Nếu không → báo lỗi "command not found".

Vì sao điều này quan trọng với Antigravity Kit?

• Lệnh ag-kit cần có trong PATH để bạn gọi được từ mọi nơi.
• Lệnh python cần có trong PATH để các script kiểm tra tự động của Kit có thể chạy được.

---

4. Kiểm tra và cấu hình PATH

Kiểm tra PATH hiện tại

Windows (PowerShell):

powershell
$env:PATH -split ";"

macOS / Linux:

bash
echo $PATH

Kiểm tra ag-kit có trong PATH chưa

bash
# Tất cả hệ điều hành
where ag-kit # Windows
which ag-kit # macOS / Linux

Nếu lệnh trên trả về đường dẫn (ví dụ: C:\Users\ten-ban\AppData\Roaming\npm\ag-kit), bạn đã cấu hình đúng.

Kiểm tra python có trong PATH chưa

bash
where python # Windows
which python # macOS / Linux

---

5. Cấu hình PATH thủ công (khi gặp lỗi)

Windows — Thêm thư mục npm global vào PATH

B1: Tìm thư mục npm global:

powershell
npm config get prefix

Kết quả thường là: C:\Users\ten-ban\AppData\Roaming\npm

B2: Thêm vào PATH:

1. Mở Settings → tìm kiếm "Environment Variables".
2. Nhấn "Edit the system environment variables".
3. Chọn biến Path trong phần "User variables" → nhấn Edit.
4. Nhấn New → dán đường dẫn từ Bước 1 vào.
5. Nhấn OK và khởi động lại Terminal.

B3: Xác nhận lại:

powershell
ag-kit --version

macOS / Linux — Thêm vào .bashrc hoặc .zshrc

bash
# Tìm thư mục npm global
npm config get prefix
# Thường là: /usr/local hoặc /home/ten-ban/.npm-global


# Thêm vào file cấu hình shell
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
# Hoặc cho bash:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc


# Áp dụng thay đổi
source ~/.zshrc # hoặc source ~/.bashrc

---

6. Quy trình làm việc điển hình với nhiều dự án

Đây là quy trình khuyến nghị khi bạn làm việc với nhiều dự án trên cùng một máy:

1. Cài đặt một lần:
npm install -g @vudovn/ag-kit


2. Cho mỗi dự án mới:
cd my-new-project
ag-kit init


3. Cập nhật định kỳ (không làm thường xuyên):
ag-kit update ← chạy trong thư mục dự án

---

7. Gỡ cài đặt toàn cục (khi cần)

Nếu bạn muốn gỡ bỏ cài đặt toàn cục:

bash
npm uninstall -g @vudovn/ag-kit

Lưu ý: Gỡ cài đặt toàn cục không xóa bất kỳ thư mục .agent/ nào đã được tạo trong các dự án. Để xóa khỏi một dự án cụ thể, hãy xóa thủ công thư mục .agent/ đó.