# 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.
Cài đặt nhanh (`npx`)Cài đặt toàn cục (`npm -g`)
**Tốc độ lần đầu**Chậm hơn (phải tải mỗi lần)Nhanh hơn (đã có sẵn)
**Cần cài trước**KhôngCó
**Phù hợp khi**Dùng thỉnh thoảngDùng thường xuyên, nhiều dự án
**Cập nhật**Tự động lấy bản mới nhấtCần chạy lại lệnh cài
--- ## 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 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 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 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 powershell $env:PATH -split ";" ``` **macOS / Linux:**
```bash bash echo $PATH ``` ### Kiểm tra `ag-kit` có trong PATH chưa
```bash 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 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 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 powershell ag-kit --version ``` ### macOS / Linux — Thêm vào `.bashrc` hoặc `.zshrc`
```bash 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:
```html 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:
```html 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/` đó.