移动云 EOS 技能#

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

首次使用 — 自动设置#

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

步骤 1：检查当前状态#

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

• Windows 系统： powershell

  {baseDir}\scripts\setup.ps1 -CheckOnly
  
  

• Linux/macOS 系统： bash

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

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

1. 基础环境：Node.js 和 npm 是否已安装

2. Node.js SDK：相关 Node.js SDK 依赖是否已安装

3. 环境变量配置：检查以下环境变量是否已设置且有值：

   • 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 存储服务。请提供：

1. AccessKey — 移动云对象存储 API 密钥 ID
2. SecretKey — 移动云对象存储 API 密钥 Key
3. Region — 存储桶区域
4. Bucket — 存储桶名称
5. Endpoint — 存储桶公网域名

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

方式二：使用配置文件

告诉用户：

您也可以提供一个配置文件，包含凭证信息。配置文件格式如下：

properties

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 系统：

powershell

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

Linux/macOS 系统：

bash

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

方式二：使用配置文件

Windows 系统：

powershell

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

Linux/macOS 系统：

bash

{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，以便后续子进程能够读取到最新的环境变量： javascript

  // 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 操作：

1. 检查配置状态：每次执行 EOS 操作前，先运行环境检查脚本确认配置正常

2. 直接执行操作：确认配置正常后，直接执行相应的 EOS 操作命令

3. 环境变量管理：

   • 所有操作凭证从环境变量读取
   • 切换桶操作通过 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]

bash

# 列出所有存储桶
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。

图片处理说明#

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

---

使用规范#

1. 禁止修改脚本文件：agent 禁止修改 scripts/ 目录下的任何文件

   • 只能通过约定的方式调用脚本
   • 不得读取、编辑或修改 scripts/eos_node.mjs、 scripts/setup.ps1、 scripts/setup.sh 等文件
   • 不得创建新的脚本文件

2. 操作前检查配置：每次执行 EOS 操作前，先运行环境检查脚本

   • Windows: {baseDir}\scripts\setup.ps1 -CheckOnly

   • Linux/macOS: {baseDir}/scripts/setup.sh --check-only

   • 确认环境变量已设置后再执行操作

   • 特殊情况：如果仅缺失 EOS_BUCKET，仍可执行以下操作：

     • list-buckets（列出所有存储桶）
     • create-bucket（创建新存储桶，需要手动指定桶名）
     • delete-bucket（删除存储桶，需要手动指定桶名）

3. 首次使用先运行环境检查：

   • Windows: {baseDir}\scripts\setup.ps1 -CheckOnly
   • Linux/macOS: {baseDir}/scripts/setup.sh --check-only

4. 凭证不明文展示：引导用户自行通过 setup 脚本设置环境变量，避免在对话中明文展示敏感信息

5. 所有文件路径（ objectKey/ EOSpath/ --key）为存储桶内的相对路径，如 images/photo.jpg

6. 错误处理：调用失败时先用 setup 脚本检查环境和环境变量

7. 方式一脚本源码 见 scripts/eos_node.mjs

8. 跨平台兼容：根据操作系统选择对应的 setup 脚本（Windows 用 .ps1，Linux/macOS 用 .sh）

9. 环境变量管理：

   • 首次使用时，通过 setup 脚本设置环境变量
   • 环境变量会持久化保存（Windows 设置为 User 级别，Linux/macOS 写入 shell 配置文件）
   • 切换桶操作通过 setup 脚本更新环境变量
   • 新会话会自动使用这些环境变量，无需重新设置

10. 安全提示：避免将包含敏感信息的配置文件提交到版本控制系统

11. 列举文件操作安全规范（高危操作）：

• 默认只查询一页数据：默认每页返回 100 条，用户可指定 --max-keys（最大 100）

• 分页查询需要用户确认：返回第一页后，检查 isTruncated 字段，如果有更多数据，提示用户可以继续查询下一页，每次翻页都需要用户确认

• 自动查询后续所有数据需二次确认：

  • 如果用户要求自动查询后续所有数据，必须提示该操作可能造成较大开销
  • 必须等待用户明确确认后才能继续查询
  • 最多连续查询 10 页（最多 1000 条数据）

• 分批查询机制：如果查询 10 页后还有剩余数据，再次提示用户是否需要继续查询，每次最多连续查询 10 页

• 推荐使用前缀过滤：对于大型桶，强烈建议使用 --prefix 参数缩小查询范围，避免全量列举

• 示例流程： bash

  # 第一页查询
  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 参数缩小查询范围

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

• 必须使用 --confirm 参数：执行清空桶操作时，必须显式传递 --confirm 参数，否则脚本会拒绝执行

• 删除桶时的提示：如果桶不为空， delete-bucket 操作会失败，错误消息会明确告知用户需要使用 empty-bucket --confirm 命令清空桶

• 禁止自动执行清空操作：脚本不会自动执行清空桶的操作，必须用户主动要求并确认

• 操作流程： bash

  # 尝试删除非空桶（会失败）
  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 确认要删除的文件，对于生产环境的桶，建议先备份重要数据

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

图片处理能力（新增）#

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

依赖#

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

脚本边界#

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

常用命令#

bash

# 生成图片处理签名链接
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 应直接透传，不擅自改写参数名、参数顺序或分隔格式

常见处理串示例#

text

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