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 install
Cài Kit vào runtime, scope và delivery mode rõ ràng với đầu ra cùng đường khôi phục đã được rà soát.
Dùng ak kit install để resolve một Kit rồi tạo đầu ra cho runtime hoặc thư mục
build. Đây là entry point hướng đến thao tác cài, dùng cùng implementation với
ak kit init.
Cú pháp
ak kit install <kit-name><kit-name> là một Kit ID có thể cài. Trên TTY tương tác, bỏ trống giá trị này
có thể mở setup wizard; lần gọi từ script thiếu giá trị sẽ thất bại.
Trước khi chạy
Kit đã phát hành được resolve từ remote registry đã xác thực theo mặc định. Với
ví dụ remote, hãy thay <channel> bằng kênh phát hành đang chọn trên header tài
liệu. Nếu bỏ --channel, CLI chọn stable; Kit trả phí cần session CLI hợp lệ
và entitlement trước preview hoặc ghi dữ liệu.
ak whoami
ak licensesQuá trình resolve từ xa có thể liên hệ registry, làm mới xác thực đã lưu, tải artifact dành cho runtime và ghi verified cache. Cache đã xác minh đầy đủ có thể xử lý một số lỗi offline, nhưng lỗi từ chối entitlement rõ ràng không fallback sang cache.
Chỉ dùng --local --kits-dir <dir> cho nguồn development hoặc CI có chủ đích.
Grok Build là signed registry target cho cài 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 emit runtime file và lifecycle metadata cho Grok; Grok vẫn sở hữu
authentication, model, trust, permission và sandbox behavior.
Đối số
<kit-name> là Kit ID có thể cài đặt duy nhất. Đối số này bắt buộc khi chạy
script hoặc non-interactive; TTY tương tác có thể mở setup wizard khi bỏ qua.
Lệnh không có alias.
Tuỳ chọn
| Tuỳ chọn | Mặc định | Tác động |
|---|---|---|
--accept-risks <token> | Trống | Cùng --fresh, chấp nhận đúng các rủi ro an toàn mà kế hoạch trước đã liệt kê, bằng token đã in ra. |
--beta | false | Viết tắt của --channel beta. |
--build-only | false | Build vào thư mục đầu ra cục bộ thay vì cài. |
--channel <channel> | stable | Chọn remote kit channel. |
--exclude-skills <names> | Trống | Cài mọi Skill ngoại trừ tập phân tách bằng dấu phẩy. |
--force | false | Cho phép ghi đè có giới hạn lên target đã có dữ liệu. |
--fresh | false | Đặt lại một install target đã chọn về chỉ còn đầu ra của Kit sau khi xác nhận và có snapshot đã xác minh. Không dùng cùng --force, --no-backup, --build-only hoặc --out. |
-g, --global | false | Dùng user scope của runtime 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 snapshot trước khi cài và bảo vệ takeover khi áp dụng. |
--out <dir> | Trống | Đặt thư mục gốc cho build hoặc export. |
--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õ cờ này. |
--select-skills | false | Chọn Skill tương tác; cần TTY. |
--skills <names> | Trống | Chỉ cài tập Skill phân tách bằng dấu phẩy. |
--switch-to-plugin | false | Chọn Claude Code plugin delivery tại scope đã chọn. |
--target <ids> | claude-code | Chọn một hoặc nhiều emitter target phân tách bằng dấu phẩy, gồm dsh, grok và pi; command facts sinh tự động có thể chậm hơn target projection Kit mới đăng ký. |
--version <version> | Phiên bản mới nhất của channel | Chọn phiên bản Kit từ xa. |
--zip | false | Với --target portable, ghi thêm một ZIP có thể upload cho mỗi Skill. |
--skills, --exclude-skills và --select-skills là các chế độ lựa chọn thay
thế nhau. --out cần --build-only với production target. Export-only target
như portable ngầm bật build mode khi có --out. Xem các cờ dùng chung tại
quy ước CLI.
Chọn route
| Route | Selector | Destination chính |
|---|---|---|
| Claude Code native trong project | --target claude-code | Các bề mặt .claude của project cùng lifecycle metadata trong .agentkit. |
| Claude Code native của user | --target claude-code --global | Các bề mặt Claude của user cùng lifecycle data của AgentKit. |
| Claude plugin trong project | --target claude-code --switch-to-plugin | Plugin ak-<kit> trong project. |
| Claude plugin của user | --target claude-code --global --switch-to-plugin | ak-<kit> dưới user plugin root đã cấu hình. |
| Codex trong project hoặc user | --target codex cùng --global nếu cần | Các bề mặt .agents và .codex trong project hoặc user. |
| Cursor trong project hoặc user | --target cursor cùng --global nếu cần | Các bề mặt .cursor trong project hoặc user. |
| DeepSeek Harness trong project hoặc user | --target dsh cùng --global nếu cần | .dsh/skills/ trong project hoặc ${DSH_HOME:-~/.dsh}/skills/ cùng lifecycle metadata. |
| Grok Build trong project hoặc user | --target grok cùng --global nếu cần | .grok trong project hoặc $GROK_HOME (mặc định ~/.grok) cùng lifecycle metadata. |
| Pi trong project hoặc user | --target pi cùng --global nếu cần | .pi/{skills,agents,rules,extensions} trong project hoặc profile Pi coding-agent đang hoạt động. |
| Oh My Pi trong project hoặc user | --target omp cùng --global nếu cần | Skill portable ak-<slug> dưới .omp/skills của project hoặc root profile OMP đã phân giải, cùng các bề mặt OMP tương ứng. |
| AGY của user | --target agy --global | Skill Gemini/AGY global cùng Agent tùy chọn dưới ~/.gemini/config/agents/<name>/agent.md, projection từ package remote claude-code đã ký với frontmatter tương thích runtime. |
| Build hoặc export | --build-only --out <dir> hoặc --target portable --out <dir> | Thư mục đầu ra đã chọn. |
Bản cài project từ chối route trỏ vào bản cài cấp người dùng, chẳng hạn thư mục
project chính là thư mục home của bạn, .agentkit của project chính là AgentKit
home, hoặc .claude, .codex hay Pi extension của project trùng với root cấp
người dùng tương ứng. Bước kiểm tra áp dụng cho mọi target đã chọn, chạy trước
mọi bộ chọn Skill, preview, lock, snapshot hay thao tác ghi, và thoát 6. Chạy
lại với --global để quản lý bản cài cấp người dùng, hoặc chạy từ một thư mục
project khác. Route build và export không bị kiểm tra.
Bản cài trong project và user có thể cùng tồn tại. Claude native và plugin là hai delivery mode riêng trong một scope; chuyển mode là thao tác rõ ràng, có snapshot bảo vệ.
portable chỉ để export. Thiếu --out, install dùng chung early exit 1 của
implementation init trước preview, prompt, phân giải source, lifecycle hoặc ghi
đĩa:
init: target "portable" is export-only and has no install mode; re-run with --out DIR to export a standalone build--out ngầm chọn build mode và giữ source mặc định từ remote. Dùng rõ
--build-only --out chọn source mặc định cho local development. Thêm --zip khi
portable export cũng cần tạo một ZIP có thể upload cho mỗi Skill. AGY chỉ hỗ trợ
global và không phải peer trong lifecycle refresh.
Vì install dùng implementation của init, hành vi OMP là tương đương. Thư mục
Skill đã projection và tên top-level trong SKILL.md dùng ak-<slug>, còn alias
trong body như /ak:cook, $ak:cook và selector ak run <kit>/<skill> --target omp được giữ nguyên. OMP trong project đã trust cũng
discover .agents/skills của project: .omp/skills của project che bản
.agents/skills xung đột với bản cài project, còn .agents/skills của project
che bản trong profile OMP khi dùng bản cài global từ project đó. Lệnh cảnh báo
rồi tiếp tục; lệnh không bỏ qua emission OMP, xóa hoặc viết lại Skill, thay đổi
.agents hay setting OMP, yêu cầu --force hoặc trả exit 6.
Ví dụ
# Cài Codex project-native từ nguồn release.
ak kit install engineer --target codex --channel <channel>
ak kit install engineer --target pi --channel <channel>
# Cài Claude user plugin một cách tường minh.
ak kit install engineer --target claude-code --global --switch-to-plugin --channel <channel>
# Cài unattended có chủ đích.
ak kit install engineer --target codex --yes --no-interactive --json --channel <channel>
# Nguồn development cục bộ với tập Skill đã chọn.
ak kit install engineer --local --kits-dir ./kits --skills ak-cook,ak-plan --yes
# Cài Grok trong project từ nguồn local development rõ ràng.
ak kit install engineer --local --kits-dir ./kits --target grok --yes
# Portable export với một ZIP có thể upload cho mỗi Skill.
ak kit install engineer --target portable --out ./ak-export --zipHành vi xác nhận
Trên TTY tương tác, install mode preview destination rồi hỏi
Continue? [y/N]:. 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ể ghi dữ liệu khi thiếu --yes. Trong tự động hoá, hãy dùng --yes để thể
hiện rõ chủ đích thay đổi. --fresh là ngoại lệ: lần chạy bằng script thiếu
--yes sẽ dừng với mã 3.
Từ chối trên TTY hiện thoát với mã 1. Route build và export không hiển thị
install preview.
Đầ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 và báo Kit, đường dẫn đầu ra, số tệp, install mode, scope, tổng hợp Hook, cảnh báo cùng thông tin khôi phục khi có.
Với --json, stdout chứa envelope có phiên bản với kind=kit.init và dữ liệu
lệnh dưới data. Trừ khi có --quiet, stderr còn chứa các status record thô
với action, kit, destination và status; status là preview trước khi
ghi và complete sau khi thành công.
Dữ liệu thành công gồm kit, target, targets tuỳ chọn, mode,
installMode, scope, outDir, filesWritten, success cùng các trường Skill,
Hook, warning, transition, configuration và recovery tuỳ chọn. 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ẻ.
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: <count> group(s) - see warnings khỏi Hook matchers narrowed (some tool matches unsupported on this target): <count> matcher(s) - see warnings. Drop hoặc narrow được báo không làm
quá trình cài thất bại.
Mã thoát
| Mã | Ý nghĩa |
|---|---|
0 | Install, build hoặc export đã chọn hoàn tất. |
1 | Lỗi validation, nguồn, xác thực, entitlement, destination, emission, ghi dữ liệu hoặc từ chối trên TTY. Runtime hiện cũng dùng 1 khi không tìm thấy Kit cục bộ hoặc target đã có dữ liệu. |
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ỷ, hoặc lần đặt lại --fresh không chạy vì cần xác nhận hoặc cần chấp nhận các rủi ro đã liệt kê. |
4 | Một thao tác vòng đời Kit khác đang giữ khoá. |
6 | Route project trỏ vào bản cài cấp người dùng; chạy lại với --global hoặc từ thư mục project khác. |
Phần help dành mã 5 cho Kit cục bộ không tồn tại và 6 cho target đã có dữ
liệu, nhưng hai lỗi install này hiện rơi về mã 1. Chỉ lỗi từ chối route cấp
người dùng được phân loại là 6; đừng rẽ nhánh theo 5 hoặc 6 cho các trường
hợp khác cho đến khi runtime thay đổi cách phân loại.
Tác động, an toàn và khôi phục
Quá trình cài có thể ghi tệp native của runtime, ownership và lifecycle metadata, cấu hình project, Hook script, thư mục Skill, trạng thái chuyển mode cùng cấu hình runtime của user. Bản cài Codex ở user scope có thể đăng ký AgentKit MCP runtime.
Tệp không xác định và tệp do người dùng sửa được giữ nguyên, trừ khi thao tác hỗ
trợ và --force cho phép ghi đè có giới hạn. AgentKit thường tạo snapshot cho
bề mặt owned bị ảnh hưởng trước khi buộc ghi đè hoặc chuyển mode. Một số snapshot
có thể dùng với ak backups restore; đầu ra project-local có thể chỉ báo thư mục
dữ liệu snapshot thủ công nằm ngoài restore scope thông thường.
ak backups show <id>
ak backups verify <id>--fresh đặt lại một target đã chọn về chỉ còn đầu ra của Kit: lệnh xoá tệp tuỳ
chỉnh và tệp chưa ghi nhận trong lifecycle root riêng của Kit sau một lần xác
nhận và một snapshot đã xác minh, khác với --force vốn giữ lại các tệp đó. Kế
hoạch, cách đồng ý, risk token, các trường hợp bị từ chối và đầu ra khôi phục
giống như
ak kit init --fresh.
Hãy làm theo lệnh khôi phục hoặc đường dẫn thủ công được báo. Không xoá toàn bộ runtime home hoặc giả định mọi snapshot là backup toàn phần hay có tính giao dịch.
Giới hạn và lệnh liên quan
Codex không thể chiếu mọi Claude command, Hook matcher hoặc status-line feature.
Hãy xem cảnh báo sau một lần cài thành công. Engineer projection một group
task-state PostToolUse bị drop hoàn toàn và hai shared matcher bị narrow;
Marketing có ba narrow và không có full drop. Matcher atom được hỗ trợ vẫn hoạt
động. Trên Windows, Hook Codex .cjs đủ điều kiện nằm trong Codex home có
thể dùng .cmd shim thuộc ownership của AgentKit cho đường dẫn có khoảng trắng;
đường dẫn bên ngoài, có metacharacter hoặc non-ASCII không an toàn vẫn bị giới
hạn và được báo rõ.
Codex home do wrapper quản lý chỉ được alias leaf hooks cuối cùng tới
~/.codex/hooks canonical, bằng symlink POSIX hoặc directory junction trên
Windows; command Hook, thao tác ghi, rollback và ownership dùng identity
canonical đó. Parent có link và target không canonical vẫn không được hỗ trợ.
ak kit initdùng cùng implementation cài đặt.ak kit refreshđồng bộ lại route hiện có và xoá đầu ra cũ còn clean và owned.ak kit uninstallpreview hoặc xoá đầu ra đã cài còn owned.- Thông tin lệnh đầy đủ
- Cài Kit an toàn
- 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.