用途
ve-tos-cli 用于火山引擎 TOS 对象存储相关工作。当用户要求 AI 智能体检查、配置、列举、上传、下载、同步或执行其他 TOS 存储操作时，可触发该技能。
前置检查与安装
在使用前应先用 ve-tos-cli --version 检查工具是否可用，然后规划命令；除非用户提供明确路径，否则使用 PATH 中第一个匹配的可执行文件。如果二进制文件缺失，则不应运行任何存储操作。
若 ve-tos-cli --version 失败且用户需要安装帮助，可建议以下安装方式之一：
- cargo install ve-tos-cli
- npm install -g ve-tos-cli
- pip install ve-tos-cli
- brew tap volcengine/ve-storage-uni-cli https://github.com/volcengine/ve-storage-uni-cli
- brew install ve-tos-cli
- winget install ve-tos-cli
- curl -fsSL https://github.com/volcengine/ve-storage-uni-cli/releases/latest/download/install.sh | sh -s -- ve-tos-cli
在执行写入、删除、移动、覆盖、同步、更改配置或暴露签名 URL 等命令前，需要先阅读 references/safety.md。
能力发现
可使用以下命令查看能力、诊断环境和查看配置：
- ve-tos-cli capabilities --view compact --output json
- ve-tos-cli doctor --output json
- ve-tos-cli config show --output json
连接配置
ve-tos-cli config init 会写入生产默认值 cn-beijing 和 tos-cn-beijing.volces.com。如果这些默认值被替换，需要显式配置 endpoint；CLI 从不会根据 region 自动构造 endpoint。可识别的 endpoint 仍可提供签名 region，而自定义 endpoint 需要显式指定 region。
示例命令：
- ve-tos-cli config init
- ve-tos-cli config set access_key_id <volcengine-tos-access-key>
- ve-tos-cli config set secret_access_key <volcengine-tos-secret-key>
- ve-tos-cli config set endpoint https://tos-cn-shanghai.volces.com
裸 AK/SK 密钥存储在活动 profile 的 [profile.ve-tos] credentials 段中，与 tos-cli 凭据相互独立。
认证模式
ve-tos-cli 支持 aksk 或 unified 两种认证模式。优先级顺序为：--auth-mode > [profile.ve-tos].auth_mode > TOS_AUTH_MODE > aksk。
Unified 模式会从外部登录框架中选择同名 profile，忽略本地 AK/SK，且不会将外部凭据复制到 TOS 配置中。可使用 ve login 创建或刷新该外部登录；CLI 仅在发起 HTTP 请求时向 SDK 请求签名凭据。
相关示例命令：
- ve-tos-cli --profile default --auth-mode unified ls
- ve-tos-cli config set auth_mode unified
- ve login
- ve-tos-cli doctor --check auth --profile default
常用命令
- ve-tos-cli ls tos://bucket/prefix/ --output json
- ve-tos-cli stat tos://bucket/key --output json
- ve-tos-cli cp ./file.txt tos://bucket/file.txt --dry-run
- ve-tos-cli sync ./dir tos://bucket/prefix/ --dry-run
- ve-tos-cli presign tos://bucket/key --expires 3600 --output json
当不确定某个命令的参数时，可使用 ve-tos-cli <command> --help 查询。
适用场景与限制
该技能适用于需要通过命令行或 AI 智能体操作火山引擎 TOS 对象存储的场景，包括列举对象、查看对象信息、上传、下载、同步、生成预签名 URL 以及配置和诊断连接信息。
限制方面：在二进制文件缺失时不得执行存储操作；写入、删除、移动、覆盖、同步、更改配置或暴露签名 URL 前必须先阅读安全文档；endpoint 不会被自动从 region 构造，自定义 endpoint 需显式指定 region；unified 模式会忽略本地 AK/SK。其他关于计费、价格、平台支持范围或效果的信息，现有资料暂未提供。