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 dùng --channel, rồi updates.channel đã lưu, rồi kênh của binary phát hành đang chạy, rồi stable, 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, phạm vi hoặc nguồn không hợp lệ trả 2.

Trên Windows, cổng CLI đó thay binary tại chỗ dưới update lock độc quyền, kiểm tra preimage của binary đang chạy, rồi re-execute lệnh ak update gốc để Kit refresh tiếp tục ngay lần gọi đầu. ak self-update độc lập vẫn dùng staged detached helper. Paired Desktop apply stage các artifact CLI và Desktop khớp nhau, rồi helper đáng tin cậy commit thao tác thay thế sau khi process cha nhả các executable.

Wizard chiếu một lựa chọn --target lên từng bước. Ví dụ, pi vẫn hợp lệ cho bước project nhưng bị bỏ qua ở bước Kit global; nếu không target nào đã chọn áp dụng được ở global scope, wizard bỏ qua bước đó rồi tiếp tục. Target tường minh không áp dụng cho scope và nguồn đã chọn sẽ bị từ chối trước discovery hoặc mutation.

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

Sau cây kits/ được theo dõi, cập nhật project khi áp dụng còn refresh mọi runtime đã cài của từng Kit trong project (.claude, .codex và adapter root), mỗi lượt cho một cặp Kit và runtime. Project chỉ có bản cài runtime từ ak kit init sẽ được refresh các bản cài đó. Bản xem trước và --dry-run liệt kê các refresh runtime dự kiến mà không ghi gì. Một lượt thất bại không dừng các lượt khác, và lệnh trả mã thoát 1 ở cuối. Thu hẹp runtime bằng --target:

ak update . --target claude-code,codex --yes

Runtime được yêu cầu nhưng chưa có bản cài trong project được báo trong skipped_targets. Thư mục project trỏ tới bản cài cấp người dùng, như thư mục home, sẽ bỏ qua refresh runtime và hướng dẫn chạy ak update --global. --force ở project không lưu trữ các Skill Codex cũ của ClaudeKit; việc đó vẫn thuộc ak update --global --force hoặc ak migrate --from ck. Xem Refresh runtime của dự án.

Theo mặc định, cập nhật project áp dụng chỉ snapshot đúng những tệp nó ghi hoặc prune — một bundle có thể restore, và kết quả gồm cả lệnh restore. --force, --backup, hoặc backups.enabled: true trong ~/.agentkit/config.yaml capture toàn bộ project thay vào đó; --no-backup bỏ qua hoàn toàn snapshot, kể cả snapshot mà --force tạo. 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.

Để biết khi nào mỗi lệnh lifecycle tự động snapshot và cách backups.scope giới hạn phần capture ~/.claude/, xem ak backups.

Cập nhật nền tự động (opt-in)

ak update --schedule daily|weekly bật cập nhật nền tách rời, khởi động ở lệnh ak thông thường đầu tiên sau khoảng thời gian đã chọn, refresh CLI và kit global cộng thêm mọi project đã opt-in bằng --project <dir> (đã đăng ký qua ak projects add) có git tree sạch và không có agent session đang chạy. Cập nhật nền cho project chỉ refresh cây kits/ được theo dõi; nó không bao giờ refresh bản cài runtime và ghi một thông báo hướng dẫn chạy ak update <dir> --yes:

ak update --schedule daily --project .
ak update --status --json
ak update --schedule off

Các cờ settings (--schedule, --project, --no-project, --status, --ack) chỉ đổi auto_update: trong ~/.agentkit/config.yaml hoặc đọc state; chúng không bao giờ tự áp dụng cập nhật và không thể kết hợp với cờ cập nhật hay đối số project-dir. Cập nhật nền không bao giờ khởi động khi có AK_NO_AUTO_UPDATE=1 hoặc CI, với lệnh gọi --json, hoặc với lệnh thuộc lifecycle/interactive như update, init hay kit. Một Kit hook (session-heartbeat.cjs) đánh dấu project đang có session sống để updater bỏ qua; kết quả chưa xem in một lần ở SessionStart tiếp theo và có thể xác nhận bằng ak update --status --ack --json. Xem tham chiếu ak update và check auto_update của ak doctor để biết chi tiết.

Lần chạy nền dùng release channel từ updates.channel; khoá auto_update: chỉ chứa lịch chạy và các project đã opt-in. Project có thay đổi chưa commit hoặc có agent session đang chạy sẽ không được cập nhật; nó ở trạng thái chờ và được thử lại ở lần chạy đến hạn tiếp theo. Project không phải git repository sẽ bị bỏ qua. Kit global vẫn được cập nhật bất kể có agent session đang chạy hay không, giống như khi chạy ak update --global tương tác.

Mỗi kết quả chạy nền chỉ hiển thị một lần: dưới dạng tóm tắt một dòng trên stderr của lệnh ak tương tác tiếp theo, hoặc qua thông báo lúc session bắt đầu, tuỳ cái nào đến trước. ak update --status vẫn tiếp tục hiển thị kết quả, và check Auto-update của ak doctor báo lịch chạy, kết quả gần nhất, lần chạy bị kẹt hoặc quá hạn, và các project đã opt-in nhưng không còn cập nhật được.

Việc phát hiện session phụ thuộc vào các event mà runtime gửi tới Hook session-heartbeat.cjs:

• Codex không có event SessionEnd, nên marker session của nó chỉ hết hạn sau thời gian sống (TTL).
• Pi chạy Hook khi session bắt đầu, khi gửi prompt và khi dừng, nhưng hoãn SessionEnd; marker của nó cũng hết hạn theo TTL.

Kiểm tra git tree sạch vẫn bảo vệ thay đổi chưa commit khi một session không được phát hiện.

Trên Windows, lần chạy nền phải tách khỏi job object của terminal. Khi job đó cấm breakaway, AgentKit không khởi động lần chạy bên trong job; nó ghi nhận lần chạy là deferred (spawn_in_job) và thử lại sau.

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. Tính hợp lệ của target phụ thuộc cả scope và nguồn: cập nhật project từ remote chấp nhận bất kỳ runtime nào trong claude-code, codex, cursor, dsh, grok, omp hoặc pi; cập nhật global từ remote chấp nhận claude-code, codex, cursor, dsh, grok hoặc omp; cập nhật global từ local cũng chấp nhận tập đó. Dùng --target hoặc alias --runtime, nhưng chỉ truyền một tên flag. Target tường minh không áp dụng cho scope và nguồn đã chọn sẽ bị từ chối trước discovery hoặc mutation.

Runtime đã chọn nhưng chưa cài global được báo là bỏ qua thay vì được tạo mới. Trong lần chạy remote --global không có bộ lọc, bản cài chỉ dùng nguồn local vẫn xuất hiện dưới dạng kết quả bỏ qua với reason source_inapplicable; lệnh không ngầm refresh từ nguồn khác. Hãy làm theo hướng dẫn next và chạy ak update --global --local --kits-dir <dir>. Phân biệt giữa bản xem trước ngầm định trả 3 và dry run tường minh trả 0 cũng áp dụng ở global scope.

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.

Khi lọc chẩn đoán tiếp theo, ak doctor --adapter chỉ chấp nhận claude-code, codex và cursor, là các adapter có doctor suite riêng. Mọi giá trị adapter khác đều không hợp lệ và trả mã 2 thay vì trả về tập kiểm tra rỗng nhưng thành công.

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