/byted-volcengine-tosutil

name: "byted-volcengine-tosutil"
description: "围绕火山引擎对象存储 tosutil 生成与校验命令、规划桶/对象操作并诊断错误。用户提到 tosutil、TOS 桶对象管理、批量上传下载或相关排障时调用。"

火山引擎 tosutil Skill

这个 Skill 面向火山引擎对象存储 TOS 的 `tosutil` 命令行工具，负责把用户意图转换成安全、可执行、可校验的 `tosutil` 操作流程。

目标一句话

把“要对 TOS 做什么操作”的需求，转换成**默认只预览**的 `tosutil` 命令，并在需要执行时输出**结构化 JSON 结果 + 可复现证据 + 可诊断建议**。

输入与输出

• 输入：目标命令（如 `ls/cp/rm/du/setmeta`）+ 最少必要参数（如 `tos://` 地址、本地路径、递归开关）+ 可选公共参数（`endpoint/region/credentials/conf`）。
• 输出：统一 JSON 协议（`ok/code/message/data/ts`），包含 `preview.shell`（脱敏后的可复现命令）、执行摘要、失败时的 `advice.code` 与 `next_actions`。

默认行为（降低用户成本 + 安全）

• 默认只生成命令预览，不执行（需要显式 `--run` 才会执行）。
• 破坏性命令（例如 `rm`）默认不执行：必须显式 `--yes`（或 legacy 模式下 `--assume-yes`）才会真正运行。
• 输出默认脱敏：不会回显 AK/SK/Token。

何时使用

当用户要求以下任一场景时调用本 Skill：

• 使用 `tosutil` 初始化或更新 TOS 配置
• 创建桶、列举桶/对象、查询对象属性
• 上传、下载、复制、批量删除对象
• 计算对象容量、设置对象元数据
• 分析 `Http status [403]`、连通性失败、命令参数错误等问题
• 为 `share`、`set-acl`、`mount`、`probe`、`netdig` 等高级命令生成执行方案

文档事实基线

基于 `tosutil` 文档体系，可确认以下事实：

• `tosutil` 是访问和管理火山引擎对象存储 TOS 的命令行工具，适合本地与 TOS 之间的批量数据处理、脚本集成和中小数据迁移。
• 核心命令包括 `ls`、`mkdir`、`du`、`mb`、`cp`、`setmeta`、`stat`、`rm`、`share`、`set-acl`、`mount`。
• 辅助命令包括 `config`、`help`、`probe`、`netdig`、`hash`、`fcp`、`clear`、`version`、`ping`、`connect`、`traceroute`、`curl`。
• 初始化配置支持永久密钥、STS 临时密钥和匿名访问三种方式。
• 初始化时应使用 TOS 协议域名，而不是 S3 协议域名。
• `rm` 默认存在二次确认；递归和批量删除必须显式评估风险。
• `du` 在百万级对象下可能耗时较长，优先按目录拆分计算。

下载与安装

`tosutil` 支持 Windows、Linux 和 macOS。使用本 Skill 前，建议先根据当前操作系统与芯片架构下载对应版本，并完成执行权限设置。

官方下载建议

• Linux amd64：支持直接下载二进制并执行
• macOS amd64（Intel）：支持直接下载二进制并执行
• macOS arm64（Apple M 系列芯片）：支持直接下载二进制并执行
• Windows 64bit：下载 `tosutil.exe`
• 官方同时提供对应的 `sha256` 校验文件，建议下载后做完整性校验
• 当前 `tosutil` 最新版本主要适用于 Windows、macOS 和 Linux amd 系统

安装命令

Linux：

wget https://m645b3e1bb36e-mrap.mrap.accesspoint.tos-global.volces.com/linux/amd64/tosutil
chmod a+x tosutil
sudo mv tosutil /usr/local/bin

macOS Intel：

wget https://m645b3e1bb36e-mrap.mrap.accesspoint.tos-global.volces.com/darwin/amd64/tosutil
chmod a+x tosutil
sudo mv tosutil /usr/local/bin

macOS Apple Silicon：

wget https://m645b3e1bb36e-mrap.mrap.accesspoint.tos-global.volces.com/darwin/arm64/tosutil
chmod a+x tosutil
sudo mv tosutil /usr/local/bin

Windows：

wget https://m645b3e1bb36e-mrap.mrap.accesspoint.tos-global.volces.com/windows/tosutil -O tosutil.exe

安装注意事项

• macOS 默认可能拦截未验证开发者应用；如果首次执行 `tosutil` 时被系统阻止，需要在系统安全设置中放行
• Linux / macOS 下载后通常需要执行 `chmod a+x tosutil`
• 如果希望在任意目录直接执行 `tosutil`，建议将二进制移动到已加入 `PATH` 的目录，例如 `/usr/local/bin`
• 如果二进制没有加入 `PATH`，请使用绝对路径调用，例如 `/absolute/path/to/tosutil version`
• 本 Skill 在未加入 `PATH` 的场景下，建议通过 `--tosutil-binary <absolute-path>` 显式指定二进制位置，避免找不到工具

安装后校验

如果已加入 `PATH`：

tosutil version
tosutil config
tosutil ls

如果未加入 `PATH`：

/absolute/path/to/tosutil version
/absolute/path/to/tosutil config
/absolute/path/to/tosutil ls

结合本 Skill 的建议：

• 先用 `version` 验证二进制是否可执行
• 再用 `config` 确认配置文件路径
• 最后用 `ls` 验证凭证、地域和网络连通性

如果 `tosutil` 已加入 `PATH`，可这样调用本 Skill：

python3 .trae/skills/byted-volcengine-tosutil/scripts/main.py \
  ls \
  --preflight

如果 `tosutil` 未加入 `PATH`，可这样调用本 Skill：

python3 .trae/skills/byted-volcengine-tosutil/scripts/main.py \
  ls \
  --tosutil-binary /absolute/path/to/tosutil \
  --preflight

工作原则

• 优先确认目标是“读操作”还是“写操作/删操作”。
• 优先生成最小可行命令，避免一次性拼接过多危险参数。
• 对批量上传、下载、复制任务，先确认并发和分片阈值，再执行。
• 对删除类任务，默认给出预检查步骤和回滚提示，不直接跳过确认。
• 遇到高级命令且参数未完全确认时，优先结合 `tosutil help <command>` 校验，不臆造参数。

标准流程

1. 识别场景

将用户请求归类到以下场景之一：

• 初始化配置：`config`
• 桶操作：`ls`、`mb`、`stat`
• 对象传输：`cp`
• 对象删除：`rm`
• 对象元数据：`setmeta`
• 容量统计：`du`
• 故障诊断：`version`、`ls`、`help`、`probe`、`netdig`、`ping`、`connect`、`traceroute`

2. 预检查

执行或建议以下检查：

tosutil version
tosutil config
tosutil ls

检查重点：

• 工具是否已安装且可执行
• `Endpoint` 是否为 TOS 协议域名
• `Region` 与目标桶地域是否一致
• `AK/SK` 或 `STS Token` 是否存在且权限足够
• 返回结果中是否出现 `Bucket number is:`、`Http status [403]`、`A connection attempt failed`

3. 参数归一化

在生成命令前，统一整理以下参数：

• 资源地址：本地路径、`tos://bucket`、`tos://bucket/prefix`
• 凭证模式：永久密钥、STS、匿名访问
• 公共参数：`-e`、`-re`、`-i`、`-k`、`-t`、`-conf`
• 桶类型：`-bt=fns|hns`
• 批量任务并发：`-j`
• 分片并发或分片任务控制：`-p`、`-threshold`、`-ps`
• 结果输出目录：`-o`

4. 命令生成

根据资源类型自动选择命令模式：

• 本地 -> TOS：上传
• TOS -> 本地：下载
• TOS -> TOS：对象复制
• 单对象：单任务模式
• 目录或前缀：递归模式 `-r`
• 大文件：根据阈值切换分片任务

5. 输出校验

解析执行结果中的以下信号：

• 成功标志：`successfully`、`Bucket number is:`、`Succeed count is:`、`Task id is:`
• 权限问题：`Http status [403]`
• 网络问题：`A connection attempt failed`
• 参数问题：命令帮助输出、必选参数缺失、路径格式错误
• 清理建议：断点续传失败时考虑 `clear`

命令映射

初始化配置

永久密钥（推荐）：

tosutil config -i <ak> -k <sk> -e <endpoint> -re <region>

endpoint和region 可以参考“附录：地域及访问域名”，优先使用内网endpoint，若内网endpoint不可用则使用公网网endpoint

STS：

tosutil config -i <ak> -k <sk> -t <token> -e <endpoint> -re <region>

匿名访问：

tosutil config -i= -k= -t= -e <endpoint> -re <region>

桶与对象常见命令

tosutil ls
tosutil mb tos://bucketname
tosutil cp /local/file.txt tos://bucketname/file.txt
tosutil cp tos://bucketname/file.txt /local/file.txt
tosutil rm tos://bucketname/file.txt
tosutil du tos://bucketname
tosutil setmeta tos://bucketname/object.png -meta aaa:bbb#ccc:ddd

安全策略

• 删除对象前先判断是否为单对象、目录前缀、桶级删除。
• 对 `rm -r`、`rm -f`、批量元数据更新、批量复制等操作，先输出影响范围说明。
• 如用户只要求“生成命令”，默认不直接执行。
• 如需执行高风险命令，先建议列举目标对象或做 `dryRun` 风格校验；若命令本身不支持 `dryRun`，先做只读检查。

集成实现建议

本 Skill 的实现以“本地 CLI 封装层”而不是“直接调用 TOS HTTP API”为主，因为文档主体提供的是 `tosutil` 命令接口。

脚本入口（推荐子命令模式）

命令预览（不执行）：

python3 .trae/skills/byted-volcengine-tosutil/scripts/main.py ls --cloud-url tos://bucketname

执行并返回结构化结果：

python3 .trae/skills/byted-volcengine-tosutil/scripts/main.py ls --cloud-url tos://bucketname --preflight --run

高风险删除（必须显式确认）：

python3 .trae/skills/byted-volcengine-tosutil/scripts/main.py rm --cloud-url tos://bucketname/prefix/ --recursive --run --yes

兼容旧入口（legacy）：

python3 .trae/skills/byted-volcengine-tosutil/scripts/main.py --command ls --