Projects, artifacts và checkpoints

AgentKit làm việc bên trong project thực, nơi nội dung được tạo ra và công việc sẵn có của bạn có thể nằm cạnh nhau. Mô hình an toàn dựa trên việc phân biệt các tệp cài đặt đã ghi nhận với tệp mà AgentKit không sở hữu.

Project là vị trí, không phải tuyên bố quyền sở hữu

Registry project của AgentKit theo dõi các thư mục được khởi tạo bằng ak new hoặc ak init; bạn cũng có thể chủ động thêm hoặc xóa entry trong registry. Registry giúp CLI tìm project. Đăng ký một thư mục không chuyển quyền sở hữu nội dung trong đó cho AgentKit.

Cài Kit theo scope project là một khái niệm riêng. Thao tác này ghi nội dung runtime được hỗ trợ cho workspace hiện tại và lưu metadata lifecycle cho bản cài đó. Cài theo scope người dùng sẽ ghi vào các vị trí người dùng của runtime được chọn. Xem Runtime adapter để hiểu các tổ hợp scope và cách phân phối.

Cấu hình nơi lưu docs và plan

Khi tiếp nhận một project hiện có, ak init --docs-dir <path> --plans-dir <path> lưu một hoặc cả hai giá trị vào .agentkit/config.yaml dưới dạng paths.docs và paths.plans. Cách này giúp AgentKit tránh layout docs/ hoặc plans/ có sẵn của project mà không nhận các thư mục đó làm nội dung cài đặt do AgentKit sở hữu.

Giá trị tương đối phải nằm trong project và không được trỏ vào cây .agentkit do AgentKit sở hữu. Giá trị paths.plans tương đối an toàn được dùng chung bởi các Skill Engineer, ak plan, journal, thao tác reindex và migration, cùng trình đọc plan của Desktop/dashboard. Với vị trí plan bị thiếu, sai định dạng, nằm ngoài project hoặc đi qua liên kết, các bề mặt Go native này fallback về plans/ mặc định.

Giá trị tuyệt đối được phép để hợp nhất nơi lưu artifact. Hook session-start của Engineer export giá trị tuyệt đối của paths.docs hoặc paths.plans nguyên vẹn trong CK_DOCS_PATH hoặc CK_PLANS_PATH; giá trị tương đối được resolve dưới project base của session. Cấu hình và các Skill dùng giá trị tuyệt đối, nhưng ak plan, journal và Desktop/dashboard chủ động fallback về plans/ trong project thay vì đọc một thư mục plan tuyệt đối.

AgentKit ghi nhận những gì

Với một Kit đã cài, AgentKit ghi nhận đường dẫn và fingerprint nội dung của các tệp nó đã tạo. Các thao tác lifecycle sau đó dùng dữ liệu này để phân loại tệp:

Ranh giới này cũng áp dụng cho cấu hình runtime dùng chung. AgentKit xóa hoặc cập nhật đăng ký mà nó xác định được là của mình và giữ cấu hình ngoài quyền sở hữu. Nếu CLI không chứng minh được quyền sở hữu, giữ nguyên là kết quả đúng.

Artifact thuộc về workflow và project

Workflow có thể tạo code, plan, report, hình ảnh hoặc các tệp khác. Đây là artifact, không tự động trở thành tệp cài đặt do AgentKit quản lý. Hãy review chúng bằng công cụ phù hợp với project—thường là editor, test và diff của hệ thống quản lý phiên bản.

Hãy xem output của model là một đề xuất cho đến khi bạn kiểm tra xong. Đặc biệt, cần review trước khi:

• Commit hoặc merge code;
• Publish nội dung hoặc liên hệ người khác;
• Gửi dữ liệu nhạy cảm đến dịch vụ bên ngoài;
• Chấp thuận hành động phá hủy hoặc có thể phát sinh chi phí.

Metadata cài đặt của AgentKit không thể quyết định một artifact có đúng, an toàn hay sẵn sàng để publish hay chưa.

Checkpoint và snapshot khôi phục

Checkpoint là thời điểm kiểm tra trạng thái trước khi tiếp tục. Với công việc trong project, đó có thể là plan đã được duyệt, các test tập trung đã pass hoặc diff đã được review. Với thao tác lifecycle của AgentKit, CLI còn tạo snapshot rollback trước các thay đổi được hỗ trợ như ghi đè bắt buộc, chuyển chế độ cài hoặc gỡ cài đặt.

Snapshot được lưu trong khu vực backup của AgentKit và có manifest các đường dẫn đã chụp. Đây là bản ghi khôi phục có scope, không phải bản backup đầy đủ cho repository hay thư mục runtime của bạn. Bỏ qua bằng --no-backup sẽ loại bỏ đường khôi phục đó và chỉ dành cho người dùng chấp nhận rủi ro.

Trước khi khôi phục, hãy kiểm tra snapshot và xem trước restore plan:

ak backups list
ak backups show <id>
ak backups verify <id>
ak backups restore <id> --dry-run

Restore hoạt động theo nguyên tắc replace-only: nó có thể ghi đè đường dẫn đã chụp và xóa đường dẫn được liệt kê rõ trong plan đã xác nhận, còn tệp không liên quan được tạo sau đó thường vẫn được giữ. Restore nhiều tệp không phải là một transaction; lỗi hệ thống có thể để lại trạng thái trung gian. Hãy review plan trước khi áp dụng và tạo snapshot mới trước nếu phù hợp.

Khôi phục project bundle yêu cầu một giá trị --allow-root chính xác cho mỗi root đã lưu mà ak backups show <id> hiển thị. Một số snapshot trong project cục bộ lại cần làm theo hướng dẫn khôi phục thủ công mà thao tác đã in ra; hãy giữ backup ID và đường dẫn được báo.

Vòng review an toàn

Luồng thay đổi đặt bước phân loại quyền sở hữu và bằng chứng khôi phục có scope giữa preview và thao tác ghi. Việc khôi phục vẫn chỉ giới hạn ở các đường dẫn bị ảnh hưởng; đây không phải object checkpoint hay rollback toàn bộ máy.

flowchart LR
  accTitle: Thay đổi và khôi phục có xét quyền sở hữu
  accDescr: Xem trước kế hoạch, phân loại quyền sở hữu tệp, lưu snapshot hoặc journal có scope, áp dụng thay đổi đã xác nhận, rồi audit hoặc chỉ khôi phục các tệp bị ảnh hưởng.
  preview["Xem trước kế hoạch"] --> ownership["Phân loại quyền sở hữu"]
  ownership --> record["Snapshot hoặc journal"]
  record --> mutate["Áp dụng thay đổi đã xác nhận"]
  mutate --> audit["Audit hoặc khôi phục có scope"]

1. Đọc preview của thao tác và cảnh báo từ adapter.
2. Giữ công việc không liên quan bằng hệ thống quản lý phiên bản hoặc bản backup riêng của bạn.
3. Để AgentKit tạo snapshot; không dùng --force như cách khôi phục thường lệ.
4. Chạy workflow và kiểm tra artifact được tạo.
5. Test hành vi đã thay đổi và review diff.
6. Chỉ sau đó mới commit, publish hoặc chấp thuận hành động bên ngoài.

Không khôi phục bằng cách xóa toàn bộ thư mục runtime home hoặc thư mục cấu hình của project. Hãy bắt đầu từ report của thao tác, trạng thái quyền sở hữu và manifest snapshot để việc khôi phục chỉ giới hạn ở các tệp bị ảnh hưởng.

Với lệnh backup và lifecycle chính xác, hãy dùng Tham chiếu CLI.