---
name: tencent-cos-upload
description: 上传文件到腾讯云COS并生成可直接访问的URL。当需要将本地文件（图片、视频、音频、文档等）上传到腾讯云对象存储，并获取公开可访问链接时使用。触发场景：上传文件到COS、生成文件外链、存储媒体资源、备份文件到云端。
---

# 腾讯云COS文件上传

将本地文件上传到腾讯云COS，返回可直接访问的URL。

## 前置依赖

```bash
pip3 install cos-python-sdk-v5 --break-system-packages
```

## 使用方式

### 方式一：调用脚本（推荐）

```bash
python3 scripts/cos_upload.py <local_file> <cos_key> [--content-type <mime_type>]
```

- `local_file`：本地文件路径
- `cos_key`：COS上的存储路径（如 `vala_llm/data/image.png`）
- `--content-type`：可选，MIME类型（如 `image/png`），不指定则自动检测

输出一行URL：`https://<domain>/<cos_key>`

示例：
```bash
python3 scripts/cos_upload.py /tmp/photo.png vala_llm/user_feedback/image/2026-04-10/abc123.png
# 输出: https://static.valavala.com/vala_llm/user_feedback/image/2026-04-10/abc123.png
```

### 方式二：Python代码引用

```python
import sys
sys.path.insert(0, '/root/.openclaw/skills/tencent-cos-upload/scripts')
from cos_upload import CosUploader

uploader = CosUploader()
url = uploader.upload('/tmp/photo.png', 'vala_llm/images/photo.png')
print(url)  # https://static.valavala.com/vala_llm/images/photo.png
```

批量上传：
```python
results = uploader.upload_batch([
    ('/tmp/a.png', 'path/a.png'),
    ('/tmp/b.mp4', 'path/b.mp4'),
])
# results = [('path/a.png', 'https://...'), ('path/b.png', 'https://...')]
```

## 配置

凭证从 `secrets.md` 的腾讯云COS部分读取，脚本中通过硬编码加载（非环境变量）。

如需修改配置（换桶、换域名），编辑 `scripts/cos_upload.py` 顶部的常量。

## COS路径规范

建议按 `{业务}/{类型}/{日期}/` 组织：
```
vala_llm/
├── user_feedback/
│   ├── image/2026-04-10/
│   ├── video/2026-04-10/
│   ├── audio/2026-04-10/
│   └── file/2026-04-10/
└── asr_audio_backup/
    ├── online/20260410/
    └── test/20260410/
```

## 文件名规范

- 避免中文，使用纯ASCII字符（字母、数字、短横线、下划线）
- 推荐格式：`{唯一ID}{扩展名}`，如 `abc123def456.png`

## 常见MIME类型

| 扩展名 | Content-Type |
|--------|-------------|
| .png | image/png |
| .jpg/.jpeg | image/jpeg |
| .mp4 | video/mp4 |
| .mov | video/quicktime |
| .mp3 | audio/mpeg |
| .ogg | audio/ogg |
| .wav | audio/wav |
| .pdf | application/pdf |