cloud-upload-backup

Tencent Agent Storage (云文件上传备份工具)

将本地文件上传至 Tencent Agent Storage，自动生成下载链接和图片预览。上传的文件存储在用户独有的云盘空间中，支持跨端访问——无论是手机、电脑还是平板，用户都可以随时随地查看和下载自己的文件。

When to Use

Agent MUST activate this skill when any of the following conditions are met:

Quick Reference

| Command | Usage | Description | |---------|-------|-------------| | upload | node scripts/agent-storage.js upload '' | Upload local file to cloud, returns download link | | info | node scripts/agent-storage.js info '' | Get file info and regenerate download link | | list | node scripts/agent-storage.js list '' | List files in a cloud directory |

Setup

Prerequisites

此 skill 需要 Node.js ≥ 14 和 npm。Agent 在首次执行前必须检测运行环境：

node --version   # 期望输出 v14.x 或更高
npm --version

如果 node 命令不存在或版本低于 14，直接安装：

根据用户系统自动选择安装方式：

# macOS (Homebrew)
brew install node
macOS (无 Homebrew)
curl -o node.pkg "https://nodejs.org/dist/v20.18.0/node-v20.18.0.pkg" && sudo installer -pkg node.pkg -target / && rm node.pkg
Linux (Debian/Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs
Linux (其他发行版 / 通用)
curl -fsSL https://nodejs.org/dist/v20.18.0/node-v20.18.0-linux-x64.tar.xz | sudo tar -xJ -C /usr/local --strip-components=1
Windows (PowerShell, 管理员)
winget install OpenJS.NodeJS.LTS
Windows (无 winget)
下载安装包: https://nodejs.org/dist/v20.18.0/node-v20.18.0-x64.msi 并运行
跨平台 (已有 nvm)
nvm install --lts

此 skill 还依赖 smh-node-sdk npm 包。必须在使用前完成安装（二选一）：

# 方式一：全局安装（推荐）
npm install -g smh-node-sdk
方式二：本地安装到项目目录
npm install smh-node-sdk

> 脚本会按以下顺序查找 SDK：当前项目 node_modules → 全局 node_modules。如果未找到，脚本会报错并提示安装命令。

About the upload script

此 skill 的运行脚本位于 scripts/agent-storage.js。Agent 直接通过 node scripts/agent-storage.js '' 调用，无需额外写入临时文件。脚本源码可在 scripts/ 目录中审阅。

Credential configuration

凭证从以下配置文件中自动加载（优先级从高到低）。

> 安全说明：脚本仅读取配置文件中 smh_ 前缀的环境变量（smh_libraryId、smh_accessToken 等），不会访问配置文件中的其他字段或敏感信息。

> 关于 token 权限：Tencent Agent Storage 的文件上传和下载链接生成 API 要求 space_admin 级别的 accessToken，这是 Tencent Agent Storage 服务端对文件写入操作的最低权限要求。

模式一：直接凭证（accessToken）

凭证文件查找顺序（先找到者优先）：

1. 通用配置 — ~/.tencentAgentStorage/.env 2. OpenClaw — ~/.openclaw/openclaw.json 的 env 字段 3. Hermes — ~/.hermes/.env

通用配置（推荐） — 在 ~/.tencentAgentStorage/.env 中配置：

# ~/.tencentAgentStorage/.env
smh_basePath=https://api.tencentsmh.cn
smh_libraryId=smhxxx-xxxxx
smh_spaceId=space-xxxxx
smh_accessToken=

OpenClaw — 在 ~/.openclaw/openclaw.json 的 env 字段中配置：

{
  "env": {
    "smh_basePath": "https://api.tencentsmh.cn",
    "smh_libraryId": "smhxxx-xxxxx",
    "smh_spaceId": "space-xxxxx",
    "smh_accessToken": ""
  }
}

Hermes — 在 ~/.hermes/.env 中配置：

smh_basePath=https://api.tencentsmh.cn
smh_libraryId=smhxxx-xxxxx
smh_spaceId=space-xxxxx
smh_accessToken=

Procedure

Agent uses this skill in any scenario that requires uploading files to the cloud.

Complete flow

User triggers file upload
  → Step 1: Identify the local file path(s)
  → Step 2: Run upload script (loop for batch)
  → Step 3: Extract downloadUrl from JSON output (signed COS URL)
  → Step 4: Deliver the download link with execution notice

> IMPORTANT: 默认使用 conflictStrategy: "rename" 上传。当云端已存在同名文件时，脚本会自动重命名（如 file(1).pdf），确保上传始终成功并返回正确的下载链接。只有用户明确说了 "覆盖"/"替换" 时，才使用 conflictStrategy: "overwrite"；用户明确要求先确认时，才使用 conflictStrategy: "ask"。

Step 2: Upload

Single file (默认):

node scripts/agent-storage.js upload '{"localPath":"/path/to/file.pdf","conflictStrategy":"rename"}'

Upload to specific directory:

node scripts/agent-storage.js upload '{"localPath":"/path/to/photo.jpg","remotePath":"photos/photo.jpg","conflictStrategy":"rename"}'

User explicitly requested overwrite:

node scripts/agent-storage.js upload '{"localPath":"/path/to/report.pdf","conflictStrategy":"overwrite"}'

Batch upload:

node scripts/agent-storage.js upload '{"localPath":"/path/to/file1.pdf","conflictStrategy":"rename"}'
node scripts/agent-storage.js upload '{"localPath":"/path/to/file2.docx","conflictStrategy":"rename"}'

#### Conflict handling

When using conflictStrategy: "rename" (默认), if a same-name file already exists, the script automatically renames the file (e.g. file(1).pdf) and completes the upload, ensuring a valid download link is always returned.

When using conflictStrategy: "ask", if a same-name file already exists, the script returns {"success":false,"conflict":true}. Agent must then ask the user:

> 云端已存在同名文件 {filename}，你想怎么处理？ > > 1. 🔄 覆盖 — 替换云端文件 > 2. 📝 重命名 — 自动改名上传（如 file(1).pdf） > 3. ❌ 取消 — 不上传

三种策略对照：

| Strategy | Behavior | When to use | |----------|----------|-------------| | rename (默认) | 同名文件存在时自动重命名，确保上传成功并返回正确链接 | 大多数场景，需要保证用户拿到下载链接 | | overwrite | 直接覆盖已有文件 | 用户明确说 "覆盖", "替换", "更新文件" | | ask | 同名文件存在时返回错误，Agent 询问用户 | 用户明确要求先确认时 |

Step 4: Deliver link + execution notice

After every successful upload, include this notice alongside the download link(s):

> 链接已生成，链接有效期 2 小时，可直接在浏览器或手机中打开。

链接输出规则（MUST）： 1. 必须使用带 COS 签名的直链（downloadUrl 字段），域名为 *.tencentsmhuc.cn，参数含 q-sign-algorithm 和 q-signature 2. 禁止输出含 accessToken 的中转链接（如 https://api.tencentsmh.cn/...?access_token=...），这会泄露凭证 3. 链接必须完整输出，禁止任何形式的截断、省略或缩写——不能用 ...、<省略> 等替代任何部分。签名链接通常很长，这是正常的

Single file example:

> 链接已生成，链接有效期 2 小时，可直接在浏览器或手机中打开。 > > 已上传文件: report.pdf 大小: (2.3 MB) > 下载链接: {脚本返回的完整 downloadUrl，原样输出，不得截断}

Batch example:

> 链接已生成，链接有效期 2 小时，可直接在浏览器或手机中打开。 > > 📎 report.pdf (2.3 MB) — {完整 downloadUrl} > 📎 photo.jpg (1.1 MB) — {完整 downloadUrl}

File Size Support

There is NO file size limit. The upload script supports files of any size, including multi-GB videos.

Commands

所有命令输出 JSON 到 stdout。

upload

node scripts/agent-storage.js upload ''

JSON 参数：

Output:

{
  "success": true,
  "upload": {
    "localFile": "/path/to/photo.jpg",
    "remotePath": "photo.jpg",
    "fileSize": 2048576,
    "fileSizeHuman": "2.0 MB",
    "uploadTime": "3.2s",
    "rapidUpload": false
  },
  "downloadUrl": "https://bucket-xxxxx.tencentsmhuc.cn/smhxxx/...photo.jpg?response-content-disposition=inline&smh-space=space-xxx&x-cos-security-token=...&q-sign-algorithm=sha1&q-signature=..."
}

info

node scripts/agent-storage.js info ''

JSON 参数：

Output:

{
  "success": true,
  "remotePath": "report.pdf",
  "downloadUrl": "https://bucket-xxxxx.tencentsmhuc.cn/smhxxx/...report.pdf?response-content-disposition=inline&smh-space=space-xxx&x-cos-security-token=...&q-sign-algorithm=sha1&q-signature=...",
  "fileInfo": {
    "name": "report.pdf",
    "size": 2048576,
    "type": "application/pdf",
    "creationTime": "2026-03-13T10:00:00Z",
    "modificationTime": "2026-03-13T10:00:00Z"
  }
}

list

node scripts/agent-storage.js list ''

JSON 参数：

Full Example

# Step 0: 安装 smh-node-sdk（首次使用前执行一次）
npm install -g smh-node-sdk
Step 1: 上传文件
node scripts/agent-storage.js upload '{"localPath":"/path/to/report.pdf","conflictStrategy":"rename"}'
Step 2: 查询文件信息
node scripts/agent-storage.js info '{"remotePath":"report.pdf"}'
Step 3: 列出云端文件
node scripts/agent-storage.js list '{"dirPath":"/","limit":20}'

Pitfalls

Error handling

所有命令输出 JSON 到 stdout。错误也以 JSON 返回：{"success": false, "error": "..."}

| 错误 | 处理方式 | |------|---------| | 上传失败（success: false） | 告诉用户："文件上传失败：{具体原因}。你可以稍后再试，或者检查网络连接。" | | 同名冲突（conflict: true） | 询问用户选择覆盖、重命名或取消 | | 文件不存在 | 让用户确认路径 | | 网络错误 | 重试 2 次，间隔 3s；仍失败告知用户 | | 配置缺失 | 提示用户在 ~/.tencentAgentStorage/.env、~/.openclaw/openclaw.json 的 env 字段或 ~/.hermes/.env 中添加 smh_* 配置 |

上传失败对话模板（当 success: false 时必须使用）：

> ❌ 文件上传失败：{error 中的具体原因}。 > > 你可以： > 1. 🔄 重试 — 重新上传这个文件 > 2. ❌ 取消 — 暂时不上传

Prohibited actions

Common mistakes

Verification

Upload was successful when ALL of the following are true:

1. Script output contains "success": true 2. downloadUrl field is present and non-empty 3. Agent delivered the download link to the user with the execution notice: "链接已生成，有效期 2 小时，可直接在浏览器或手机中打开"

To verify a previously uploaded file still exists:

node scripts/agent-storage.js info '{"remotePath":""}'

If the response contains "success": true, the file is accessible and a fresh download link is returned.

Prerequisites

此 skill 需要 Node.js ≥ 14 和 npm。Agent 在首次执行前必须检测运行环境：

node --version   # 期望输出 v14.x 或更高
npm --version

如果 node 命令不存在或版本低于 14，直接安装：

根据用户系统自动选择安装方式：

# macOS (Homebrew)
brew install node
macOS (无 Homebrew)
curl -o node.pkg "https://nodejs.org/dist/v20.18.0/node-v20.18.0.pkg" && sudo installer -pkg node.pkg -target / && rm node.pkg
Linux (Debian/Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs
Linux (其他发行版 / 通用)
curl -fsSL https://nodejs.org/dist/v20.18.0/node-v20.18.0-linux-x64.tar.xz | sudo tar -xJ -C /usr/local --strip-components=1
Windows (PowerShell, 管理员)
winget install OpenJS.NodeJS.LTS
Windows (无 winget)
下载安装包: https://nodejs.org/dist/v20.18.0/node-v20.18.0-x64.msi 并运行
跨平台 (已有 nvm)
nvm install --lts

此 skill 还依赖 smh-node-sdk npm 包。必须在使用前完成安装（二选一）：

# 方式一：全局安装（推荐）
npm install -g smh-node-sdk
方式二：本地安装到项目目录
npm install smh-node-sdk

> 脚本会按以下顺序查找 SDK：当前项目 node_modules → 全局 node_modules。如果未找到，脚本会报错并提示安装命令。

About the upload script

此 skill 的运行脚本位于 scripts/agent-storage.js。Agent 直接通过 node scripts/agent-storage.js '' 调用，无需额外写入临时文件。脚本源码可在 scripts/ 目录中审阅。

Credential configuration

凭证从以下配置文件中自动加载（优先级从高到低）。

> 安全说明：脚本仅读取配置文件中 smh_ 前缀的环境变量（smh_libraryId、smh_accessToken 等），不会访问配置文件中的其他字段或敏感信息。

> 关于 token 权限：Tencent Agent Storage 的文件上传和下载链接生成 API 要求 space_admin 级别的 accessToken，这是 Tencent Agent Storage 服务端对文件写入操作的最低权限要求。

模式一：直接凭证（accessToken）

凭证文件查找顺序（先找到者优先）：

1. 通用配置 — ~/.tencentAgentStorage/.env 2. OpenClaw — ~/.openclaw/openclaw.json 的 env 字段 3. Hermes — ~/.hermes/.env

通用配置（推荐） — 在 ~/.tencentAgentStorage/.env 中配置：

# ~/.tencentAgentStorage/.env
smh_basePath=https://api.tencentsmh.cn
smh_libraryId=smhxxx-xxxxx
smh_spaceId=space-xxxxx
smh_accessToken=

OpenClaw — 在 ~/.openclaw/openclaw.json 的 env 字段中配置：

{
  "env": {
    "smh_basePath": "https://api.tencentsmh.cn",
    "smh_libraryId": "smhxxx-xxxxx",
    "smh_spaceId": "space-xxxxx",
    "smh_accessToken": ""
  }
}

Hermes — 在 ~/.hermes/.env 中配置：

smh_basePath=https://api.tencentsmh.cn
smh_libraryId=smhxxx-xxxxx
smh_spaceId=space-xxxxx
smh_accessToken=