ecloud-eos

移动云对象存储(EOS)技能。当用户需要上传、下载、管理云存储文件等操作时使用此技能。

Install

openclaw skills install ecloud-eos

移动云 EOS 技能

通过 Node.js SDK 脚本管理移动云对象存储。

首次使用 — 自动设置

当用户首次要求操作 EOS 时，按以下流程操作：

步骤 1：检查当前状态

检测操作系统并运行相应的检查脚本：

Windows 系统：
```
{baseDir}\scripts\setup.ps1 -CheckOnly
```

Linux/macOS 系统：

{baseDir}/scripts/setup.sh --check-only

检查脚本会验证以下内容：

基础环境：Node.js 和 npm 是否已安装
Node.js SDK：相关 Node.js SDK 依赖是否已安装
环境变量配置：检查以下环境变量是否已设置且有值：
- EOS_ACCESS_KEY — 移动云对象存储 API 密钥 ID
- EOS_SECRET_KEY — 移动云对象存储 API 密钥 Key
- EOS_REGION — 存储桶区域
- EOS_BUCKET — 存储桶名称
- EOS_ENDPOINT — 存储桶公网域名

判断标准：

✅ 所有检查项都显示 OK：配置已完成，可以直接使用 EOS 操作
⚠️ 部分环境变量缺失但可继续操作：
- 如果仅缺失 EOS_BUCKET，仍可执行部分操作：
  - list-buckets（列出所有存储桶）
  - create-bucket（创建新存储桶，需要手动指定桶名）
  - delete-bucket（删除存储桶，需要手动指定桶名）
❌ 其他环境变量缺失：进入步骤 2，引导用户配置

如果输出显示一切 OK（nodejs sdk 已安装、环境变量已配置），跳到「执行策略」。

步骤 2：如果未配置，引导用户提供凭证

方式一：直接提供凭证信息

我需要您的移动云凭证来连接 EOS 存储服务。请提供：

AccessKey — 移动云对象存储 API 密钥 ID

SecretKey — 移动云对象存储 API 密钥 Key

Region — 存储桶区域

Bucket — 存储桶名称

Endpoint — 存储桶公网域名

您可以参考移动云控制台-首页订购对象存储。您可以参考移动云控制台-创建认证信息获取 AK/SK 认证信息。您可以参考移动云控制台-地域和访问域名获取最新的地域和域名信息。

方式二：使用配置文件

告诉用户：

您也可以提供一个配置文件，包含凭证信息。配置文件格式如下：
accessKey=your-access-key
secretKey=your-secret-key
region=anhui1  # 请根据最新地域列表选择合适的region
bucket=your-bucket-name
endpoint=https://eos-anhui-1.cmecloud.cn  # 请根据最新地域列表选择对应endpoint
配置文件模板位于：references/config_template.properties

请将配置文件路径提供给我，我会使用它来设置环境。

步骤 3：用户提供凭证后，运行自动设置

方式一：使用命令行参数

Windows 系统：

{baseDir}\scripts\setup.ps1 -AccessKey "<AccessKey>" -SecretKey "<SecretKey>" -Region "<Region>" -Bucket "<Bucket>" -Endpoint "<Endpoint>"

Linux/macOS 系统：

{baseDir}/scripts/setup.sh --access-key "<AccessKey>" --secret-key "<SecretKey>" --region "<Region>" --bucket "<Bucket>" --endpoint "<Endpoint>"

方式二：使用配置文件

Windows 系统：

{baseDir}\scripts\setup.ps1 -CopyConfigFile "<path-to-config-file>"

Linux/macOS 系统：

{baseDir}/scripts/setup.sh --copy-config-file "<path-to-config-file>"

脚本会自动：

检查并安装 nodejs sdk（如果未安装）
从配置文件读取凭证并设置环境变量
验证 EOS 连接

重要说明：

您提供的配置文件不会被修改
环境变量会持久化保存（Windows 设置为 User 级别，Linux/macOS 写入 shell 配置文件）
重新打开终端后无需重新设置，新会话会自动使用这些环境变量

agent 必须更新自己的 process.env：调用 setup.ps1 后，agent 应该根据传递的参数更新自己的 process.env，以便后续子进程能够读取到最新的环境变量：

// agent 更新自己的 process.env
process.env.EOS_ACCESS_KEY = accessKey;
process.env.EOS_SECRET_KEY = secretKey;
process.env.EOS_REGION = region;
process.env.EOS_BUCKET = bucket;
process.env.EOS_ENDPOINT = endpoint;

步骤 4：执行策略

配置完成后，按照以下策略执行 EOS 操作：

检查配置状态：每次执行 EOS 操作前，先运行环境检查脚本确认配置正常
直接执行操作：确认配置正常后，直接执行相应的 EOS 操作命令
环境变量管理：
- 所有操作凭证从环境变量读取
- 切换桶操作通过 setup 脚本更新环境变量
- 环境变量已持久化，新会话会自动使用

方式一：Node.js SDK 脚本

官方文档: https://ecloud.10086.cn/op-help-center/doc/outline/56247

通过 scripts/eos_node.mjs 执行存储操作。凭证从环境变量读取。

常用命令

以下省略 node {baseDir}/scripts/eos_node.mjs 前缀。完整格式：node {baseDir}/scripts/eos_node.mjs <action> [options]

# 列出所有存储桶
list-buckets

# 创建桶（需要手动指定桶名）
create-bucket --bucket my-new-bucket

# 删除桶（需要手动指定桶名，注意：桶必须为空才能删除）
delete-bucket --bucket my-old-bucket

# 清空桶（删除桶内所有文件，⚠️ 高危操作，必须使用 --confirm 参数确认）
empty-bucket --bucket my-bucket --confirm

# 切换存储桶（使用 setup 脚本）
#
# 切换存储桶需要调用 setup 脚本，因为需要更新系统环境变量。
# 调用方式如下：
#
# Windows 系统：
#   {baseDir}\scripts\setup.ps1 -SetBucket <bucket-name>
#
# Linux/macOS 系统：
#   {baseDir}/scripts/setup.sh --set-bucket <bucket-name>
#
# 示例：
#   Windows: {baseDir}\scripts\setup.ps1 -SetBucket my-new-bucket
#   Linux/macOS: {baseDir}/scripts/setup.sh --set-bucket my-new-bucket
#
# 说明：
#   - 切换桶后，系统环境变量会被更新，新会话会自动使用新的桶
#   - 切换操作会验证新桶是否可访问
#   - 如果新桶不存在或无权限，会显示警告信息
#   - **agent 必须更新自己的 process.env.EOS_BUCKET**：调用 setup.ps1 -SetBucket 后，agent 应该更新自己的 `process.env.EOS_BUCKET`，以便后续子进程能够读取到新的桶名

# 查询桶访问权限
get-bucket-acl

# 设置桶访问权限（private、public-read、public-read-write）
set-bucket-acl --acl private

# 设置防盗链（白名单模式，只允许指定域名访问）
set-referer --referers "https://example.com,https://www.example.com" --type allow

# 设置防盗链（黑名单模式，拒绝指定域名访问）
set-referer --referers "https://evil.com" --type deny

# 查询防盗链设置
get-referer

# 删除防盗链
delete-referer

# 上传文件
upload-object --file /path/to/file.jpg --key remote/path/file.jpg

# 下载文件
download-object --key remote/path/file.jpg --output /path/to/save/file.jpg

# 复制文件（同一桶内）
copy-object --source-key remote/path/source.jpg --dest-key remote/path/destination.jpg

# 复制文件（跨桶）
copy-object --source-key remote/path/source.jpg --dest-key remote/path/destination.jpg --dest-bucket target-bucket

# 列出文件（⚠️ 高危操作，遵循安全规范）
list-objects

# 带前缀列出文件（推荐做法：缩小查询范围）
list-objects --prefix "images/"

# 限制每页返回数量（默认100，最大100）
list-objects --max-keys 50

# 分页获取下一页（使用上一次返回的 nextMarker，每次翻页需用户确认）
list-objects --max-keys 50 --marker "file50.jpg"

# 查看文件信息
head-object --key remote/path/file.jpg

# 判断文件是否存在
exists-object --key remote/path/file.jpg

# 查询文件访问权限
get-object-acl --key remote/path/file.jpg

# 设置文件访问权限（private、public-read、public-read-write）
set-object-acl --key remote/path/file.jpg --acl public-read

# 生成文件共享外链（默认过期时间3600秒）
generate-url --key remote/path/file.jpg

# 生成文件共享外链（自定义过期时间，单位：秒）
generate-url --key remote/path/file.jpg --expires 7200

# 删除文件
delete-object --key remote/path/file.jpg

所有命令输出 JSON 格式，success: true 表示成功，退出码 0。

图片处理说明

图片处理扩展能力见下方“图片处理能力（新增）”章节。

使用规范

禁止修改脚本文件：agent 禁止修改 scripts/ 目录下的任何文件
- 只能通过约定的方式调用脚本
- 不得读取、编辑或修改 scripts/eos_node.mjs、scripts/setup.ps1、scripts/setup.sh 等文件
- 不得创建新的脚本文件
操作前检查配置：每次执行 EOS 操作前，先运行环境检查脚本
- Windows: {baseDir}\scripts\setup.ps1 -CheckOnly
- Linux/macOS: {baseDir}/scripts/setup.sh --check-only
- 确认环境变量已设置后再执行操作
- 特殊情况：如果仅缺失 EOS_BUCKET，仍可执行以下操作：
  - list-buckets（列出所有存储桶）
  - create-bucket（创建新存储桶，需要手动指定桶名）
  - delete-bucket（删除存储桶，需要手动指定桶名）
首次使用先运行环境检查：
- Windows: {baseDir}\scripts\setup.ps1 -CheckOnly
- Linux/macOS: {baseDir}/scripts/setup.sh --check-only
凭证不明文展示：引导用户自行通过 setup 脚本设置环境变量，避免在对话中明文展示敏感信息
所有文件路径（objectKey/EOSpath/--key）为存储桶内的相对路径，如 images/photo.jpg
错误处理：调用失败时先用 setup 脚本检查环境和环境变量
方式一脚本源码见 scripts/eos_node.mjs
跨平台兼容：根据操作系统选择对应的 setup 脚本（Windows 用 .ps1，Linux/macOS 用 .sh）
环境变量管理：
- 首次使用时，通过 setup 脚本设置环境变量
- 环境变量会持久化保存（Windows 设置为 User 级别，Linux/macOS 写入 shell 配置文件）
- 切换桶操作通过 setup 脚本更新环境变量
- 新会话会自动使用这些环境变量，无需重新设置
安全提示：避免将包含敏感信息的配置文件提交到版本控制系统
列举文件操作安全规范（高危操作）：

默认只查询一页数据：默认每页返回 100 条，用户可指定 --max-keys（最大 100）
分页查询需要用户确认：返回第一页后，检查 isTruncated 字段，如果有更多数据，提示用户可以继续查询下一页，每次翻页都需要用户确认
自动查询后续所有数据需二次确认：
- 如果用户要求自动查询后续所有数据，必须提示该操作可能造成较大开销
- 必须等待用户明确确认后才能继续查询
- 最多连续查询 10 页（最多 1000 条数据）
分批查询机制：如果查询 10 页后还有剩余数据，再次提示用户是否需要继续查询，每次最多连续查询 10 页
推荐使用前缀过滤：对于大型桶，强烈建议使用 --prefix 参数缩小查询范围，避免全量列举

示例流程：

# 第一页查询
node {baseDir}/scripts/eos_node.mjs list-objects --max-keys 100
# 如果返回 isTruncated=true，记录 nextMarker 值
# 第二页查询（需用户确认）
node {baseDir}/scripts/eos_node.mjs list-objects --max-keys 100 --marker "file100.jpg"

安全提示：避免在对象数量巨大的桶上执行全量列举，优先使用 --prefix 参数缩小查询范围

清空桶操作安全规范（极高危操作）：

必须使用 --confirm 参数：执行清空桶操作时，必须显式传递 --confirm 参数，否则脚本会拒绝执行
删除桶时的提示：如果桶不为空，delete-bucket 操作会失败，错误消息会明确告知用户需要使用 empty-bucket --confirm 命令清空桶
禁止自动执行清空操作：脚本不会自动执行清空桶的操作，必须用户主动要求并确认

操作流程：

# 尝试删除非空桶（会失败）
node {baseDir}/scripts/eos_node.mjs delete-bucket --bucket my-bucket
# 返回错误：桶不为空，无法删除。请先使用 empty-bucket 命令清空桶内的所有文件。
# 注意：清空桶是高危操作，需要使用 --confirm 参数确认。

# 用户决定清空桶（必须使用 --confirm 参数）
node {baseDir}/scripts/eos_node.mjs empty-bucket --bucket my-bucket --confirm

# 清空完成后，再删除桶
node {baseDir}/scripts/eos_node.mjs delete-bucket --bucket my-bucket

安全提示：清空桶操作不可逆，删除后无法恢复。在执行清空前，建议先使用 list-objects 确认要删除的文件，对于生产环境的桶，建议先备份重要数据

图片处理参数规范：见下方“图片处理能力（新增）”章节

图片处理能力（新增）

以下内容为 EOS skill 新增的图片处理扩展，集中维护，避免与原有对象存储操作说明耦合。

依赖

图片处理沿用现有 EOS 凭证与环境变量
新增脚本依赖：@smithy/hash-node、@smithy/protocol-http

脚本边界

scripts/eos_node.mjs
- 仍负责通用 EOS 对象操作
- 图片处理仅保留“生成带 x-eos-process 的签名访问链接”的轻量能力
scripts/eos_image.mjs
- 负责图片处理专属流程
- 包括生成图片处理签名 URL、下载处理结果、通过 sys/saveas 持久化回桶

常用命令

# 生成图片处理签名链接
node {baseDir}/scripts/eos_image.mjs generate-url --key images/avatar.jpg --process "image/resize,w_400,h_400"

# 下载处理后的图片
node {baseDir}/scripts/eos_image.mjs download-object --key images/avatar.jpg --process "image/resize,w_400,h_400/rounded-corners,r_24" --output /tmp/avatar.png

# 持久化处理结果到当前桶
node {baseDir}/scripts/eos_image.mjs saveas-object --key images/avatar.jpg --process "image/resize,w_800,h_800/format,png" --target-key derived/avatar-800.png

# 持久化处理结果到指定桶
node {baseDir}/scripts/eos_image.mjs saveas-object --bucket source-bucket --key images/avatar.jpg --process "image/watermark,text_SGVsbG8" --target-bucket target-bucket --target-key outputs/avatar-watermark.jpg

能力边界

图片处理只针对 EOS 中已经存在的图片对象
图片处理请求统一使用 GET
处理型动作返回图片字节流，查询型动作如 info、average-hue 返回文本结果
私有对象必须把 x-eos-process 纳入签名 URL
EOS 默认不保存处理结果；只有显式追加 |sys/saveas,... 时才会回写到桶
水印图片只能引用同桶内对象；网络图片或本地图片需先上传到 EOS
图片处理能力只在指定可用资源池内生效；其他资源池即使在 URL 后追加处理参数也不会生效
图片处理要求目标桶已为 data_deliver 用户开启 bucket policy 中的 GetObject 和 PutObject 权限；未开启时禁止使用图片处理

资源池

图片处理仅支持以下资源池：

fenhu1 （华东-苏州3）
beijing7 （华北-北京6）
ningbo1 （华东-杭州）
zhengzhou1（华中-郑州）
zhengzhou4（华中-郑州2）
fujian1 （福建-厦门）
fujian2 （福建-厦门2）
fujian3 （福建-厦门3）

除以上资源池外，其他资源池均不支持图片处理，表现为对象 URL 后拼接的处理参数无效。

调用规则

agent 在执行任何图片处理前，必须先确认当前桶所属资源池是否在上述支持列表中；如果不在支持列表中，必须停止图片处理并明确告知用户“当前资源池不支持图片处理”
agent 在执行任何图片处理前，必须检测目标桶是否已为 data_deliver 用户开启 bucket policy 中的 GetObject 和 PutObject 权限；若未开启，必须停止图片处理，并提示用户先完成 bucket policy 配置
未通过“资源池支持性检查”或“data_deliver bucket policy 检查”时，不允许生成图片处理签名 URL，不允许下载处理结果，也不允许执行 sys/saveas
处理串格式：image/<action>[,<param>_<value>...]/<action>[,<param>_<value>...]
多个处理 step 必须按顺序拼接，agent 不应重排用户已明确给出的 step
持久化格式：image/...|sys/saveas,o_<object-key-base64url>,b_<bucket-base64url>
sys/saveas 中的对象 key 和桶名都需要使用 URL-safe Base64 编码
resize、crop、circle、info、rounded-corners、rotate、average-hue、watermark 等都视为 --process 里的子动作，不单独定义为 CLI 一级命令
当用户已经明确给出完整处理串时，agent 应直接透传，不擅自改写参数名、参数顺序或分隔格式

常见处理串示例

image/resize,w_200,h_200
image/crop,w_100,h_100,g_center
image/circle
image/info
image/rounded-corners,r_20
image/rotate,90
image/average-hue
image/resize,w_800,h_800/crop,w_400,h_400,g_center/rotate,90
image/resize,w_1024,h_1024/format,png|sys/saveas,o_ZGVyaXZlZC9hLTAxLnBuZw,b_bXktYnVja2V0

参考文档

图片处理参数字典：references/image_process_reference.md