Skill: qianjunye/us3-uploader-encrypted (version 1.0.0)

--- name: us3-uploader description: | Upload files to UCloud US3 (UFile) object storage and generate download URLs. 当用户需要：上传文件、发送文件、分享文件、生成文件链接、把文件发给用户、导出文件、 生成PDF/图片/文档后发送、任何文件产出需要给用户时，必须使用此 skill。 沙箱内的文件用户无法直接访问，必须上传到 US3 生成下载链接。 metadata: | { "openclaw": { "always": true } } --- # US3 Uploader > [!CAUTION] > **强制要求 - 文件产出必须上传！** > > 如果任务产出的内容是**任何类型的文件**，包括但不限于： > - 图片（截图、生成的图片、处理后的图片等） > - 视频（录制、剪辑、转码后的视频等） > - PDF（生成的报告、转换的文档等） > - 其他文档（Word、Excel、PPT、代码压缩包等） > > **必须执行以下步骤：** > 1. 使用 `python3 scripts/upload_to_us3.py <文件路径>` 上传到 US3 > 2. 将生成的下载链接发送给用户 > > **禁止：** 只告诉用户"文件已保存在 /tmp/xxx"或本地路径。沙箱环境中的文件用户**完全无法访问**，必须上传后提供链接！ ## Overview Upload files to UCloud US3 (UFile) object storage using the official Python SDK and automatically generate download URLs with authentication signatures. ## Quick Start ### 1. Set Environment Variables ```bash export US3_PUBLIC_KEY='your-public-key' export US3_PRIVATE_KEY='your-private-key' export US3_BUCKET='bucket-name.region.ufileos.com' # full domain format (e.g., my-bucket.cn-bj.ufileos.com) export US3_MAX_FILE_SIZE_MB='50' # optional, defaults to 50MB ``` **Note:** If your `US3_BUCKET` contains the full domain (with dots), the endpoint will be automatically extracted. You don't need to set `US3_ENDPOINT` separately. ### 2. Upload a File ```bash python3 scripts/upload_to_us3.py <file_path> ``` ## Features - **Timestamp and MD5-based filename**: Files are uploaded with format `YYYYMMDD_HHMMSS_md5hash.ext` (e.g., `20260205_153025_a3b4c5d6e7f8g9h0.jpg`) - **File size limit**: Configurable max size (default 50MB), rejects larger files - **Signed download URLs**: Valid for 7 days with authentication - **Auto-install SDK**: Installs ufile SDK if not present - **Force download**: Sets Content-Disposition to download (not preview) - **Direct URL output**: Provides complete download URL directly to users ## Output Format The upload script will output the download URL directly for easy sharing: ``` Uploading screenshot.png to US3... Bucket: my-bucket Remote name: 20260205_153025_a3b4c5d6e7f8g9h0.png File size: 2.50MB ✓ Upload successful! 📋 Download URL (valid for 7 days): https://my-bucket.cn-sh2.ufileos.com/20260205_153025_a3b4c5d6e7f8g9h0.png?...signature... ℹ️ Note: - Click to download file directly (not preview) - URL contains authentication signature (required by US3) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📥 下载链接（7天内有效）： https://my-bucket.cn-sh2.ufileos.com/20260205_153025_a3b4c5d6e7f8g9h0.png?...signature... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` ## Getting UCloud Credentials 1. Log in to UCloud Console: https://console.ucloud.cn 2. Navigate to **API 密钥** (API Keys) 3. Create or view API keys 4. Copy Public Key and Private Key ### Create a Bucket 1. Go to **对象存储 US3** 2. Click **创建存储空间** (Create Bucket) 3. Enter unique bucket name 4. Select region (e.g., 上海 Shanghai) 5. Note the bucket endpoint ## Common Endpoints - Beijing: `cn-bj.ufileos.com` - Shanghai: `cn-sh2.ufileos.com` - Guangzhou: `cn-gd.ufileos.com` - Hong Kong: `hk.ufileos.com` ## Security Notes - ⚠️ Never commit credentials to version control - Keep API keys secure and private - Rotate API keys periodically

path: USAGE_EXAMPLE.md
content: # US3 Uploader - 使用示例

## 自动上传工作流

当 AI 完成文件处理后，会自动上传到 US3 并提供下载链接：

### 示例 1：处理图片后上传

```bash
# 1. 处理图片（例如：压缩、裁剪等）
convert input.jpg -resize 800x600 /tmp/processed_image.jpg

# 2. 自动上传到 US3
python3 scripts/upload_to_us3.py /tmp/processed_image.jpg

# 输出示例：
# Uploading processed_image.jpg to US3...
#   Bucket: your-bucket
#   Remote name: 20260205_153025_a3b4c5d6e7f8g9h0.jpg
#   File size: 0.50MB
#
# ✓ Upload successful!
#
# 📋 Download URL (valid for 7 days):
# https://your-bucket.cn-sh2.ufileos.com/20260205_153025_a3b4c5d6e7f8g9h0.jpg?UCloudPublicKey=...&Signature=...&Expires=...
#
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 📥 下载链接（7天内有效）：
# https://your-bucket.cn-sh2.ufileos.com/20260205_153025_a3b4c5d6e7f8g9h0.jpg?UCloudPublicKey=...&Signature=...&Expires=...
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 示例 2：生成 PDF 报告后上传

```bash
# 1. 生成 PDF 报告
pandoc report.md -o /tmp/monthly_report.pdf

# 2. 自动上传
python3 scripts/upload_to_us3.py /tmp/monthly_report.pdf
```

### 示例 3：批量上传文件

```bash
# 上传多个文件
for file in /tmp/processed_*.jpg; do
    python3 scripts/upload_to_us3.py "$file"
done
```

## 文件名格式说明

- **旧格式**（完整原文件名）：`20260204_153025_screenshot.jpg`
- **新格式**（时间戳+MD5）：`20260205_153025_a3b4c5d6e7f8g9h0.jpg`

新格式的优点：
- ✅ 时间戳便于按时间排序
- ✅ MD5 哈希确保唯一性（相同文件相同哈希）
- ✅ 避免文件名过长问题
- ✅ 防止特殊字符导致的路径问题
- ✅ 去重检测（相同内容的文件有相同 MD5）

## 下载链接特性

1. **有效期**：7天（604800秒）
2. **签名验证**：URL 包含 UCloud 签名，确保安全
3. **强制下载**：设置 `Content-Disposition` 头，点击直接下载而非预览
4. **原文件名**：下载时使用原始文件名，而非时间戳名称

## AI 使用指南

当 AI 需要给用户提供文件时：

1. **处理文件**（如果需要）
2. **上传到 US3**：
   ```bash
   python3 scripts/upload_to_us3.py <file_path>
   ```
3. **提取并发送下载链接**：
   - 从输出中找到最后的分隔线区域
   - 复制完整的 URL
   - 直接发送给用户

示例回复格式：
```
搞定！图片已处理完成（390KB → 28KB）

下载链接（7天有效）：
https://your-bucket.cn-sh2.ufileos.com/20260205_153025_a3b4c5d6e7f8g9h0.jpg?UCloudPublicKey=...&Signature=...&Expires=...
```

## 环境变量配置

确保已设置以下环境变量：

```bash
export US3_PUBLIC_KEY='your-public-key'
export US3_PRIVATE_KEY='your-private-key'
export US3_BUCKET='your-bucket-name'
export US3_ENDPOINT='cn-sh2.ufileos.com'  # 可选，默认值
export US3_MAX_FILE_SIZE_MB='50'          # 可选，默认 50MB
```


path: references/us3_config.md
content: # US3 CLI Configuration Guide

## Overview

This document explains how to install and configure us3cli (filemgr) for uploading files to UCloud US3 (UFile) object storage.

## Installation

### Download us3cli

**Official sources:**
- GitHub Releases: https://github.com/ucloud/us3cli/releases
- Official Documentation: https://docs.ucloud.cn/ufile/tools/us3cli/prepare

**Select the correct binary for your platform:**
- macOS: `filemgr-darwin` or `filemgr-mac`
- Linux: `filemgr-linux`
- Windows: `filemgr-windows.exe`

**Installation steps (macOS/Linux):**
```bash
# Download the binary (replace URL with latest version)
curl -L https://github.com/ucloud/us3cli/releases/download/vX.X.X/filemgr-darwin -o filemgr

# Make it executable
chmod +x filemgr

# Move to PATH (optional)
sudo mv filemgr /usr/local/bin/filemgr
```

**Verify installation:**
```bash
filemgr --help
```

## Configuration

### Required Credentials

You need the following from your UCloud account:

1. **Public Key** (API 公钥) - YOUR_PUBLIC_KEY_HERE
2. **Private Key** (API 私钥) - YOUR_PRIVATE_KEY_HERE
3. **Bucket Name** - your-bucket-name
4. **Endpoint** - cn-sh2.ufileos.com

### How to Get Credentials

You need to obtain your own credentials from UCloud console. See the section above for how to get them.

### Configure us3cli

Run the interactive configuration command:

```bash
filemgr-config --action putconfig
```

You will be prompted to enter:
- **Public Key**: Your API public key
- **Private Key**: Your API private key
- **Bucket Name**: Your bucket name
- **Endpoint**: Region endpoint (e.g., cn-bj.ufileos.com)
- **File Host**: Leave empty or press Enter

**Example configuration session:**
```
Please input your public key: TOKEN_xxxxx-xxxx-xxxx
Please input your private key: xxxxx-xxxx-xxxx-xxxx
Please input your bucket name: my-bucket
Please input your bucket endpoint: cn-bj.ufileos.com
Please input your file host (optional): [Press Enter]
```

The configuration is saved to `~/.us3cliconfig`

### View Current Configuration

```bash
filemgr-config --action getconfig
```

## Common Endpoints by Region

- **北京 Beijing**: `cn-bj.ufileos.com`
- **上海 Shanghai**: `cn-sh2.ufileos.com`
- **广州 Guangzhou**: `cn-gd.ufileos.com`
- **香港 Hong Kong**: `hk.ufileos.com`
- **新加坡 Singapore**: `sg.ufileos.com`
- **美国 US**: `us-ca.ufileos.com`

## Testing the Setup

Test by uploading a file:

```bash
filemgr --action put --bucket your-bucket --key test.txt --file /path/to/test.txt
```

Successful upload will show:
```
Put file test.txt success!!
```

## Download URL Format

After upload, files are accessible at:
```
https://{bucket}.{endpoint}/{filename}
```

Example:
```
https://my-bucket.cn-bj.ufileos.com/document.pdf
```

## Security Best Practices

- ⚠️ Never commit `.us3cliconfig` to version control
- Keep API keys secure and private
- Use `.gitignore` to exclude config files
- Rotate API keys periodically
- Use separate buckets for different environments (dev/prod)
- For public sharing, set bucket permissions to public-read

## Troubleshooting

**"filemgr: command not found"**
- Ensure the binary is executable: `chmod +x filemgr`
- Ensure it's in your PATH or use full path: `/path/to/filemgr`

**"Config file not found"**
- Run: `filemgr-config --action putconfig` to create configuration

**Upload fails with authentication error**
- Verify your API keys are correct
- Check if keys are still active in UCloud console
- Ensure bucket name and endpoint match your configuration


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)