ak kit init

Dùng ak kit init khi bạn muốn resolve một Kit và chuyển các capability của Kit đó sang runtime hoặc thư mục build. Hãy chọn target, scope và delivery mode trước khi chạy, vì các lựa chọn này quyết định cả hoạt động mạng lẫn thay đổi trên đĩa.

Chọn đúng lệnh vòng đời

Khi mục tiêu là cập nhật route hiện có, hãy dùng ak kit refresh thay vì thực hiện một bản cài mới buộc ghi đè.

Trước khi bắt đầu

Theo mặc định, Kit phát hành dùng remote registry có xác thực. Channel được resolve theo thứ tự: --channel tường minh, rồi channel ghi trong install receipt của destination đã có, rồi kit.channel, rồi stable. --channel tường minh chỉ áp dụng cho request đó và không được lưu; nó không đổi các lần ak kit init, ak kit refresh hay ak update sau. 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í yêu cầu phiên CLI hợp lệ và entitlement trước khi hiển thị preview hoặc ghi dữ liệu.

ak whoami
ak licenses

Quá trình resolve từ xa có thể gia hạn trạng thái xác thực cục bộ, liên hệ registry, tải artifact dành riêng cho runtime và ghi verified cache. Cache đã được xác minh đầy đủ có thể đáp ứng một số trường hợp lỗi offline; cache chưa có hoặc không xác minh được sẽ bị từ chối an toàn.

Chỉ dùng --local --kits-dir <dir> khi chủ động chọn nguồn development hoặc CI. Đây không phải phương án dự phòng khi xác thực hoặc entitlement thất bại.

Cách dùng

ak kit init <kit-name>

Trong script, hãy cung cấp một tên Kit có thể cài. Trên TTY tương tác, việc bỏ trống tên có thể mở wizard thiết lập; lần gọi từ script thiếu tên sẽ thất bại.

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, lệnh dùng channel trong receipt hiện có, rồi kit.channel, rồi stable.

Tuỳ chọn của lệnh

--skills, --exclude-skills và --select-skills là các chế độ lựa chọn thay thế nhau. --select-skills cần terminal tương tác. Các cờ dùng chung được liệt kê trong quy ước CLI.

Chọn target, scope và mode

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 ở project scope và user scope có thể cùng tồn tại. Claude native và plugin delivery là hai mode riêng trong cùng scope; việc chuyển mode là thao tác rõ ràng, có snapshot bảo vệ. Codex không có đầy đủ mức tương đương với Claude về command, Hook hoặc status line, vì vậy hãy xem kỹ cảnh báo thay vì giả định mọi component đều được chiếu sang runtime.

Với Hook Codex global, wrapper đã thiết lập chỉ được alias leaf hooks cuối cùng tới ~/.codex/hooks canonical của user đã resolve, bằng symlink POSIX hoặc directory junction trên Windows. AgentKit dùng path canonical đó cho command, thao tác ghi, rollback và ownership. Parent có link và leaf resolve ra target khác đều bị từ chối.

portable chỉ để export. --target portable không có --out trả mã 1 trước preview, xác nhận, phân giải source, lifecycle preflight 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

Chỉ dùng --out sẽ giữ source mặc định từ remote và JSON báo mode: "build". Dùng rõ --build-only --out vẫn hợp lệ và 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. Portable không ghi install record. AGY chỉ hỗ trợ global và không phải peer trong lifecycle refresh. Pi là target projection cài đặt, không phải adapter ak run; dùng discovery riêng của Pi cho .pi/skills đã emit và đừng thay bằng --target omp trừ khi bạn muốn dispatch qua Oh My Pi.

Projection OMP dùng thư mục portable ak-<slug> và name: ak-<slug> ở top-level trong SKILL.md đã projection. Lệnh không viết lại alias trong body như /ak:cook hoặc $ak:cook, còn ak run <kit>/<skill> --target omp giữ nguyên selector dispatch. Trong project đã trust, .omp/skills của project che bản .agents/skills xung đột với bản cài OMP project; .agents/skills của project che bản trong profile OMP khi dùng bản cài global từ project đó. ak kit init --target omp cảnh báo rồi tiếp tục mà 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.

Xem lại hành vi xác nhận

Trên TTY tương tác, install mode hiển thị preview destination và hỏi Continue? [y/N]:. Nhấn Enter mà không nhập gì, hoặc nhập câu trả lời khác y hay yes, đều là từ chối.

Hiện tại, từ chối trên TTY thoát với mã 1, không phải 3. Route build và export không hiển thị install preview vì chúng ghi vào thư mục đầu ra đã chọn, không phải install destination.

Khi chủ động tự động hoá, hãy chỉ định rõ route và xác nhận:

ak kit init engineer --target codex --yes --no-interactive --json --channel <channel>

# Cài Grok trong project từ nguồn local development rõ ràng.
ak kit init engineer --local --kits-dir ./kits --target grok --yes

# Cài Grok cho user từ cùng nguồn cục bộ rõ ràng.
ak kit init engineer --local --kits-dir ./kits --target grok --global --yes

# Portable export với một ZIP có thể upload cho mỗi Skill.
ak kit init engineer --target portable --out ./ak-export --zip

Hiểu tác động trên đĩa

Một lần cài có thể ghi tệp native của runtime, metadata về ownership và vòng đời AgentKit, cấu hình project, Hook script, thư mục Skill native và bản ghi chuyển mode. Bản cài Codex global còn có thể đăng ký AgentKit MCP runtime trong cấu hình Codex của user.

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 được hỗ trợ cùng --force rõ ràng cho phép ghi đè có giới hạn. Trước khi refresh phá huỷ hoặc ghi để chuyển mode, AgentKit thường tạo recovery snapshot. Không dùng --no-backup cho cài đặt thông thường.

Đặt lại một target với --fresh

ak kit init <kit> --fresh đặt lại một install target đã chọn về chỉ còn đầu ra của Kit. Một target gồm một Kit, một runtime và một scope. Dùng lệnh này khi lifecycle root riêng của Kit đã tích tụ tệp tuỳ chỉnh hoặc tệp cũ mà refresh hay --force vẫn giữ lại. ak kit install nhận cùng cờ này.

# Xem kế hoạch; lần chạy dạng script dừng tại đây với mã 3.
ak kit init engineer --fresh --target codex

# Đặt lại sau khi đã xem kế hoạch.
ak kit init engineer --fresh --target codex --yes

Quá trình đặt lại chạy theo thứ tự:

1. Dựng kế hoạch chỉ đọc. Kế hoạch liệt kê reset root riêng của Kit, các tệp hiện có ở đó, tệp tuỳ chỉnh hoặc chưa được ghi nhận sẽ bị xoá, tệp đã ghi nhận có chỉnh sửa cục bộ sẽ bị bỏ (trong và ngoài reset root), link và tệp đặc biệt được giữ, các runtime root dùng chung không bị đặt lại, và mọi rủi ro an toàn.
2. Hỏi đồng ý một lần (xem bên dưới).
3. Dựng lại kế hoạch khi đang giữ khoá vòng đời. Nếu rủi ro an toàn đã thay đổi, lệnh hỏi lại trên TTY hoặc dừng với mã 3 trong lần chạy dạng script.
4. Snapshot mọi đường dẫn mà lần đặt lại có thể xoá hoặc ghi đè, rồi xác minh từng snapshot. Snapshot xác minh thất bại sẽ được chụp lại một lần.
5. Emit Kit.
6. Quét các tệp còn sót trong reset root. Tệp đã thay đổi kể từ lúc dựng kế hoạch được giữ lại. Tệp cũ đã ghi nhận của Kit này bị xoá kể cả khi đã bị sửa, vì snapshot đã xác minh giữ nội dung của chúng.

Những gì lần đặt lại không động tới:

• Runtime root dùng chung, như .claude hoặc ~/.codex, chỉ thay đổi qua các tệp mà Kit này đã ghi nhận, giống như với --force.
• Các Kit khác, các runtime khác và bản cài project hoặc global còn lại không bị đặt lại.
• Link, junction, reparse point và tệp đặc biệt trong reset root được giữ và không bao giờ bị đi theo.
• Lựa chọn Skill trước đó không được kế thừa. Toàn bộ Kit được cài trừ khi bạn truyền --skills, --exclude-skills hoặc --select-skills.

Với Codex, bảng [agents.<slug>] trỏ tới tệp Agent đã bị xoá sẽ được dọn, nên không còn mục config_file treo.

Đồng ý và rủi ro an toàn

Riêng --yes không bao giờ chấp nhận rủi ro. Kế hoạch liệt kê một rủi ro cho mỗi kiểm tra mà nó không chứng minh được:

• unproven-ownership: reset root đang có dữ liệu nhưng không có install manifest, hoặc manifest không đọc được.
• other-kit-ownership: install manifest của reset root ghi tên Kit khác.
• snapshot-unverified: recovery snapshot xác minh thất bại hai lần. Không có gì bị đặt lại cho tới khi bạn chấp nhận rủi ro này.

Risk token bao trùm đúng loại rủi ro, đường dẫn và tệp của kế hoạch đó cho Kit và target đó. Với rủi ro other-kit-ownership, token còn bao trùm Kit sở hữu root, nên việc chấp nhận bản ghi của một Kit không bao giờ bao trùm bản ghi của Kit khác. Rủi ro, tệp hoặc Kit sở hữu mới sẽ đổi token. Nếu kế hoạch dưới khoá có ít rủi ro hơn những gì bạn đã chấp nhận, lần đặt lại vẫn tiếp tục. Token truyền cho kế hoạch không có rủi ro sẽ bị bỏ qua kèm thông báo. Token đã chấp nhận snapshot chưa xác minh sẽ tiếp tục chấp nhận điều đó cho target ấy, nên đừng lưu lại cho các lần chạy sau. --accept-risks mà không có --fresh thoát 2.

Với --json, lần chạy bị dừng ghi envelope có kind=kit.init_fresh_plan và status: "confirmation-required". Data gồm reason (not-confirmed, risks-not-accepted, risks-changed hoặc snapshot-unverified), resetRoots, notReset, unrecordedPaths, modifiedRecordedPaths, modifiedOutsidePaths, keptLinks, risks, riskToken, confirmWith và command. Mỗi mục trong risks có kind, path, detail, effect và files, thêm owner với rủi ro other-kit-ownership. Đầu ra cho người dùng giới hạn mỗi danh sách đường dẫn ở 25 mục; kế hoạch JSON mang đầy đủ danh sách.

Điều chỉnh tự động

• pi, grok, omp và dsh giữ đầu ra Kit và tệp runtime trong cùng một thư mục, nên không có ranh giới chỉ thuộc Kit. Yêu cầu fresh ở đó chạy refresh --force có snapshot thay thế, in một thông báo và giữ tệp tuỳ chỉnh.
• Reset root đi qua link hoặc reparse point cũng chuyển sang refresh --force có snapshot kèm thông báo.
• Bản cài Claude Code dạng plugin được đặt lại tại chỗ ở plugin mode, kể cả khi bỏ --switch-to-plugin.
• Bản cài Codex vẫn dùng bố cục Skill cũ được migrate trước bằng refresh --force có snapshot, rồi được đặt lại trong cùng lệnh.

Các trường hợp bị từ chối

Các trường hợp sau thoát 2 trước khi lần đặt lại động tới bất cứ thứ gì:

• --fresh cùng --force, --no-backup, --build-only hoặc --out.
• Nhiều hơn một target.
• Target chỉ để export như portable.

Các trường hợp sau thoát 1 trước mọi thay đổi:

• Đang chờ chuyển từ native sang plugin. Hoàn tất bằng ak kit init <kit> --switch-to-plugin, rồi chạy --fresh.
• Đang chờ một legacy migration transition. Chạy ak migrate rollback trước.
• Bằng chứng ownership đã ghi nhận không đọc được.
• Claude home global không thuộc AgentKit. Chạy ak kit init <kit> --global để thiết lập ownership trước.
• Ranh giới mơ hồ, như runtime root nằm trong reset root, hoặc reset root không phải thư mục.
• Không chụp được snapshot.

Route project 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, thoát 6 trước khi kế hoạch được lập. Chạy lại với --global hoặc từ thư mục project khác.

Đầu ra khôi phục

Sau khi đặt lại, đầu ra cho người dùng báo từng reset root cùng số tệp tuỳ chỉnh hoặc chưa ghi nhận và tệp cũ đã sửa bị xoá, từng root dùng chung không bị đặt lại, và từng snapshot trước khi đặt lại:

[i] Fresh reset: <reset-root> now holds only engineer output (removed 3 custom/unrecorded and 1 modified stale file(s))
[i] Pre-reset target saved (verified <id>). Roll back: <restore-command>

Snapshot ngoài phạm vi restore báo Manual recovery data: <path> thay cho lệnh restore. Snapshot chưa xác minh đã được chấp nhận được gắn nhãn UNVERIFIED, may be incomplete. Nếu không có gì để đặt lại, đầu ra nói rõ điều đó và không liệt kê snapshot.

Với --json, data.fresh gồm resetRoots, notReset, snapshots (mỗi mục có id, roots, verify_command, và restore_command hoặc manual_data_path, thêm unverified khi đã được chấp nhận), snapshotVerified, removedUnrecorded, removedStaleModified và reason. Trường cũ forceSnapshot ở cấp trên chỉ nêu snapshot đã xác minh, nên nó trống khi snapshot duy nhất là snapshot chưa xác minh đã được chấp nhận. Nếu lần chạy thất bại sau khi đã chụp snapshot, lỗi nêu từng snapshot cùng cách xác minh và restore.

Khi ak kit init chuyển tiếp sang CLI đã cập nhật trước, lệnh tiếp nối mang --fresh và mọi token --accept-risks đã chấp nhận, không bao giờ mang --force. Desktop, ak update và ak doctor không có fresh mode.

--fresh khác --force thế nào

Hai cờ này loại trừ lẫn nhau.

Đọc đầu ra dành cho người dùng và JSON

Ở chế độ hiển thị cho người dùng, tiến trình, preview destination và prompt xác nhận xuất hiện trên stderr. Phần tổng hợp kết quả cuối cùng xuất hiện trên 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 liên quan.

Với --json, stdout chứa một envelope thành công có phiên bản với kind=kit.init và kết quả lệnh dưới data. Trừ khi đặt --quiet, stderr còn nhận các bản ghi trạng thái thô với status=preview trước khi ghi và status=complete sau khi ghi. Hãy xử lý stdout và stderr riêng biệt.

Dữ liệu thành công có thể bao gồm Kit và target đã chọn, mode, install mode, scope, thư mục đầu ra, số lượng tệp và Skill, tổng hợp Hook đã cài, cảnh báo, trạng thái cấu hình project, chuyển mode và các trường recovery snapshot có giới hạn. Dữ liệu projection Hook còn có thể chứa hooksDropped, droppedHookSummaries, hookMatchersNarrowed và narrowedHookSummaries; giá trị zero hoặc nil bị lược bỏ.

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, gồm lỗi từ bước kiểm tra đối số của lệnh. Các dạng bí mật đã biết và query string của URL được che, còn đường dẫn vẫn hiển thị. --verbose có thể lộ lỗi gốc thô; hãy kiểm tra trước khi chia sẻ.

Kết quả và mã thoát

Ý nghĩa mã thoát phụ thuộc từng lệnh. Đặc biệt, đừng diễn giải việc từ chối trên TTY theo cam kết mã thoát dùng chung 3.

Khôi phục sau bản cài thất bại hoặc buộc ghi đè

Khi đầu ra có recovery snapshot, hãy kiểm tra snapshot trước khi thay đổi thêm tệp:

ak backups show <id>
ak backups verify <id>

Một số snapshot nằm dưới restore root do AgentKit quản lý có thể được áp dụng bằng ak backups restore <id>. Ngược lại, bản cài buộc ghi đè trong project có thể báo một thư mục dữ liệu snapshot để khôi phục thủ công vì đầu ra đó nằm ngoài restore scope thông thường. Hãy làm theo phương thức khôi phục trong kết quả; đừng giả định mọi snapshot đều dùng cùng một lệnh restore.

Sau khi khôi phục hoặc cài đặt, hãy mở lại runtime đích và gọi một Skill đã cài. Nếu runtime không tìm thấy Skill, hãy kiểm tra target, project scope hay user scope, và Claude native hay plugin mode trước khi cài lại.

Đọc kết quả chiếu Hook

Phần tổng hợp thành công báo các Hook event và script đã cài khi có. Disclosure projection Hook dùng hai dòng riêng:

Hook groups not projected: <count> group(s) - see warnings
Hook matchers narrowed (some tool matches unsupported on this target): <count> matcher(s) - see warnings

Sau đó, lệnh in phần tổng hợp nêu rõ hành động cho từng drop hoặc narrow. Full drop gỡ group; narrow giữ handler trên matcher atom được hỗ trợ.

Với Codex, Engineer có một group task-state PostToolUse bị drop hoàn toàn và hai matcher dùng chung bị narrow. Marketing không có full drop và có ba narrow. Cài đặt vẫn thành công: đây là giới hạn target, không phải Hook đã được sửa hoặc lỗi cài đặt nghiêm trọng.

Lệnh liên quan

• Thông tin đầy đủ của lệnh ak kit init
• Cài Kit an toàn
• Xử lý sự cố cài Kit
• Đăng ký project hiện có bằng ak init
• Tạo project bằng ak new
• Refresh route đã cài

Nhóm Hook chưa được project có thể là unsupported hoặc được harness bridge trì hoãn. Đọc hooksDeferred riêng với nhóm unsupported; deferred không đồng nghĩa không được hỗ trợ vĩnh viễn.