Vận hành ak CLI an toàn với ak:ak

Dùng ak:ak khi hành động tiếp theo là chạy một subcommand ak hoặc diễn giải output của nó. Skill này sở hữu mô hình vận hành an toàn cho chính control-plane CLI — không phải flag reference, phần đó do ak <cmd> --help và envelope --json là chuẩn.

Chọn ak:ak cho vận hành CLI

Dùng ak:ak khi

• Hành động tiếp theo là gọi một subcommand ak (init, kit, skills, plan, journal, doctor, recover, self-update, login, …).
• Bạn cần phân biệt lệnh chỉ đọc và lệnh mutation vòng đời trước khi lệnh chạy.
• Bạn cần xác định rõ scope project vs user/global, adapter, hoặc chế độ delivery trước khi thay đổi rơi vào chỗ không mong muốn.
• Bạn cần diễn giải envelope ak <cmd> --json.

Chọn Skill khác khi

• Viết hoặc tinh chỉnh Marketing Skill — dùng ak:skill-creator.
• Viết hoặc thực thi implementation plan — dùng ak:plan hoặc ak:cook.
• Viết technical journal entry — dùng ak:journal.
• Chọn Skill nào chạy cho một task — dùng ak:agentkit (task router).
• Workflow đặc thù của kit đã có Skill riêng — dùng Skill đó.

ak:agentkit quyết định Skill nào chạy. ak:ak chạy chính binary ak.

Giao thức vận hành an toàn

1. Phân loại thao tác, xác định project/user scope, Kit, runtime và delivery mode.
2. Kiểm tra version và help của binary đã cài. Tái sử dụng bằng chứng trong phiên khi binary, version và target không đổi; kiểm tra lại sau update hoặc đổi target.
3. Đọc status/validation trước thay đổi vòng đời. Kiểm tra state một phần trước retry; retry trong phạm vi đã được cho phép không cần hỏi xác nhận lặp lại.
4. Tiếp tục thay đổi additive hoặc có thể reconcile an toàn trong authorization hiện có. Dùng --yes và --no-interactive cho script đã được cho phép nếu lệnh hỗ trợ. Prompt không phải ranh giới mutation duy nhất; một số writer ghi trực tiếp.
5. Overwrite, reset, restore hoặc removal phá hủy cần authorization rõ scope và cơ chế preview/snapshot được hỗ trợ. Giữ file lạ và file đã sửa. Không kết hợp --force và --fresh. Khi plan --fresh dừng lại với danh sách rủi ro và risk token, hãy cho người dùng xem từng rủi ro cùng các file liên quan, và chỉ chạy lại với --accept-risks <token> sau khi người dùng chấp nhận đúng danh sách đó. Token chỉ áp dụng cho project, target và Kit có plan đã in ra nó; không dùng lại ở nơi khác và không lưu cho các lần chạy sau. Xem ak kit init --fresh.
6. Báo chính xác lệnh, scope, kết quả và bằng chứng còn thiếu. Dùng --json cho output máy đọc. --quiet ghi đè --verbose; không chạy lại mutation chỉ để lấy verbose log.

Họ lệnh theo task

• Bootstrap và setup — ak init, ak new, ak setup, ak onboard. Toàn bộ mutating; xác nhận kit và scope trước. ak setup chỉ ghi cấu hình người dùng. ak onboard chạy setup, đăng nhập CLI, rồi cài kit. Basic setup giữ nguyên consent telemetry đã lưu và không hỏi về nó; đổi consent một cách tường minh qua ak setup, không coi đó là điều kiện trước của onboarding.
• Kits — ak kit init|install|refresh|validate|uninstall|list-kits|repair-install-mode. list-kits và validate chỉ đọc; còn lại mutate.
• Skills — inventory (ak skills list|show|search|install|remove|graph) và môi trường từng Skill (ak skill install|remove|repair|upgrade|verify).
• Agents, content, commands — cùng hình dáng như skills: đọc (list, show, search), ghi (install, remove), và một mutation chuyên biệt cho mỗi nhóm.
• Plans và journals — quản lý plan/journal file-first. ak plan list|show|status|search|validate|resolve|parse chỉ đọc. ak plan create|check|uncheck|add-phase|update|use|archive|close|reindex|migrate mutate. ak plan kanban là TUI chẩn đoán. ak journal list|show|validate đọc; ak journal create ghi.
• Chẩn đoán — ak describe, ak doctor, ak activity, ak audit, ak sessions, ak analytics, ak backups, ak versions, ak changelog, ak diagnostics export. Phần lớn chỉ đọc; enable/disable/delete của analytics và content-search mutate. ak describe <cmd> --json trả về cờ, mã thoát và agent contract của một lệnh mà không cần mạng.
• Công việc cải thiện — ak insights work list chỉ đọc. work create ghi một kế hoạch có phạm vi trong project đã đăng ký, còn work defer|dismiss|awaiting-verification|verify lưu trạng thái vòng đời cục bộ; hãy xếp chúng vào nhóm mutate. verify so sánh bằng chứng đã ghi, không bao giờ chạy model hay sửa artifact.
• So sánh quyết định dạng shadow — ak eval decision <request.json|-> chạy một phép so sánh shadow tường minh. Hãy xem lệnh này là mutate: lệnh đã bật sẽ gửi dữ liệu ra bên ngoài và có thể phát sinh chi phí, dù không ghi báo cáo cục bộ nào. Lệnh yêu cầu consent semantic_decision ở user scope, và cấu hình project chỉ có thể hạn chế thêm. Credential được resolve từ môi trường process, rồi .env trong AgentKit home, không bao giờ từ .env của project. Không bao giờ bật lệnh này từ credential sẵn có trong môi trường hoặc như một phần của routing thông thường. Kiểm tra status, fallback_reason và provenance; quyết định có hiệu lực luôn là quyết định legacy đã cung cấp. Xem tham chiếu ak eval decision.
• Thử nghiệm workflow, triage và UI — ak eval workflow xác thực dữ kiện quyết định của scenario, fix hoặc debug ở mode mặc định off; --mode shadow còn cần consent tường minh workflow-controller và có thể phát sinh chi phí. ak eval triage so sánh finding triage dạng shadow với quyết định review có thẩm quyền, còn ak eval ui báo tín hiệu regression UI dạng shadow khi được opt in, và ở mode shadow cần consent tường minh ui-regression. Hãy xếp cả ba lệnh vào nhóm mutate. Hành động có hiệu lực, thẩm quyền review và kết quả test tất định luôn giữ nguyên. ak eval workflow-benchmark, ak eval triage-benchmark và ak eval ui-benchmark đánh giá bằng chứng đã gắn nhãn cục bộ ở chế độ offline và chỉ đọc.
• Test impact — ak test optimize --base <ref> --json lập kế hoạch mà không thực thi check, nhưng hãy xếp lệnh này vào nhóm mutate: --run thực thi lệnh repository đáng tin cậy và --output tạo receipt mới. Mode semantic mặc định tắt; mode được cấp quyền tường minh có thể gửi dữ kiện ngắn gọn ra bên ngoài và phát sinh chi phí, shadow giữ nguyên baseline, còn advisory chỉ thêm check. ak test classify-e2e cần grant consumer riêng, có thể phát sinh chi phí và không bao giờ sửa class manifest. ak test benchmark là lệnh mutate vì nó thực thi regression corpus đáng tin cậy trong workspace tạm thời cô lập; --semantic-replay vẫn chạy offline.
• Secrets — ak secrets list, get, export và recovery list chỉ đọc. set, delete, rotate, import-env, approve, audit, grant, grants, revoke, trust và recovery accept-rollback|add|init|remove được xếp vào nhóm mutate.
• Điều phối runtime — đọc ak orchestrate --help của binary đã cài trước. probe chạy version/help bounded và ghi metadata cache thuộc sở hữu; không chứng minh authentication hay gọi inference. prepare, advance và accept persist evidence job/attempt/artifact đã resolve. events, output và diagnose kiểm tra evidence đã ghi. Giám sát process bên ngoài yêu cầu Darwin. Bundle chẩn đoán loại argv và environment riêng.
• Khôi phục — ak recover, ak backups restore. Mutating và không thể đảo ngược nếu trước đó chưa có ak backups create.
• Watch và daemons — ak watch start|stop|status|dry-run, ak content schedule daemon, ak codex-agent-runtime serve, ak api start|stop|status, ak config start|stop|status.
• Config, auth, và MCP — ak config prefs resolve|set|unset|validate, auth cấp cao nhất (ak login, ak logout, ak whoami, ak licenses), và ak mcp add|link|list|remove|show|verify. Lệnh auth ở cấp cao nhất, không dưới cha ak auth. Đăng nhập email OTP cần terminal tương tác; với đăng nhập bằng script hoặc headless, hãy dùng route API key thay vì pipe mã OTP.
• Self-update và migrations — ak self-update, ak migrate prefs|rollback. Chạy ak versions và kiểm tra ak changelog trước khi gọi.
• Cập nhật nền tự động — ak update --schedule daily|weekly|off, --project/--no-project và --ack là các cờ settings: mutating (ghi auto_update: trong ~/.agentkit/config.yaml), nhưng không tự áp dụng cập nhật nào. ak update --status chỉ đọc. Bước cập nhật project chạy nền chỉ đồng bộ cây kits/ được theo dõi; còn ak update <dir> --yes chạy có người giám sát sẽ làm mới thêm mọi runtime đã cài trong project (--target a,b thu hẹp phạm vi). Không bao giờ bật schedule hoặc opt-in một project mà không có yêu cầu tường minh của người dùng.

Nguồn chuẩn

Command appendix sinh ra có mốc version. Nếu tụt sau ak --version, coi appendix là gợi ý ban đầu và kiểm tra lại cờ với ak <cmd> --help trước mọi lệnh mutating. ak self-update tiến version binary độc lập với nội dung skill đã cài, nên version lệch là bình thường sau self-update và trước khi ak update refresh lần tiếp theo.

Bề mặt chuẩn, theo thứ tự:

1. ak <cmd> --help hoặc ak describe <cmd> --json — luôn cập nhật cho binary đang chạy. Xem contract của lệnh.
2. Output ak <cmd> --json — đọc framing do ak describe khai báo: envelope có version, ndjson, protocol hoặc json-legacy; unspecified nghĩa là chưa biết.
3. Command reference đi kèm Skill — chỉ số khởi đầu, có thể tụt.

Anti-pattern

• Không kết hợp --force với --fresh cho bất kỳ lệnh vòng đời nào.
• Không chạy installer, refresh, migration, uninstall, hoặc destructive smoke test lên state thật của maintainer. Đặt AgentKit home tạm trước.
• Không bịa cờ không có trong ak <cmd> --help. Metadata Cobra là chuẩn.
• Không coi capability chỉ có trong source là đang hoạt động trong binary đã cài. Xác nhận qua ak versions hoặc ak doctor.
• Không suy khả năng adapter từ adapter khác.
• Không báo cáo kết quả lệnh mutating mà không nêu scope đã resolve — hãy nêu project vs global, adapter, và conflict đã bỏ qua.

Skill liên quan

• ak:agentkit — task router (Skill nào chạy).
• ak:skill-creator — tác giả Marketing Skill.
• ak:plan — vòng đời implementation plan.
• ak:journal — technical journal entry.

Về hiệu quả và usage cục bộ, xem ak insights, ak eval và ak usage. Thu thập, đánh giá, consent và đóng góp có tác động khác nhau; kiểm tra từng lệnh trước khi gọi.