腾讯云 COS 原生操作技能

面向 OpenClaw 的腾讯云 COS 原生操作技能。适用于上传本地文件、批量同步目录、大文件分片上传、生成临时签名链接、浏览对象与文件夹视图、复制/移动/重命名/删除对象、统计目录体量，以及排查 COS 凭证和 Bucket 配置。

腾讯云 COS 技能

把腾讯云 COS 变成 OpenClaw 可直接调用的一组高频对象存储工作流。

适合这些典型任务：

• 把本地文件或整个目录快速上传到 COS
• 为图片、压缩包、构建产物生成临时访问链接
• 浏览某个前缀下的文件结构，做复制、移动、重命名、清理
• 处理视频、模型、备份包等大文件上传
• 快速判断凭证、地域、Bucket、自定义域名哪里配错了

默认做法是：

• 优先检查关键配置与目标路径
• 在需要时生成并执行简洁脚本，直接完成对象存储操作
• 结果以结构化 JSON 或简洁中文返回给用户

适用场景

当用户出现这些意图时启用：

• 把本地文件上传到腾讯云 COS
• 批量上传一个目录或多个文件到 COS
• 上传大文件并控制并发、分片大小、断点续传策略
• 获取 COS 对象的临时签名 URL
• 列出某个前缀下的文件或文件夹
• 创建、删除、移动、复制、重命名 COS 对象
• 统计某个目录下的文件数量和总大小
• 排查 COS 凭证、地域、Bucket、自定义域名配置

前置条件

要求具备可访问腾讯云 COS 的运行环境和必要配置。

如果关键配置不完整，先明确缺什么，不要猜。

脚本资源

优先使用 scripts/ 里的可执行脚本，而不是每次临时重写一遍逻辑。

可直接复用的脚本：

• scripts/check_config.js - 检查关键配置是否齐全
• scripts/upload_file.js - 上传单个文件
• scripts/upload_batch.js - 批量上传文件或整个目录
• scripts/generate_signed_url.js - 生成临时签名链接
• scripts/list_objects.js - 列出对象或文件夹视图
• scripts/manage_objects.js - 删除、批量删除、复制、移动、重命名、创建文件夹
• scripts/upload_large_file.js - 大文件分片上传
• scripts/delete_folder.js - 删除文件夹，支持递归删除
• scripts/get_folder_stats.js - 统计目录文件数量、总体积和类型分布

调用方式统一为：

bash

node projects/skills/tx-cos/scripts/<script>.js '<json>'

默认执行策略

1. 先检查配置

优先先跑 scripts/check_config.js 确认关键配置是否齐全。

如果必需项缺失，直接告诉用户缺哪几个，不继续执行上传/删除类操作。

2. 需要真实操作时，优先调用现成脚本

这个技能的目标是让代理直接完成对象存储相关工作，而不是额外引入中间层。

优先采用脚本化、输入输出明确的执行方式；只有脚本覆盖不了时，才补临时逻辑。

3. 输出要面向人类

返回结果时优先包含：

• 操作是否成功
• 对象键 / 路径
• URL / ETag / 大小 / 数量等关键信息
• 失败时给出可执行的修复建议

不要把整段 SDK 原始响应直接甩给用户，除非对方明确要原始 JSON。

常用工作流

上传单文件

适用：用户说“把这个文件传到 COS”。

执行前要先确认本地文件存在、路径是文件而不是目录。返回结果时至少包含对象键、访问地址或资源标识、以及是否上传成功。

批量上传

适用：上传整个目录、多个文件、构建产物。

建议策略：

• 先枚举文件列表
• 明确远端前缀映射规则
• 控制并发，避免一下子打爆带宽
• 汇总成功数、失败数、失败文件

如果用户没有指定对象键规则，默认保留相对路径。

大文件上传

适用：视频、模型文件、压缩包。

优先用分片上传接口，并显式设置：

• SliceSize
• AsyncLimit
• 进度回调

如果要做长时间上传，告诉用户：

• 文件大小
• 并发设置
• 预计风险（网络抖动、覆盖同名对象）

获取签名 URL

适用：用户要临时下载链接、分享给别人。

关键参数：

• Key
• Expires

默认有效期可设为 3600 秒；如果用户没说，明确说明是临时链接。

列目录 / 文件夹视图

COS 没有真实目录，通常要用 Prefix + Delimiter: '/' 模拟文件夹。

当用户要“看看某个目录里有什么”时：

• 优先返回文件夹和文件的分组视图
• 结果过多时只展示前若干项，并提示可继续翻

删除、复制、移动、重命名

这些操作要更谨慎：

• 删除前，确认对象键或前缀范围
• 批量删除前，最好先列出将被删除的对象数量
• 移动/重命名本质通常是复制后删除，要提示这一点
• 跨 bucket 复制时，确认目标 bucket 是否由当前凭证可访问

如果用户表达不明确，比如“删一下旧文件”，先澄清范围。

安全边界

• 绝不在回复里泄露敏感凭证
• 输出配置检查结果时，只给出必要状态，不展示敏感值
• 对删除、批量删除、递归删除操作保持高警惕
• 如果涉及公开分享链接，提醒用户签名 URL 有时效，公开 Bucket 需额外确认
• 不要擅自假设 Bucket 名、地域、对象路径

故障排查

常见问题与处理：

• 凭证错误：检查访问凭证是否正确
• 地域错误：检查地域配置是否和 Bucket 实际地域一致
• Bucket 名错误：确认名称是否完整且可访问
• 本地路径不存在：先校验文件存在
• 自定义域名访问异常：先回退到默认访问域名验证
• 大文件失败：降低并发、增大分片、重试上传