Lỗi cài Kit

Dùng trang này khi ak kit init hoặc ak kit install thất bại trước khi runtime đích có thể dùng Kit.

Xác nhận điều kiện cần

ak --version
ak whoami --json
ak licenses --json

Các kết quả mong đợi là đúng phiên bản CLI, đúng tài khoản và có grant cho Kit. Đăng nhập thành công nhưng Kit không có trong ak licenses là lỗi quyền sử dụng, không phải lỗi cài đặt. Hãy xem Đăng nhập và quyền sử dụng Kit trước.

Xác nhận target và scope

Chạy lệnh cài từ project sẽ sở hữu nội dung project-scoped. Ghi rõ runtime để đích không mơ hồ:

ak kit init engineer --target claude-code
ak kit init engineer --target codex

Scope mặc định là project hiện tại. --global chọn user scope của runtime. Cài thành công trong một scope không làm Kit xuất hiện trong project hoặc user profile khác.

Với Claude Code, project-native delivery là mặc định. Plugin delivery là lựa chọn riêng:

ak kit init engineer --target claude-code --switch-to-plugin
ak kit init engineer --target claude-code --global --switch-to-plugin

Lệnh đầu chọn project plugin; lệnh thứ hai chọn user plugin. Không thêm --switch-to-plugin vào bản cài Codex.

Với bản phát hành, authenticated remote registry là nguồn mặc định. --local dành cho nguồn development hoặc CI rõ ràng và yêu cầu --kits-dir hoặc AGENTKIT_KITS_DIR; đây không phải fallback cho lỗi registry.

Đọc nhóm lỗi

Hãy dùng cả nội dung lỗi và mã thoát; v2.11.0 không gắn nhóm cụ thể hơn vào mọi đường lỗi thiếu nguồn hoặc target đã có nội dung. Từ chối trên TTY hoặc nhấn Enter cũng thoát 1, nhưng xảy ra tại preview gate trước khi resolve nguồn hoặc thay đổi bản cài. Ngược lại, hủy hay gián đoạn muộn hơn không bảo đảm target còn nguyên: snapshot, journal, cache entry hoặc staged write có thể đã tồn tại. Giữ mọi recovery ID và audit target trước khi thử lại.

Bản cài Codex vẫn có thể thành công khi in Hooks dropped (unsupported on this target). Đây là partial projection được công bố, không phải lỗi exit. JSON báo hooksDropped và droppedHookSummaries; hãy xem event, matcher và handler được nêu thay vì thử lại với --force. Xem Runtime không tìm thấy Skill hoặc Agent để biết các ranh giới được hỗ trợ.

Summary riêng Capabilities excluded (unsupported on this target) nghĩa là adapter chủ động bỏ một export vì runtime không có capability cần thiết. Với Engineer trên Codex, ak:team bị bỏ vì Codex không cung cấp đầy đủ lifecycle Agent Teams; ordinary subagent không được dùng làm fallback. JSON báo capabilityExclusions và capabilityExclusionSummaries. Đây là hành vi projection dự kiến, không phải lý do để thử cài lại.

Khi đích đã có tệp, không thử lại ngay với --force. Trước tiên hãy xác định nội dung do AgentKit sở hữu, thuộc install mode khác hay chứa thay đổi của người dùng.

Kiểm tra runtime và nội dung đã ghi nhận

ak doctor --adapter claude-code --json
ak doctor --adapter codex --json

Chỉ chạy adapter bạn đã chọn. Chọn một adapter được document: claude-code, codex hoặc cursor. Tên --check không tồn tại là lỗi lệnh; dùng ak doctor --list để xem các tên mà CLI đang cài hỗ trợ. Filter claude-code cũng giữ lại các shared check.

Các check integrity và removability của Kit chỉ kiểm tra thư mục có bằng chứng ownership AgentKit rõ ràng: lifecycle install manifest khớp hoặc metadata plugin Claude/Codex ghi tác giả AgentKit. Thư mục third-party trong plugin root hoặc Skill root dùng chung bị bỏ qua. Integrity Codex chấp nhận cả layout phẳng và layout namespace/Kit cũ, nhưng chỉ hình dạng thư mục không chứng minh ownership. Vì vậy, dòng Doctor no kits installed có thể nghĩa là không tìm thấy Kit nào quy được cho AgentKit dù root dùng chung vẫn chứa nội dung khác.

Với nội dung Claude Code, audit đúng delivery mode:

ak audit engineer
ak audit engineer --project-dir .
ak audit engineer --plugin-mode --project-dir ./ak-engineer

Lệnh đầu audit user plugin, lệnh thứ hai audit project-native install và lệnh thứ ba audit project plugin có plugin root là ./ak-engineer. ak audit chỉ đọc: thoát 0 là sạch; thoát 1 nghĩa là có drift hoặc audit thất bại; Kit argument không hợp lệ thoát 2. Dùng --strict khi manifest bị thiếu hoặc không đọc được cũng phải làm check thất bại.

Khôi phục cài đặt thất bại

Refresh và các đường ghi đè dùng recovery snapshot. Nếu lệnh in snapshot hoặc recovery ID, hãy kiểm tra trước khi restore:

ak backups list
ak backups show <id>
ak backups verify <id>
ak backups restore <id> --dry-run

Chỉ restore sau khi preview nêu đúng state bạn muốn thay thế. Nếu cài đặt hoàn tất nhưng ak audit chứng minh nội dung phát hành bị drift, coi lệnh refresh theo Kit mà audit in là điểm bắt đầu. Audit không dựng lại runtime, scope hoặc Claude delivery mode ban đầu: thêm selector --target, --global và --switch-to-plugin khi áp dụng trước khi xác nhận. Không thêm --no-backup, đổi kênh hoặc xóa runtime home để sửa lỗi.

Restore chỉ thay thế các tệp trong snapshot, giữ nguyên tệp không liên quan được tạo sau đó và không bảo đảm giao dịch tất cả-hoặc-không. Xem Cập nhật và khôi phục trước khi áp dụng snapshot.

Xác minh kết quả

Chạy lại doctor cho adapter. Sau đó mở session runtime mới trong cùng project và xác minh Skill hoặc Agent mong đợi đã có. Nếu cài đặt khỏe nhưng runtime vẫn không discover được, tiếp tục với Runtime không tìm thấy Skill hoặc Agent.

Trang liên quan

• Cài Kit
• Đăng nhập và quyền sử dụng Kit
• Cập nhật và khôi phục