prefs
ak config prefs
Chọn thao tác tra cứu, validate hoặc thay đổi Hook toggle, journal.auto, worktree.root, agent model hay semantic_decision có giới hạn, đồng thời giữ đúng scope, default, secret và ranh giới backup.
Dùng ak config prefs để tìm các lệnh resolve hoặc thay đổi giá trị preference
đã được ghi của AgentKit. Bản thân lệnh nhóm chỉ in trợ giúp; lệnh không đọc hay
ghi tệp config.
Cách dùng
ak config prefsLệnh không có cờ riêng. Các cờ dùng chung được mô tả trong
quy ước CLI, nhưng --json không biến phần trợ giúp của
nhóm thành preference payload.
Chọn lệnh preference
| Mục tiêu | Lệnh | Tác động |
|---|---|---|
| Xem giá trị đã ghi có hiệu lực | ak config prefs resolve | Đọc config user và project hiện tại, rồi deep-merge project lên user. |
| Kiểm tra cú pháp và schema config | ak config prefs validate | Đọc tệp user/project hiện có hoặc một --file rõ ràng; không ghi gì. |
| Ghim một Hook toggle, bước journal tự động, worktree root mặc định, một agent model theo capability tier của runtime, hoặc một thiết lập semantic decision | ak config prefs set <key> <value> | Backup config đã chọn nếu tồn tại, rồi ghi atomically một boolean hooks.<name>, đúng leaf journal.auto, đúng path worktree.root, một model ID agent_models.<runtime>.<tier>, hoặc một leaf semantic_decision.*. |
Ngừng ghim một Hook toggle, journal.auto, worktree.root, agent model, hoặc thiết lập semantic decision | ak config prefs unset <key> | Xoá một leaf hooks.<name>, journal.auto, worktree.root, agent_models.<runtime>.<tier>, hoặc semantic_decision.* trong scope đã chọn khi tồn tại, có backup trước khi ghi lại. |
Các lệnh này không chỉnh provider key, API token, update setting hay section
khác do setup quản lý. Credential của semantic decision nằm trong biến môi
trường TYPESAFE_API_KEY, không bao giờ nằm trong config.
Hiểu scope và thứ tự ưu tiên
Hai tệp ứng viên là:
- user scope:
~/.agentkit/config.yamlhoặc$AGENTKIT_HOME/config.yaml; - project scope:
.agentkit/config.yamldưới working directory hiện tại của lệnh.
Resolve deep-merge giá trị project lên giá trị user. Mapping project có thể ghi
đè một nested key nhưng vẫn giữ giá trị user bên cạnh. Kết quả chỉ gồm giá trị
đã được ghi: key thiếu không được điền default của binary. Mỗi Kit Hook tự áp
dụng default tích hợp khi không có giá trị, và journal.auto mặc định là
true.
set và unset mặc định dùng user scope; truyền --scope project để chọn tệp
của project hiện tại. Scope dựa trên working directory của process, không dựa
vào project đã đăng ký được chọn ở nơi khác.
semantic_decision là ngoại lệ của thứ tự ưu tiên project trên user. Chỉ user
scope mới cấp được sự đồng ý dùng provider hoặc chọn thiết lập provider;
project scope chỉ có thể đặt semantic_decision.enabled hoặc một mục
semantic_decision.consumers.<consumer> thành false. Xem
ak eval decision để biết cách quyền được resolve và
dữ liệu nào được gửi đi.
Ranh giới riêng tư và đầu ra
Resolve dùng allowlist cho các section preference rồi đổi tên field sang cách
viết camel-case cũ mà Kit Hook sử dụng. Section credential của setup, gồm
keys và api, bị loại. Tuy nhiên, section extensions được giữ nguyên, vì
vậy hãy xem đầu ra preference là dữ liệu user-authored có thể nhạy cảm và kiểm
tra trước khi chia sẻ log.
Các lệnh preference dùng object JSON thô riêng cho từng lệnh thay vì success
envelope chung schema_version/kind/data. ak config prefs trần in trợ
giúp Cobra thông thường ra stdout và thường thoát 0.
Lỗi runtime của các lệnh preference không được chuyển tập trung thành JSON
error envelope. Với --json, lỗi có thể không phát object chẩn đoán; hãy dùng
mã thoát process và validate đầu ra thành công trước khi xử lý. Lỗi parse cờ có
thể vẫn in hướng dẫn dùng dạng plain text và thoát 2.
Subcommand không tồn tại hoặc positional token dư đi theo đường lỗi runtime
chung và thoát 1.
Ranh giới ghi và khôi phục
Set/unset giữ section YAML không được model, comment, thứ tự key và schema
editor directive. Tệp được thay qua sibling temporary file với mode 0600.
Target hiện có được sao chép trước dưới ~/.agentkit/backups/config/; đầu ra
thành công báo đường dẫn backup chính xác.
Backup là bản sao của từng tệp config, không phải transaction xuyên user và project scope. Tránh nhiều config writer chạy đồng thời. Để khôi phục, dừng các writer khác, kiểm tra backup được báo rồi copy tệp đó về config path được báo; không có lệnh rollback preference tự động.