SKILL.md
技能名称
七牛云上传 + 服务端自动删除（生命周期）
技能标识
qiniu-upload-auto-delete
技能类型
文件存储 / 云上传 / 自动清理
技能介绍
上传本地文件到七牛云对象存储，核心支持设置服务端资源自动删除有效期（N天后七牛官方自动删除文件，不可恢复），返回永久访问地址（公开/私有可选），链接不会过期，文件删除后自动失效。
纯本地运行，无外部API依赖，安全可控，适配OCR手写图片、临时文件、隐私资料等场景，可替代Base64存储方案，大幅提升页面渲染效率和数据库性能，无需手动清理文件，实现资源自动生命周期管理。
核心功能
-
本地文件（图片、文档等任意格式）上传至七牛云对象存储
-
上传时可自定义设置资源自动删除天数，默认7天，支持覆盖默认配置
-
生成永久访问地址，支持公开/私有两种模式，私有链接需密钥签名
-
纯本地运行，无外部API依赖，安全可控，适配多系统（Linux/mac/Windows）
-
数据库仅需存储文件key，无需存储Base64，提升渲染效率和数据库性能
-
支持文件完整性校验（通过七牛返回的hash值）
依赖环境
-
运行环境：Node.js（任意稳定版本）
-
依赖包：qiniu（七牛官方SDK）
依赖安装命令：
npm install qiniu --save
安装方法
方法1：SkillHub一键安装
skillhub install qiniu-upload-auto-delete
方法2：本地ZIP包上传安装
-
新建文件夹
qiniu-upload-auto-delete -
放入IDENTITY.md、SOUL.md、SKILL.md、skill.js 4个文件
-
压缩文件夹为ZIP格式
-
访问 https://skillhub.cn → 技能管理 → 上传技能包 → 选择ZIP文件完成安装
全局配置说明
安装完成后需手动配置七牛云密钥信息，执行以下命令进入配置界面：
skill config qiniu-upload-auto-delete
配置格式（替换为自身七牛云信息）：
{
"accessKey": "你的七牛云AK",
"secretKey": "你的七牛云SK",
"bucket": "你的七牛对象存储空间名",
"domain": "你的七牛资源访问域名（带https，如：https://xxx.bkt.clouddn.com）",
"region": "存储区域（z0=华东，z1=华北，z2=华南，na0=北美，as0=东南亚）",
"defaultDeleteDays": 7 // 默认自动删除天数，建议≥1天
}
配置项说明：
-
accessKey：七牛云账号AK（登录七牛云控制台 → 个人中心 → 密钥管理获取）
-
secretKey：七牛云账号SK（同上）
-
bucket：对象存储空间名（七牛云对象存储 → 空间管理 → 空间名称）
-
domain：资源访问域名（七牛云对象存储 → 空间管理 → 域名管理 → 已绑定域名，带https）
-
region：存储机房区域（z0=华东，z1=华北，z2=华南，na0=北美，as0=东南亚）
-
defaultDeleteDays：默认自动删除天数（单位：天），建议设置≥1天
注意：七牛域名（https://xxx.bkt.clouddn.com）若出现「网页解析失败」报错，需检查域名是否已正确绑定七牛空间、是否开启HTTPS，以及域名是否在有效期内。
入参规范
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| filePath | string | 是 | 本地文件绝对路径，Linux/mac用/，Windows用\，如：/tmp/ocr-handwrite.png |
| deleteDays | number | 否 | 覆盖默认，指定N天后自动删除（服务端真删除） |
| isPrivate | boolean | 否 | 是否生成私有访问链接（默认false=公开），私有链接需签名访问 |
| # 调用示例 |
示例1：基础调用（默认7天删除，公开链接）
skill run qiniu-upload-auto-delete '{"filePath":"/tmp/ocr-image.png"}'
示例2：自定义配置（7天删除，私有链接）
skill run qiniu-upload-auto-delete '{
"filePath":"/tmp/handwrite.jpg",
"deleteDays":7,
"isPrivate":true
}'
出参规范
| 字段 | 说明 |
|---|---|
| key | 云端存储文件名，与本地文件名一致 |
| hash | 七牛文件唯一哈希值，用于校验文件完整性 |
| url | 永久访问地址（公开/私有），链接不会过期，文件删除后访问返回404 |
| deleteAfterDays | 实际设置的自动删除天数 |
| deleteAt | 预计删除时间戳（秒），可转换为本地时间 |
| deleteHuman | 格式化本地过期时间，便于直观查看（如：2026/4/23 16:00:00） |
| 出参示例： |
{
"key": "handwrite.jpg",
"hash": "Fs3Vxxxxxxxxxxxxxx",
"url": "https://xxx.bkt.clouddn.com/handwrite.jpg?e=1776998400&token=xxx",
"deleteAfterDays": 7,
"deleteAt": 1745555200,
"deleteHuman": "2026/4/23 16:00:00"
}
能力限制
-
仅支持本地文件上传，不支持base64直接传入
-
资源自动删除为七牛服务端规则，删除后不可恢复，请谨慎设置天数
-
单文件大小受七牛云单次上传限制（默认支持4GB以内，可通过七牛控制台调整）
-
私有链接依赖七牛密钥签名，密钥修改后，旧的私有链接会失效
-
七牛域名解析失败时，需检查域名绑定、HTTPS配置及域名有效期
最佳使用场景
-
OCR手写图片、截图临时存储，自动清理，节省七牛存储空间
-
隐私图片、内部资料存储，限时留存，防止长期泄露
-
替代Base64存储方案，数据库仅存文件key，提升页面渲染效率和数据库性能
-
临时文件、一次性资料上传，无需手动清理，实现自动过期删除
> （注：文档部分内容可能由 AI 生成）
