tencent-agent-storage

name	tencent-agent-storage
description	Tencent Agent Storage skill for cloud drive and file delivery workflows. Use when the user asks to upload, back up, list, search, share, preview, download, or regenerate links for files in a personal cloud drive, or when generated task outputs need to be delivered as cloud links.

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

Command	Usage	Description
upload	node scripts/agent-storage.js upload '<json>'	Upload local file to cloud, returns download link
uploadDir	node scripts/agent-storage.js uploadDir '<json>'	Upload entire folder to cloud, preserving directory structure
info	node scripts/agent-storage.js info '<json>'	Get file info and regenerate download link
list	node scripts/agent-storage.js list '<json>'	List files in a cloud directory
search	node scripts/agent-storage.js search '<json>'	Search files by name
mkdir	node scripts/agent-storage.js mkdir '<json>'	Create a directory in cloud storage

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

三种策略对照：

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.

• 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"  
             
  

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" 
       
    
  

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

上传失败对话模板（当 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.