ak config prefs set

Dùng ak config prefs set để ghim một soft-preference của Hook, preference journal.auto, hoặc mặc định worktree.root 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> <true|false>

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

Ba 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.

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.

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

Key như keys.anthropic, api.token, telemetry.enabled, hooks.Bad-Name, hooks.a.b, mọi journal.<other>, và mọi worktree.<other> 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. Project scope từ chối value là absolute path với warning và fall through xuống scope kế tiếp, vì project config được 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.

Scope và tác động filesystem

Writer chỉ thay leaf hooks.<name>, journal.auto, hoặc worktree.root đã 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
}

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