3.0.0-beta.15). Tính năng có thể thay đổi trước bản stable tiếp theo.Chuyển sang stable →ak kit
ak kit refresh
Đồng bộ lại route Kit đã cài, xoá đầu ra cũ còn clean và owned, đồng thời giữ thay đổi của người dùng.
Dùng ak kit refresh để tạo lại đầu ra cho Kit đã cài sau khi nội dung export
thay đổi. Refresh chỉ xoá tệp generated đã ngừng dùng khi AgentKit chứng minh
được chúng còn clean và owned; nội dung không xác định hoặc do người dùng sửa
được giữ nguyên.
Cú pháp
ak kit refresh <kit-name><kit-name> là bắt buộc. Lệnh này refresh route hiện có; hãy dùng
ak kit install khi chưa có route.
Trước khi chạy
Theo mặc định, lệnh resolve từ remote registry. Channel được resolve theo thứ
tự: --channel tường minh, rồi channel ghi trong install receipt của
destination, rồi kit.channel, rồi stable. --channel tường minh chỉ áp dụng
cho request này và không được lưu. Receipt mâu thuẫn tạo cảnh báo, chuyển sang
kit.channel và không bao giờ bị ghi đè. Kit trả phí cần phiên CLI hợp lệ và entitlement. Quá trình resolve có
thể làm mới xác thực đã lưu, liên hệ registry, tải artifact và cập nhật
verified cache trước khi bắt đầu ghi lifecycle.
ak whoami
ak licensesChỉ dùng --local --kits-dir <dir> cho nguồn development hoặc CI rõ ràng.
Refresh không có cờ dry-run. Hãy chạy ak audit trước nếu cần kiểm tra drift.
Grok Build và Pi là signed registry target cho refresh Kit thông thường. Chỉ
dùng --local --kits-dir <dir> khi bạn chủ động chọn source development hoặc
CI. AgentKit re-emit runtime file và lifecycle metadata cho target đã chọn;
runtime đó vẫn sở hữu authentication, model, trust, permission và sandbox
behavior.
Đối số
<kit-name> là Kit ID đã cài duy nhất cần đồng bộ lại. Đối số này bắt buộc; lệnh
không mở prompt để chọn Kit.
Lệnh không có alias.
Tuỳ chọn
| Tuỳ chọn | Mặc định | Tác động |
|---|---|---|
--channel <channel> | Channel trong receipt, rồi kit.channel, rồi stable | Chọn remote kit channel chỉ cho request này; giá trị không được lưu. |
-g, --global | false | Refresh route ở user scope thay cho project hiện tại. |
--kits-dir <dir> | Trống | Chọn nguồn Kit cục bộ rõ ràng. |
--local | false | Dùng nguồn cục bộ rõ ràng thay cho registry. |
--no-backup | false | Bỏ qua recovery snapshot trước khi refresh. |
--registry-url <url> | Biến môi trường hoặc mặc định bản phát hành | Ghi đè URL gốc của registry. |
--remote | true | Dùng remote registry có xác thực; không cần truyền rõ. |
--switch-to-plugin | false | Chọn Claude Code plugin delivery tại project hoặc user scope. |
--target <ids> | Các target đã cài được phát hiện | Chọn một hoặc nhiều emitter target phân tách bằng dấu phẩy, gồm grok và pi. |
--version <version> | Phiên bản mới nhất của channel | Chọn phiên bản Kit từ xa. |
Xem các cờ dùng chung tại quy ước CLI.
Resolve target, scope và mode
Khi không có --target, refresh đọc lifecycle marker trong scope đã chọn và
refresh mọi runtime đã cài mà nó phát hiện. Project scope phát hiện Claude Code project-native, Cursor trong project và đầu
ra project được nhận diện. User scope quét các user lifecycle target đã đăng ký.
Nếu không phát hiện target, lệnh thoát 6 và yêu cầu truyền --target hoặc cài
Kit trước. Với route Grok hoặc Pi, truyền --target grok hoặc --target pi khi detection còn mơ hồ;
remote registry resolution vẫn là mặc định trừ khi bạn chọn rõ
--local --kits-dir <dir>.
Refresh trong project bị từ chối với mã thoát 6 khi route của bất kỳ runtime
nào được chọn hoặc phát hiện trỏ vào bản cài cấp người dùng, chẳng hạn khi bạn
chạy lệnh từ thư mục home. Bước kiểm tra chạy một lần cho mọi runtime, trước mọi
lượt refresh theo runtime, lock, snapshot hay thao tác ghi. Dùng
ak kit refresh <kit> --global cho bản cài cấp người dùng.
Claude plugin delivery luôn phải được chọn rõ ràng:
# Claude project plugin.
ak kit refresh engineer --switch-to-plugin --yes
# Claude user plugin.
ak kit refresh engineer --global --switch-to-plugin --yesClaude plugin đã cài không bị âm thầm xem là đầu ra native, kể cả khi có target khác cùng tồn tại. Project scope và user scope vẫn độc lập.
Refresh nhiều runtime
Package Kit từ xa gắn với từng runtime. Khi một lần refresh từ xa bao gồm nhiều
runtime, dù được phát hiện hay liệt kê bằng --target, AgentKit refresh lần lượt
từng runtime. Mỗi runtime có lượt tải đã xác minh, preflight, preview xác nhận và
thao tác ghi có snapshot riêng. Nếu một runtime lỗi, chỉ thay đổi của runtime đó
được rollback và các runtime còn lại vẫn được refresh.
Sau runtime cuối cùng, lệnh in phần tổng hợp refresh với một dòng cho mỗi
runtime. Mọi runtime chưa được refresh đều có lệnh retry: để refresh riêng
runtime đó:
ak kit refresh <kit-name> [--global] --target <target> --yesLệnh retry lặp lại scope cùng các tuỳ chọn --channel, --version,
--registry-url, --no-backup, --switch-to-plugin và --yes của lần chạy
gốc. Hãy chạy nó sau khi đã xử lý lỗi được báo.
Từ chối preview của một runtime sẽ dừng vòng lặp: runtime đó được báo là
declined và các runtime sau là not_attempted. Interrupt cũng đánh dấu các
runtime còn lại là not_attempted. Runtime đã refresh xong vẫn giữ kết quả.
Refresh từ nguồn --local tường minh không dùng các lượt theo từng runtime này.
Ví dụ
# Tự phát hiện route project đã cài.
ak kit refresh engineer --yes
# Refresh tường minh một route Codex.
ak kit refresh engineer --target codex --yes
# Refresh rõ route Pi.
ak kit refresh engineer --target pi --yes
# Refresh từ nguồn development cục bộ tường minh.
ak kit refresh engineer --local --kits-dir ./kits --target codex --yes
# Refresh route Grok trong project từ nguồn cục bộ bắt buộc.
ak kit refresh engineer --local --kits-dir ./kits --target grok --yes
# Refresh unattended có chủ đích.
ak kit refresh engineer --target codex --yes --no-interactive --jsonHành vi xác nhận
Refresh dùng install destination preview và hỏi Continue? [y/N]: trên TTY
tương tác. Chỉ y hoặc yes mới tiếp tục.
--json, --no-interactive và stdin không phải TTY sẽ bỏ qua prompt và có
thể refresh khi thiếu --yes. Hãy thêm --yes trong tự động hoá để thể hiện
rõ thao tác ghi.
Từ chối trên TTY hiện thoát với mã 1, không phải 3.
Đầu ra và stream
Tiến trình, destination preview và xác nhận dành cho người dùng dùng stderr. Phần tổng hợp cuối dùng stdout. Nó báo Kit, route, số tệp, install mode, scope, kết quả Hook, cảnh báo, thay đổi được giữ lại và thông tin khôi phục.
Với --json, stdout dùng envelope có phiên bản kind=kit.init vì refresh dùng
lại result model của cài đặt. Dữ liệu gồm kit, target, targets tuỳ chọn,
mode, installMode, scope, outDir, filesWritten, success cùng các
trường Skill, Hook, warning, transition và snapshot tuỳ chọn. Trừ khi có
--quiet, stderr còn phát status record thô preview và complete với
action=install.
Lần refresh chạy một lượt cho mỗi runtime dùng envelope kind=kit.refresh thay
thế. Dữ liệu gồm kit và mảng targets[] với một phần tử cho mỗi runtime:
| Trường | Ý nghĩa |
|---|---|
target | ID runtime. |
status | refreshed, failed, declined hoặc not_attempted. |
error | Lý do lỗi khi status là failed. |
rerun | Lệnh retry cho riêng runtime đó, có ở mọi runtime chưa được refresh. |
result | Kết quả refresh của runtime khi status là refreshed, kèm warnings và notices bên cạnh. |
Mỗi runtime đã refresh cũng phát status record preview và complete riêng
trên stderr.
Dữ liệu projection Hook còn có thể chứa hooksDropped, droppedHookSummaries,
hookMatchersNarrowed và narrowedHookSummaries tùy chọn. Output cho người dùng
tách Hook groups not projected khỏi Hook matchers narrowed
(some tool matches unsupported on this target) rồi in warning tương ứng. Drop
hoặc narrow được báo vẫn là lần refresh thành công.
Lỗi trong chế độ JSON, kể cả lỗi phân tích cờ (mã thoát 2), kết thúc stderr
bằng error envelope dùng chung:
schema_version, error, error_code và exit_code.
Lỗi thực thi dành cho người dùng và JSON hiển thị lý do cần để khôi phục theo
mặc định, che các dạng bí mật đã biết và query string của URL, nhưng giữ đường
dẫn. --verbose có thể lộ lỗi gốc thô; hãy kiểm tra trước khi chia sẻ.
Mã thoát
| Mã | Ý nghĩa |
|---|---|
0 | Route đã chọn được đồng bộ thành công. |
1 | Lỗi validation, nguồn, xác thực, entitlement, mode, ownership, emission, snapshot, ghi dữ liệu hoặc từ chối trên TTY. Runtime hiện cũng dùng 1 cho phần lớn lỗi không tìm thấy Kit cục bộ và target không an toàn. Trong refresh theo từng runtime, 1 nghĩa là ít nhất một runtime lỗi hoặc chưa chạy, kể cả khi runtime khác đã refresh. |
2 | Cobra từ chối cờ, argument hoặc tổ hợp cờ. |
3 | Đường huỷ hoặc interrupt dùng chung trả về trạng thái huỷ. |
4 | Một thao tác vòng đời Kit khác đang giữ khoá. |
6 | Không phát hiện target đã cài trong scope đã chọn, hoặc route project trỏ vào bản cài cấp người dùng. |
Phần help dành mã 5 cho Kit cục bộ không tồn tại và mô tả mã 6 rộng hơn,
nhưng chỉ đường không phát hiện target và lỗi từ chối route cấp người dùng được
phân loại rõ là 6; đừng giả định
mọi lỗi nguồn hoặc ownership dùng mã dành sẵn trong help.
Tác động và an toàn khi xoá tệp cũ
Refresh dùng force re-emission path bên trong. Với --yes, lệnh xác minh yêu
cầu lifecycle update trước đường ghi có snapshot đó. Lệnh tạo snapshot cho bề mặt
owned bị ảnh hưởng trừ khi có --no-backup, ghi đầu ra hiện tại, cập nhật
lifecycle manifest và xoá đường dẫn cũ có hash đã ghi vẫn khớp dữ liệu trên đĩa.
- Đường dẫn cũ còn clean và owned có thể bị xoá.
- Đường dẫn hiện tại còn clean và owned có thể bị thay thế.
- Đường dẫn owned đã sửa được giữ lại và báo rõ.
- Tệp không xác định được giữ lại và không bị nhận vào ownership.
- Đường dẫn liên kết không an toàn và tập đầu ra dự kiến rỗng sẽ fail closed hoặc bị bỏ qua kèm cảnh báo thay vì gây xoá diện rộng.
Skill selection trước đó được giữ khi route refresh có selection metadata. Refresh không phải quyền xoá nội dung runtime tuỳ chỉnh.
Khôi phục và giới hạn
Giữ mọi snapshot được báo cho đến khi runtime tìm lại Kit đã refresh và một Skill đã cài hoạt động.
ak backups show <id>
ak backups verify <id>Dùng lệnh restore được báo khi snapshot nằm trong restore scope; nếu không, dùng thư mục khôi phục thủ công được báo. Khôi phục có giới hạn và restore nhiều tệp không được đảm bảo có tính giao dịch.
Codex không thể chiếu mọi Claude command, Hook matcher hoặc status-line feature.
Refresh Engineer có thể báo một full drop task-state cùng hai shared narrow;
Marketing có thể báo ba narrow và không có full drop. Atom được hỗ trợ vẫn hoạt
động. Trên Windows, refresh còn có thể phát .cmd shim
thuộc ownership của AgentKit cho đường dẫn Hook Codex .cjs đủ điều kiện nằm
trong Codex home và có khoảng trắng; đường dẫn bên ngoài hoặc không an toàn vẫn
được báo cảnh báo.
Với Hook Codex global, refresh chỉ follow alias ở leaf hooks cuối cùng tới
~/.codex/hooks canonical — symlink POSIX hoặc directory junction trên Windows
— và giữ command, thao tác ghi, rollback cùng ownership trên identity canonical
đó. Parent có link và target khác đều bị từ chối.
agy là target projection global, không phải peer trong lifecycle refresh cho
production. Hãy chạy lại route init/install global rõ ràng thay vì xem nó là
route đã cài mà refresh có thể phát hiện.
Lệnh liên quan
ak kit installcài route mới.ak kit uninstallpreview hoặc xoá route đã cài.ak kit validatekiểm tra authoring tree cục bộ.- Thông tin lệnh đầy đủ
- Cài và refresh Kit
- Xử lý sự cố cài Kit
hooksDeferred là tập con của hooksDropped: harness bridge chưa project được subscription này, không đồng nghĩa runtime không hỗ trợ. Đọc summary để phân biệt deferred và unsupported.