Skill: ecloud-eos/ecloud-eos (version 1.1.0)

--- name: ecloud-eos description: 移动云对象存储(EOS)技能。当用户需要上传、下载、管理云存储文件等操作时使用此技能。 metadata: { "openclaw": { "emoji": "☁️", "requires": {}, "install": [ { "id": "eos-s3-client", "kind": "node", "package": "@aws-sdk/client-s3", "label": "Install S3 Node.js SDK", }, { "id": "eos-s3-request-presigner", "kind": "node", "package": "@aws-sdk/s3-request-presigner", "label": "Install S3 Request Presigner", }, { "id": "eos-smithy-hash-node", "kind": "node", "package": "@smithy/hash-node", "label": "Install Smithy Hash Node", }, { "id": "eos-smithy-protocol-http", "kind": "node", "package": "@smithy/protocol-http", "label": "Install Smithy Protocol HTTP", }, ], }, } --- # 移动云 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** — 存储桶公网域名 > > 您可以参考 [移动云控制台-首页](https://ecloud.10086.cn/op-help-center/doc/category/729) 订购对象存储。 > 您可以参考 [移动云控制台-创建认证信息](https://ecloud.10086.cn/op-help-center/doc/article/24501) 获取 AK/SK 认证信息。 > 您可以参考 [移动云控制台-地域和访问域名](https://ecloud.10086.cn/op-help-center/doc/article/48082) 获取最新的地域和域名信息。 **方式二：使用配置文件** 告诉用户： > 您也可以提供一个配置文件，包含凭证信息。配置文件格式如下： > > ```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` 参数缩小查询范围 12. **清空桶操作安全规范**（极高危操作）： - **必须使用 --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` 确认要删除的文件，对于生产环境的桶，建议先备份重要数据 13. **图片处理参数规范**：见下方“图片处理能力（新增）”章节 ## 图片处理能力（新增） 以下内容为 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`


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal:  | SkillSpector: suspicious (CRITICAL)