Làm quen

Bạn hoàn tất onboarding khi trợ lý lập trình đã chọn nhận diện được một skill của Engineer Kit trong project do bạn kiểm soát.

Trước khi bắt đầu

Bạn cần:

• ak có trong PATH — xem Cài đặt.
• Claude Code hoặc Codex đã được cài và đăng nhập bằng tài khoản riêng của runtime đó.
• Tài khoản AgentKit có quyền sử dụng Engineer Kit.
• Một project thử nghiệm nơi bạn có thể thêm cấu hình runtime.

Xác thực AgentKit cấp quyền truy cập các kit có license. Nó không đăng nhập Claude Code hay Codex vào provider, và đăng nhập runtime không cấp quyền sử dụng kit AgentKit.

Cấu hình AgentKit

ak setup

Wizard phát hiện trạng thái đăng nhập Claude Code và Codex, cho phép chọn runtime adapter đang bật và cập nhật nguyên tử ~/.agentkit/config.yaml với kit mặc định cùng tùy chọn telemetry. Chạy lại lệnh là an toàn và cho cùng kết quả. Thiết lập cơ bản không sao chép credential của runtime và không cài kit.

Dùng các lệnh sau cho những mục đích khác nhau:

Bạn không cần chạy ak init trước khi cài kit ở scope project; hãy dùng lệnh đó khi muốn AgentKit tiếp nhận và theo dõi toàn bộ project hiện có.

Nếu project đã dùng docs/ hoặc plans/ cho mục đích khác, hãy chọn vị trí AgentKit tương đối theo project khi tiếp nhận:

ak init ./myproj --docs-dir handbook --plans-dir work/plans

Lệnh lưu các giá trị dưới dạng paths.docs và paths.plans trong .agentkit/config.yaml. Giá trị tương đối phải nằm trong project và không được trỏ vào .agentkit; giá trị không hợp lệ khiến lệnh thoát trước khi ghi trạng thái project. Giá trị paths.plans tương đối được các Skill Engineer, ak plan, journal và khung plan của Desktop/dashboard sử dụng.

Đăng nhập AgentKit

Hãy dùng đúng tài khoản AgentKit sở hữu kit. Đăng nhập thành công bằng tài khoản khác vẫn có thể không trả về quyền Engineer Kit.

User API key (khuyến nghị)

Tạo user API key trong Account Dashboard, sau đó chạy lệnh này cục bộ với key thật của bạn:

ak login --api-key ak_live_... --no-interactive

Phương thức này phù hợp cho việc dùng thường xuyên và môi trường không tương tác. AgentKit lưu API key và phiên CLI trong các tệp được giới hạn quyền truy cập dưới ~/.agentkit/auth (hoặc %USERPROFILE%\.agentkit\auth trên Windows) để có thể làm mới phiên.

Email OTP

ak login --email you@example.com

AgentKit gửi mã dùng một lần tới địa chỉ đó và yêu cầu bạn nhập mã. OTP không được lưu; phiên có thể làm mới sau đó được lưu cục bộ. Nếu chưa nhận được thư, hãy kiểm tra Spam, Junk và Promotions, rồi xác nhận địa chỉ thuộc tài khoản sở hữu kit.

Kích hoạt thiết bị bằng license key

ak login --license-key ak_license_... --no-interactive

Lệnh này kích hoạt thiết bị hiện tại và lưu một phiên thiết bị của ứng dụng tách biệt với phiên CLI do đăng nhập bằng API key hoặc email tạo ra. Chỉ thêm --device-name <name> khi bạn cần nhãn thiết bị rõ ràng. Quyền sử dụng kit vẫn được kiểm tra riêng.

Xác minh danh tính và quyền sử dụng

ak whoami
ak licenses

ak whoami xác nhận tài khoản hiện tại và trạng thái xác thực trực tiếp. ak licenses liệt kê quyền theo từng kit. Chỉ tiếp tục khi Engineer Kit xuất hiện. Đăng nhập và quyền sử dụng là hai phép kiểm tra riêng: đăng nhập thành công không tạo ra quyền còn thiếu. Khi không có phiên cục bộ, ak whoami báo trạng thái chưa xác thực và trả exit code 0; script phải kiểm tra kết quả thay vì xem exit code bằng không là bằng chứng đã đăng nhập.

Cài Engineer Kit

Chuyển tới project thử nghiệm, chọn runtime và xem trước kế hoạch cài đặt trước khi xác nhận.

ak kit init engineer --target claude-code

ak kit init engineer --target codex

Mặc định, đây là các bản cài native ở scope project từ remote registry đã xác thực và kênh kit stable. Với Claude Code, delivery dạng plugin yêu cầu --switch-to-plugin; độc lập với lựa chọn đó, --global chọn scope người dùng của runtime thay vì scope project. Phần tóm tắt thành công nêu engineer, vị trí đầu ra, install mode, scope và số tệp đã ghi.

Trên Codex, kết quả thành công có thể báo cả Hook group bị drop hoàn toàn và matcher chỉ bị thu hẹp một phần. Engineer hiện có một full drop—group task-state PostToolUse không được hỗ trợ—và hai matcher dùng chung bị thu hẹp nhưng vẫn giữ các tool atom được hỗ trợ hoạt động. Output cho người dùng dùng Hooks dropped (unsupported on this target) và Hook matchers narrowed (some tool matches unsupported on this target); cả hai đều không có nghĩa cài đặt thất bại.

Trên Windows, Hook .cjs đủ điều kiện bên trong Codex home đã resolve có thể dùng shim .cmd sibling do AgentKit quản lý khi path chứa khoảng trắng. Lời nhắc plan của Engineer được đăng ký tại Stop: nó không phát output khi không có plan đang hoạt động và trả JSON hợp lệ, không chặn trong trường hợp còn lại. Lời nhắc này không được phát hành dưới dạng đăng ký SubagentStop.

Chạy và xác minh skill đầu tiên

Khởi động lại trợ lý hoặc mở phiên mới để nạp lại nội dung đã cài, rồi gọi:

/ak:cook Add a health-check endpoint

$ak:cook Add a health-check endpoint

Bạn hoàn tất onboarding khi trợ lý nhận diện ak:cook, đọc yêu cầu và bắt đầu workflow của skill trong project hiện tại.

Khôi phục và lỗi thường gặp

• ak whoami báo chưa xác thực: chạy lại một phương thức ak login cụ thể.
• Engineer Kit không có trong ak licenses: xác nhận bạn dùng tài khoản đã mua kit. Cài lại không thể tạo quyền sử dụng.
• Runtime chưa có hoặc chưa đăng nhập: cài runtime và dùng claude auth login hoặc codex login, rồi chạy lại ak setup.
• Skill không được nhận diện: xác nhận phần tóm tắt cài đặt ghi đúng target, khởi động lại trợ lý và chạy ak doctor --exit-on-fail trước khi cài lại.
• Đích xung đột với nội dung hiện có: dừng lại và xem cảnh báo quyền sở hữu. Đừng dùng --force như phản ứng đầu tiên.

AgentKit giữ các tệp không rõ nguồn gốc và tệp người dùng đã sửa trong thao tác kit thông thường. Khi một thay đổi phá hủy được hỗ trợ cần snapshot khôi phục, CLI sẽ in backup ID. Hãy giữ ID tới khi đã xác minh kết quả. Kiểm tra thông tin, xác minh và xem trước snapshot trước khi áp dụng:

ak backups show <backup-id>
ak backups verify <backup-id>
ak recover <backup-id> --dry-run
ak recover <backup-id>

Restore là replace-only: nó khôi phục các path đã có trong snapshot nhưng thường giữ những tệp không liên quan được tạo sau đó. Quy trình restore nhiều tệp không có tính giao dịch và có thể dừng sau một số lần ghi nếu host gặp sự cố. Với project bundle, hãy lặp lại chính xác các giá trị --allow-root do ak backups show hiển thị khi thao tác khôi phục yêu cầu.

Tiếp tục với Khởi động nhanh, hoặc đọc Cài đặt kit trước khi đổi scope, chọn skill hay refresh một bản cài.