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

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

When to Use

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

• User mentions cloud drive keywords: 网盘、云盘、云空间、龙虾盘、专属网盘、cloud drive, my drive
• User requests file listing or browsing: 列出文件、有哪些文件、list files, show files
• User requests upload or backup: 上传文件、备份到云、存到网盘、upload, backup, save to cloud
• User asks to send/deliver files: 把文件发给我、发到手机、send file, deliver file
• User requests links or sharing: 生成下载链接、分享文件、download link, share link
• User queries file status: 这个云文件还在吗、链接过期了、is file still there
• User requests file search: 搜索文件、找文件、检索文件、搜索云盘、search files, find file
• Implicit: A task produces output files that need to be delivered to the user, or the user's intent implies needing a file on another device

Quick Reference

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 包（要求 ^1.0.8）。必须在使用前完成安装（二选一）：

# 方式一：全局安装（推荐）
npm install -g smh-node-sdk@^1.0.8

# 方式二：本地安装到项目目录
npm install smh-node-sdk@^1.0.8

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

About the upload script

此 skill 的运行脚本位于 scripts/agent-storage.js。Agent 直接通过 node scripts/agent-storage.js <command> '<json>' 调用，无需额外写入临时文件。脚本源码可在 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=<your-access-token>

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

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

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

smh_basePath=https://api.tencentsmh.cn
smh_libraryId=smhxxx-xxxxx
smh_spaceId=space-xxxxx
smh_accessToken=<your-access-token>

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. ❌ 取消 — 不上传

三种策略对照：

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.

• Small files (≤ 50 MB): Single-part upload.
• Large files (> 50 MB): Multipart upload — the file is read in 5 MB chunks, never loaded entirely into memory.

Commands

所有命令输出 JSON 到 stdout。

upload

node scripts/agent-storage.js upload '<json>'

JSON 参数：
- localPath（必填）：本地文件绝对路径，支持 ~ 展开
- remotePath（可选）：云端目标路径，省略则上传到根目录并保留原文件名
- conflictStrategy（可选）：rename（默认）| ask | overwrite
- purpose（可选）：download（默认，链接点击触发下载）| preview（链接在浏览器内预览）
- expireHours（可选）：链接有效期，单位为小时，默认 2（即 2 小时）

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://smhxxxxx.gz-c1.smhshare.com/s/xxxxxxxxxx"
}

uploadDir

node scripts/agent-storage.js uploadDir '<json>'

JSON 参数：
- localPath（必填）：本地文件夹绝对路径，支持 ~ 展开
- remotePath（可选）：云端目标目录路径，省略则使用本地文件夹名称
- conflictStrategy（可选）：rename（默认）| overwrite

说明：
- 递归上传整个文件夹，自动保留目录结构
- 会先在云端创建对应的目录层级，再逐个上传文件
- 文件按顺序上传（不并行），避免 API 过载

Output:

{
  "success": true,
  "uploadDir": {
    "localPath": "/path/to/my-folder",
    "remotePath": "my-folder",
    "totalFiles": 5,
    "successCount": 5,
    "failCount": 0,
    "totalSize": 10485760,
    "totalSizeHuman": "10.0 MB",
    "uploadTime": "8.5s"
  },
  "files": [
    { "file": "doc.pdf", "size": 2048576, "sizeHuman": "2.0 MB", "success": true },
    { "file": "images/photo.jpg", "size": 1048576, "sizeHuman": "1.0 MB", "success": true }
  ]
}

info

node scripts/agent-storage.js info '<json>'

JSON 参数：
- remotePath（必填）：云端文件路径
- purpose（可选）：download（默认，链接点击触发下载）| preview（链接在浏览器内预览）
- expireHours（可选）：链接有效期，单位为小时，默认 2（即 2 小时）
- basePath / libraryId / spaceId / accessToken（可选）：直接传参模式凭证

Output:

{
  "success": true,
  "remotePath": "report.pdf",
  "downloadUrl": "https://smhxxxxx.gz-c1.smhshare.com/s/xxxxxxxxxx",
  "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>'

JSON 参数：
- dirPath（可选）：目录路径，默认 /
- limit（可选）：最大返回数量，默认 50

search

node scripts/agent-storage.js search '<json>'

JSON 参数：
- keywords（必填）：搜索关键字，字符串或字符串数组（数组元素间为"或"关系）
- scope（可选）：搜索范围目录路径，如 photos；不填则搜索整个空间
- limit（可选）：最大返回数量，默认 20，取值范围 [1, 100]
- marker（可选）：分页标识，用于获取后续页
- inExtnames（可选）：限定文件后缀，字符串或字符串数组，如 ["pdf","docx"]
- excludeExtnames（可选）：排除文件后缀，字符串或字符串数组
- fileTypes（可选）：文件类型过滤，取值 all | dir | file | symlink

> 注意：搜索仅支持按文件名匹配（type: "filename"），不支持全文内容检索。

Output:

{
  "success": true,
  "keywords": ["报告"],
  "type": "filename",
  "total": 3,
  "nextMarker": null,
  "results": [
    {
      "name": "周报告.pdf",
      "type": "file",
      "size": 2048576,
      "sizeHuman": "2.0 MB",
      "contentType": "application/pdf",
      "creationTime": "2026-03-13T10:00:00Z",
      "modificationTime": "2026-03-13T10:00:00Z",
      "text": null,
      "textPage": null,
    }
  ]
}

mkdir

node scripts/agent-storage.js mkdir '<json>'

JSON 参数：
- dirPath（必填）：要创建的文件夹路径，如 photos 或 docs/2026
- conflictStrategy（可选）：rename（默认）| ask | overwrite

Output:

{
  "success": true,
  "dirPath": "photos",
  "message": "文件夹 \"photos\" 创建成功"
}

Full Example

# Step 0: 安装 smh-node-sdk（首次使用前执行一次）
npm install -g smh-node-sdk@^1.0.8

# 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}'

# Step 4: 搜索文件（按文件名）
node scripts/agent-storage.js search '{"keywords":"report"}'

# Step 5: 上传整个文件夹
node scripts/agent-storage.js uploadDir '{"localPath":"/path/to/my-folder","conflictStrategy":"rename"}'

# Step 6: 创建文件夹
node scripts/agent-storage.js mkdir '{"dirPath":"photos"}'

Pitfalls

Error handling

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

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

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

Prohibited actions

• NEVER 在 success: false 时展示下载链接
• NEVER 在上传失败时不告知用户，必须明确提示"文件上传失败"及原因
• NEVER 硬编码或暴露 SMH 凭证给用户
• NEVER 未经用户主动要求就上传其本地个人文件
• NEVER 跳过执行通知："链接已生成，有效期 2 小时，可直接在浏览器或手机中打开"
• NEVER 在用户未明确要求覆盖时使用 conflictStrategy: "overwrite"
• NEVER 把含 accessToken 的中转链接（如 https://api.tencentsmh.cn/...?access_token=...）发给用户。返回给用户的必须是带 COS 签名的直链（域名为 *.tencentsmhuc.cn，参数含 q-sign-algorithm 和 q-signature），即脚本输出的 downloadUrl 字段
• NEVER 截断、省略或用 ... 缩写链接。发给用户的下载链接/预览链接必须是脚本返回的完整 URL，一个字符都不能少。链接通常很长（含签名参数），这是正常的，必须原样完整输出

Common mistakes

• 用户说"上传文件"但没指定路径 → 追问："你要上传哪个文件？告诉我文件路径或文件名就行。"
• 用户说"确定上传 xxx"或"把 xxx 发给我" → 直接执行上传（conflictStrategy: "rename"）
• 同名文件冲突：默认使用 conflictStrategy: "rename"，自动重命名保证上传成功。只有用户明确要求覆盖时才用 overwrite，用户明确要求先确认时才用 ask
• 文件默认上传到云空间根目录，用户可通过 remotePath 参数指定目标路径
• 下载链接为通过 SDK infoFile({ purpose: 'download' }) 获取的带签名 COS 直链（https://bucket-xxxxx.tencentsmhuc.cn/...?q-sign-algorithm=sha1&q-signature=...），可直接在浏览器或手机中打开预览/下载，有效期约 2 小时。必须原样完整输出此链接，禁止截断或省略任何部分
• 批量上传按顺序处理（不并行），避免 API 过载
• 执行通知：每次上传完成后必须告知用户："链接已生成，有效期 2 小时，可直接在浏览器或手机中打开"

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":"<filename>"}'

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