volcengine-tosutil

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

火山引擎 tosutil Skill

Volcengine tosutil Skill

这个 Skill 面向火山引擎对象存储 TOS 的

tosutil

命令行工具，负责把用户意图转换成安全、可执行、可校验的

tosutil

操作流程。

This Skill is designed for the

tosutil

command-line tool of Volcengine Object Storage TOS. It converts user intent into safe, executable, and verifiable

tosutil

operation workflows.

目标一句话

Goal in One Sentence

把“要对 TOS 做什么操作”的需求，转换成默认只预览的

tosutil

命令，并在需要执行时输出结构化 JSON 结果 + 可复现证据 + 可诊断建议。

Convert a request to “perform an operation on TOS” into a

tosutil

command that previews only by default and, when execution is required, outputs structured JSON results + reproducible evidence + diagnostic recommendations.

输入与输出

Inputs and Outputs

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

Input: target command (such as
```
ls/cp/rm/du/setmeta
```
) + minimum necessary parameters (such as
```
tos://
```
addresses, local paths, and recursive flags) + optional common parameters (
```
endpoint/region/credentials/conf
```
).
Output: a unified JSON protocol (
```
ok/code/message/data/ts
```
) containing
```
preview.shell
```
(a redacted, reproducible command), an execution summary, and
```
advice.code
```
plus
```
next_actions
```
upon failure.

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

Default Behavior (Lower User Cost + Safety)

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

By default, only generate a command preview and do not execute it (
```
--run
```
must be explicitly provided to execute).
Destructive commands (such as
```
rm
```
) do not execute by default:
```
--yes
```
(or
```
--assume-yes
```
in legacy mode) must be explicitly provided before they actually run.
Output is redacted by default: AK/SK/Token are never echoed.

何时使用

When to Use

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

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

Invoke this Skill when the user requests any of the following scenarios:

Initialize or update TOS configuration using
```
tosutil
```
Create buckets, list buckets/objects, or query object properties
Upload, download, copy, or batch-delete objects
Calculate object capacity or set object metadata
Analyze issues such as
```
Http status [403]
```
, connectivity failures, or command argument errors
Generate execution plans for advanced commands such as
```
share
```
,
```
set-acl
```
,
```
mount
```
,
```
probe
```
, and
```
netdig
```

文档事实基线

Documented Fact Baseline

基于

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
```
在百万级对象下可能耗时较长，优先按目录拆分计算。

Based on the

tosutil

documentation set, the following facts can be confirmed:

```
tosutil
```
is a command-line tool for accessing and managing Volcengine Object Storage TOS. It is suitable for batch data processing between local systems and TOS, script integration, and small- and medium-scale data migration.

Core commands include

ls

mkdir

du

mb

cp

setmeta

stat

rm

share

set-acl

, and

mount

Auxiliary commands include

config

help

probe

netdig

hash

fcp

clear

version

ping

connect

traceroute

, and

curl

Initialization configuration supports permanent keys, STS temporary credentials, and anonymous access.
During initialization, use a TOS protocol domain rather than an S3 protocol domain.
```
rm
```
includes a secondary confirmation by default; recursive and batch deletions require an explicit risk assessment.
```
du
```
may take a long time when processing millions of objects, so prefer splitting calculations by directory.

下载与安装

Download and Installation

tosutil

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

tosutil

supports Windows, Linux, and macOS. Before using this Skill, it is recommended to download the appropriate version based on the current operating system and chip architecture and set the execute permission.

官方下载建议

Official Download Recommendations

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

Linux amd64: supports direct binary download and execution
macOS amd64 (Intel): supports direct binary download and execution
macOS arm64 (Apple M-series chips): supports direct binary download and execution
Windows 64-bit: download
```
tosutil.exe
```
Official
```
sha256
```
checksum files are also provided. It is recommended to verify the binary's integrity after downloading it
The latest version of
```
tosutil
```
mainly targets Windows, macOS, and Linux amd systems

安装命令

Installation Commands

Linux：

bash

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：

bash

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：

bash

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

Windows：

bash

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

Linux:

bash

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:

bash

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:

bash

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

Windows:

bash

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

安装注意事项

Installation Notes

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>
```
显式指定二进制位置，避免找不到工具

macOS may block unverified developer applications by default. If the system blocks
```
tosutil
```
on first execution, allow it in the system security settings
After downloading on Linux / macOS, you usually need to run
```
chmod a+x tosutil
```
If you want to run
```
tosutil
```
directly from any directory, move the binary to a directory included in
```
PATH
```
, such as
```
/usr/local/bin
```
If the binary has not been added to
```
PATH
```
, invoke it using an absolute path, for example
```
/absolute/path/to/tosutil version
```
When the binary is not included in
```
PATH
```
, this Skill recommends explicitly specifying its location through
```
--tosutil-binary <absolute-path>
```
to avoid tool-not-found errors

安装后校验

Verification After Installation

如果已加入

PATH

：

bash

tosutil version
tosutil config
tosutil ls

如果未加入

PATH

：

bash

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

结合本 Skill 的建议：

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

如果

tosutil

已加入

PATH

，可这样调用本 Skill（路径相对 skill 根目录）：

bash

python3 scripts/main.py \
  ls \
  --preflight

如果

tosutil

未加入

PATH

，可这样调用本 Skill：

bash

python3 scripts/main.py \
  ls \
  --tosutil-binary /absolute/path/to/tosutil \
  --preflight

If it has been added to

PATH

bash

tosutil version
tosutil config
tosutil ls

If it has not been added to

PATH

bash

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

Recommendations:

First use
```
version
```
to verify that the binary is executable
Then use
```
config
```
to confirm the configuration file path
Finally use
```
ls
```
to verify credentials, region, and network connectivity

tosutil

has been added to

PATH

, this Skill can be invoked as follows (the path is relative to the Skill root directory):

bash

python3 scripts/main.py \
  ls \
  --preflight

tosutil

has not been added to

PATH

, this Skill can be invoked as follows:

bash

python3 scripts/main.py \
  ls \
  --tosutil-binary /absolute/path/to/tosutil \
  --preflight

工作原则

Working Principles

优先确认目标是“读操作”还是“写操作/删操作”。
优先生成最小可行命令，避免一次性拼接过多危险参数。
对批量上传、下载、复制任务，先确认并发和分片阈值，再执行。
对删除类任务，默认给出预检查步骤和回滚提示，不直接跳过确认。
遇到高级命令且参数未完全确认时，优先结合
```
tosutil help <command>
```
校验，不臆造参数。
非交互删除使用
```
-f
```
，不是
```
-y
```
。清理部署产物时优先删除受限前缀，例如
```
tosutil rm tos://bucket/prefix/ -r -f
```
，避免漏删测试 artifact 或误删无关对象。

First determine whether the goal is a “read operation” or a “write/delete operation.”
Prefer generating the minimum viable command and avoid combining too many dangerous parameters at once.
For batch upload, download, or copy tasks, confirm concurrency and multipart thresholds before execution.
For deletion tasks, provide pre-check steps and rollback guidance by default; do not bypass confirmation.
When encountering an advanced command whose parameters are not fully confirmed, validate them with
```
tosutil help <command>
```
and never invent parameters.
For non-interactive deletion, use
```
-f
```
, not
```
-y
```
. When cleaning deployment artifacts, prefer deleting constrained prefixes, for example
```
tosutil rm tos://bucket/prefix/ -r -f
```
, to avoid leaving test artifacts behind or accidentally deleting unrelated objects.

标准流程

Standard Process

1. 识别场景

1. Scenario Recognition

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

初始化配置：
```
config
```
桶操作：
```
ls
```
、
```
mb
```
、
```
stat
```
对象传输：
```
cp
```
对象删除：
```
rm
```
对象元数据：
```
setmeta
```
容量统计：
```
du
```

故障诊断：

version

、

ls

、

help

、

probe

、

netdig

、

ping

、

connect

、

traceroute

Classify the user request into one of the following scenarios:

Initialization configuration:
```
config
```
Bucket operations:
```
ls
```
,
```
mb
```
,
```
stat
```
Object transfer:
```
cp
```
Object deletion:
```
rm
```
Object metadata:
```
setmeta
```
Capacity statistics:
```
du
```

Troubleshooting:

version

ls

help

probe

netdig

ping

connect

traceroute

2. 预检查

2. Preflight Checks

执行或建议以下检查：

bash

tosutil version
tosutil config
tosutil ls

检查重点：

工具是否已安装且可执行
```
Endpoint
```
是否为 TOS 协议域名
```
Region
```
与目标桶地域是否一致
```
AK/SK
```
或
```
STS Token
```
是否存在且权限足够

返回结果中是否出现

Bucket number is:

、

Http status [403]

、

A connection attempt failed

Execute or suggest the following checks:

bash

tosutil version
tosutil config
tosutil ls

Key checks:

Whether the tool is installed and executable
Whether
```
Endpoint
```
uses a TOS protocol domain
Whether
```
Region
```
matches the target bucket's region
Whether
```
AK/SK
```
or
```
STS Token
```
is present and has sufficient permissions

Whether the output contains

Bucket number is:

Http status [403]

, or

A connection attempt failed

3. 参数归一化

3. Parameter Normalization

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

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

Before generating a command, organize the following parameters:

Resource address: local path,
```
tos://bucket
```
, or
```
tos://bucket/prefix
```
Credential mode: permanent keys, STS, or anonymous access
Common parameters:
```
-e
```
,
```
-re
```
,
```
-i
```
,
```
-k
```
,
```
-t
```
,
```
-conf
```
Bucket type:
```
-bt=fns|hns
```
Batch task concurrency:
```
-j
```
Multipart concurrency or multipart task control:
```
-p
```
,
```
-threshold
```
,
```
-ps
```
Result output directory:
```
-o
```

4. 命令生成

4. Command Generation

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

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

Automatically select the command mode based on the resource type:

Local -> TOS: upload
TOS -> local: download
TOS -> TOS: object copy
Single object: single-task mode
Directory or prefix: recursive mode
```
-r
```
Large file: switch to a multipart task according to the threshold

5. 输出校验

5. Output Validation

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

成功标志：

successfully

、

Bucket number is:

、

Succeed count is:

、

Task id is:

权限问题：
```
Http status [403]
```
网络问题：
```
A connection attempt failed
```
参数问题：命令帮助输出、必选参数缺失、路径格式错误
清理建议：断点续传失败时考虑
```
clear
```

Parse the following signals in the execution result:

Success indicators:

successfully

Bucket number is:

Succeed count is:

Task id is:

Permission issue:
```
Http status [403]
```
Network issue:
```
A connection attempt failed
```
Argument issue: command help output, missing required arguments, or invalid path format
Cleanup recommendation: consider
```
clear
```
when a resumable transfer fails

命令映射

Command Mapping

初始化配置

Initialization Configuration

永久密钥（推荐）：

bash

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

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

STS：

bash

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

匿名访问：

bash

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

Permanent keys (recommended):

bash

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

endpoint

and

region

can be found in “Appendix: Regions and Access Domains.” Prefer the private endpoint; if the private endpoint is unavailable, use the public endpoint.

STS:

bash

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

Anonymous access:

bash

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

桶与对象常见命令

Common Bucket and Object Commands

bash

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

bash

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

安全策略

Security Strategy

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

Before deleting an object, determine whether the target is a single object, directory prefix, or bucket-level deletion.
For
```
rm -r
```
,
```
rm -f
```
, batch metadata updates, batch copies, and similar operations, first output an impact-scope description.
If the user only asks to “generate commands,” do not execute them directly by default.
If a high-risk command must be executed, first suggest listing the target objects or performing a
```
dryRun
```
-style validation. If the command does not support
```
dryRun
```
, perform a read-only check first.

集成实现建议

Integration Implementation Recommendations

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

tosutil

命令接口。

This Skill should be implemented primarily as a “local CLI wrapper layer” rather than by “directly calling the TOS HTTP API,” because the main body of the documentation provides the

tosutil

command interface.

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

Script Entry (Recommended Subcommand Mode)

命令预览（不执行）：

bash

python3 scripts/main.py ls --cloud-url tos://bucketname

执行并返回结构化结果：

bash

python3 scripts/main.py ls --cloud-url tos://bucketname --preflight --run

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

bash

python3 scripts/main.py rm --cloud-url tos://bucketname/prefix/ --recursive --run --yes

兼容旧入口（legacy）：

bash

python3 scripts/main.py --command ls --cloud-url tos://bucketname

推荐目录结构：

text

volcengine-tosutil/
├── SKILL.md
├── references/
│   └── doc-survey.md
└── scripts/
    ├── main.py
    ├── models.py
    ├── result_handler.py
    └── tosutil_service.py

推荐核心类：

```
CommonOptions
```
/
```
CredentialMode
```
：封装永久密钥、STS、匿名模式和公共参数
```
TosResource
```
：封装本地路径与
```
tos://
```
资源的解析结果
```
CommandSpec
```
：封装命令名、参数列表、风险级别、是否破坏性操作
```
TosutilRunner
```
：统一执行
```
tosutil
```
命令并收集退出码、标准输出、标准错误
```
result_handler
```
：统一负责结果解析、错误映射与结构化输出字段整理
```
tosutil_service
```
：统一负责命令构建、预检查、执行、脱敏和公共校验逻辑

Command preview without execution:

bash

python3 scripts/main.py ls --cloud-url tos://bucketname

Execute and return a structured result:

bash

python3 scripts/main.py ls --cloud-url tos://bucketname --preflight --run

High-risk deletion with explicit confirmation:

bash

python3 scripts/main.py rm --cloud-url tos://bucketname/prefix/ --recursive --run --yes

Legacy entry-point compatibility:

bash

python3 scripts/main.py --command ls --cloud-url tos://bucketname

Recommended directory structure:

text

volcengine-tosutil/
├── SKILL.md
├── references/
│   └── doc-survey.md
└── scripts/
    ├── main.py
    ├── models.py
    ├── result_handler.py
    └── tosutil_service.py

Recommended core classes:

```
CommonOptions
```
/
```
CredentialMode
```
: encapsulate permanent keys, STS, anonymous mode, and common parameters
```
TosResource
```
: parse local paths and
```
tos://
```
resources
```
CommandSpec
```
: encapsulate the command name, argument list, risk level, and whether the operation is destructive
```
TosutilRunner
```
: execute
```
tosutil
```
commands consistently and collect exit codes, standard output, and standard error
```
result_handler
```
: parse results, map errors, and organize structured output fields
```
tosutil_service
```
: build commands, run preflight checks, execute operations, redact sensitive data, and validate common parameters

关键规则

Key Rules

配置规则

Configuration Rules

```
config
```
写入的是本机配置文件，默认位于用户目录下的
```
.tosutilconfig
```
```
-conf
```
只能指向已有配置文件路径，不负责自动创建新文件
优先建议使用显式
```
region + endpoint
```
，避免跨地域误操作

```
config
```
writes to a local configuration file, which by default resides at
```
.tosutilconfig
```
under the user's home directory
```
-conf
```
can only point to an existing configuration file path; it does not automatically create a new file
Prefer explicitly specifying
```
region + endpoint
```
to avoid cross-region mistakes

传输规则

Transfer Rules

```
cp
```
需要根据源和目标地址类型自动推断是上传、下载还是云上复制
批量任务的实际并发需综合
```
-j
```
与分片并发参数评估，避免盲目调大
大文件和批量任务优先显式设置阈值、并发和输出目录，便于排错

```
cp
```
should infer upload, download, or cloud-to-cloud copy based on the source and destination address types
Actual concurrency for batch tasks should be evaluated using both
```
-j
```
and multipart concurrency parameters; do not blindly increase it
For large files and batch tasks, explicitly set thresholds, concurrency, and output directories to facilitate troubleshooting

统计规则

Statistics Rules

```
du
```
在海量对象场景下不要默认全桶递归扫描
如桶开启版本控制，可按需加入版本相关参数并拆分统计范围

Do not recursively scan the entire bucket by default with
```
du
```
when there are massive numbers of objects
If bucket versioning is enabled, version-related parameters may be added as needed and the statistics scope may be split

元数据规则

Metadata Rules

```
setmeta
```
支持单对象和批量前缀模式
批量模式必须明确
```
-r
```
，并限制最大并发
```
-j
```

```
setmeta
```
supports both single-object and batch-prefix modes
Batch mode must explicitly use
```
-r
```
, and the maximum concurrency
```
-j
```
must be limited

故障诊断提示

Troubleshooting Tips

权限问题

Permission Issues

如果结果出现
```
Http status [403]
```
，优先检查 AK/SK、STS 是否失效，以及目标桶/对象权限

If the result contains
```
Http status [403]
```
, first check whether the AK/SK or STS credentials have expired and whether the target bucket/object permissions are sufficient

网络问题

Network Issues

如果结果出现
```
A connection attempt failed
```
，优先检查网络、代理、防火墙和
```
Endpoint
```

If the result contains
```
A connection attempt failed
```
, first check the network, proxy, firewall, and
```
Endpoint
```

参数问题

Argument Issues

如果高级命令参数不确定，先执行
```
tosutil help <command>
```

If the parameters of an advanced command are uncertain, first execute
```
tosutil help <command>
```

清理问题

Cleanup Issues

断点续传或异常中断后，可考虑
```
clear
```
清理记录文件并尽力做云端清理

After a resumable transfer or abnormal interruption, consider using
```
clear
```
to clean up record files and attempt cloud-side cleanup

最佳实践

Best Practices

首次接管环境时，先执行
```
version
```
、
```
config
```
、
```
ls
```
三连检查
初始化必须使用 TOS 协议域名
匿名访问只适用于公开读或公共写场景
百万级对象统计按目录拆分
批量任务先保守设置并发，再逐步调优
对高风险命令保留二次确认和影响面说明

When first taking over an environment, run the
```
version
```
,
```
config
```
, and
```
ls
```
check sequence
Initialization must use a TOS protocol domain
Anonymous access only applies to public-read or public-write scenarios
Split statistics for millions of objects by directory
Start with conservative concurrency for batch tasks and tune it gradually
Keep secondary confirmation and impact-scope explanations for high-risk commands

交互模板

Interaction Templates

用户想上传文件

When the User Wants to Upload a File

确认本地路径、目标桶、目标对象名
判断是否需要递归上传
检查配置与连通性
生成
```
cp
```
命令
返回成功判据与失败排查点

Confirm the local path, target bucket, and target object name
Determine whether recursive upload is required
Check the configuration and connectivity
Generate the
```
cp
```
command
Return success criteria and troubleshooting points

用户想删除目录

When the User Wants to Delete a Directory

先确认目标前缀
先建议
```
ls
```
验证影响范围
再生成
```
rm -r
```
如用户确认强制删除，再考虑
```
-f
```

First confirm the target prefix
First suggest
```
ls
```
to verify the impact scope
Then generate
```
rm -r
```
If the user confirms forced deletion, consider
```
-f
```

用户想排查无法访问

When the User Wants to Troubleshoot an Access Failure

检查
```
version
```
检查
```
config
```
执行
```
ls
```
根据
```
403
```
、连接失败、参数错误做分类诊断

Check
```
version
```
Check
```
config
```
Run
```
ls
```
Categorize the diagnosis based on
```
403
```
, connection failure, or argument error

测试要求

Testing Requirements

用文档示例作为命令构造测试样本
用示例输出作为解析器快照样本
对
```
403
```
、网络失败、空配置、匿名访问、递归删除等场景做单元测试
对
```
cp
```
的上传/下载/云上复制三种方向分别做集成测试
对
```
rm
```
、
```
setmeta
```
、
```
du
```
的批量参数做边界测试

Use documented examples as command-construction test samples
Use example outputs as parser snapshot samples
Add unit tests for scenarios including
```
403
```
, network failures, empty configuration, anonymous access, and recursive deletion
Add integration tests for all three directions of
```
cp
```
: upload, download, and cloud-to-cloud copy
Add boundary tests for the batch parameters of
```
rm
```
,
```
setmeta
```
, and
```
du
```

限制说明

Limitations

本 Skill 优先覆盖文档中最核心的
```
config
```
、
```
ls
```
、
```
mb
```
、
```
cp
```
、
```
rm
```
、
```
du
```
、
```
setmeta
```
、
```
stat
```
、
```
help
```
、
```
version
```
```
share
```
、
```
set-acl
```
、
```
mount
```
、
```
probe
```
、
```
netdig
```
、
```
curl
```
等高级命令采用扩展适配模式
如果某个高级命令的参数未在当前引用资料中完整展开，必须先通过
```
help
```
或补充文档确认后再执行

<br />

This Skill prioritizes the core commands documented in the most detail:
```
config
```
,
```
ls
```
,
```
mb
```
,
```
cp
```
,
```
rm
```
,
```
du
```
,
```
setmeta
```
,
```
stat
```
,
```
help
```
, and
```
version
```
Advanced commands such as
```
share
```
,
```
set-acl
```
,
```
mount
```
,
```
probe
```
,
```
netdig
```
, and
```
curl
```
use an extended adaptation mode
If the parameters of an advanced command are not fully documented in the current reference materials, they must be confirmed through
```
help
```
or supplemental documentation before execution

<br />

附录：地域及访问域名

Appendix: Regions and Access Domains

地域（Region）：表示 TOS 的数据中心所在物理位置。
访问域名（Endpoint）：表示 TOS 对外服务的访问域名。

Region 中文名称	Region ID	Endpoint (内网/外网)	S3 Endpoint (内网/外网)
华北2（北京）	cn-beijing	内网: tos-cn-beijing.ivolces.com外网: tos-cn-beijing.volces.com	内网: tos-s3-cn-beijing.ivolces.com外网: tos-s3-cn-beijing.volces.com
华南1（广州）	cn-guangzhou	内网: tos-cn-guangzhou.ivolces.com外网: tos-cn-guangzhou.volces.com	内网: tos-s3-cn-guangzhou.ivolces.com外网: tos-s3-cn-guangzhou.volces.com
华东2（上海）	cn-shanghai	内网: tos-cn-shanghai.ivolces.com外网: tos-cn-shanghai.volces.com	内网: tos-s3-cn-shanghai.ivolces.com外网: tos-s3-cn-shanghai.volces.com
中国香港	cn-hongkong	内网: tos-cn-hongkong.ivolces.com外网: tos-cn-hongkong.volces.com	内网: tos-s3-cn-hongkong.ivolces.com外网: tos-s3-cn-hongkong.volces.com
亚太东南（柔佛）	ap-southeast-1	内网: tos-ap-southeast-1.ivolces.com外网: tos-ap-southeast-1.volces.com	内网: tos-s3-ap-southeast-1.ivolces.com外网: tos-s3-ap-southeast-1.volces.com
亚太东南（雅加达）	ap-southeast-3	内网: tos-ap-southeast-3.ivolces.com外网: tos-ap-southeast-3.volces.com	内网: tos-s3-ap-southeast-3.ivolces.com外网: tos-s3-ap-southeast-3.volces.com

Region: indicates the physical location of the TOS data center.
Endpoint: indicates the domain name through which TOS provides external services.

Region Name	Region ID	Endpoint (Private/Public)	S3 Endpoint (Private/Public)
China North 2 (Beijing)	cn-beijing	Private: tos-cn-beijing.ivolces.com; Public: tos-cn-beijing.volces.com	Private: tos-s3-cn-beijing.ivolces.com; Public: tos-s3-cn-beijing.volces.com
China South 1 (Guangzhou)	cn-guangzhou	Private: tos-cn-guangzhou.ivolces.com; Public: tos-cn-guangzhou.volces.com	Private: tos-s3-cn-guangzhou.ivolces.com; Public: tos-s3-cn-guangzhou.volces.com
China East 2 (Shanghai)	cn-shanghai	Private: tos-cn-shanghai.ivolces.com; Public: tos-cn-shanghai.volces.com	Private: tos-s3-cn-shanghai.ivolces.com; Public: tos-s3-cn-shanghai.volces.com
Hong Kong, China	cn-hongkong	Private: tos-cn-hongkong.ivolces.com; Public: tos-cn-hongkong.volces.com	Private: tos-s3-cn-hongkong.ivolces.com; Public: tos-s3-cn-hongkong.volces.com
Asia Pacific Southeast (Johor)	ap-southeast-1	Private: tos-ap-southeast-1.ivolces.com; Public: tos-ap-southeast-1.volces.com	Private: tos-s3-ap-southeast-1.ivolces.com; Public: tos-s3-ap-southeast-1.volces.com
Asia Pacific Southeast (Jakarta)	ap-southeast-3	Private: tos-ap-southeast-3.ivolces.com; Public: tos-ap-southeast-3.volces.com	Private: tos-s3-ap-southeast-3.ivolces.com; Public: tos-s3-ap-southeast-3.volces.com