Cập nhật AgentKit và Kit

CLI ak và các Kit đã cài có vòng đời phát hành riêng. Cập nhật CLI không thay thế nội dung Kit, còn làm mới Kit không thay thế CLI. Hãy kiểm tra và cập nhật từng lớp một cách chủ động.

Chọn kênh

AgentKit phát hành qua hai kênh stable và beta:

• Chọn stable cho dòng phát hành thông thường.
• Chọn beta khi bạn chủ động thử hành vi prerelease và có thể review các thay đổi về tương thích.

Các lệnh Kit mặc định dùng stable; beta cần được chọn rõ ràng. Lệnh ak self-update có thể kế thừa kênh đã lưu, vì vậy hãy truyền --channel stable hoặc --channel beta khi lựa chọn này quan trọng. Giữ CLI và Kit trên cùng kênh bạn đã chọn.

Các ví dụ bên dưới dùng stable. Chỉ thay bằng beta như một quyết định đầy đủ, không phải cách xử lý sự cố nhất thời.

Dùng trình cập nhật hợp nhất khi phù hợp

Trong terminal tương tác, lệnh ak update không có flag sẽ lần lượt xử lý cập nhật CLI đã ký, các Kit global rồi các Kit trong project. Mỗi bước mặc định là Không:

ak update
ak update --yes

--yes chấp nhận các bước được đề xuất, nhưng kiểm tra bản cập nhật CLI đã ký hoặc phiên bản tối thiểu vẫn là cổng bắt buộc trước mọi thay đổi Kit. Dùng các lệnh có phạm vi bên dưới khi bạn chỉ muốn cập nhật một lớp. Lỗi ở cổng CLI, lỗi một phần khi cập nhật Kit hoặc gián đoạn sau khi đã thay đổi trả mã 1; target hoặc phạm vi không hợp lệ trả 2.

Xem lại bản phát hành CLI

Đọc changelog đã xác minh, kiểm tra bản mới hoặc xác minh đầy đủ bản cập nhật mà không thay binary:

ak self-update --changelog --channel stable
ak self-update --check --channel stable
ak self-update --dry-run --channel stable

--changelog là chế độ chỉ đọc và không thể dùng cùng các flag cập nhật. --dry-run tải và xác minh artifact cần thiết trong vùng tạm, sau đó giữ nguyên binary đã cài.

Cập nhật CLI

Áp dụng sau khi bước kiểm tra thành công:

ak self-update --channel stable --yes
ak --version

Trình cập nhật xác minh metadata phát hành và nội dung artifact trước khi thay binary. Nếu thay thế thất bại, transaction tự khôi phục binary trước đó. Cập nhật binary CLI không có bước ak backups restore dành cho người dùng.

Cài đặt qua package manager

Nếu executable ak đang chạy thuộc Homebrew hoặc Scoop, ak self-update không tự thay thế nó. Hãy chạy lệnh gốc của package manager mà CLI báo:

brew upgrade ak
scoop update ak

AgentKit nhận diện dựa trên executable thực tế và receipt của package manager, không chỉ dựa trên việc package manager có tồn tại ở đâu đó trên máy.

Xem trước cập nhật Kit trong project

ak update mặc định chỉ xem trước trừ khi bạn xác nhận bằng --yes. Chỉ định project, Kit và kênh để kế hoạch không mơ hồ:

ak update . --kits engineer --channel stable --show-diff
ak update . --kits engineer --channel stable --show-diff --dry-run

Bản xem trước không ghi file và không tạo snapshot. Lệnh phân loại các file sắp đến và hiển thị file do người dùng sửa sẽ được bỏ qua. Nếu không có --yes, bản xem trước ngầm định trong script trả mã thoát 3; --dry-run thực hiện cùng bản xem trước không thay đổi dữ liệu và trả 0, thuận tiện hơn cho CI. Áp dụng kế hoạch đã review bằng:

ak update . --kits engineer --channel stable --yes

Khi áp dụng, cập nhật project tạo snapshot trước thay đổi. Theo mặc định, file do người dùng sửa được giữ lại. Chỉ dùng --force sau khi review chính xác diff và quyết định snapshot là đủ để khôi phục; đây không phải flag làm mới thông thường.

Xem trước cập nhật Kit global

Cập nhật global tìm các bản cài thuộc quyền sở hữu AgentKit trong phạm vi người dùng. Xem trước tất cả, hoặc lọc theo Kit và runtime:

ak update --global --channel stable
ak update --global --kits engineer --target codex --channel stable
ak update --global --kits engineer --local --kits-dir ./kits --target grok

Chỉ áp dụng sau khi bản xem trước nhận diện đúng các bản cài mong muốn:

ak update --global --kits engineer --target codex --channel stable --yes
ak update --global --kits engineer --local --kits-dir ./kits --target grok --yes

Cập nhật global luôn giữ file do người dùng sửa. Runtime bạn đã chọn nhưng chưa cài global được báo là bỏ qua thay vì được tạo mới. Dùng --target hoặc alias --runtime để chọn runtime đã cài như claude-code, codex, cursor hoặc grok; chỉ truyền một trong hai tên cờ. Phân biệt giữa bản xem trước ngầm định trả 3 và dry run rõ ràng trả 0 cũng áp dụng ở phạm vi global.

Nếu discovery Claude Code global đi tới một Claude home không được đánh dấu là do AgentKit sở hữu, lệnh update từ chối takeover foreign home trước mọi mutation của emitter hoặc ownership. Lệnh vẫn có thể in snapshot ID vì recovery material được tạo trước bước kiểm tra này; ID đó không có nghĩa đã xảy ra partial write. Hãy xác nhận home được discover là bản cài global mong muốn, rồi chạy ak kit init <kit> --global để thiết lập lại ownership trước khi refresh. Đừng restore snapshot chỉ vì ID xuất hiện cùng lỗi từ chối này.

Làm mới một tuyến cài đặt cụ thể

Dùng ak kit refresh khi cần giữ chính xác target, phạm vi hoặc cách phân phối Claude Code của bản cài hiện có:

ak kit refresh engineer --target codex --channel stable --yes
ak kit refresh engineer --global --switch-to-plugin --channel stable --yes

Refresh tạo snapshot khôi phục, ghi lại output AgentKit hiện tại, và chỉ gỡ các đường dẫn sinh tự động hoặc thuộc quyền sở hữu đã cũ khi bằng chứng quyền sở hữu vẫn khớp. Lệnh giữ tập Skill được chọn trước đó và giữ nguyên đường dẫn đã sửa, không an toàn, là liên kết hoặc được dùng chung. Hãy xem lại màn hình xác nhận và tránh dùng --no-backup.

Xác minh cập nhật

Sau khi cập nhật:

1. Chạy ak --version và xác nhận đúng kênh/phiên bản đã chọn.
2. Xem bản tóm tắt cập nhật để tìm file bị bỏ qua hoặc được giữ lại.
3. Mở lại từng runtime bị ảnh hưởng.
4. Gọi một Skill quan trọng đã cài trong mỗi target vừa cập nhật.

Nếu Kit cần CLI mới hơn, hãy cập nhật ak trên cùng kênh trước rồi chạy lại bản xem trước của Kit.

Nếu các file mong đợi không thay đổi

Hãy kiểm tra lần lượt tuyến cài trước khi buộc ghi lại:

1. Xác nhận đúng lớp: ak self-update chỉ thay binary CLI, ak update xử lý nội dung project thuộc quyền sở hữu AgentKit, còn ak kit refresh phát lại một tuyến runtime đã cài.
2. So sánh cả phiên bản CLI và phiên bản/channel của Kit đã resolve với phiên bản bạn mong đợi.
3. Khớp đúng target, scope project hoặc global, cùng delivery mode native hoặc plugin của Claude Code. Tuyến khác sẽ ghi vào đích khác.
4. Kiểm tra file có thuộc tập Skill đã chọn trước đó hay không.
5. Xem lại preview và bằng chứng quyền sở hữu. Đường dẫn do người dùng sửa, không rõ nguồn gốc, là liên kết hoặc dùng chung có thể được chủ động giữ lại dù thao tác thành công. Lỗi refusing foreign-home takeover thì dừng trước mutation; hãy làm theo đúng lệnh khôi phục ak kit init <kit> --global được in.

Xem Cơ chế cài đặt và làm mới để hiểu các lớp quyền sở hữu, quy tắc reconciliation và ví dụ trước/sau. Đừng xóa toàn bộ thư mục runtime chỉ để làm cho refresh có vẻ thành công.

Khôi phục cập nhật Kit

Giữ lại ID snapshot và đường dẫn khôi phục mà thao tác đã in ra. Kiểm tra snapshot trước khi restore:

ak backups list
ak backups show <id>
ak backups verify <id>
ak recover <id> --dry-run

ak recover là alias chính xác của ak backups restore. Restore theo cơ chế replace-only: lệnh ghi đè các file đã capture, chỉ gỡ chính xác các đường dẫn được ghi nhận là không tồn tại hoặc thư mục plugin AgentKit đã phê duyệt rõ ràng, và thường giữ nguyên file không liên quan được tạo sau snapshot.

Nếu ak backups show <id> liệt kê các root của project bundle, hãy lặp lại mọi root chính xác trong lệnh khôi phục:

ak recover <id> --allow-root /absolute/project --dry-run
ak recover <id> --allow-root /absolute/project

Khi có nhiều root, hãy lặp lại --allow-root với mọi đường dẫn chính xác trong cả hai lệnh.

Nếu thao tác báo snapshot của project nằm ngoài phạm vi ak backups restore, hãy dùng thư mục chứa file snapshot được in ra và chỉ sao chép lại các file bị ảnh hưởng. Nếu không, áp dụng kế hoạch restore đã review bằng ak recover <id> và xác nhận prompt. Với project bundle, hãy giữ mọi flag --allow-root đã xem lại trong lệnh áp dụng đó.

Restore nhiều file không có tính transaction; nếu bị gián đoạn, trạng thái có thể dở dang. Hãy giữ riêng công việc không liên quan và tạo snapshot mới trước khi quay lui nếu thực tế cho phép. Không recover --latest một cách mù quáng, xóa toàn bộ thư mục runtime hoặc chạy lại cập nhật lỗi với --force trước khi hiểu trạng thái hiện tại. Từ chối restore trả mã 3, backup lock đang bị giữ trả 4, snapshot không hợp lệ hoặc không tồn tại trả 5, còn lỗi khác trả 1.

Xem thêm

• Cài đặt Kit