腾讯云对象存储上传，跨平台支持。

触发条件

• 用户要求上传文件到云存储
• 需要生成文件下载链接
• 备份本地文件到云端
• 需要公开分享文件（图片/文档）

前提条件

必需配置

TENCENT_COS_SECRET_ID=你的SecretId
TENCENT_COS_SECRET_KEY=你的SecretKey
TENCENT_COS_BUCKET=你的Bucket名称
TENCENT_COS_REGION=Bucket地域（如 ap-guangzhou）

Bucket 地域对照

跨平台用法

macOS / Linux（CLI 方式）

# 安装腾讯云 COS CLI
# pip 安装（Python 3.6+）
pip3 install cos-python-sdk-v5
# 上传文件（Python）
python3 << 'EOF'
from qcloud_cos import CosConfig, CosS3Client
import os
secret_id = os.getenv('TENCENT_COS_SECRET_ID')
secret_key = os.getenv('TENCENT_COS_SECRET_KEY')
bucket = os.getenv('TENCENT_COS_BUCKET')
region = os.getenv('TENCENT_COS_REGION')
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key)
client = CosS3Client(config)
# 上传
response = client.upload_file(
    Bucket=bucket,
    Key='filename.txt',
    LocalFilePath='/local/path/file.txt'
)
print(response['ETag'])
EOF
# 生成分享链接（3600秒有效期）
# 腾讯云 COS 控制台设置 bucket 公有读私有写或公有读写
# 链接格式：https://{bucket}.cos.{region}.myqcloud.com/{key}

Linux（CLI 方式）

# 安装 coscmd CLI 工具
pip3 install coscmd
# 配置（交互式）
coscmd config -a SECRET_ID -s SECRET_KEY -b BUCKET -r REGION
# 上传
coscmd upload /local/file.txt remote/path/file.txt
# 生成分享链接（需要 bucket 设置公有读）
coscmd generate-download-link remote/path/file.txt

Windows (PowerShell)

# 安装 Python（从 python.org 下载）
# 安装 SDK
pip install cos-python-sdk-v5
# 上传（Python）
python -c "
from qcloud_cos import CosConfig, CosS3Client
import os
config = CosConfig(
    Region=os.getenv('TENCENT_COS_REGION'),
    SecretId=os.getenv('TENCENT_COS_SECRET_ID'),
    SecretKey=os.getenv('TENCENT_COS_SECRET_KEY')
)
client = CosS3Client(config)
response = client.upload_file(
    Bucket=os.getenv('TENCENT_COS_BUCKET'),
    Key='filename.txt',
    LocalFilePath='C:\path\to\file.txt'
)
print(response['ETag'])
"

使用决策树

1. 用户要上传文件？
   → 确认文件路径和目标名称
是否有腾讯云配置？
   
→ 无 → 引导用户获取 SecretId/Key/Bucket
文件大小？
   
→ < 20MB → 直接上传
   → > 20MB → 分片上传
需要多久有效期？
   
→ 临时链接 → 预签名 URL（可设置过期时间）
   → 永久链接 → 公有读 bucket 设置

输出格式

## ☁️ 上传结果
文件名: example.txt
大小: 1.2 MB
Bucket: my-bucket
Region: ap-guangzhou
COS 路径: remote/path/example.txt
🔗 访问链接
直接下载（公有读 bucket）：
https://my-bucket.cos.ap-guangzhou.myqcloud.com/remote/path/example.txt
预签名链接（私有 bucket，7天有效）：
[生成签名链接]
预览（图片/文档）：
[在线预览链接]

注意事项

• 预签名链接可设置过期时间（建议临时文件用短过期时间）
• Bucket 设置公有读后，链接永久有效
• 敏感文件不要设置公有读，用预签名链接
• 分片上传适合大文件（> 20MB）
• 腾讯云 COS 费用：存储 0.118元/GB/月，流量 0.5元/GB

备选方案（无腾讯云账号）

如无腾讯云账号，可用以下免费方案：

• 飞书云盘：免费 10GB，直接通过 feishu_drive_file 上传
• 火山引擎 S3（Coze 环境）：通过 Coze TTS 插件的 S3Storage 上传