Cập nhật và khôi phục

Tách cập nhật binary khỏi Kit, diễn giải mã thoát preview và lỗi, rồi chỉ restore snapshot đã xác minh.

Dùng trang này khi cập nhật không apply, cập nhật sai scope, báo lỗi một phần hoặc cần rollback.

Xác định thứ bạn muốn cập nhật

ak self-update xử lý binary ak. ak update điều phối CLI, Kit global và Kit project, hoặc cập nhật một scope được chọn rõ ràng. ak kit refresh làm mới độc lập một route Kit đã cài.

Kiểm tra binary mà không thay đổi disk:

ak --version
ak self-update --check --channel <channel> --json

Check thành công thoát 0; đọc các trường available, status và phiên bản để biết có bản cập nhật hay không. Lỗi mạng, xác minh, staging hoặc thay binary thoát 1; flag không hợp lệ thoát 2. Binary do package manager quản lý sẽ báo manager và lệnh upgrade gốc thay vì tự thay binary. Kênh cập nhật binary và kênh Kit package là hai thiết lập riêng. Kiểm tra đúng kênh binary dự kiến và chọn rõ cùng kênh Kit dự kiến khi compatibility yêu cầu chúng khớp nhau; không sửa cached manifest.

Preview thay đổi Kit và project

ak update ./myproj --dry-run --show-diff

Project --dry-run rõ ràng chỉ đọc và thoát 0 khi preview thành công. Trong script hoặc session non-interactive, ak update ./myproj không có --yes cũng chỉ preview nhưng thoát 3 để automation phân biệt “chưa apply” với cập nhật đã apply. Lệnh ak update trống trong terminal interactive mở wizard CLI → Kit global → Kit project; mỗi bước apply mặc định là No.

Chỉ apply sau khi kiểm tra project, runtime, Kit và kênh đã chọn:

ak update ./myproj --yes

Dùng ak self-update --yes để chỉ cập nhật binary, hoặc ak update --global --yes cho các user install do AgentKit sở hữu. Lệnh trống ak update --yes chấp nhận mọi bước của unified wizard, nên chỉ dùng khi chủ ý cả ba scope.

Cập nhật Kit global là preserve-only: --force không cho phép ghi đè tệp global đã được người dùng sửa. Bản cài chỉ có Claude user plugin sẽ được báo thay vì refresh ngầm; refresh đúng route đó bằng:

ak kit refresh <kit> --global --switch-to-plugin --yes

Nếu refresh Claude global báo refusing foreign-home takeover, lệnh đã dừng trước khi thay đổi Claude home được discover. Snapshot ID vẫn có thể xuất hiện vì snapshot được tạo trước bước từ chối ownership; ID đó chứng minh recovery material tồn tại, không chứng minh đã có partial write. Hãy xác nhận đây là bản cài global mong muốn, rồi chạy đúng lệnh ak kit init <kit> --global trong lỗi để thiết lập lại ownership. Đừng restore chỉ vì lỗi trước mutation này có snapshot.

Lỗi runtime khi apply, CLI hard gate, Kit lỗi một phần hoặc ngắt sau khi đã mutation thoát 1. Kết hợp scope hoặc target không hợp lệ thoát 2.

Workaround khi một runtime global lỗi trên Windows

Cập nhật global báo kết quả riêng cho từng runtime. Nếu row Claude Code lỗi trước mutation còn row Codex báo updated, Codex đã được cập nhật; đừng mô tả toàn bộ lần cập nhật là thất bại.

Đừng coi hướng dẫn terminal chung về dung lượng disk hoặc quyền backup là root cause. Guidance hiện tại dùng classification đó cho mọi raw error chứa snapshot. Snapshot ID được in chứng minh ít nhất một capture trước đó đã thành công. Nó không chứng minh có partial write, và một capture sau vẫn có thể lỗi vì dung lượng, ACL hoặc security software, Claude path bị lock hoặc không đọc được, foreign-home refusal, hay lỗi snapshot-path khác.

Đọc local detail trước

Trong PowerShell, tìm row Claude Code lỗi và các marker liên quan trong local report mới nhất:

$report = Get-ChildItem "$env:USERPROFILE\.agentkit\support\update-report-*.md" |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 1

$report.FullName
Select-String -Path $report.FullName `
  -Pattern '^### engineer \[claude-code\]$','^- Detail:','^- Snapshot:'

Chỉ chia sẻ các dòng - Detail: và - Snapshot: liên quan. Hãy redact username, địa chỉ email, project path, token và diagnostics không liên quan. Khi chưa có raw - Detail:, hãy giữ nguyên trạng thái chưa xác định nguyên nhân.

Nếu cần thêm bằng chứng, các check sau chỉ đọc:

ak backups show <snapshot-id> --json
ak backups verify <snapshot-id>
ak doctor --json --offline
Get-PSDrive -Name C

Sửa đúng nguyên nhân rồi chỉ retry Claude Code

Giữ nguyên .agentkit, .claude và snapshot. Không bypass safety boundary bằng --no-backup.

Nếu path bị lock hoặc không đọc được, đóng Claude Code và process đang giữ path đó, sửa đúng readability hoặc quyền của chính path đó rồi retry.
Nếu detail báo hết dung lượng, giải phóng dung lượng trên volume chứa source và AgentKit backups.
Nếu detail là refusing foreign-home takeover, trước tiên xác nhận AgentKit thực sự nên sở hữu global Claude Code surface. Sau đó dùng đúng recovery command ak kit init engineer --global. Đây là quyết định ownership, không phải lỗi permissions.

Sau khi sửa nguyên nhân, chỉ retry runtime đã lỗi:

ak update --global --target claude-code --yes

Tại thời điểm behavior này được xác minh, 2.8.0-beta.8 là bản beta mới nhất. Trong phiên bản đó, detail refusing foreign-home takeover phải nhận guidance ownership trước mutation chuyên biệt ở trên. Nếu đúng detail đó lại nhận generic snapshot guidance, hãy giữ các dòng report đã redact và liên hệ support; coi đây là guidance regression, không phải bằng chứng lỗi snapshot hoặc permissions.

Cảnh báo Codex như preserving hook script ...cook-after-plan-reminder.cjs là một kết quả ownership-preservation riêng. Không dùng nó để chẩn đoán lỗi snapshot Claude Code.

Kiểm tra kết quả

ak --version
ak doctor --json
ak audit --project-dir . --json

Phiên bản CLI và báo cáo doctor xác nhận state của binary và môi trường. Audit ở đây kiểm tra nội dung Kit Claude Code project-native; dùng ak audit --json cho user plugin hoặc --plugin-mode --project-dir ./ak-engineer cho project plugin root được nêu. Thoát 0 là sạch và thoát 1 nghĩa là drift hoặc lỗi audit. Nhớ rằng doctor mặc định có thể báo không khỏe nhưng vẫn thoát 0; hãy kiểm tra data.healthy.

Kiểm tra recovery snapshot

Các đường cập nhật Kit project và global có mutation tạo recovery snapshot. Binary self-update dùng verified replacement. Dùng snapshot ID mà thao tác Kit lỗi đã in khi có:

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

list, show, verify và restore preview đều chỉ đọc. show hoặc verify thoát 5 nếu ID không tồn tại; verify thoát 1 nếu snapshot hỏng. Không restore snapshot không vượt qua xác minh.

Output cập nhật project có thể nói snapshot nằm ngoài scope của ak backups restore và in thư mục snapshot files. Khi đó, làm theo đường copy thủ công được in cho các tệp project bị ảnh hưởng; không cố mở rộng quyền restore hoặc restore state không liên quan.

Restore snapshot đã xác minh

Preview trước rồi xác nhận đúng ID:

ak backups restore <id> --dry-run
ak backups restore <id>

Nếu ak backups show <id> liệt kê project bundle root, chỉ authorize đúng các đường dẫn tuyệt đối đó bằng một --allow-root lặp lại cho mỗi root:

ak backups restore <id> --allow-root /absolute/project

Đường dẫn rộng hơn hoặc khác sẽ bị từ chối.

Chỉ dùng --latest sau khi ak backups list chứng minh snapshot mới nhất thuộc thao tác này. Mã thoát restore được phân loại:

Mã thoát	Ý nghĩa
`0`	Preview hoặc restore hoàn tất.
`1`	Lỗi xác minh, authority, I/O hoặc lỗi restore khác.
`2`	Argument không hợp lệ, ví dụ kết hợp ID với `--latest`.
`3`	Bạn từ chối xác nhận; không có gì được restore.
`4`	Một thao tác backup khác đang giữ lock.
`5`	Snapshot ID không hợp lệ hoặc không tồn tại, hoặc chưa có snapshot nào.

Restore theo kiểu replace-only: nó ghi đè tệp đã capture, xóa đúng path được ghi là không tồn tại cùng các cây AgentKit plugin được chấp thuận rõ ràng, và giữ các tệp không liên quan được tạo sau đó. Restore nhiều tệp không transactional, nên host failure có thể để lại state trung gian; tránh ngắt thao tác và tạo một backup phù hợp trước khi rollback khi có thể.

Sau restore, chạy lại ak --version, ak doctor --json và audit áp dụng được. Không xóa backup storage, runtime home hoặc ~/.agentkit; các hành động đó xóa bằng chứng và đường khôi phục bạn cần. Không dùng --force như cách thử lại cập nhật thông thường.