byted-volcengine-tosutil

Files (6)

• SKILL.md
• doc-survey.md · references/
• main.py · scripts/
• models.py · scripts/
• result_handler.py · scripts/
• tosutil_service.py · scripts/

SKILL.md (first lines)

# 火山引擎 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：

```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
```

### 安装注意事项

- 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`：

```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` 验证凭证、地域和网络连通性

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples