Trang 4.3: Các tham số nâng cao (Sử dụng --force, --path, --quiet).

1. Tổng quan các tham số

Công cụ ag-kit hỗ trợ nhiều tham số (options/flags) để tinh chỉnh hành vi cho từng tình huống cụ thể.

---

2. Tham số --force

Chức năng

Cho phép ghi đè lên thư mục .agent/ đã tồn tại. Mặc định, ag-kit init sẽ báo lỗi nếu thư mục này đã có.

Cú pháp

bash
ag-kit init --force

Khi nào dùng

Ví dụ

bash
# Thử cài đặt thông thường (sẽ báo lỗi nếu đã có .agent/)
ag-kit init
# Error: .agent/ already exists. Use --force to overwrite.


# Cài đặt lại với --force
ag-kit init --force
# ✅ Overwriting .agent/... Done!

⚠️ Cảnh báo: --force sẽ xóa toàn bộ thư mục .agent/ hiện tại trước khi cài lại. Mọi tùy chỉnh trong đó sẽ bị mất. Hãy sao lưu trước nếu cần.

---

3. Tham số --path

Chức năng

Chỉ định thư mục đích để cài đặt Kit thay vì thư mục hiện tại trong terminal.

Cú pháp

bash
ag-kit init --path <đường-dẫn-đến-thư-mục>

Khi nào dùng

Ví dụ thực tế

bash
# Cấu trúc monorepo:
my-monorepo/
├── apps/
│ ├── web/ ← muốn cài vào đây
│ └── mobile/ ← và cả đây
└── packages/


# Cài vào web app mà không cần cd
ag-kit init --path ./apps/web


# Cài vào mobile app
ag-kit init --path ./apps/mobile


# Kết hợp với --force nếu đã có .agent/ cũ
ag-kit init --path ./apps/web --force

---

4. Tham số --branch

Chức năng

Chỉ định nhánh Git cụ thể trên repository để tải bộ kit. Mặc định sử dụng nhánh main (phiên bản ổn định nhất).

Cú pháp

bash
ag-kit init --branch <tên-nhánh>
ag-kit update --branch <tên-nhánh>

Các nhánh phổ biến

Ví dụ

bash
# Cài từ nhánh chính thức (mặc định)
ag-kit init
# Tương đương với:
ag-kit init --branch main


# Thử nghiệm tính năng mới nhất (chưa phát hành)
ag-kit init --branch dev


# Cập nhật từ nhánh dev
ag-kit update --branch dev

Lưu ý: Nhánh dev có thể chứa các tính năng chưa hoàn thiện. Chỉ dùng cho môi trường phát triển và thử nghiệm cá nhân.

---

5. Tham số --quiet

Chức năng

Chạy lệnh ở chế độ im lặng — ẩn bớt các thông báo thông thường, chỉ hiển thị lỗi nghiêm trọng (nếu có).

Cú pháp

bash
ag-kit init --quiet
ag-kit update --quiet

Khi nào dùng

• CI/CD pipelines: Khi bạn không muốn log quá dài làm rối output của build pipeline.
• Script tự động: Khi chạy trong script shell không cần đọc log chi tiết.
• Chạy hàng loạt: Khi cần cài/cập nhật Kit cho nhiều dự án cùng lúc.

Ví dụ trong GitHub Actions

yaml
name: Setup Antigravity Kit
on: [push]


jobs:
setup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Node.js
uses: actions/setup-node@v3
with:
node-version: '20'
- name: Install Antigravity Kit
run: |
npm install -g @vudovn/ag-kit
ag-kit init --quiet --force

---

6. Tham số --dry-run

Chức năng

Thực hiện một lần chạy "giả định" — hiển thị tất cả những gì sẽ xảy ra nhưng không thực sự làm gì trên hệ thống. Không tạo, không xóa, không thay đổi file nào.

Cú pháp

bash
ag-kit init --dry-run
ag-kit update --dry-run

Khi nào dùng

• Trước khi cài đặt trên dự án quan trọng để xem trước thao tác.
• Kiểm tra xem lệnh có hoạt động đúng không mà không có rủi ro.
• Xem danh sách file sẽ được tạo ra.

Ví dụ kết quả của --dry-run

bash
ag-kit init --dry-run

[DRY RUN] The following actions would be performed:
- Create directory: ./.agent/
- Create file: ./.agent/ARCHITECTURE.md
- Create file: ./.agent/AGENT_FLOW.md
- Create directory: ./.agent/agents/ (20 files)
- Create directory: ./.agent/skills/ (36 directories)
- Create directory: ./.agent/workflows/ (11 files)
- Create directory: ./.agent/rules/
- Create directory: ./.agent/scripts/
[DRY RUN] No changes were made.

---

7. Kết hợp nhiều tham số

Các tham số có thể kết hợp với nhau tùy ý:

bash
# Cài vào thư mục cụ thể, ghi đè nếu tồn tại, chạy im lặng
ag-kit init --path ./apps/web --force --quiet


# Xem trước thao tác cập nhật từ nhánh dev
ag-kit update --branch dev --dry-run


# Cài đặt vào thư mục cụ thể, xem trước (không thực sự làm)
ag-kit init --path ./packages/shared --dry-run

---

8. Bảng tham chiếu nhanh (Quick Reference)

bash
# Cài đặt cơ bản
ag-kit init


# Cài đặt (ghi đè nếu đã có)
ag-kit init --force


# Cài vào thư mục khác
ag-kit init --path ./my-app


# Cài từ nhánh cụ thể
ag-kit init --branch dev


# Chạy im lặng (cho CI/CD)
ag-kit init --quiet --force


# Xem trước không làm gì
ag-kit init --dry-run


# Kết hợp: cài vào thư mục khác, ghi đè, im lặng
ag-kit init --path ./apps/web --force --quiet


# Cập nhật và xem trước
ag-kit update --dry-run


# Cập nhật im lặng (cho automation)
ag-kit update --quiet


# Kiểm tra trạng thái
ag-kit status