腾讯云文件上传备份工具

要解决的问题

在许多自动化或跨设备工作流中，一个常见的痛点是：当 Agent 生成了报告、图表、处理后的图片等文件后，如何让用户在手机、平板或另一台电脑上安全、方便地获取。简单的文件路径分享在云端环境无效，而手动传输则打断流程。这个技能旨在解决文件安全交付与跨端访问的问题。

工作机制与关键步骤

该技能将本地文件或文件夹作为输入，通过脚本与腾讯云对象存储交互，完成上传，并始终返回一个带有时效性的、带签名的下载直链。

核心能力包括：

• 文件上传：支持单文件 (upload) 和整个文件夹 (uploadDir) 的递归上传，后者会保留原始目录结构。
• 文件管理：提供列表 (list)、搜索 (search)、创建目录 (mkdir)、重命名/移动 (rename) 等操作，实现对云端文件的简单管理。
• 安全链接生成：通过 info 命令为已有文件重新生成访问链接。所有下载链接都是带 COS 签名的临时直链，有效期默认2小时，无需额外配置访问权限。

关键流程中，Agent 必须处理上传冲突。默认策略是 rename（自动重命名，如 file(1).pdf），确保上传始终成功。只有当用户明确要求“覆盖”时，才使用 overwrite 策略；当用户要求先确认时，则使用 ask 策略。

适用边界与注意点

在使用此技能时，请注意以下技术约束和最佳实践：

• 凭证与权限：运行需要配置 space_admin 级别的访问令牌。脚本会从特定路径（如 ~/.tencentAgentStorage/.env）的 smh_ 前缀环境变量中读取，切勿硬编码或泄露凭证。
• 链接规范：向用户展示的链接必须是脚本返回的完整 downloadUrl，该链接域名为 *.tencentsmhuc.cn 并包含签名参数。禁止使用含 access_token 的中转链接，且禁止截断链接内容。
• 文件大小与上传：无文件大小限制。大于50MB的文件会采用分片上传，避免内存溢出，但上传过程是串行的。
• 搜索能力：文件搜索 (search) 仅支持按文件名匹配，不支持文件内容检索。
• 错误处理：所有命令通过 JSON 返回结果。当上传失败时，Agent 必须明确提示用户错误原因并提供重试选项，且绝不能在失败时提供下载链接。