@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

package/templates/.claude/skills/avatar-boot-starter-oss/SKILL.md

@@ -1,594 +1,76 @@
 ---
 name: avatar-boot-starter-oss
-description: 当涉及 OSS、对象存储、文件上传、文件下载、阿里云存储 相关功能时使用此技能 - 为 Spring Boot 3.5.3 应用提供基于阿里云 OSS SDK 3.18.1 的对象存储能力，包含文件上传下载、分片上传、签名 URL、STS 直传。
+description: Avatar Boot OSS 模块使用指南。当用户询问对象存储接入、文件上传下载、预签名URL、分片上传、文件路径规范、DB存储规范、FileKey编码，或需要接入 avatar-boot-starter-oss 时触发。支持阿里云OSS/MinIO/腾讯COS/AWS S3。
 ---
 
-Avatar Boot 的阿里云 OSS 对象存储集成模块，基于 aliyun-sdk-oss 3.18.1 提供开箱即用的文件上传、下载和管理能力。
+# Avatar Boot Starter OSS 使用指南
 
-## 功能特性
+你是 Avatar Boot OSS 模块的使用顾问与开发助手。
 
-- ✅ **自动配置** - 基于 Spring Boot 自动配置机制，自动装配 OSSClient
-- ✅ **简单上传** - 支持 putObject 方式上传文件和流
-- ✅ **分片上传** - 支持大文件分片上传，自动管理分片生命周期
-- ✅ **签名 URL** - 生成预签名 URL，支持临时授权访问
-- ✅ **STS 直传** - 支持客户端直传模式，减轻服务端带宽压力
-- ✅ **生命周期管理** - 支持配置文件自动过期和存储类型转换
+## 交互流程（必须遵守）
 
-## 快速开始
+**每次被触发时，先通过 AskUserQuestion 工具询问用户意图：**
 
-### 1. 添加依赖
+问题："您好！我是 Avatar Boot OSS 模块助手，请问您需要哪方面的帮助？"
+选项：
+1. **快速接入** - 添加依赖、配置 OSS 连接信息
+2. **文件上传** - 字节数组上传、本地文件上传、预签名前端直传
+3. **文件下载** - 预签名下载URL、本地下载、大文件分片下载
+4. **分片上传** - 前端大文件分片上传完整流程
+5. **规范说明** - 文件路径规范、DB存储规范、FileKey编码
 
-在项目的 `pom.xml` 中添加依赖：
+**根据用户选择，用 Read 工具按下方「文档读取路由」加载对应文档，然后给出具体指导。**
 
-```xml
-<dependency>
-    <groupId>com.iflytek.avatar.boot</groupId>
-    <artifactId>avatar-boot-starter-oss</artifactId>
-</dependency>
-```
-
-> 版本由 Avatar Boot BOM 统一管理，无需指定 version。内置 aliyun-sdk-oss 3.18.1。
-
-### 2. 配置文件
-
-在 `application.yml` 中添加 OSS 配置：
-
-```yaml
-aliyun:
-  oss:
-    endpoint: https://oss-cn-shanghai.aliyuncs.com   # OSS 端点
-    access-key-id: ${OSS_ACCESS_KEY_ID}              # AccessKey ID（从环境变量读取）
-    access-key-secret: ${OSS_ACCESS_KEY_SECRET}       # AccessKey Secret（从环境变量读取）
-    bucket-name: your-bucket-name                     # 默认 Bucket
-```
-
-**安全提醒**：AccessKey 信息禁止硬编码在配置文件中，必须通过环境变量或密钥管理服务注入。
-
-### 3. OSSClient 配置类
-
-```java
-package com.example.config;
-
-import com.aliyun.oss.OSS;
-import com.aliyun.oss.OSSClientBuilder;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-
-@Configuration
-public class OssConfig {
-
-    @Value("${aliyun.oss.endpoint}")
-    private String endpoint;
-
-    @Value("${aliyun.oss.access-key-id}")
-    private String accessKeyId;
-
-    @Value("${aliyun.oss.access-key-secret}")
-    private String accessKeySecret;
-
-    @Bean(destroyMethod = "shutdown")
-    public OSS ossClient() {
-        return new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
-    }
-}
-```
-
-## 文件上传
-
-### 简单上传（putObject）
-
-```java
-package com.example.service;
-
-import com.aliyun.oss.OSS;
-import com.aliyun.oss.model.ObjectMetadata;
-import com.aliyun.oss.model.PutObjectResult;
-import lombok.RequiredArgsConstructor;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.stereotype.Service;
-import org.springframework.web.multipart.MultipartFile;
-
-import java.io.InputStream;
-import java.time.LocalDate;
-import java.time.format.DateTimeFormatter;
-import java.util.UUID;
-
-@Slf4j
-@Service
-@RequiredArgsConstructor
-public class OssUploadService {
-
-    private final OSS ossClient;
-
-    @Value("${aliyun.oss.bucket-name}")
-    private String bucketName;
-
-    /**
-     * 上传文件
-     * @return 文件访问路径
-     */
-    public String uploadFile(MultipartFile file) {
-        // 生成文件路径：日期 + UUID
-        String objectKey = generateObjectKey(file.getOriginalFilename());
-
-        try (InputStream inputStream = file.getInputStream()) {
-            ObjectMetadata metadata = new ObjectMetadata();
-            metadata.setContentType(file.getContentType());
-            metadata.setContentLength(file.getSize());
-            // 设置自定义元数据
-            metadata.addUserMetadata("original-filename", file.getOriginalFilename());
-
-            PutObjectResult result = ossClient.putObject(bucketName, objectKey, inputStream, metadata);
-            log.info("文件上传成功: objectKey={}, etag={}", objectKey, result.getETag());
-
-            return objectKey;
-        } catch (Exception e) {
-            log.error("文件上传失败: filename={}", file.getOriginalFilename(), e);
-            throw new RuntimeException("文件上传失败", e);
-        }
-    }
-
-    /**
-     * 上传字符串内容
-     */
-    public String uploadContent(String content, String fileName) {
-        String objectKey = generateObjectKey(fileName);
-        ossClient.putObject(bucketName, objectKey, new java.io.ByteArrayInputStream(content.getBytes()));
-        return objectKey;
-    }
-
-    /**
-     * 生成文件路径：按日期分目录 + UUID 文件名
-     * 格式：upload/2026/03/09/uuid.ext
-     */
-    private String generateObjectKey(String originalFilename) {
-        String datePath = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
-        String ext = "";
-        if (originalFilename != null && originalFilename.contains(".")) {
-            ext = originalFilename.substring(originalFilename.lastIndexOf("."));
-        }
-        return String.format("upload/%s/%s%s", datePath, UUID.randomUUID().toString().replace("-", ""), ext);
-    }
-}
-```
-
-### 分片上传（Multipart Upload）
-
-```java
-@Service
-@RequiredArgsConstructor
-public class MultipartUploadService {
-
-    private final OSS ossClient;
-
-    @Value("${aliyun.oss.bucket-name}")
-    private String bucketName;
-
-    /**
-     * 分片上传大文件
-     * @param file 文件
-     * @param partSize 分片大小（字节），建议 5MB-100MB
-     */
-    public String multipartUpload(MultipartFile file, long partSize) {
-        String objectKey = "upload/" + LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"))
-                + "/" + UUID.randomUUID().toString().replace("-", "")
-                + getExtension(file.getOriginalFilename());
-
-        // 1. 初始化分片上传
-        InitiateMultipartUploadRequest initRequest =
-                new InitiateMultipartUploadRequest(bucketName, objectKey);
-        InitiateMultipartUploadResult initResult = ossClient.initiateMultipartUpload(initRequest);
-        String uploadId = initResult.getUploadId();
-        log.info("分片上传初始化: uploadId={}, objectKey={}", uploadId, objectKey);
-
-        try {
-            long fileSize = file.getSize();
-            int partCount = (int) Math.ceil((double) fileSize / partSize);
-            List<PartETag> partETags = new ArrayList<>();
-
-            InputStream inputStream = file.getInputStream();
-            for (int i = 0; i < partCount; i++) {
-                long startPos = i * partSize;
-                long curPartSize = Math.min(partSize, fileSize - startPos);
-
-                // 2. 上传分片
-                UploadPartRequest uploadPartRequest = new UploadPartRequest();
-                uploadPartRequest.setBucketName(bucketName);
-                uploadPartRequest.setKey(objectKey);
-                uploadPartRequest.setUploadId(uploadId);
-                uploadPartRequest.setInputStream(inputStream);
-                uploadPartRequest.setPartSize(curPartSize);
-                uploadPartRequest.setPartNumber(i + 1);
-
-                UploadPartResult uploadPartResult = ossClient.uploadPart(uploadPartRequest);
-                partETags.add(uploadPartResult.getPartETag());
-                log.info("分片 {}/{} 上传成功", i + 1, partCount);
-            }
-
-            // 3. 完成分片上传
-            CompleteMultipartUploadRequest completeRequest =
-                    new CompleteMultipartUploadRequest(bucketName, objectKey, uploadId, partETags);
-            ossClient.completeMultipartUpload(completeRequest);
-            log.info("分片上传完成: objectKey={}", objectKey);
-
-            return objectKey;
-        } catch (Exception e) {
-            // 取消分片上传，清理已上传的分片
-            ossClient.abortMultipartUpload(
-                    new AbortMultipartUploadRequest(bucketName, objectKey, uploadId));
-            log.error("分片上传失败，已取消: uploadId={}", uploadId, e);
-            throw new RuntimeException("分片上传失败", e);
-        }
-    }
-
-    private String getExtension(String filename) {
-        if (filename != null && filename.contains(".")) {
-            return filename.substring(filename.lastIndexOf("."));
-        }
-        return "";
-    }
-}
-```
-
-## 文件下载
-
-### 服务端下载
-
-```java
-@Service
-@RequiredArgsConstructor
-public class OssDownloadService {
-
-    private final OSS ossClient;
-
-    @Value("${aliyun.oss.bucket-name}")
-    private String bucketName;
-
-    /**
-     * 下载文件到字节数组
-     */
-    public byte[] downloadFile(String objectKey) {
-        try {
-            OSSObject ossObject = ossClient.getObject(bucketName, objectKey);
-            try (InputStream inputStream = ossObject.getObjectContent()) {
-                return inputStream.readAllBytes();
-            }
-        } catch (Exception e) {
-            log.error("文件下载失败: objectKey={}", objectKey, e);
-            throw new RuntimeException("文件下载失败", e);
-        }
-    }
-
-    /**
-     * 下载文件到 HttpServletResponse（浏览器下载）
-     */
-    public void downloadToResponse(String objectKey, String fileName,
-                                    HttpServletResponse response) {
-        try {
-            OSSObject ossObject = ossClient.getObject(bucketName, objectKey);
-            ObjectMetadata metadata = ossObject.getObjectMetadata();
-
-            response.setContentType(metadata.getContentType());
-            response.setContentLengthLong(metadata.getContentLength());
-            response.setHeader("Content-Disposition",
-                    "attachment; filename=" + URLEncoder.encode(fileName, StandardCharsets.UTF_8));
-
-            try (InputStream in = ossObject.getObjectContent();
-                 OutputStream out = response.getOutputStream()) {
-                in.transferTo(out);
-                out.flush();
-            }
-        } catch (Exception e) {
-            log.error("文件下载失败: objectKey={}", objectKey, e);
-            throw new RuntimeException("文件下载失败", e);
-        }
-    }
-}
-```
-
-### 生成预签名 URL
-
-```java
-@Service
-@RequiredArgsConstructor
-public class OssPresignedUrlService {
-
-    private final OSS ossClient;
-
-    @Value("${aliyun.oss.bucket-name}")
-    private String bucketName;
-
-    /**
-     * 生成下载预签名 URL（有效期 1 小时）
-     */
-    public String generateDownloadUrl(String objectKey) {
-        return generatePresignedUrl(objectKey, 3600, HttpMethod.GET);
-    }
-
-    /**
-     * 生成上传预签名 URL（有效期 10 分钟）
-     */
-    public String generateUploadUrl(String objectKey) {
-        return generatePresignedUrl(objectKey, 600, HttpMethod.PUT);
-    }
-
-    /**
-     * 生成预签名 URL
-     * @param expireSeconds 过期时间（秒）
-     */
-    public String generatePresignedUrl(String objectKey, int expireSeconds, HttpMethod method) {
-        Date expiration = new Date(System.currentTimeMillis() + expireSeconds * 1000L);
-
-        GeneratePresignedUrlRequest request =
-                new GeneratePresignedUrlRequest(bucketName, objectKey, method);
-        request.setExpiration(expiration);
-
-        URL url = ossClient.generatePresignedUrl(request);
-        log.info("生成预签名 URL: objectKey={}, expireSeconds={}", objectKey, expireSeconds);
-        return url.toString();
-    }
-}
-```
-
-## 文件命名策略
-
-**推荐的文件命名规则：**
-
-```
-{业务类型}/{年}/{月}/{日}/{UUID}.{扩展名}
-```
-
-| 场景 | 路径格式 | 示例 |
-|------|---------|------|
-| 用户头像 | `avatar/{yyyy}/{MM}/{dd}/{uuid}.jpg` | `avatar/2026/03/09/a1b2c3d4.jpg` |
-| 文档上传 | `document/{yyyy}/{MM}/{dd}/{uuid}.pdf` | `document/2026/03/09/e5f6g7h8.pdf` |
-| 临时文件 | `temp/{yyyy}/{MM}/{dd}/{uuid}.tmp` | `temp/2026/03/09/i9j0k1l2.tmp` |
-| 导出文件 | `export/{yyyy}/{MM}/{dd}/{uuid}.xlsx` | `export/2026/03/09/m3n4o5p6.xlsx` |
-
-**命名规范：**
-
-1. **使用 UUID 作为文件名**：避免文件名冲突和中文编码问题
-2. **按日期分目录**：便于管理和生命周期策略配置
-3. **保留原始扩展名**：便于浏览器识别文件类型
-4. **不使用原始文件名**：防止路径遍历攻击和特殊字符问题
-
-## 客户端直传（STS Token）
-
-### 获取 STS 临时凭证
-
-```java
-package com.example.service;
-
-import com.aliyuncs.DefaultAcsClient;
-import com.aliyuncs.auth.sts.AssumeRoleRequest;
-import com.aliyuncs.auth.sts.AssumeRoleResponse;
-import com.aliyuncs.profile.DefaultProfile;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.stereotype.Service;
-
-@Slf4j
-@Service
-public class StsTokenService {
-
-    @Value("${aliyun.oss.access-key-id}")
-    private String accessKeyId;
-
-    @Value("${aliyun.oss.access-key-secret}")
-    private String accessKeySecret;
-
-    @Value("${aliyun.oss.sts.role-arn}")
-    private String roleArn;
-
-    @Value("${aliyun.oss.sts.region-id:cn-shanghai}")
-    private String regionId;
-
-    /**
-     * 获取 STS 临时凭证
-     * @param sessionName 会话名称
-     * @param durationSeconds 有效期（秒），最短 900，最长 3600
-     */
-    public StsCredentials getStsToken(String sessionName, long durationSeconds) {
-        try {
-            DefaultProfile profile = DefaultProfile.getProfile(regionId, accessKeyId, accessKeySecret);
-            DefaultAcsClient client = new DefaultAcsClient(profile);
-
-            AssumeRoleRequest request = new AssumeRoleRequest();
-            request.setRoleArn(roleArn);
-            request.setRoleSessionName(sessionName);
-            request.setDurationSeconds(durationSeconds);
-
-            // 限制上传路径的策略
-            String policy = """
-                    {
-                      "Version": "1",
-                      "Statement": [
-                        {
-                          "Effect": "Allow",
-                          "Action": ["oss:PutObject"],
-                          "Resource": ["acs:oss:*:*:your-bucket-name/upload/*"]
-                        }
-                      ]
-                    }
-                    """;
-            request.setPolicy(policy);
-
-            AssumeRoleResponse response = client.getAcsResponse(request);
-            AssumeRoleResponse.Credentials credentials = response.getCredentials();
-
-            return new StsCredentials(
-                    credentials.getAccessKeyId(),
-                    credentials.getAccessKeySecret(),
-                    credentials.getSecurityToken(),
-                    credentials.getExpiration()
-            );
-        } catch (Exception e) {
-            log.error("获取 STS Token 失败", e);
-            throw new RuntimeException("获取 STS Token 失败", e);
-        }
-    }
-}
-```
-
-### 前端直传接口
-
-```java
-@RestController
-@RequestMapping("/api/oss")
-@RequiredArgsConstructor
-public class OssController {
-
-    private final StsTokenService stsTokenService;
-
-    @Value("${aliyun.oss.endpoint}")
-    private String endpoint;
-
-    @Value("${aliyun.oss.bucket-name}")
-    private String bucketName;
-
-    /**
-     * 获取前端直传凭证
-     */
-    @GetMapping("/sts-token")
-    public Result<Map<String, Object>> getStsToken() {
-        StsCredentials credentials = stsTokenService.getStsToken("web-upload", 900);
-
-        Map<String, Object> data = new HashMap<>();
-        data.put("accessKeyId", credentials.getAccessKeyId());
-        data.put("accessKeySecret", credentials.getAccessKeySecret());
-        data.put("securityToken", credentials.getSecurityToken());
-        data.put("expiration", credentials.getExpiration());
-        data.put("endpoint", endpoint);
-        data.put("bucket", bucketName);
-        data.put("dir", "upload/" + LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd")) + "/");
-
-        return Result.success(data);
-    }
-}
-```
-
-## 生命周期管理
-
-### 配置文件自动过期
-
-```java
-@Service
-@RequiredArgsConstructor
-public class OssLifecycleService {
-
-    private final OSS ossClient;
-
-    @Value("${aliyun.oss.bucket-name}")
-    private String bucketName;
-
-    /**
-     * 配置临时文件 7 天后自动删除
-     */
-    public void setupTempFileLifecycle() {
-        SetBucketLifecycleRequest request = new SetBucketLifecycleRequest(bucketName);
-
-        LifecycleRule rule = new LifecycleRule();
-        rule.setId("auto-delete-temp");
-        rule.setPrefix("temp/");
-        rule.setStatus(LifecycleRule.RuleStatus.Enabled);
-        rule.setExpirationDays(7);  // 7 天后删除
-
-        request.setLifecycleRules(List.of(rule));
-        ossClient.setBucketLifecycle(request);
-        log.info("临时文件生命周期规则已配置：7 天后自动删除");
-    }
-}
-```
-
-## 最佳实践
-
-### 1. 安全
-
-- **AccessKey 安全**：禁止硬编码，使用环境变量或密钥管理服务
-- **最小权限**：STS Token 限制具体的 Bucket 和路径
-- **Bucket 权限**：设为私有（private），通过签名 URL 访问
-- **上传校验**：校验文件类型和大小，防止恶意文件上传
-
-### 2. 性能
-
-- **大文件分片上传**：超过 100MB 的文件使用分片上传
-- **客户端直传**：使用 STS Token 方式，减轻服务端带宽压力
-- **CDN 加速**：静态资源配合 CDN 使用，降低 OSS 流量成本
-- **OSSClient 复用**：OSSClient 是线程安全的，全局复用，不要每次 new
-
-### 3. 可靠性
-
-- **异常处理**：捕获 OSSException 和 ClientException 分别处理
-- **分片上传清理**：失败时调用 abortMultipartUpload 清理碎片
-- **签名 URL 有效期**：下载 URL 1 小时，上传 URL 10 分钟
-- **文件存在性检查**：下载前使用 `doesObjectExist()` 检查
-
-### 4. 成本
-
-- **生命周期管理**：临时文件和日志设置自动过期
-- **存储类型**：不常访问的文件转为低频或归档存储
-- **签名 URL 替代公开访问**：避免 Bucket 设为 public-read
-
-## 常见问题
-
-### 1. AccessDenied（权限拒绝）
-
-**原因**：AccessKey 权限不足或 Bucket 策略限制
-
-**解决**：
-- 检查 AccessKey 是否有 OSS 操作权限
-- 检查 Bucket Policy 和 ACL 配置
-- STS Token 检查 Policy 中的 Resource 和 Action 是否匹配
-- 确认 AccessKey 未被禁用或过期
-
-### 2. 上传超时
-
-**原因**：文件过大或网络不稳定
+---
 
-**解决**：
-- 大文件（>100MB）使用分片上传
-- 增大 OSSClient 超时配置
-- 检查网络带宽和稳定性
-- 使用客户端直传减轻服务端压力
+## 行为准则
 
-### 3. 签名 URL 无法访问
+1. **回答要具体**：引用具体的方法名、配置项
+2. **主动提醒**：
+   - AK/SK 必须通过环境变量注入，禁止明文写入代码
+   - DB 中只存 `{bucket}/{filekey}`，不存完整 URL
+   - 临时文件（temp/）用完必须主动删除
+3. **使用中文回答**
 
-**原因**：URL 已过期或签名方式不匹配
+---
 
-**解决**：
-- 检查 URL 过期时间设置
-- 确保生成 URL 时的 endpoint 与实际访问一致
-- 检查是否使用了 HTTPS（endpoint 和访问方式要一致）
-- 验证 Bucket 名称和 objectKey 是否正确
+## 文档读取路由
 
-### 4. 分片上传碎片清理
+> 所有路径相对于 skill 目录 `docs/skills/avatar-boot-starter-oss-skill/`
 
-**原因**：分片上传未完成或失败后碎片未清理
+| 用户需求 | 需读取的文件 |
+|:--|:--|
+| 快速接入 / 配置说明 | `references/快速接入与配置.md` |
+| 文件上传 / 下载 / 分片上传 | `references/核心功能.md` |
+| 规范说明 / 注意事项 | `references/规范与注意事项.md` |
 
-**解决**：
-- 上传失败时调用 `abortMultipartUpload` 清理
-- 配置 Bucket 生命周期规则自动清理碎片
-- 定期检查未完成的分片上传任务并清理
+---
 
-### 5. 文件名中文乱码
+## 通用参考信息
 
-**原因**：文件名编码问题
+### 支持的 OSS 类型
 
-**解决**：
-- 使用 UUID 作为 OSS objectKey，不使用中文文件名
-- 原始文件名存储在数据库或 OSS 元数据中
-- 下载时通过 Content-Disposition 设置文件名，注意 URL 编码
+| type 值 | 说明 | 预签名URL特性 |
+|:--|:--|:--|
+| `ALIOSS` | 阿里云 OSS | signedHeaders 为空，URL 可直接浏览器访问 |
+| `MINIO` | MinIO | 可能含 x-amz-te header，需客户端携带 |
+| `TXCOS` | 腾讯 COS | 同 MinIO |
+| `AWS3` | AWS S3 | 同 MinIO |
 
-## 依赖版本
+### 签名URL有效期建议
 
-- aliyun-sdk-oss: 3.18.1
-- Spring Boot: 3.5.3
-- Java: 21
+| 场景 | 建议有效期 |
+|:--|:--|
+| 视频播放 | 2~4 小时 |
+| 文件下载 | 15~30 分钟 |
+| 封面图/缩略图 | 1~2 小时 |
+| 预签名上传 | 30~60 分钟 |
 
-## 参考文档
+### OssFileKeyHelper 路径格式
 
-- [阿里云 OSS Java SDK 文档](https://help.aliyun.com/document_detail/32008.html)
-- [阿里云 OSS 最佳实践](https://help.aliyun.com/document_detail/31850.html)
-- [STS 临时授权访问](https://help.aliyun.com/document_detail/100624.html)
+| 方法 | 格式 |
+|:--|:--|
+| `materialKey(tenantId, filename)` | `materials/{tenantId}/{yyyy}/{MM}/{dd}/{uuid}/{filename}` |
+| `videoKey(tenantId, taskId, filename)` | `videos/{tenantId}/{yyyy}/{MM}/{dd}/{taskId}/{filename}` |
+| `tempKey(serviceName, taskId, filename)` | `temp/{serviceName}/{yyyy}/{MM}/{dd}/{taskId}/{filename}` |
+| `staticKey(version, filename)` | `static/{version}/{filename}` |