Trang 4.2: Cập nhật phiên bản và quản lý dữ liệu (ag-kit update).

1. Lệnh ag-kit update — Cập nhật bộ kit

Mục đích

Cập nhật toàn bộ nội dung thư mục .agent/ lên phiên bản mới nhất từ repository chính thức.

Cú pháp

bash
ag-kit update [options]

---

2. Điều gì xảy ra khi chạy ag-kit update?

Lệnh này thực hiện các bước theo thứ tự:

1. Kết nối đến GitHub để lấy phiên bản mới nhất
│
▼
2. So sánh phiên bản hiện tại với phiên bản mới nhất
│
▼
3. ⚠️ XÓA toàn bộ thư mục .agent/ hiện tại
│
▼
4. Tải về và giải nén phiên bản mới
│
▼
5. Tạo lại .agent/ với nội dung mới
│
▼
6. Báo cáo kết quả cập nhật

⚠️ Cảnh báo quan trọng: Bước 3 là xóa hoàn toàn thư mục .agent/. Nếu bạn đã tùy chỉnh Agent, Skill hoặc Workflow trong thư mục này, tất cả sẽ bị mất nếu không sao lưu trước.

3. Chiến lược sao lưu trước khi cập nhật

Phương án 1: Sao lưu thủ công (Đơn giản nhất)

bash
# Tạo bản sao thư mục .agent/
cp -r .agent/ .agent-backup/ # macOS / Linux
xcopy .agent .agent-backup /E /I # Windows


# Thực hiện cập nhật
ag-kit update


# Sau khi cập nhật, merge lại các tùy chỉnh của bạn thủ công

Phương án 2: Dùng Git (Khuyến nghị cho dự án nhóm)

Nếu thư mục .agent/ đã được commit vào Git:

bash
# Commit trạng thái hiện tại để lưu lịch sử
git add .agent/
git commit -m "backup: save custom .agent configs before update"


# Cập nhật Kit
ag-kit update


# Nếu cần khôi phục tùy chỉnh, dùng git diff để xem sự khác biệt
git diff HEAD~1 .agent/

Phương án 3: Tách biệt tùy chỉnh (Bền vững nhất)

Tạo các file tùy chỉnh riêng biệt thay vì sửa file gốc:

• Thêm Agent tùy chỉnh: .agent/agents/my-team-agent.md (file mới, không ghi đè file gốc)
• Thêm Workflow tùy chỉnh: .agent/workflows/my-deploy.md (file mới)
• Không sửa các file Agent/Skill gốc (ví dụ không sửa frontend-specialist.md)

Với phương án này, sau khi update, các file gốc được cập nhật, còn các file tùy chỉnh của bạn vẫn giữ nguyên.

---

4. Khi nào nên cập nhật?

---

5. Kiểm tra CHANGELOG trước khi cập nhật

Trước khi chạy lệnh update, hãy đọc file CHANGELOG.md để biết những thay đổi trong phiên bản mới:

bash
# Xem CHANGELOG trên GitHub
# https://github.com/vudovn/antigravity-kit/blob/main/CHANGELOG.md

Mỗi phiên bản mới thường ghi rõ:

• Added: Thứ gì mới được thêm vào.
• Changed: Thứ gì thay đổi (có thể ảnh hưởng đến tùy chỉnh của bạn).
• Removed: Thứ gì bị xóa (cẩn thận nếu bạn đang phụ thuộc vào nó).
• Fixed: Lỗi nào đã được vá.

---

6. Cập nhật từ một nhánh cụ thể

Nếu bạn muốn thử nghiệm phiên bản chưa phát hành chính thức:

bash
# Cập nhật từ nhánh 'dev' (thử nghiệm)
ag-kit update --branch dev


# Quay về nhánh chính thức
ag-kit update --branch main

Lưu ý: Chỉ dùng nhánh dev cho mục đích thử nghiệm, không dùng trên môi trường production.

---

7. Rollback (Hoàn tác cập nhật)

Antigravity Kit không có lệnh rollback tích hợp. Để hoàn tác:

Nếu đã sao lưu thủ công:

bash
# Xóa .agent/ mới
rm -rf .agent/


# Khôi phục bản cũ
cp -r .agent-backup/ .agent/

Nếu đang dùng Git:

bash
# Khôi phục về commit trước khi update
git checkout HEAD~1 -- .agent/

Nếu muốn cài lại một phiên bản cụ thể: Hiện tại chưa có cú pháp chọn phiên bản cụ thể trong CLI. Cách làm thủ công là:

1. Clone repository về: git clone https://github.com/vudovn/antigravity-kit.git
2. Checkout tag phiên bản mong muốn: git checkout v2.0.1
3. Sao chép thư mục .agent/ vào dự án của bạn.

---

8. Cập nhật trong môi trường CI/CD

Nếu bộ kit là một phần trong quy trình CI/CD của đội:

yaml
# Ví dụ trong GitHub Actions
- name: Install/Update Antigravity Kit
run: ag-kit init --quiet --force
# (hoặc ag-kit update --quiet)

Tham số --quiet giúp ẩn bớt output không cần thiết trong log CI/CD.