ak migrate prefs

Dùng ak migrate prefs khi cài đặt .ck.json cũ vẫn còn, kể cả sau khi nội dung Kit đã được chuyển. Lệnh chỉ migrate preference; không di chuyển hoặc cài Kit.

Cách dùng

ak migrate prefs [flags]

Lệnh được công bố không có argument theo vị trí. Implementation hiện tại bỏ qua token theo vị trí thừa; đừng dựa vào hành vi này.

Tuỳ chọn

Apply yêu cầu cả --dry-run=false và --yes:

ak migrate prefs --dry-run=false --yes

Lệnh không hỏi hoặc đọc stdin. --json, --no-interactive và stdin không phải TTY không bỏ qua yêu cầu --yes rõ ràng. Các cờ đầu ra dùng chung nằm trong quy ước CLI.

Quyền quyết định nguồn và đích

Lệnh kiểm tra tối đa hai tệp cục bộ:

AGENTKIT_CLAUDE_HOME có thể đổi Claude home, còn AGENTKIT_HOME có thể đổi AgentKit home. Project scope luôn lấy từ thư mục làm việc hiện tại. Lệnh không dùng mạng, registry, xác thực, entitlement, provider, tiến trình ngoài hay cache.

Hiểu merge precedence

Mỗi tệp cũ đọc được trở thành plan gồm các action ở mức leaf:

• giá trị chưa có trong AgentKit được đánh dấu migrate;
• giá trị đã có trong config.yaml, kể cả null rõ ràng, là keep_existing và được ưu tiên;
• section cấp cao nhất đã biết được map sang tên section AgentKit;
• key cấp cao nhất chưa biết được giữ dưới extensions;
• giá trị giống credential ở project là omit_secret và không bao giờ được ghi vào project config.

Credential ở user scope không bị lược bỏ. Nếu preference user cũ có tên key chứa passphrase, password, secret, token, apikey hoặc api_key, apply có thể chép giá trị đó vào config.yaml của user. Writer đặt mode của tệp kết quả thành 0600.

Tệp .ck.json cũ luôn được giữ nguyên. Có thể chạy lại migration vì giá trị AgentKit hiện có luôn được ưu tiên.

Ghi dữ liệu, journal và rollback

Dry-run đọc cả hai scope và không ghi gì. Apply tạo thư mục config còn thiếu với quyền chỉ dành cho user rồi thay mỗi config atomically qua tệp tạm cùng thư mục.

Trước lần ghi config đầu tiên, AgentKit lưu pre-image của mọi đích vào một migration rollback journal. Nếu bất kỳ bước apply nào lỗi, journal được giữ để ak migrate rollback khôi phục tệp trước apply. Khi mọi lần ghi thành công, journal bị bỏ; ak migrate rollback không thể hoàn tác một preference migration đã hoàn tất.

Đầu ra human và JSON

Stdout dạng human báo từng nguồn và đích, số lượng migrate, keep_existing, credential bị lược bỏ và nguồn không đọc được. Không có nguồn là kết quả sạch nothing to migrate.

Một .ck.json lỗi hoặc không đọc được sẽ bị bỏ qua trong khi scope đọc được khác vẫn tiếp tục. Ngay cả khi mọi nguồn tìm thấy đều không đọc được, lệnh vẫn báo skipped và thoát 0; hãy coi skipped là một phần của kết quả, không phải tín hiệu lỗi fatal.

JSON stdout dùng map riêng của lệnh, không dùng shared envelope kind/data:

{
  "schema_version": 1,
  "prefs": {
    "schema_version": 1,
    "status": "planned",
    "plans": [
      {
        "schema_version": 1,
        "scope": "global",
        "source_path": "/home/you/.claude/.ck.json",
        "config_path": "/home/you/.agentkit/config.yaml",
        "entries": [
          {"legacy_path":"statusline","config_path":"statusline","action":"migrate"}
        ]
      }
    ]
  }
}

Status có thể là no_sources, planned hoặc completed. Plan không chứa giá trị preference, nhưng báo cáo human và JSON lộ path cục bộ; hãy che path trước khi chia sẻ log. Lỗi lệnh vẫn là plain text thay vì shared JSON error envelope.

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

Lệnh liên quan

• Thông tin đầy đủ của migration
• Migrate từ ClaudeKit
• Xử lý sự cố cấu hình