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 --channel <channel>
ak kit init engineer --target codex --channel <channel>
ak kit init engineer --target grok --channel <channel>
ak kit init engineer --target pi --channel <channel>
ak kit init engineer --target omp --channel <channel>

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 trên ak kit init, lệnh dùng channel ghi trong install receipt của destination đã có, rồi kit.channel, rồi stable; stable có thể trả version_not_available cho target chỉ tồn tại ở kênh khác. --channel tường minh không được lưu. 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 --channel <channel>
ak kit init engineer --target claude-code --global --switch-to-plugin --channel <channel>

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 target đã 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. --target grok dùng package registry Grok đã ký theo mặc định. Chỉ thêm --local --kits-dir khi bạn chủ động chọn nguồn development hoặc CI.

Bản cài Pi native trong project ghi dưới <project>/.pi/{skills,agents,rules,extensions}. Bản cài Pi global ghi trực tiếp dưới profile PI_CODING_AGENT_DIR hoặc ~/.pi/agent đang hoạt động. Theo mặc định, bản cài mới sẽ từ chối profile đã có nội dung; chỉ thử lại với --force sau khi xem các đường dẫn đang chiếm chỗ và quyết định cho phép ghi đè. Nếu project đã trust có Skill Codex trùng tên dưới .agents/skills/, lệnh cài Pi cảnh báo bản nào được ưu tiên: .pi/skills/ thắng ở scope project, còn .agents/skills/ của project thắng bản trong profile Pi global. Cảnh báo không xóa hoặc ghi lại Skill nào.

OMP projection thư mục Skill portable và tên top-level trong SKILL.md thành ak-<slug> mà không viết lại alias trong body như /ak:cook hoặc $ak:cook. ak run <kit>/<skill> --target omp giữ nguyên selector dispatch. OMP trong project đã trust cũng discover .agents/skills của project. Khi trùng tên, .omp/skills của project che .agents/skills 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 OMP global từ project đó. Cả ak kit init và ak kit install đều cảnh báo rồi tiếp tục mà không bỏ qua emission OMP hay thay đổi Skill, .agents hoặc setting OMP. Đây không phải exit 6 và không cần --force.

Bản cài Grok native trong project ghi dưới <project>/.grok và lưu quyền sở hữu lifecycle dưới <project>/.agentkit/adapters/grok/<kit>. Bản cài global dùng ${GROK_HOME:-~/.grok} và ${AGENTKIT_HOME:-~/.agentkit}/adapters/grok/<kit>. Đường này tách biệt với việc Grok scan .claude/settings.json trong Claude-compat mode. Hook native trong project không chạy đến khi bạn chủ động trust project trong Grok.

Đọ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 Hook groups not projected. Đâ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ỏ export được nêu tên vì runtime không có capability cần thiết. JSON báo capabilityExclusions và capabilityExclusionSummaries; hãy kiểm tra các tên đó thay vì suy ra một Skill khác đã bị loại. Projection Engineer cho Codex có ak:team, nhưng khi dùng vẫn cần live team lifecycle và phải dừng thay vì thay bằng ordinary subagent nếu thiếu các capability đó.

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.

Với Hook Codex global, đừng xem mọi link là tương đương. Chỉ leaf hooks cuối cùng được trỏ tới ~/.codex/hooks canonical của user đã resolve, dưới dạng symlink POSIX hoặc directory junction trên Windows; parent có link và target khác bị từ chối. Hãy xử lý path không khớp thay vì retry bằng --force.

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. Nếu CLI đã cài chưa có filter Doctor riêng cho Grok, thay vào đó hãy kiểm tra install summary, native root và khả năng discovery của Grok. 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 theo adapter ở nơi có check đó. Với Pi, hãy mở session Pi mới trong cùng project hoặc profile global đang hoạt động, rồi xác minh .pi/skills/ak-<slug>/SKILL.md, .pi/agents/ và .pi/extensions/ thay vì tìm .pi/commands/. Với Grok native, hãy mở session mới trong cùng project, trust Hook trong project nếu áp dụng và xác minh discovery dưới .grok. Sau đó xác nhận 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

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.