tos-file-access

TOS ファイルアクセス

このスキルでは、Volcano Engine または BytePlus の TOS 互換オブジェクトストレージにファイルやディレクトリをアップロードしたり、URL からファイルをダウンロードしたりするためのユーティリティを提供します。

概要

TOS 互換オブジェクトストレージは Volcano Engine と BytePlus で使用されており、AWS S3 に似ています。このスキルでは、次の操作ができます。

• アップロード：エージェントが生成したファイルまたはディレクトリ全体を TOS にアップロードし、共有可能な署名付き URL（ファイルの場合）または TOS パス（ディレクトリの場合）を取得します。
• ダウンロード：URL からファイルをダウンロードし、エージェントが処理できるようローカルストレージに保存します。

一般的なワークフロー

エージェント実行前：ユーザーファイルをダウンロードする

ユーザーからファイルの 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

エージェント実行後：出力ファイルまたはディレクトリをアップロードする

ファイルまたはディレクトリ（動画、グラフ、レポート、出力フォルダーなど）を生成した後、ユーザーがアクセスできるよう 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：ダウンロードする 1 つ以上の 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

**戻り値：**ダウンロードしたファイルの絶対パスを 1 行につき 1 つ出力します。

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 ロールのサポート：利用可能な場合、スクリプトは VeFaaS IAM から認証情報を自動的に取得します。
• エラー処理：ネットワーク、権限、ファイルに関する問題について、スクリプトは明確なエラーメッセージを表示します。
• バケットの指定：バケット名は --bucket パラメーターで指定する必要があります（必須）。
• エンドポイントの選択：TOS_REGION=ap-southeast-1 の場合は BytePlus が優先されます。それ以外では、CLOUD_PROVIDER=byteplus を指定すると BytePlus が選択されます。その他すべての場合は Volcano Engine が使用されます。