专属云盘文件管理

技能文档

---
name: tencent-agent-storage
title: 专属云盘文件管理
category: 办公效率
description: 管理个人专属云盘空间，支持上传文件/整个文件夹、生成下载链接、文件列表、按名搜索、创建目录、重命名与移动，大文件分片上传不受体积限制。当用户提到「网盘」「云盘」「云空间」「上传文件」「备份到云」「生成下载链接」「把文件发给我」「发到手机」「分享文件」或任务产出的成果文件需要交付给用户时触发。触发词：云盘、网盘、上传文件、下载链接、备份、分享文件。
---

# 专属云盘文件管理

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

## 技能工作流

### 步骤1：环境准备（首次使用前）

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

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

如果 `node` 命令不存在或版本低于 14，按用户系统选择安装方式：

```bash
# macOS (Homebrew)
brew install node

# Linux (Debian/Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs

# Windows (PowerShell, 管理员)
winget install OpenJS.NodeJS.LTS

# 跨平台 (已有 nvm)
nvm install --lts
```

此技能依赖 `smh-node-sdk` npm 包（**要求 ^1.0.9**），必须在使用前完成安装（二选一）：

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

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

> 脚本按以下顺序查找 SDK：当前项目 node_modules → 全局 node_modules。未找到时报错并提示安装命令。运行脚本位于 `scripts/agent-storage.js`，通过 `node scripts/agent-storage.js <命令> '<json>'` 调用，无需额外写入临时文件。

### 步骤2：配置凭证（首次使用前）

在 `~/.tencentAgentStorage/.env` 中配置（文件不存在时新建）：

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

> **安全说明**：脚本仅读取配置文件中 `smh_` 前缀的环境变量（`smh_libraryId`、`smh_accessToken` 等），不会访问配置文件中的其他字段或敏感信息。
>
> **关于 token 权限**：文件上传和下载链接生成 API 要求 `space_admin` 级别的 accessToken，这是服务端对文件写入操作的最低权限要求。

### 步骤3：确认上传文件

- 用户明确给出路径 → 直接使用；用户说「上传文件」但未指定路径 → 追问：「你要上传哪个文件？告诉我文件路径或文件名就行。」
- 用户说「确定上传 xxx」或「把 xxx 发给我」 → 直接执行上传（默认冲突策略 `rename`）。
- **未经用户主动要求，绝不上传其本地个人文件。**

### 步骤4：执行上传

**单文件（默认）**：

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

**上传到指定目录**：

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

**批量上传**（逐个顺序执行，不并行）：

```bash
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"}'
```

**整个文件夹**（递归上传，保留目录结构）：

```bash
node scripts/agent-storage.js uploadDir '{"localPath":"/path/to/my-folder","conflictStrategy":"rename"}'
```

**冲突策略（重要）**：默认使用 `conflictStrategy: "rename"`，云端已存在同名文件时自动重命名（如 `file(1).pdf`），确保上传始终成功并返回正确链接。**只有用户明确说「覆盖」「替换」时才用 `overwrite`；用户明确要求先确认时才用 `ask`**（`ask` 模式遇同名返回 `{"success":false,"conflict":true}`，需询问用户选择覆盖 / 重命名 / 取消）。

| 策略 | 行为 | 适用场景 |
|------|------|----------|
| `rename`（**默认**） | 同名文件存在时自动重命名，确保上传成功并返回正确链接 | 大多数场景，需要保证用户拿到下载链接 |
| `overwrite` | 直接覆盖已有文件 | 用户明确说「覆盖」「替换」「更新文件」 |
| `ask` | 同名文件存在时返回错误，由 Agent 询问用户 | 用户明确要求先确认时 |

**文件大小**：无体积上限。≤ 50 MB 单次上传；> 50 MB 自动分片上传（5 MB 一片），不会整体载入内存。

### 步骤5：交付下载链接

上传成功后，从脚本 JSON 输出中提取 `downloadUrl`（带 COS 签名的直链），连同固定提示语一起发给用户：

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

批量场景逐行列出：

> 📎 report.pdf (2.3 MB) — {完整 downloadUrl}
> 📎 photo.jpg (1.1 MB) — {完整 downloadUrl}

**链接输出规则（必须遵守）**：

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

### 步骤6：其他管理操作（按需）

```bash
# 查询文件信息并重新生成下载链接
node scripts/agent-storage.js info '{"remotePath":"report.pdf"}'

# 列出云端目录文件
node scripts/agent-storage.js list '{"dirPath":"/","limit":20}'

# 按文件名搜索（不支持全文检索）
node scripts/agent-storage.js search '{"keywords":"报告"}'

# 创建目录
node scripts/agent-storage.js mkdir '{"dirPath":"photos"}'

# 重命名 / 移动（改变路径即为移动）
node scripts/agent-storage.js rename '{"fromPath":"docs/old.pdf","toPath":"docs/new.pdf"}'
```

各命令的完整 JSON 参数与返回结构见 `references/api-reference.md`。

---

## 异常处理

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

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

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

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

---

## 硬边界

- **绝不**在 `success: false` 时展示下载链接
- **绝不**在上传失败时不告知用户，必须明确提示「文件上传失败」及原因
- **绝不**硬编码或向用户暴露 SMH 凭证
- **绝不**未经用户主动要求就上传其本地个人文件
- **绝不**跳过执行通知：「链接已生成，有效期 2 小时，可直接在浏览器或手机中打开」
- **绝不**在用户未明确要求覆盖时使用 `conflictStrategy: "overwrite"`
- **绝不**把含 `accessToken` 的中转链接发给用户，必须发带 COS 签名的完整直链

---

## 结果确认

上传成功当且仅当以下全部成立：

1. 脚本输出含 `"success": true`
2. `downloadUrl` 字段存在且非空
3. 已把下载链接连同执行通知一起交付给用户

验证此前上传的文件是否仍可访问：

```bash
node scripts/agent-storage.js info '{"remotePath":"<文件名>"}'
```

返回 `"success": true` 即文件可访问，并会返回新的下载链接。

---

## 参考资料

- 各命令完整参数与返回结构 → `references/api-reference.md`

使用说明

# 专属云盘文件管理

把本地文件上传到个人专属云盘，自动生成可直接在浏览器或手机打开的下载链接，支持文件夹整体上传、文件搜索、重命名与移动。

## 使用

对 Agent 说：

```text
把 /path/to/report.pdf 上传到云盘，给我下载链接
把生成好的报告发到我手机上
看看云盘里有哪些文件
```

命令行直接调用：

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

首次使用前需在 `~/.tencentAgentStorage/.env` 配置 `smh_*` 凭证，并安装 `smh-node-sdk`（见 SKILL.md 步骤1-2）。

## 工作原理

通过 `smh-node-sdk` 调用专属云盘服务 API：小文件单次上传，大文件（>50MB）自动按 5MB 分片；上传成功后返回带 COS 签名的下载直链（默认有效期 2 小时）。云端同名文件默认自动重命名，保证上传始终成功。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。