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? 

 

 

 

 

 Tình huống 

 Hành động 

 

 

 

 

 Phiên bản mới có tính năng bạn cần 

 ✅ Nên cập nhật 

 

 

 Có bản vá lỗi (bugfix) quan trọng 

 ✅ Nên cập nhật 

 

 

 Cần kiểm tra tương thích trước 

 ✅ Đọc CHANGELOG trước, rồi cập nhật 

 

 

 Đang giữa dự án phức tạp 

 ⚠️ Cân nhắc — cập nhật sau khi hoàn thành sprint 

 

 

 Đã tùy chỉnh nhiều file gốc 

 ⚠️ Sao lưu kỹ trước khi 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à: 

 

 Clone repository về:  git clone https://github.com/vudovn/antigravity-kit.git 

 Checkout tag phiên bản mong muốn:  git checkout v2.0.1 

 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.