Runtime adapter

So sánh runtime adapter cho Claude Code, Codex, Cursor, DeepSeek Harness, Grok, Pi và Oh My Pi.

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, Cursor, DeepSeek Harness, Grok, Pi và Oh My Pi dùng cấu trúc native theo project hoặc người dùng. Cài Grok và DeepSeek Harness từ nguồn cục bộ vẫn khả dụng cho development và CI với source --local --kits-dir 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ợ.
DeepSeek Harness	Target Kit registry đã ký với projection native dưới `<project>/.dsh/`, đồng thời hỗ trợ dispatch Skill qua `ak run --target dsh`. Setup ghi adapter đã bật và resolve `AGENTKIT_DSH_BIN` hoặc `dsh`; setup không cài package Kit. Hãy xác nhận đích user-scope từ install summary. Command và export không được hỗ trợ vẫn là sidecar không hoạt động. Cài từ nguồn cục bộ vẫn khả dụng cho development và CI.
Grok Build	Target Kit registry đã ký với projection native. 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. Cài từ nguồn cục bộ vẫn khả dụng cho development và CI.
Pi	Projection Kit `--target pi` đã đăng ký ở source. `ak setup --adapter` và onboard `--target` liệt kê `pi` như Kit target chỉ emit. Bản cài project ghi Skill portable `ak-<slug>` dưới `.pi/skills/`, Agent đã remap dưới `.pi/agents/`, rule thuộc sở hữu dưới `.pi/rules/` và extension first-party dưới `.pi/extensions/`. Bản cài global có điều kiện ghi trực tiếp dưới profile Pi coding-agent đang hoạt động. Pi vẫn là spike cho dispatch: không có `ak run --target pi`, không wrap harness đầy đủ, không ghi `.pi/commands/`, và sidecar không hoạt động vẫn nằm trong lifecycle ownership. Pi giữ native TUI footer theo mặc định; AgentKit chỉ gọi `setFooter` khi được truyền `statuslineMode` khác `none` một cách tường minh.
Oh My Pi	Target cài native cho scope project hoặc người dùng, đồng thời hỗ trợ dispatch Skill không tương tác qua `ak run --target omp`. Skill, Agent, rule và instruction của Kit dùng các bề mặt discovery native của OMP; export không được hỗ trợ vẫn là sidecar không hoạt động. Oh My Pi tự quản backend và credential đã cấu hình.

Projection và discovery trên Pi

Bản cài project bằng ak kit init <kit> --target pi ghi các thư mục Skill portable như .pi/skills/ak-cook/SKILL.md, Agent đã remap như .pi/agents/Explore.md, .pi/agents/Plan.md và .pi/agents/ak-<kit>-*.md, cùng rule thuộc sở hữu dưới .pi/rules/. Hook, file coding-level, file statusline .cjs được emit, script chạy được và sidecar nằm dưới .pi/extensions/agentkit-hooks-<kit>/; Agent runner dùng chung nằm dưới .pi/extensions/agentkit-agent/. AgentKit không ghi .pi/commands/ và không đăng ký slash command của Pi. File statusline của kit được emit cạnh extension; Pi giữ native TUI footer trừ khi bạn truyền statuslineMode khác none một cách tường minh.

Projection asset thành công không bảo đảm extension bridge đang hoạt động. Nếu tập Hook sau adaptation không đạt ngưỡng bảo mật fail closed bắt buộc, Skill và Agent vẫn được projection, nhưng entrypoint của bridge vẫn không hoạt động hoặc AgentKit gỡ bridge trước đó của chính Kit đó. Summary nêu các cặp security coverage còn thiếu và cảnh báo khi Kit có nội dung được bridge phân phối: Hook, rule, output style hoặc statusline. Khi không có bất kỳ nội dung nào trong số đó, không có cảnh báo bridge không hoạt động. Bridge không hoạt động không nạp Hook, rule, output style, statusline hay công cụ ask_user của Kit.

Với --global, AgentKit ghi trực tiếp dưới profile Pi coding-agent đang hoạt động, phân giải từ PI_CODING_AGENT_DIR hoặc ~/.pi/agent; lệnh không thêm một đoạn .pi/ nữa dưới profile đó. Theo mặc định, bản cài mới sẽ từ chối profile đã có nội dung. Chỉ truyền --force sau khi xem các đường dẫn đang chiếm chỗ và quyết định cho phép ghi đè. Projection Pi tách biệt với dispatch Oh My Pi: bản phát hành này không có ak run --target pi và không wrap agent loop của Pi.

Projection và discovery trên Oh My Pi

Bản cài project bằng ak kit init <kit> --target omp ghi Skill portable bên dưới .omp/skills/ak-<slug>/, với name: ak-<slug> ở top-level trong mỗi SKILL.md đã projection. Agent được ghi vào .omp/agents/<name>.md, còn rule vào .omp/rules/<name>.md. Alias trong body như /ak:cook và $ak:cook không bị viết lại. AgentKit cũng thêm một block theo Kit vào AGENTS.md của project, giới hạn bởi  và . Khi cập nhật hoặc gỡ Kit đó, AgentKit chỉ thay đổi block được quản lý và giữ nguyên nội dung của người dùng.

Với --global, AgentKit phân giải root OMP theo thứ tự: AGENTKIT_OMP_HOME, OMP_HOME, PI_CODING_AGENT_DIR, rồi ~/.omp/agent. Các thư mục skills/, agents/, rules/ cùng AGENTS.md nằm dưới root đã phân giải. Command, Hook, schema, script, file status line và các bề mặt Kit không được hỗ trợ khác được giữ ở trạng thái không hoạt động dưới .agentkit/adapters/omp/<kit>/sidecars/ thay vì được project thành behavior native của OMP.

Cài đặt và dispatch là hai tuyến riêng. ak kit init ... --target omp tạo projection Kit để runtime discover; ak run <kit>/<skill> --target omp chạy một Skill đã resolve qua OMP CLI cục bộ mà không thay thế inventory đã cài hoặc thay đổi selector <kit>/<skill>.

OMP trong project đã trust cũng discover .agents/skills của project. Nếu các dạng canonical như ak:advise và ak-advise xung đột, bản cài OMP project dưới .omp/skills che bản trong .agents/skills của project. Khi dùng bản cài OMP global từ project đã trust đó, bản .agents/skills của project che bản trong profile OMP. ak kit init --target omp cảnh báo rồi tiếp tục: lệnh vẫn emit nội dung OMP, không xóa hoặc viết lại Skill nào, không thay đổi .agents hay setting OMP, đồng thời không cần --force và không trả exit 6.

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 dsh và ak run <kit>/<skill> --target grok là các tuyến dispatch native của AgentKit. DeepSeek Harness resolve AGENTKIT_DSH_BIN hoặc dsh; Grok resolve AGENTKIT_GROK_BIN hoặc grok. AgentKit sở hữu việc đóng khung process, còn runtime và người dùng sở hữu model, xác thực, trust, quyền, sandbox và cấu hình native. Dispatch Grok tách biệt với Claude-compat scanner của Grok đọc settings .claude. Remote DeepSeek Harness và Grok init cùng refresh dùng package registry đã ký; chỉ dùng --local --kits-dir khi bạn chủ động chọn nguồn development hoặc CI.

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 Hook groups not projected; 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.

Codex home do wrapper quản lý chỉ được liên kết leaf hooks cuối cùng tới thư mục canonical ~/.codex/hooks của user đã resolve. Link đó có thể là symlink POSIX hoặc directory junction trên Windows. AgentKit resolve alias đó một lần rồi dùng path canonical cho thao tác ghi Hook, command, rollback và ownership. Parent có link, hoặc leaf resolve ra bất kỳ đích nào khác thư mục hooks canonical của user, đều bị từ chối.

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ọn DeepSeek Harness với --target dsh khi bạn muốn package DeepSeek Harness đã ký, hoặc dùng ak run --target dsh để dispatch Skill trực tiếp qua binary dsh cục bộ; chỉ thêm --local --kits-dir cho nguồn development hoặc CI.
Chọn Grok Build với --target grok khi bạn muốn package Grok đã ký; chỉ thêm --local --kits-dir cho nguồn development hoặc CI.
Chọn Oh My Pi bằng --target omp khi cần package OMP Kit đã ký, hoặc dùng ak run --target omp để dispatch Skill trực tiếp.
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.

Bảng capability theo runtime

Package phụ thuộc bản phát hành; cài đặt được không chứng minh dispatch hoặc parity với provider đang chạy.

Runtime	Package registry	Project / global	Setup/onboard	ak run	Giới hạn
Claude Code	Có	Có / Có	Có	Có	Native/plugin
Codex	Có	Có / Có	Có	Có	MCP runtime dispatch
Cursor	Có	Có / Có	Có	Có	Projection production; chưa xác minh đủ live parity
DeepSeek Harness (`dsh`)	Có	Có / Có	Có	Có	Projection và dispatch native
Grok / Oh My Pi	Có	Có / Có	Có	Có	Runtime quản lý xác thực provider
Pi	Có	Có / Có	Có	Không	Target emitter; orchestration là surface riêng
Cloud Harness (`cloud-harness`)	Có (chỉ phân phối)	Không / Không	Không	Không	Package đã ký được phát hành cho Cloud Harness MCP harness; `ak` từ chối dùng nó làm target cài đặt cục bộ
AGY	Không	Không / Có	Không	Không	Chỉ export Skill và Agent tùy chọn ở global; nguồn là package Claude Code đã ký; không project, Hook hoặc MCP projection
Portable	Không	Export với `--out`	Không	Không	File độc lập; không có lifecycle của runtime đã cài
OpenCode	Không	Không	Không	Không	Adapter stub chưa đăng ký; orchestration ngoài cần live probe riêng

AGY không có đầy đủ contract refresh như các target chính. Export global và cleanup ownership không đồng nghĩa hỗ trợ ak run --target agy. Setup không liệt kê target export-only. Tương tự, cloud-harness không phải target của kit init, setup hay ak run; Cloud Harness MCP harness dùng trực tiếp package đã ký của nó. Bảng này không tuyên bố đã chạy live canary mới với provider.

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.

Để hiểu cách chọn model và override theo Agent, đọc Model của Agent trên từng runtime.