Dùng integration tương thích S3 ak:storage

Export ak-storage sở hữu định danh runtime riêng ak:storage. Dùng integration này để làm việc với asset marketing qua client tương thích S3 sau khi review credential, local path, object key, tác động provider và thay đổi dependency. Export ak-ckm-storage riêng hiện sở hữu ak:ckm-storage và vẫn là router với operation contract riêng.

Chọn ak:storage cho client integration

Scope integration được hỗ trợ

• Upload một tệp local tới object key đã chọn.
• Download một object tới local path đã duyệt.
• List object theo prefix tùy chọn.
• Remove một object hoặc kiểm tra object có tồn tại không.
• Tạo object URL từ cấu hình.
• Preview hoặc thực hiện sync đệ quy folder local.

Chọn workflow khác khi

• Bạn cần chính xác grammar subcommand list, sync, upload hoặc url của router ak:ckm-storage.
• Bạn cần tạo bucket, đổi bucket policy, signed URL, versioning, lifecycle rule, điều phối migration, retry hoặc transactional rollback.
• Bạn cần bảo đảm hỗ trợ theo provider. Provider được nêu tên mô tả intent tương thích, không phải behavior dịch vụ hiện tại đã xác minh.

Chuẩn bị credential và dependency có chủ đích

Giữ credential trong tệp environment local đã ignore, dùng credential giới hạn ở bucket theo least privilege và không dán hay in giá trị secret trong prompt hoặc output của Skill.

Integration lazy-load @aws-sdk/client-s3. Cài package bằng npm install @aws-sdk/client-s3 sẽ đổi dependency và lockfile của project hiện tại, vì vậy hãy review và duyệt mutation đó riêng với quyền truy cập storage. isConfigured() chỉ kiểm tra bốn variable bắt buộc có tồn tại hay không; hàm không xác minh SDK khả dụng, credential hợp lệ, connectivity, quyền bucket hay provider health. Thao tác dùng provider fail closed khi không thể tạo client và thường báo S3 not configured. Message chung đó không phân biệt thiếu SDK với thiếu cấu hình. getPublicUrl() vẫn tạo chuỗi mà không cần SDK hay provider request, còn sync dry run có thể scan và map tệp khi đã có cấu hình bắt buộc vì không upload.

Trạng thái định danh theo runtime

/ak:storage "Preview sync ./approved-assets tới campaign/launch, hiển thị mọi object key và chờ approval trước mọi upload"

/ak:storage "Preview sync ./approved-assets tới campaign/launch, hiển thị mọi object key và chờ approval trước mọi upload"

$ak:storage "Preview sync ./approved-assets tới campaign/launch, hiển thị mọi object key và chờ approval trước mọi upload"

Source Skill không định nghĩa positional subcommand kiểu router. Hãy nêu thao tác, local path, object key hoặc prefix cùng ranh giới approval trong yêu cầu. Chỉ dùng ak:ckm-storage khi bạn muốn dùng argument contract riêng của router đó.

Review contract thao tác client

Đây là function của integration client, không phải subcommand dành cho người dùng của router ak:ckm-storage. Upload và sync suy ra content type phổ biến; extension không biết dùng application/octet-stream.

Hiểu các giai đoạn integration

1. Đọc cấu hình từ environment variable mà không log giá trị secret.
2. Lazy-load AWS S3 SDK và tạo path-style client cho endpoint đã cấu hình.
3. Xác minh đủ trạng thái local cho thao tác đã chọn.
4. Gửi request tương ứng tới provider hoặc tạo URL mà không gửi request.
5. Trả kết quả theo từng thao tác: result object có cấu trúc cho thao tác provider, existence result cho exists(), hoặc chuỗi URL cho getPublicUrl(). Live sync upload từng tệp và giữ kết quả cho mỗi tệp.

Cloudflare R2, AWS S3, MinIO, Backblaze B2 và DigitalOcean Spaces được nêu làm ví dụ tương thích. Dạng endpoint, authentication, public access, availability, pricing và tác động billing vẫn cần được xác minh hiện tại với provider đã chọn.

Giữ approval và tác động bên ngoài rõ ràng

• Duyệt việc cài dependency riêng với sử dụng credential và truy cập storage.
• Coi destination download và source folder sync là ranh giới mutation workspace hoặc disclosure dữ liệu.
• Preview toàn bộ mapping tệp sang object trước recursive sync. Dry run scan folder local nhưng không upload.
• Coi remove là thao tác phá hủy. Yêu cầu key chính xác cùng approval rõ ràng; client không có recycle bin hay bước recovery tích hợp.
• URL từ getPublicUrl không chứng minh object tồn tại hay public. Việc tạo URL không đổi bucket policy.
• Client không cung cấp retry, transaction, rollback hay atomicity xuyên nhiều tệp. Sync thất bại có thể để lại các tệp trước đó đã upload thành công.

Xác minh bằng chứng thao tác

Một integration call đã review nên báo:

• thao tác đã chọn, bucket, endpoint host, local path và object key hoặc prefix mà không hiển thị credential;
• mapping preview trước recursive sync;
• success hoặc failure có cấu trúc theo từng object;
• tệp local chính xác được download, hoặc key được gửi tới DeleteObject cùng kết quả trả về;
• số lượng upload và failure cho sync, gồm cả partial failure;
• cách recovery thủ công cho mọi kết quả non-atomic.

Xử lý sự cố an toàn

Tiếp tục với Tổng quan Marketing Kit, Cài đặt Kit hoặc Runtime adapter.

Biết các giới hạn hiện tại

• ak:storage xác định integration; ak:ckm-storage xác định router riêng phụ thuộc client này.
• Integration expose thao tác client nhưng không có grammar positional argument riêng, nên yêu cầu phải nêu rõ thao tác và ranh giới.
• List chỉ gửi một request và không có pagination bằng continuation token.
• Sync tuần tự và non-atomic, không rollback upload đã hoàn tất.
• Tương thích provider là intent được ship, không phải bảo đảm hiện tại về support, public access, availability, pricing hay billing behavior.