tos-file-access

TOS 文件访问

此技能提供实用工具，可将文件和目录上传到 Volcano Engine 或 BytePlus 的 TOS 兼容对象存储，并从 URL 下载文件。

概述

TOS 兼容对象存储由 Volcano Engine 和 BytePlus 使用，类似于 AWS S3。此技能支持：

• 上传：将 Agent 生成的文件或整个目录上传到 TOS，并获取可分享的签名 URL（用于文件）或 TOS 路径（用于目录）
• 下载：从 URL 下载文件到本地存储，以供 Agent 处理

典型工作流

Agent 执行前：下载用户文件

当用户提供文件 URL（TOS 或外部 URL）时，请在处理前下载：

# Download single file
python scripts/file_download.py https://example.com/data.csv

# Download multiple files
python scripts/file_download.py https://example.com/data.csv https://example.com/config.json

# Specify save directory and filenames
python scripts/file_download.py https://example.com/data.csv --save-dir /workspace --filenames dataset.csv

Agent 执行后：上传输出文件或目录

生成文件或目录（视频、图表、报告、输出文件夹等）后，将其上传到 TOS，供用户访问：

# Upload single file (auto-detected)
python scripts/tos_upload.py /path/to/output.mp4 --bucket my-bucket

# Upload entire directory (auto-detected)
python scripts/tos_upload.py /path/to/output_folder --bucket my-bucket

# Upload to BytePlus with custom expiration
TOS_REGION=ap-southeast-1 python scripts/tos_upload.py /path/to/report.pdf --bucket my-bucket --expires 86400

脚本

scripts/file_download.py

从 URL 下载文件到本地存储。

用法：

python scripts/file_download.py <url1> [url2 ...] [--save-dir DIR] [--filenames NAME1 NAME2 ...]

参数：

• urls：一个或多个要下载的 URL（位置参数，必填）
• --save-dir：保存目录（可选，默认为 /tmp）
• --filenames：下载文件的自定义文件名（可选，必须与 URL 数量一致）

示例：

# Download single file to /tmp
python scripts/file_download.py https://tos-cn-beijing.volces.com/bucket/file.pdf

# Download to specific directory
python scripts/file_download.py https://example.com/data.json --save-dir /workspace/data

# Download multiple files with custom names
python scripts/file_download.py \
  https://example.com/file1.pdf \
  https://example.com/file2.jpg \
  --save-dir /workspace \
  --filenames document.pdf image.jpg

**返回：**打印下载文件的绝对路径（每行一个）

scripts/tos_upload.py

将文件或目录上传到 TOS，并生成签名访问 URL（用于文件）或 TOS 路径（用于目录）。

主要功能：

• 自动检测：自动检测路径是文件还是目录
• 基于会话的路径：使用 TOOL_USER_SESSION_ID 环境变量整理上传内容
• 保留结构：对于目录，在 TOS 中保留完整目录结构
• 自动创建存储桶：如果存储桶不存在，则创建存储桶（使用私有 ACL）

用法：

python scripts/tos_upload.py <path> --bucket BUCKET [--region REGION] [--expires SECONDS]

参数：

• path：要上传的本地文件或目录路径（位置参数，必填）
• --bucket：TOS 存储桶名称（必填）
• --region：TOS 区域（可选，默认使用 TOS_REGION、DATABASE_TOS_REGION，或提供商默认值：BytePlus 使用 ap-southeast-1，Volcano Engine 使用 cn-beijing）
• --expires：签名 URL 的有效期，单位为秒（可选，默认为 604800，即 7 天；仅适用于文件上传）

上传结构：

• 文件：upload/{session_prefix}/{filename}
  • 示例：upload/skill_agent_veadk_default_user_tmp-session-20251210150057/video.mp4
• 目录：upload/{session_prefix}/{directory_name}/{relative_path}
  • 示例：upload/skill_agent_veadk_default_user_tmp-session-20251210150057/output_folder/file1.txt

会话前缀：

• 如果设置了 TOOL_USER_SESSION_ID，则使用该值作为前缀
• 否则，回退到时间戳格式 YYYYMMDD_HHMMSS

云服务提供商和身份验证： 需要满足以下条件之一：

• TOS_REGION=ap-southeast-1 时，优先选择 BytePlus 端点
• 当 TOS_REGION 不是 ap-southeast-1 时，CLOUD_PROVIDER=byteplus 会选择 BytePlus 端点
• 环境变量：VOLCENGINE_ACCESS_KEY 和 VOLCENGINE_SECRET_KEY
• VeFaaS IAM 角色（自动获取凭证）

示例：

# Upload single file (auto-detected)
python scripts/tos_upload.py /workspace/output.mp4 --bucket my-bucket

# Upload entire directory (auto-detected)
python scripts/tos_upload.py /workspace/results_folder --bucket my-bucket

# Upload to BytePlus with 1-day expiration
TOS_REGION=ap-southeast-1 python scripts/tos_upload.py /workspace/report.pdf \
  --bucket my-reports \
  --expires 86400

# Upload directory with all options
python scripts/tos_upload.py /workspace/output_dir \
  --bucket data-storage \
  --region cn-beijing

返回：

• 文件：打印可分享给用户的签名 URL（在指定时长内有效）
• 目录：打印格式为 tos://bucket-name/path/to/directory 的 TOS 路径

输出示例：

# File upload output
============================================================
✅ Upload Successful!
============================================================
Signed URL:
https://my-bucket.tos-cn-beijing.volces.com/upload/skill_agent_xxx/video.mp4?X-Tos-Signature=...
============================================================

# Directory upload output
============================================================
✅ Upload Successful!
============================================================
TOS Path:
tos://my-bucket/upload/skill_agent_xxx/output_folder
============================================================

环境变量

• TOS_REGION：TOS 区域（可选）。ap-southeast-1 表示选择 BytePlus 端点。
• CLOUD_PROVIDER：云服务提供商（可选）。当 TOS_REGION 不是 ap-southeast-1 时，byteplus 表示选择 BytePlus 端点；否则使用 Volcano Engine 端点。
• VOLCENGINE_ACCESS_KEY：对象存储身份验证用的访问密钥
• VOLCENGINE_SECRET_KEY：对象存储身份验证用的秘密密钥
• DATABASE_TOS_REGION：当未提供 --region 和 TOS_REGION 时使用的备用区域（可选）
• TOOL_USER_SESSION_ID：用于生成有序上传路径的会话 ID（可选，默认为时间戳）

常见用例

1. 视频处理：下载源视频 → 处理 → 上传结果

   # Download
   python scripts/file_download.py https://example.com/input.mp4 --save-dir /workspace
   # Process video (your code here)
   # Upload result
   python scripts/tos_upload.py /workspace/output.mp4 --bucket video-storage
   

2. 数据分析：下载数据集 → 分析 → 上传图表/报告文件夹

   # Download data
   python scripts/file_download.py https://example.com/data.csv --save-dir /workspace
   # Analyze and generate charts (your code here)
   # Upload entire results folder
   python scripts/tos_upload.py /workspace/analysis_results --bucket analysis-bucket
   

3. 批量处理：处理多个文件并上传输出目录

   # Process files (your code here, generates /workspace/batch_output/)
   # Upload entire output directory
   python scripts/tos_upload.py /workspace/batch_output --bucket batch-results
   

4. 项目导出：上传完整的项目目录结构

   # Upload project directory with subdirectories
   python scripts/tos_upload.py /workspace/my_project --bucket project-storage
   # Result: tos://project-storage/upload/{session_id}/my_project/...
   

错误处理

• 如果脚本报错 VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY are not provided or IAM Role is not configured.，请告知用户需要提供环境变量 VOLCENGINE_ACCESS_KEY 和 VOLCENGINE_SECRET_KEY。将其写入工作区中的环境变量文件。如果文件已存在，则追加到末尾。确保环境变量格式正确并生效，然后重试刚才失败的任务。

注意事项

• 自动检测：无需指定要上传文件还是目录，脚本会自动检测
• 会话整理：文件和目录会按会话 ID 自动整理，便于追踪
• 签名 URL（仅限文件）：默认有效期为 7 天（可通过 --expires 调整）
• TOS 路径（目录）：以 tos://bucket/path 格式返回，供参考
• 保留结构：上传目录时会在 TOS 中保留完整的文件夹结构
• 文件名不含时间戳：保留原始文件名（会话前缀可确保唯一性）
• 自动创建存储桶：如果存储桶不存在，则会自动创建并设置为私有 ACL
• 自动去重：如果文件已存在，下载时会自动重命名
• 支持 IAM Role：如果可用，脚本会自动从 VeFaaS IAM 获取凭据
• 错误处理：脚本会针对网络、权限或文件问题打印清晰的错误消息
• 存储桶要求：必须通过 --bucket 参数指定存储桶名称（必需）
• 端点选择：TOS_REGION=ap-southeast-1 时优先选择 BytePlus。否则，CLOUD_PROVIDER=byteplus 时选择 BytePlus。其他所有情况均使用 Volcano Engine。