\r \r

移动云 EOS 技能\r

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

首次使用 — 自动设置\r

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

步骤 1：检查当前状态\r

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

• Windows 系统：\r

  {baseDir}\scripts\setup.ps1 -CheckOnly\r
  ```\r
  

\r

• Linux/macOS 系统：\r

  {baseDir}/scripts/setup.sh --check-only\r
  ```\r
  

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

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

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

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

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

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

1. AccessKey — 移动云对象存储 API 密钥 ID\r
2. SecretKey — 移动云对象存储 API 密钥 Key\r
3. Region — 存储桶区域\r
4. Bucket — 存储桶名称\r
5. Endpoint — 存储桶公网域名\r \r 您可以参考 移动云控制台-首页 订购对象存储。\r 您可以参考 移动云控制台-创建认证信息 获取 AK/SK 认证信息。\r 您可以参考 移动云控制台-地域和访问域名 获取最新的地域和域名信息。\r \r 方式二：使用配置文件\r \r 告诉用户：\r 您也可以提供一个配置文件，包含凭证信息。配置文件格式如下：\r \r

accessKey=your-access-key\r
secretKey=your-secret-key\r
region=anhui1  # 请根据最新地域列表选择合适的region\r
bucket=your-bucket-name\r
endpoint=https://eos-anhui-1.cmecloud.cn  # 请根据最新地域列表选择对应endpoint\r
```\r
\r
配置文件模板位于：`references/config_template.properties`\r
\r
请将配置文件路径提供给我，我会使用它来设置环境。\r

\r

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

\r 方式一：使用命令行参数\r \r Windows 系统：\r

{baseDir}\scripts\setup.ps1 -AccessKey "\x3CAccessKey>" -SecretKey "\x3CSecretKey>" -Region "\x3CRegion>" -Bucket "\x3CBucket>" -Endpoint "\x3CEndpoint>"\r
```\r
\r
**Linux/macOS 系统：**\r
```bash\r
{baseDir}/scripts/setup.sh --access-key "\x3CAccessKey>" --secret-key "\x3CSecretKey>" --region "\x3CRegion>" --bucket "\x3CBucket>" --endpoint "\x3CEndpoint>"\r
```\r
\r
**方式二：使用配置文件**\r
\r
**Windows 系统：**\r
```powershell\r
{baseDir}\scripts\setup.ps1 -CopyConfigFile "\x3Cpath-to-config-file>"\r
```\r
\r
**Linux/macOS 系统：**\r
```bash\r
{baseDir}/scripts/setup.sh --copy-config-file "\x3Cpath-to-config-file>"\r
```\r
\r
脚本会自动：\r
\r
- 检查并安装 nodejs sdk（如果未安装）\r
- 从配置文件读取凭证并设置环境变量\r
- 验证 EOS 连接\r
\r
**重要说明：**\r
- 您提供的配置文件不会被修改\r
- 环境变量会持久化保存（Windows 设置为 User 级别，Linux/macOS 写入 shell 配置文件）\r
- 重新打开终端后无需重新设置，新会话会自动使用这些环境变量\r
- **agent 必须更新自己的 process.env**：调用 setup.ps1 后，agent 应该根据传递的参数更新自己的 `process.env`，以便后续子进程能够读取到最新的环境变量：\r
  ```javascript\r
  // agent 更新自己的 process.env\r
  process.env.EOS_ACCESS_KEY = accessKey;\r
  process.env.EOS_SECRET_KEY = secretKey;\r
  process.env.EOS_REGION = region;\r
  process.env.EOS_BUCKET = bucket;\r
  process.env.EOS_ENDPOINT = endpoint;\r
  ```\r
\r
### 步骤 4：执行策略\r
\r
配置完成后，按照以下策略执行 EOS 操作：\r
\r
1. **检查配置状态**：每次执行 EOS 操作前，先运行环境检查脚本确认配置正常\r
2. **直接执行操作**：确认配置正常后，直接执行相应的 EOS 操作命令\r
3. **环境变量管理**：\r
   - 所有操作凭证从环境变量读取\r
   - 切换桶操作通过 setup 脚本更新环境变量\r
   - 环境变量已持久化，新会话会自动使用\r
\r
## 方式一：Node.js SDK 脚本\r
\r
> 官方文档: https://ecloud.10086.cn/op-help-center/doc/outline/56247\r
\r
通过 `scripts/eos_node.mjs` 执行存储操作。凭证从环境变量读取。\r
\r
### 常用命令\r
\r
> 以下省略 `node {baseDir}/scripts/eos_node.mjs` 前缀。完整格式：`node {baseDir}/scripts/eos_node.mjs \x3Caction> [options]`\r
\r
```bash\r
# 列出所有存储桶\r
list-buckets\r
\r
# 创建桶（需要手动指定桶名）\r
create-bucket --bucket my-new-bucket\r
\r
# 删除桶（需要手动指定桶名，注意：桶必须为空才能删除）\r
delete-bucket --bucket my-old-bucket\r
\r
# 清空桶（删除桶内所有文件，⚠️ 高危操作，必须使用 --confirm 参数确认）\r
empty-bucket --bucket my-bucket --confirm\r
\r
# 切换存储桶（使用 setup 脚本）\r
#\r
# 切换存储桶需要调用 setup 脚本，因为需要更新系统环境变量。\r
# 调用方式如下：\r
#\r
# Windows 系统：\r
#   {baseDir}\scripts\setup.ps1 -SetBucket \x3Cbucket-name>\r
#\r
# Linux/macOS 系统：\r
#   {baseDir}/scripts/setup.sh --set-bucket \x3Cbucket-name>\r
#\r
# 示例：\r
#   Windows: {baseDir}\scripts\setup.ps1 -SetBucket my-new-bucket\r
#   Linux/macOS: {baseDir}/scripts/setup.sh --set-bucket my-new-bucket\r
#\r
# 说明：\r
#   - 切换桶后，系统环境变量会被更新，新会话会自动使用新的桶\r
#   - 切换操作会验证新桶是否可访问\r
#   - 如果新桶不存在或无权限，会显示警告信息\r
#   - **agent 必须更新自己的 process.env.EOS_BUCKET**：调用 setup.ps1 -SetBucket 后，agent 应该更新自己的 `process.env.EOS_BUCKET`，以便后续子进程能够读取到新的桶名\r
\r
# 查询桶访问权限\r
get-bucket-acl\r
\r
# 设置桶访问权限（private、public-read、public-read-write）\r
set-bucket-acl --acl private\r
\r
# 设置防盗链（白名单模式，只允许指定域名访问）\r
set-referer --referers "https://example.com,https://www.example.com" --type allow\r
\r
# 设置防盗链（黑名单模式，拒绝指定域名访问）\r
set-referer --referers "https://evil.com" --type deny\r
\r
# 查询防盗链设置\r
get-referer\r
\r
# 删除防盗链\r
delete-referer\r
\r
# 上传文件\r
upload-object --file /path/to/file.jpg --key remote/path/file.jpg\r
\r
# 下载文件\r
download-object --key remote/path/file.jpg --output /path/to/save/file.jpg\r
\r
# 复制文件（同一桶内）\r
copy-object --source-key remote/path/source.jpg --dest-key remote/path/destination.jpg\r
\r
# 复制文件（跨桶）\r
copy-object --source-key remote/path/source.jpg --dest-key remote/path/destination.jpg --dest-bucket target-bucket\r
\r
# 列出文件（⚠️ 高危操作，遵循安全规范）\r
list-objects\r
\r
# 带前缀列出文件（推荐做法：缩小查询范围）\r
list-objects --prefix "images/"\r
\r
# 限制每页返回数量（默认100，最大100）\r
list-objects --max-keys 50\r
\r
# 分页获取下一页（使用上一次返回的 nextMarker，每次翻页需用户确认）\r
list-objects --max-keys 50 --marker "file50.jpg"\r
\r
# 查看文件信息\r
head-object --key remote/path/file.jpg\r
\r
# 判断文件是否存在\r
exists-object --key remote/path/file.jpg\r
\r
# 查询文件访问权限\r
get-object-acl --key remote/path/file.jpg\r
\r
# 设置文件访问权限（private、public-read、public-read-write）\r
set-object-acl --key remote/path/file.jpg --acl public-read\r
\r
# 生成文件共享外链（默认过期时间3600秒）\r
generate-url --key remote/path/file.jpg\r
\r
# 生成文件共享外链（自定义过期时间，单位：秒）\r
generate-url --key remote/path/file.jpg --expires 7200\r
\r
# 删除文件\r
delete-object --key remote/path/file.jpg\r
```\r
\r
所有命令输出 JSON 格式，`success: true` 表示成功，退出码 0。\r
\r
### 图片处理说明\r
\r
图片处理扩展能力见下方“图片处理能力（新增）”章节。\r
\r
---\r
\r
## 使用规范\r
\r
1. **禁止修改脚本文件**：agent 禁止修改 `scripts/` 目录下的任何文件\r
   - 只能通过约定的方式调用脚本\r
   - 不得读取、编辑或修改 `scripts/eos_node.mjs`、`scripts/setup.ps1`、`scripts/setup.sh` 等文件\r
   - 不得创建新的脚本文件\r
2. **操作前检查配置**：每次执行 EOS 操作前，先运行环境检查脚本\r
   - Windows: `{baseDir}\scripts\setup.ps1 -CheckOnly`\r
   - Linux/macOS: `{baseDir}/scripts/setup.sh --check-only`\r
   - 确认环境变量已设置后再执行操作\r
   - **特殊情况**：如果仅缺失 `EOS_BUCKET`，仍可执行以下操作：\r
     - `list-buckets`（列出所有存储桶）\r
     - `create-bucket`（创建新存储桶，需要手动指定桶名）\r
     - `delete-bucket`（删除存储桶，需要手动指定桶名）\r
3. **首次使用先运行环境检查**：\r
   - Windows: `{baseDir}\scripts\setup.ps1 -CheckOnly`\r
   - Linux/macOS: `{baseDir}/scripts/setup.sh --check-only`\r
4. **凭证不明文展示**：引导用户自行通过 setup 脚本设置环境变量，避免在对话中明文展示敏感信息\r
5. **所有文件路径**（`objectKey`/`EOSpath`/`--key`）为存储桶内的相对路径，如 `images/photo.jpg`\r
6. **错误处理**：调用失败时先用 setup 脚本检查环境和环境变量\r
7. **方式一脚本源码**见 `scripts/eos_node.mjs`\r
8. **跨平台兼容**：根据操作系统选择对应的 setup 脚本（Windows 用 .ps1，Linux/macOS 用 .sh）\r
9. **环境变量管理**：\r
   - 首次使用时，通过 setup 脚本设置环境变量\r
   - 环境变量会持久化保存（Windows 设置为 User 级别，Linux/macOS 写入 shell 配置文件）\r
   - 切换桶操作通过 setup 脚本更新环境变量\r
   - 新会话会自动使用这些环境变量，无需重新设置\r
10. **安全提示**：避免将包含敏感信息的配置文件提交到版本控制系统\r
11. **列举文件操作安全规范**（高危操作）：\r
   - **默认只查询一页数据**：默认每页返回 100 条，用户可指定 `--max-keys`（最大 100）\r
   - **分页查询需要用户确认**：返回第一页后，检查 `isTruncated` 字段，如果有更多数据，提示用户可以继续查询下一页，每次翻页都需要用户确认\r
   - **自动查询后续所有数据需二次确认**：\r
     - 如果用户要求自动查询后续所有数据，必须提示该操作可能造成较大开销\r
     - 必须等待用户明确确认后才能继续查询\r
     - 最多连续查询 10 页（最多 1000 条数据）\r
   - **分批查询机制**：如果查询 10 页后还有剩余数据，再次提示用户是否需要继续查询，每次最多连续查询 10 页\r
   - **推荐使用前缀过滤**：对于大型桶，强烈建议使用 `--prefix` 参数缩小查询范围，避免全量列举\r
   - **示例流程**：\r
     ```bash\r
     # 第一页查询\r
     node {baseDir}/scripts/eos_node.mjs list-objects --max-keys 100\r
     # 如果返回 isTruncated=true，记录 nextMarker 值\r
     # 第二页查询（需用户确认）\r
     node {baseDir}/scripts/eos_node.mjs list-objects --max-keys 100 --marker "file100.jpg"\r
     ```\r
   - **安全提示**：避免在对象数量巨大的桶上执行全量列举，优先使用 `--prefix` 参数缩小查询范围\r
12. **清空桶操作安全规范**（极高危操作）：\r
   - **必须使用 --confirm 参数**：执行清空桶操作时，必须显式传递 `--confirm` 参数，否则脚本会拒绝执行\r
   - **删除桶时的提示**：如果桶不为空，`delete-bucket` 操作会失败，错误消息会明确告知用户需要使用 `empty-bucket --confirm` 命令清空桶\r
   - **禁止自动执行清空操作**：脚本不会自动执行清空桶的操作，必须用户主动要求并确认\r
   - **操作流程**：\r
     ```bash\r
     # 尝试删除非空桶（会失败）\r
     node {baseDir}/scripts/eos_node.mjs delete-bucket --bucket my-bucket\r
     # 返回错误：桶不为空，无法删除。请先使用 empty-bucket 命令清空桶内的所有文件。\r
     # 注意：清空桶是高危操作，需要使用 --confirm 参数确认。\r
\r
     # 用户决定清空桶（必须使用 --confirm 参数）\r
     node {baseDir}/scripts/eos_node.mjs empty-bucket --bucket my-bucket --confirm\r
\r
     # 清空完成后，再删除桶\r
     node {baseDir}/scripts/eos_node.mjs delete-bucket --bucket my-bucket\r
     ```\r
   - **安全提示**：清空桶操作不可逆，删除后无法恢复。在执行清空前，建议先使用 `list-objects` 确认要删除的文件，对于生产环境的桶，建议先备份重要数据\r
13. **图片处理参数规范**：见下方“图片处理能力（新增）”章节\r
\r
## 图片处理能力（新增）\r
\r
以下内容为 EOS skill 新增的图片处理扩展，集中维护，避免与原有对象存储操作说明耦合。\r
\r
### 依赖\r
\r
- 图片处理沿用现有 EOS 凭证与环境变量\r
- 新增脚本依赖：`@smithy/hash-node`、`@smithy/protocol-http`\r
\r
### 脚本边界\r
\r
- `scripts/eos_node.mjs`\r
  - 仍负责通用 EOS 对象操作\r
  - 图片处理仅保留“生成带 `x-eos-process` 的签名访问链接”的轻量能力\r
- `scripts/eos_image.mjs`\r
  - 负责图片处理专属流程\r
  - 包括生成图片处理签名 URL、下载处理结果、通过 `sys/saveas` 持久化回桶\r
\r
### 常用命令\r
\r
```bash\r
# 生成图片处理签名链接\r
node {baseDir}/scripts/eos_image.mjs generate-url --key images/avatar.jpg --process "image/resize,w_400,h_400"\r
\r
# 下载处理后的图片\r
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\r
\r
# 持久化处理结果到当前桶\r
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\r
\r
# 持久化处理结果到指定桶\r
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\r
```\r
\r
### 能力边界\r
\r
- 图片处理只针对 EOS 中已经存在的图片对象\r
- 图片处理请求统一使用 GET\r
- 处理型动作返回图片字节流，查询型动作如 `info`、`average-hue` 返回文本结果\r
- 私有对象必须把 `x-eos-process` 纳入签名 URL\r
- EOS 默认不保存处理结果；只有显式追加 `|sys/saveas,...` 时才会回写到桶\r
- 水印图片只能引用同桶内对象；网络图片或本地图片需先上传到 EOS\r
- 图片处理能力只在指定可用资源池内生效；其他资源池即使在 URL 后追加处理参数也不会生效\r
- 图片处理要求目标桶已为 `data_deliver` 用户开启 bucket policy 中的 `GetObject` 和 `PutObject` 权限；未开启时禁止使用图片处理\r
\r
### 资源池\r
\r
图片处理仅支持以下资源池：\r
\r
- fenhu1    （华东-苏州3）\r
- beijing7  （华北-北京6）\r
- ningbo1   （华东-杭州）\r
- zhengzhou1（华中-郑州）\r
- zhengzhou4（华中-郑州2）\r
- fujian1   （福建-厦门）\r
- fujian2   （福建-厦门2）\r
- fujian3   （福建-厦门3）\r
\r
除以上资源池外，其他资源池均不支持图片处理，表现为对象 URL 后拼接的处理参数无效。\r
\r
### 调用规则\r
\r
- agent 在执行任何图片处理前，必须先确认当前桶所属资源池是否在上述支持列表中；如果不在支持列表中，必须停止图片处理并明确告知用户“当前资源池不支持图片处理”\r
- agent 在执行任何图片处理前，必须检测目标桶是否已为 `data_deliver` 用户开启 bucket policy 中的 `GetObject` 和 `PutObject` 权限；若未开启，必须停止图片处理，并提示用户先完成 bucket policy 配置\r
- 未通过“资源池支持性检查”或“data_deliver bucket policy 检查”时，不允许生成图片处理签名 URL，不允许下载处理结果，也不允许执行 `sys/saveas`\r
- 处理串格式：`image/\x3Caction>[,\x3Cparam>_\x3Cvalue>...]/\x3Caction>[,\x3Cparam>_\x3Cvalue>...]`\r
- 多个处理 step 必须按顺序拼接，agent 不应重排用户已明确给出的 step\r
- 持久化格式：`image/...|sys/saveas,o_\x3Cobject-key-base64url>,b_\x3Cbucket-base64url>`\r
- `sys/saveas` 中的对象 key 和桶名都需要使用 URL-safe Base64 编码\r
- `resize`、`crop`、`circle`、`info`、`rounded-corners`、`rotate`、`average-hue`、`watermark` 等都视为 `--process` 里的子动作，不单独定义为 CLI 一级命令\r
- 当用户已经明确给出完整处理串时，agent 应直接透传，不擅自改写参数名、参数顺序或分隔格式\r
\r
### 常见处理串示例\r
\r
```text\r
image/resize,w_200,h_200\r
image/crop,w_100,h_100,g_center\r
image/circle\r
image/info\r
image/rounded-corners,r_20\r
image/rotate,90\r
image/average-hue\r
image/resize,w_800,h_800/crop,w_400,h_400,g_center/rotate,90\r
image/resize,w_1024,h_1024/format,png|sys/saveas,o_ZGVyaXZlZC9hLTAxLnBuZw,b_bXktYnVja2V0\r
```\r
\r
### 参考文档\r
\r
- 图片处理参数字典：`references/image_process_reference.md`\r