# 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
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ự:

```html
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
```

<p class="callout warning">⚠️ **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.</p>

## 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)

<div class="relative whitespace-pre-wrap word-break-all my-2 rounded-lg bg-list-hover-subtle border border-gray-500/20" id="bkmrk--1" node="[object Object]"><div class="min-h-7 relative box-border flex flex-row items-center justify-between rounded-t border-b border-gray-500/20 px-2 py-0.5">  
</div><div class="p-3"><div class="w-full h-full text-xs cursor-text"><div class="code-block"><div class="code-line" data-line-end="8" data-line-number="8" data-line-start="8"><div class="line-content"></div></div></div></div></div></div>```bash
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
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?

<div class="my-4 rounded-lg overflow-hidden border border-gray-500/20 [&_thead_tr:first-child_th:first-child]:border-t-0 [&_thead_tr:first-child_th:first-child]:border-l-0 [&_thead_tr:first-child_th:last-child]:border-t-0 [&_thead_tr:first-child_th:last-child]:border-r-0 [&_tbody_tr:last-child_td:first-child]:border-b-0 [&_tbody_tr:last-child_td:first-child]:border-l-0 [&_tbody_tr:last-child_td:last-child]:border-b-0 [&_tbody_tr:last-child_td:last-child]:border-r-0 [&_thead_tr:first-child_th]:border-t-0 [&_tbody_tr:last-child_td]:border-b-0 [&_th:first-child]:border-l-0 [&_td:first-child]:border-l-0 [&_th:last-child]:border-r-0 [&_td:last-child]:border-r-0" id="bkmrk-t%C3%ACnh-hu%E1%BB%91ng-h%C3%A0nh-%C4%91%E1%BB%99ng"><table class="min-w-full border-separate border-spacing-0"><thead><tr><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Tình huống</th><th class="bg-gray-500/20 px-3 py-2 text-left font-medium leading-snug border border-gray-500/20">Hành động</th></tr></thead><tbody><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Phiên bản mới có tính năng bạn cần</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Nên cập nhật</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Có bản vá lỗi (bugfix) quan trọng</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Nên cập nhật</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Cần kiểm tra tương thích trước</td><td class="px-3 py-2 leading-snug border border-gray-500/20">✅ Đọc CHANGELOG trước, rồi cập nhật</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Đang giữa dự án phức tạp</td><td class="px-3 py-2 leading-snug border border-gray-500/20">⚠️ Cân nhắc — cập nhật sau khi hoàn thành sprint</td></tr><tr><td class="px-3 py-2 leading-snug border border-gray-500/20">Đã tùy chỉnh nhiều file gốc</td><td class="px-3 py-2 leading-snug border border-gray-500/20">⚠️ Sao lưu kỹ trước khi cập nhật</td></tr></tbody></table>

</div>---

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

Trước khi chạy lệnh update, hãy đọc file <span class="inline-flex break-all leading-tight">CHANGELOG.md</span> để biết những thay đổi trong phiên bản mới:

```bash
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
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
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
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
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.