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 →Tham chiếu CLI
ak update
Xem trước hoặc áp dụng cập nhật dự án và kit toàn cục với backup nhận biết drift.
ak update làm mới tệp dự án thuộc quyền sở hữu của AgentKit hoặc bản cài kit toàn cục, đồng thời giữ nguyên nội dung do người dùng sở hữu.
Cú pháp
ak update [project-dir] [options]
ak update --global [options]Trước khi chạy
- Lần xem trước ngầm định không tương tác thoát với mã
3. Thêm--dry-runđể xem trước tường minh và thoát0, hoặc--yesđể áp dụng. - Lệnh trần trong TTY mở trình hướng dẫn hợp nhất. Mỗi cập nhật CLI, kit toàn cục và kit dự án mặc định là không;
--yeschấp nhận các bước phù hợp. - Lần xem trước từ xa vẫn có thể xác thực, kiểm tra quyền sử dụng, tải nội dung kit và cập nhật cache trước khi tính kế hoạch.
--forcechỉ cho phép thay thế sau snapshot trừ khi có--no-backup. Tùy chọn này không biến cài đặt toàn cục thành ghi đè vô điều kiện.--json,--quiet,--no-interactivehoặc môi trường không phải TTY chọn hành vi cho script. Trong lần chạy dự án hoặc toàn cục có tương tác, từ chối mọi lời nhắc sẽ thoát0.- Cập nhật dự án có người xác nhận (chấp nhận trong TTY hoặc
--yes) refresh câykits/được theo dõi, rồi refresh mọi runtime đã cài của từng kit dự án. Xem Refresh runtime của dự án.
Đối số
[project-dir] chọn một project. Nếu bỏ qua, chế độ project tìm project hiện tại trừ khi đặt --global. Lệnh không có alias.
Target runtime và nguồn
Việc xác minh target dùng cả scope và nguồn đã chọn:
| Scope và nguồn | Target hợp lệ |
|---|---|
| Project, remote | claude-code, codex, cursor, dsh, grok, omp hoặc pi |
| Global, remote | claude-code, codex, cursor, dsh, grok hoặc omp |
| Global, local | claude-code, codex, cursor, dsh, grok hoặc omp |
Target tường minh không áp dụng cho scope hoặc nguồn sẽ bị từ chối trước
discovery hay mutation và trả mã 2. Trong wizard hợp nhất, cùng lựa chọn đó
được chiếu lên từng bước: target chỉ dành cho project như pi bị bỏ qua ở bước
global nhưng vẫn khả dụng cho bước project. 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.
Ở cả hai scope, --target a,b lọc những runtime đã cài sẽ được refresh; nếu bỏ
trống thì refresh mọi runtime đã cài. Runtime được yêu cầu nhưng chưa có bản cài
trong scope đó được liệt kê trong skipped_targets thay vì được tạo mới. Ở
project scope, cây kits/ được theo dõi vẫn lấy từ bản tải của một runtime:
claude-code khi runtime này được chọn, đã cài, hoặc khi không chọn runtime nào;
nếu không thì lấy runtime đầu tiên được chọn.
Refresh runtime của dự án
Sau cây kits/ được theo dõi, cập nhật dự án có người xác nhận refresh mọi
runtime đã cài của từng kit dự án (.claude, .codex và adapter root) qua cùng
đường dẫn với ak kit refresh, mỗi lượt cho một cặp kit và
runtime. Danh sách kit được xét là --kits khi có, nếu không thì gồm các kit
được theo dõi trong kits/ cộng mọi kit có bản cài dự án thuộc quyền sở hữu.
- Một lượt thất bại không dừng các lượt khác. Mỗi lượt báo một dòng riêng, và
lệnh thoát
1sau khi mọi lượt hoàn tất. - Dự án chỉ có bản cài runtime từ
ak kit init, không có câykits/được theo dõi, sẽ được refresh các bản cài đó thay vì thoát2. - Xem trước và
--dry-runliệt kê từng refresh dự kiến thành một dòngpreviewvà không ghi gì. - Bước kiểm tra CLI trước khi chạy lấy yêu cầu CLI cao nhất của kit trong các runtime đã chọn.
- Bản cài Claude Code dạng plugin của dự án được báo là
plugin_only, không bị chuyển đổi. Refresh nó bằngak kit refresh <kit> --target claude-code --switch-to-plugin --yes. - Runtime mà nguồn remote không phục vụ được bỏ qua với reason
source_inapplicable; chạy lại với--local --kits-dir <dir>. - Khi thư mục dự án trỏ tới bản cài cấp người dùng (ví dụ thư mục home), runtime
đó được bỏ qua với reason
project_is_global_homevà không bao giờ được refresh. Chạyak update --globalđể refresh nó. - Nếu
--targetkhông khớp runtime dự án nào đã cài và không có câykits/được theo dõi, lệnh thoát2.
Cập nhật nền tự động (opt-in)
--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; --schedule off dừng và
xóa state. Nó refresh CLI và kit global, cộng thêm mọi project đã opt-in bằng
--project <dir> (lặp lại được; thư mục phải đã đă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 của project. Thay vào đó nó ghi một thông báo hướng dẫn
chạy ak update <dir> --yes hoặc ak kit refresh <kit>.
--no-project <dir> (lặp lại được) đưa một project ra khỏi danh sách, kể cả
khi thư mục đó không còn tồn tại. --status [--json] báo schedule và kết quả
nền gần nhất mà không đổi gì; thêm --ack để đánh dấu kết quả đó đã xem.
Các cờ settings này chỉ ghi section auto_update: trong
~/.agentkit/config.yaml — không cập nhật gì ngay, và không cờ nào trong số
--schedule, --project, --no-project, --status, --ack được kết hợp với
cờ cập nhật (--kits, --force, --global, …) hoặc đối số project-dir; hãy
chạy chúng như các lệnh riêng.
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 top-level command thuộc lifecycle/interactive
(update, self-update, setup, onboard, kit, init, migrate,
backups, recover, gui, uninstall, completion, help, bootstrap*).
Liveness được theo dõi bởi Kit hook (session-heartbeat.cjs) đăng ký trên
SessionStart, UserPromptSubmit, Stop và SessionEnd; hook ghi một marker
theo session dưới AgentKit home để updater bỏ qua project đang có session
chạy, và không bao giờ chặn hay làm hỏng session (tự thoát 0 khi lỗi). Tại
SessionStart, kết quả nền chưa được xem sẽ in thành một dòng thông báo; xác
nhận bằng ak update --status --ack --json. Xem check auto_update của
ak doctor để chẩn đoán schedule, run bị kẹt và project đã opt-in.
Tùy chọn
| Tùy chọn | Mặc định | Mục đích |
|---|---|---|
--ack | false | Cùng --status: đánh dấu kết quả cập nhật nền gần nhất đã xem. |
--backup | false | Snapshot toàn bộ project, không chỉ tệp mà refresh thay đổi; backups.enabled: true trong ~/.agentkit/config.yaml làm đây thành mặc định. |
--beta | false | Bao gồm hành vi tự cập nhật CLI beta. |
--channel <channel> | Channel trong receipt, rồi kit.channel, rồi stable | Chọn kênh kit chỉ cho request này; giá trị không được lưu. |
--dry-run | false | Xem trước mà không ghi bản cài dự án hoặc toàn cục. |
--force | false | Cho phép thay thế drift sau backup trừ khi có --no-backup. |
-g, --global | false | Cập nhật bản cài kit toàn cục. |
--kits <names> | Trống | Giới hạn danh sách kit phân tách bằng dấu phẩy. |
--kits-dir <path> | Trống | Đọc kit từ thư mục cục bộ. |
--local | false | Dùng nguồn kit cục bộ. |
--no-backup | false | Bỏ qua recovery snapshot trước khi cập nhật, kể cả snapshot mà --force tạo (chỉ dành cho power user — rủi ro mất dữ liệu). |
--no-project <dir> | Trống | Gỡ một project khỏi cập nhật nền, kể cả khi thư mục đã mất (lặp lại được). |
--project <dir> | Trống | Opt-in một project đã đăng ký qua ak projects add vào cập nhật nền (lặp lại được). |
--registry-url <url> | Trống | Ghi đè URL registry. |
--remote | true | Dùng registry từ xa. |
--runtime <runtime> | claude-code | Alias của --target; chọn runtime từ ma trận scope và nguồn bên trên. Giá trị mặc định không được tính là lựa chọn tường minh. |
--schedule <daily|weekly|off> | Trống | Đặt hoặc xóa schedule cập nhật nền (chỉ settings; không cập nhật gì ngay). |
--show-diff | false | Bao gồm diff tệp trong kế hoạch. |
--status | false | Hiện schedule cập nhật nền và kết quả gần nhất (chỉ đọc). |
--target <target> | Trống | Các runtime phân tách bằng dấu phẩy từ ma trận scope và nguồn bên trên; bỏ trống nghĩa là mọi runtime đã cài. Chỉ truyền một trong hai cờ --target hoặc --runtime. |
--version <version> | Trống | Ghim phiên bản kit. |
Ví dụ
Xem trước cập nhật dự án với trạng thái xem trước thành công:
ak update . --dry-run --show-diffÁp dụng cập nhật dự án mà không hỏi:
ak update . --yesChỉ refresh bản cài Claude Code và Codex của một dự án:
ak update . --target claude-code,codex --yesXem trước cập nhật toàn cục:
ak update --global --dry-run --kits core --runtime claude-code
ak update --global --dry-run --kits core --local --kits-dir ./kits --target grokBật cập nhật nền và kiểm tra status:
ak update --schedule daily --project .
ak update --status --jsonĐầu ra và luồng
Với --json, stdout dùng envelope chung có "kind": "update". data của dự án gồm project_dir, files_updated, files_skipped, files_new và dry_run; nó cũng có thể gồm các trường snapshot, backup_skipped, skipped, diffs, project_config, project_config_created và scope. Khi dự án có bản cài runtime, nó còn gồm
kits (một dòng cho mỗi lượt kit và runtime) và skipped_targets (runtime được
yêu cầu nhưng chưa có bản cài dự án).
Đầu ra global còn có locations, kits và skipped_targets. Mỗi kết quả Kit có thể báo cáo kit, runtime, status, channel, reason, error, why, next, các trường snapshot, locations và warnings. Envelope global cũng có thể báo backup_skipped. Runtime đã chọn nhưng chưa cài global được báo là bỏ qua thay vì được tạo mới.
Lần chạy remote global không có bộ lọc có thể discover một bản cài hiện có chỉ
dùng nguồn local. Lệnh báo bản cài đó bằng status: "skipped" và
reason: "source_inapplicable" thay vì ngầm đổi nguồn. Hãy làm theo hướng dẫn
next và chạy ak update --global --local --kits-dir <dir> để refresh từ nguồn
local tường minh. Target tường minh không tương thích với nguồn là lỗi xác minh trả mã
2, không phải kết quả source_inapplicable.
Lần xem trước JSON ngầm định in envelope thành công ra stdout rồi thoát 3. Lỗi lệnh, kể cả lỗi phân tích cờ (mã thoát 2), ghi
error envelope dùng chung ra stderr.
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 mà
không cần --verbose. Lỗi được hiển thị 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. Kết quả Kit global hoàn tất
kèm mục cần chú ý cũng hiển thị lý do đã che trong output dành cho người dùng
mà không cần --verbose; điều này không biến kết quả đó thành cập nhật thất bại.
--verbose có thể lộ lỗi thực thi thô và toàn bộ danh sách warning. Hãy kiểm
tra chẩn đoán trước khi chia sẻ.
Trạng thái thoát
| Mã | Ý nghĩa |
|---|---|
0 | Đã áp dụng cập nhật, hoàn tất dry-run tường minh hoặc từ chối lời nhắc tương tác. |
1 | Runtime, vòng đời, nguồn, snapshot, ghi, cập nhật toàn cục một phần hoặc một lượt refresh runtime của dự án thất bại; với auto-update settings và --status --ack, còn tính lỗi I/O hoặc state file đang bận. |
2 | Flag, scope, nguồn, target hoặc lựa chọn bản cài global đủ điều kiện không hợp lệ; ở project scope, không có kit được theo dõi và không có bản cài runtime, hoặc --target không khớp bản cài runtime nào của dự án; với auto-update settings, còn tính --schedule không hợp lệ, --project chưa đăng ký, hoặc cờ settings kết hợp với cờ cập nhật hay đối số project-dir. |
3 | Lần xem trước ngầm định không tương tác cần --yes để áp dụng. |
Tác động, an toàn và khôi phục
Cập nhật dự án phân loại tệp thuộc quyền sở hữu. Tệp sạch có thể được thay thế; tệp đã sửa hoặc vị trí mới bị chiếm được bỏ qua trừ khi dùng --force. Apply cũng prune các tệp AgentKit sở hữu dưới kits/<id>/ mà source tới không còn ship, và chỉ với kit có trong incoming set. Bản sạch và bản đã missing bị xóa; bản user đã sửa được giữ và báo cáo trừ khi có --force. Path không còn là regular file được để nguyên. Directory trống còn lại trong kit tree bị xóa; kit root thì không.
Theo mặc định, apply chỉ snapshot đúng những tệp nó ghi hoặc prune — một bundle có thể restore, được authorize theo project root (--allow-root), và kết quả gồm cả lệnh restore. --force, --backup, hoặc backups.enabled: true trong ~/.agentkit/config.yaml thay vào đó capture toàn bộ project; --backup không mở rộng snapshot của global kit refresh. --no-backup bỏ qua mọi snapshot, kể cả snapshot mà --force tạo, và cảnh báo trên stderr; --force --no-backup thêm cảnh báo nghiêm trọng hơn. Kết quả có cấu trúc báo backup_skipped nên snapshot_id trống chưa đủ để phân biệt skip chủ ý với lần chạy không có gì để capture. Desktop plan apply giữ nội dung người dùng dùng cùng cơ chế exact-file capture đó trừ khi nội dung người dùng bị ghi đè hoặc có backups.enabled, khi đó nó capture toàn bộ project; nó không nhận --no-backup. Một số tệp ngoài phạm vi khôi phục cần được phục hồi thủ công; làm theo snapshot_data_dir khi được báo cáo. Cấu hình dự án còn thiếu có thể được tạo trước bước phân loại và snapshot, ngay cả khi bước sau thất bại.
Các tệp được ghi tuần tự nên lỗi có thể để lại cập nhật một phần. Cập nhật toàn cục tiếp tục qua các kit, báo cáo lỗi theo kit và có thể tạo gói hỗ trợ trong ~/.agentkit/support. Chế độ force toàn cục có thể lưu trữ các Skill Codex cũ được cho phép, nhưng vẫn giữ nguyên sửa đổi của người dùng. --force ở project không bao giờ lưu trữ các Skill Codex cũ của ClaudeKit: lượt refresh runtime của dự án gặp chúng sẽ báo một dòng bỏ qua với reason needs_legacy_migration. Chạy ak migrate --from ck từ thư mục dự án, rồi chạy lại cập nhật. Việc lưu trữ qua --force vẫn chỉ là sự đồng ý của --global --force.
Trên Windows, ak update thay CLI đã ký 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 gốc trong Windows Job Object để 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.
Lệnh liên quan và giới hạn
Dùng ak new cho project mới và ak uninstall để xóa file thuộc quyền sở hữu. Sau lỗi một phần, ak doctor chỉ có thể lọc doctor suite riêng cho claude-code, codex và cursor; mọi giá trị --adapter khác đều không hợp lệ và trả mã 2. Xem quy ước CLI về flag dùng chung.