2.13.0-beta.20). Tính năng có thể thay đổi trước bản stable tiếp theo.Chuyển sang stable →Khái niệm
Runtime adapter
So sánh cách phân phối tới runtime production với Grok Build spike chỉ dùng nguồn cục bộ.
Các coding assistant không dùng chung cấu trúc tệp, bộ công cụ hay mô hình lifecycle event. Runtime adapter chuyển một Kit thành những bề mặt mà assistant được chọn thực sự có thể khám phá và sử dụng.
Adapter là ranh giới tương thích, không phải lời hứa về hành vi giống hệt nhau. Nếu runtime không có thành phần tương đương, AgentKit có thể giữ nội dung đó như tài liệu hỗ trợ không hoạt động, bỏ qua kèm cảnh báo hoặc báo là không được hỗ trợ.
Scope project và người dùng
Scope trả lời câu hỏi bản cài có hiệu lực ở đâu:
| Scope | Phạm vi khả dụng | Khi nên dùng |
|---|---|---|
| Project | Workspace hiện tại | Kit chỉ nên đi cùng hoặc áp dụng cho một project. Đây là mặc định. |
| Người dùng | Các thư mục người dùng của runtime | Bạn muốn Kit khả dụng trong nhiều project cho tài khoản người dùng của mình. CLI chọn scope này bằng --global. |
Scope không quyết định quyền sở hữu repository. Bản cài theo project cho phép AgentKit quản lý các tệp cài đặt mà nó đã ghi nhận trong project đó; nó không làm cho mọi tệp trong project thuộc sở hữu của AgentKit.
Bản cài theo project và người dùng có thể cùng tồn tại. Khi đó, runtime có thể che khuất hoặc làm trùng command hay Hook; cập nhật hoặc gỡ một scope không tự xóa scope còn lại. Hãy kiểm tra cả hai scope khi hành vi xuất hiện hai lần hoặc runtime tải một bản khác với mong đợi.
Cách phân phối native và plugin
Cách phân phối trả lời câu hỏi runtime tải bản cài như thế nào:
- Phân phối native ghi các thành phần được hỗ trợ vào vị trí project hoặc người dùng thông thường của runtime. Đây là chế độ cài mặc định.
- Phân phối plugin đóng gói và kích hoạt Kit qua cơ chế plugin của runtime.
Trong mô hình hiện được hỗ trợ, đây là lựa chọn riêng cho Claude Code bằng
--switch-to-plugin, ở scope project hoặc người dùng.
Scope và cách phân phối độc lập với nhau. Vì vậy, Claude Code có thể dùng native
theo project, native theo người dùng, plugin theo project hoặc plugin theo người
dùng. Bản cài Codex và Cursor dùng cấu trúc native theo project hoặc người dùng.
Grok Build spike cũng dùng cấu trúc native theo project hoặc người dùng, nhưng
chỉ từ nguồn Kit cục bộ rõ ràng. --switch-to-plugin không chọn cách phân phối
plugin cho các target này.
Trong cùng một scope, phân phối native và plugin cho cùng một Claude Code Kit loại trừ lẫn nhau. Chọn mode còn lại sẽ bắt đầu một lần chuyển đổi rõ ràng; thao tác đó không để cả hai bản do AgentKit sở hữu cùng hoạt động trong scope đó.
Chuyển cách phân phối là một thay đổi lifecycle. Hãy review phần preview vì AgentKit có thể cần hủy đăng ký cũ rồi tạo đăng ký mới trong khi vẫn giữ nội dung ngoài quyền sở hữu hoặc đã được sửa.
Khác biệt về capability
Các adapter được hỗ trợ có chung những workflow tệp và công cụ cốt lõi, nhưng các bề mặt hoạt động khác nhau:
| Runtime | Điều bạn nên mong đợi |
|---|---|
| Claude Code | Phân phối native hoặc plugin được chọn rõ ràng. Skills, agents, slash commands, rules, hooks và status line của AgentKit có thể hoạt động ở scope project hoặc người dùng. |
| Codex | Khám phá Skill theo cơ chế native, rules và giao việc cho Agent qua AgentKit runtime cục bộ. Hook chỉ được hỗ trợ một phần; group không được hỗ trợ sẽ không được chuyển sang runtime, còn trạng thái task được làm mới tại ranh giới lượt làm việc và subagent được hỗ trợ thay vì sau mọi lần gọi công cụ task. Tệp command của Kit chỉ được giữ làm nội dung hỗ trợ không hoạt động và Codex không có bề mặt status line của AgentKit. |
| Cursor | Adapter chuyển Skills, agents, rules và hooks sang scope project hoặc người dùng. Tệp command của Kit chỉ được giữ làm nội dung hỗ trợ không hoạt động, không có bề mặt status line của AgentKit và adapter không cung cấp công cụ quản lý plan chuyên biệt. Phạm vi xác minh cài đặt, cập nhật và invocation trực tiếp chưa đầy đủ trên mọi thiết lập provider, vì vậy không suy ra parity hoàn toàn chỉ từ việc source có hỗ trợ. |
Grok Build (spike) | Chỉ projection native từ nguồn cục bộ. Rule, Skill, Agent và Hook được hỗ trợ nằm dưới <project>/.grok hoặc ${GROK_HOME:-~/.grok}; metadata lifecycle nằm riêng dưới <project>/.agentkit/adapters/grok/<kit> hoặc ${AGENTKIT_HOME:-~/.agentkit}/adapters/grok/<kit>. Command và export không được hỗ trợ vẫn là sidecar không hoạt động. Chưa có package runtime Grok đã ký hoặc authenticated dispatch canary được phát hành. |
Hook command exec-form native trên Grok dùng launcher
agentkit-grok-envelope-shim.cjs thuộc quyền sở hữu để bổ sung field và tên tool
theo dạng Claude mà script trong Kit cần. HTTP handler và command handler không
có argument exec-form nhận raw envelope camelCase của Grok. Hook trong project
không hoạt động đến khi bạn chủ động trust project. Timeout, crash, output sai
định dạng và lỗi shim đều fail open; chỉ một denial PreToolUse áp dụng được mới
chặn action, vì vậy hãy kết hợp Hook nhạy cảm về an toàn với quyền của Grok.
ak run <kit>/<skill> --target grok là dispatch native của AgentKit. Lệnh phân
giải AGENTKIT_GROK_BIN hoặc grok; AgentKit sở hữu việc đóng khung process,
còn Grok và người dùng sở hữu model, xác thực, trust, quyền, sandbox và
.grok/config.toml. Đường này tách biệt với Claude-compat scanner của Grok đọc
settings .claude. Init và refresh Grok từ remote fail closed vì registry không
có package runtime Grok đã ký.
Với Hook native của Claude Code, AgentKit kiểm tra toàn bộ runtime closure trước khi thay đổi tệp. Preflight dừng mà không sửa gì nếu nội dung chưa được theo dõi hoặc đã bị sửa xung đột với output do runtime sở hữu. Chỉ thao tác force được cho phép rõ ràng mới có thể thay thế xung đột; xung đột xuất hiện sau preflight vẫn bị lượt kiểm tra cuối từ chối thay vì bị ghi đè.
Giới hạn projection trên Codex không làm cài đặt thất bại. Group hoàn toàn không
được hỗ trợ sẽ bị bỏ và được liệt kê dưới Hooks dropped (unsupported on this
target); JSON có thể chứa hooksDropped và droppedHookSummaries. Matcher chỉ
bị thu hẹp vẫn giữ handler trên các atom được hỗ trợ và được liệt kê dưới Hook
matchers narrowed (some tool matches unsupported on this target); JSON có thể
chứa hookMatchersNarrowed và narrowedHookSummaries. Cả bốn field đều là tùy
chọn và bị lược bỏ khi bằng không.
Với Engineer, group task-state PostToolUse không được hỗ trợ bị drop hoàn toàn,
trong khi hai matcher dùng chung bị thu hẹp. Với Marketing, ba matcher bị thu hẹp
và không group nào bị drop hoàn toàn. Đây là disclosure về capability, không phải
failure class mới. Destination và inventory adapter của Claude Code cùng Cursor
không đổi; đừng suy ra parity Cursor mới từ thay đổi package dùng chung.
Trên Windows, AgentKit có thể giúp một Hook .cjs đủ điều kiện bên trong Codex
home đã phân giải chạy được từ đường dẫn thông thường có khoảng trắng bằng cách
tạo một shim .cmd cùng cấp do AgentKit quản lý. Cơ chế này không hỗ trợ đường
dẫn bên ngoài có khoảng trắng, đường dẫn chứa ký tự đặc biệt của cmd.exe, tên
shim không phải ASCII hay argument được nhúng không an toàn hoặc không phải
ASCII; các trường hợp đó vẫn không được hỗ trợ trên Windows và sẽ phát cảnh báo.
Argument rỗng bị từ chối với cảnh báo riêng, shim cùng path và cùng nội dung được
deduplicate, còn xung đột cùng path giữ nội dung emit đầu tiên rồi cảnh báo.
Đường dẫn không cần shim tiếp tục dùng lệnh trực tiếp.
Không suy ra runtime được hỗ trợ chỉ từ tên tệp hoặc hành vi của runtime khác. Hãy dùng phần tóm tắt sau khi cài và tài liệu Skill liên quan làm căn cứ cho nội dung nào đã hoạt động. Cảnh báo về nội dung được giữ lại hoặc bị bỏ qua là kết quả capability, không nhất thiết là cài đặt thất bại.
Chọn adapter
- Chọn assistant nơi bạn sẽ chạy workflow.
- Chọn scope project hoặc người dùng theo nơi workflow cần khả dụng.
- Với Claude Code, giữ cách phân phối native trừ khi bạn chủ động muốn cơ chế kích hoạt và lifecycle của plugin.
- Chỉ chọn Grok Build khi bạn chủ động chấp nhận một
spikedùng nguồn cục bộ; không coi đây là target cài đặt production hoặc remote. - Review cảnh báo của adapter sau khi cài, đặc biệt với Hook và các bề mặt UI chỉ có ở một số runtime.
- Bắt đầu một phiên runtime mới nếu assistant chưa tải lại nội dung vừa cài.
Xem Cài đặt Kit để biết lệnh cài đặt. Xem Kits, Skills, Agents và Hooks để hiểu mô hình thành phần.