ak config prefs set

Dùng ak config prefs set để ghim một soft-preference của Hook, preference journal.auto, mặc định worktree.root, một agent model theo capability tier của runtime, hoặc một thiết lập semantic_decision trong config user hay config của project hiện tại. Lệnh thay đổi tệp đã chọn ngay; lệnh không unregister hay cài Hook và không chặn /ak:journal gọi tường minh.

Cách dùng

ak config prefs set <key> <value>

Cung cấp đúng hai argument theo vị trí.

Tuỳ chọn của lệnh

Các cờ dùng chung được mô tả trong quy ước CLI. Thao tác ghi không hỏi, nên --yes và --no-interactive không thay đổi hành vi. Lệnh không có --dry-run, --force hay preview mode.

Validate key và value

Năm dạng key được chấp nhận:

• hooks.<name> — <name> phải là basename Hook script dạng kebab-case chữ thường, khớp ^[a-z0-9]+(?:-[a-z0-9]+)*$ và không được chứa thêm dấu chấm.
• journal.auto — literal chính xác, không có key con nào dưới journal.
• worktree.root — literal chính xác, không có key con nào dưới worktree.
• agent_models.<runtime>.<tier> — <runtime> là tập đóng cursor, và <tier> là một trong inherit, sonnet, opus, fable, hoặc haiku.
• semantic_decision.<leaf> — <leaf> là enabled, provider, model, timeout_ms, hoặc consumers.<consumer>, trong đó <consumer> là domain-routing, fix-complexity, orchestration-risk, skill-routing-eval, review-triage, workflow-controller, ui-regression, test-impact, hoặc e2e-classification.

Với hooks.<name> và journal.auto, value phải là literal chữ thường chính xác true hoặc false. Với worktree.root, value là một filesystem path; project scope chỉ chấp nhận relative path (resolve theo project root), còn user scope chấp nhận cả relative path (cũng resolve theo project root) lẫn absolute path. Với agent_models.<runtime>.<tier>, value là model ID sẽ được emit cho tier đó: một token không rỗng, chỉ kiểm tra hình dạng chứ không kiểm tra catalog có entry với ID đó hay không. Runtime hoặc tier bạn không ghi sẽ giữ default catalog tích hợp của adapter tương ứng.

ak config prefs set hooks.simplify-gate false
ak config prefs set hooks.simplify-gate true --scope project
ak config prefs set journal.auto false
ak config prefs set worktree.root /Volumes/Portable/agentkit-worktrees
ak config prefs set worktree.root ../my-app-worktrees --scope project
ak config prefs set agent_models.cursor.sonnet claude-sonnet-4-6
ak config prefs set semantic_decision.provider typesafe --scope user
ak config prefs set semantic_decision.enabled true --scope user

Key như keys.anthropic, api.token, telemetry.enabled, hooks.Bad-Name, hooks.a.b, mọi journal.<other>, mọi worktree.<other>, mọi agent_models.<runtime> khác cursor, mọi agent_models.<runtime>.<tier> không nằm trong tập tier ở trên, và mọi leaf semantic_decision không có trong danh sách trên (như semantic_decision.api_key) bị từ chối trước khi ghi preference. Allowlist này ngăn lệnh trở thành editor config hoặc secret tổng quát.

Với Hook toggle, false cho phép Hook có đọc preference này exit sớm ở lần chạy tiếp theo; true ghi preference ngược lại. Harness registration không đổi, và việc đặt tên không chứng minh Hook đó đã được cài.

Với journal.auto, false chặn bước /ak:journal tự động ở cuối các workflow plan, cook, fix, ship, bootstrap mà không unregister hooks và không chặn /ak:journal gọi tường minh. true ghi preference ngược lại. Default tích hợp là true.

Với worktree.root, value chọn vị trí mặc định mà ak:worktree dùng khi không truyền --worktree-root. Ghi absolute path ở project scope trả exit 1 và không ghi file. Khi đọc project config đã tồn tại, resolver mới cảnh báo và xét scope kế tiếp; config đã commit có thể đến từ clone không đáng tin. User scope chấp nhận absolute path, phù hợp cho layout worktree trên ổ portable hoặc volume ngoài. Default tích hợp là unset, nên ak:worktree tiếp tục fallback về biến môi trường WORKTREE_ROOT và chuỗi vị trí tích hợp sẵn.

Thiết lập semantic decision

Các key này điều khiển việc đánh giá ngữ nghĩa cần opt in do ak eval decision, ak eval triage, ak eval ui, ak eval workflow, ak test optimize và ak test classify-e2e thực hiện.

Sự đồng ý dùng provider thuộc user scope. Với --scope project, lệnh chỉ chấp nhận semantic_decision.enabled false và semantic_decision.consumers.<consumer> false; chúng thu hẹp quyền đã cấp ở user scope cho project đó. Mọi key hoặc value semantic khác ở project scope thoát 1 trước khi scaffold hay ghi config project. Hãy đặt semantic_decision.provider trước khi bật, vì policy user đã bật nhưng thiếu provider sẽ không hợp lệ khi được đánh giá.

Khi config user không có map consumers, chỉ domain-routing, fix-complexity và orchestration-risk được phép. Sáu consumer còn lại (skill-routing-eval, review-triage, workflow-controller, ui-regression, test-impact và e2e-classification) đều cần được đặt tường minh semantic_decision.consumers.<consumer> true ở user scope:

ak config prefs set semantic_decision.consumers.test-impact true --scope user

Scope và tác động filesystem

Writer chỉ thay leaf hooks.<name>, journal.auto, worktree.root, agent_models.<runtime>.<tier>, hoặc semantic_decision.* đã chọn. Các section khác, YAML chưa được model, comment, thứ tự key và schema editor directive được giữ lại. Nếu hooks, journal, hoặc worktree đã tồn tại nhưng không phải mapping, lệnh từ chối ghi.

Trước khi ghi, AgentKit validate toàn bộ candidate bằng schema nhúng trong binary. Cách viết cũ có thể tạo warning nhưng không tự làm validation thất bại; schema error giữ nguyên target hiện có.

Backup, atomicity và khôi phục

Khi target tồn tại, AgentKit sao chép byte hiện tại sang tệp mode 0600 dưới $AGENTKIT_HOME/backups/config/. Backup user bắt đầu bằng config-; backup project bắt đầu bằng project-config-. Lỗi backup sẽ huỷ thao tác ghi config.

Document mới được ghi vào sibling temporary file, đổi sang mode 0600, rồi rename lên target. Nhờ vậy, reader không thấy document chỉ được ghi một phần.

Để khôi phục, dừng writer khác, kiểm tra backup_path do lệnh thành công báo, thay thủ công config_path bằng backup đó rồi chạy ak config prefs validate. Các bản sao config này không phải snapshot AgentKit đầy đủ và không có lệnh rollback tự động.

Đầu ra dành cho người dùng và JSON

Kết quả dành cho người dùng ghi thay đổi và target path ra stdout, sau đó là backup path khi đã tạo:

set hooks.simplify-gate = false (user scope) in /home/user/.agentkit/config.yaml
backed up prior config to /home/user/.agentkit/backups/config/config-<timestamp>.yaml

--json ghi object thô, không phải success envelope dùng chung:

{
  "action":"set",
  "key":"hooks.simplify-gate",
  "value":false,
  "scope":"user",
  "config_path":"/home/user/.agentkit/config.yaml",
  "backup_path":"/home/user/.agentkit/backups/config/config-<timestamp>.yaml",
  "found":true
}

Giá trị boolean được báo trong value. Giá trị chuỗi, như worktree.root, model ID của agent, semantic_decision.provider hoặc semantic_decision.model, được báo trong value_string, còn semantic_decision.timeout_ms được báo trong value_int.

backup_path bị lược bỏ khi không tạo backup. found luôn là true với lần set thành công. --quiet không chặn stdout riêng của lệnh này.

Lỗi runtime không phát JSON error envelope dùng chung và có thể im lặng dưới --json; hãy dùng trạng thái process và validate các field mong đợi. Lỗi parse cờ có thể vẫn là hướng dẫn dùng dạng plain text. Sai số positional argument đi theo đường lỗi runtime chung.

Kết quả và mã thoát

Xác minh kết quả

ak config prefs resolve --json
ak config prefs validate

Với project scope, hãy chạy resolve từ cùng thư mục project đó để tệp project dự định tham gia đúng thứ tự ưu tiên.

Lệnh liên quan

• Quy ước CLI