腾讯云COS对象存储与数据万象

技能文档

---
name: tencent-cos-skill
title: 腾讯云COS对象存储与数据万象
category: 开发工具
description: 一站式管理腾讯云对象存储（COS）与数据万象（CI）：文件上传下载、签名链接、存储桶管理，图片处理（缩放/裁剪/水印/超分辨率/二维码识别）、文档转PDF、媒体处理、内容审核、语音识别合成、OCR、数据集检索（以图搜图/以文搜图/人脸搜索）、知识库创建与语义检索，基于官方 Node.js SDK 提供统一脚本入口。当用户需要上传下载云存储文件、处理图片、转换文档、审核内容、识别语音、检索多媒体数据或搭建知识库时触发。触发词：COS上传、对象存储、图片处理、以图搜图、知识库、签名URL、OCR识别。
---

# 腾讯云 COS 技能（tencent-cos-skill）

一站式管理腾讯云对象存储(COS)和数据万象(CI)，通过统一的 Node.js SDK 脚本提供以下能力：

- **文件存储**：上传、下载、列出、删除文件，获取签名下载链接，批量操作，复制
- **存储桶管理**：列出/创建存储桶，查询数据万象及各子服务开通状态，读写 ACL、跨域、标签，并查询版本控制、生命周期、Policy、防盗链、默认加密、静态网站、日志等 COS 配置
- **图片处理**：缩放、裁剪、旋转、格式转换、文字水印、质量评估、超分辨率、智能裁剪、二维码识别
- **内容识别**：描述单个图片或视频的内容、图片标签识别、OCR 文字识别、视频 ASR/OCR 和粗分类
- **文档处理**：办公文档转 PDF、文档预览（图片/HTML）
- **媒体处理**：视频智能封面、转码、截帧、媒体信息
- **内容审核**：图片/视频/音频/文本/文档违规检测
- **智能语音**：语音识别、语音合成、音频降噪、人声分离
- **文件处理**：哈希计算、压缩、解压
- **智能检索 MetaInsight**：数据集管理、索引管理、以图搜图、文本搜图、以文搜视频片段、人脸搜索、元数据检索、多模态检索（文档/图片/视频）
- **数据集分析**：自然语言条件筛选、聚合统计、桶反查数据集、图片理解、EXIF 和 AI 媒资详情
- **结果预览**：为图片、视频和文档检索结果生成可交互 HTML 预览
- **知识库**：一键创建知识库（自动创建桶+数据集+绑定），上传文档到知识库，语义检索知识库内容

统一提供三个脚本入口，均输出 JSON：

- `scripts/cos_node.mjs`：COS 存储、写操作、处理作业和通用 CI 能力。
- `scripts/ci_api.mjs`：数据集筛选、聚合和语义检索等只读能力。
- `scripts/preview_gen.mjs`：检索结果的本地批量签名与 HTML 预览生成。

> **请注意**对象存储(COS)与数据万象(CI)均为腾讯云付费服务，使用前请知悉，**使用本技能默认视为已知悉并接受相关费用**。具体见官方文档：
> [COS 费用](https://cloud.tencent.com/document/product/436/16871) ｜ [CI 费用](https://cloud.tencent.com/document/product/460/6970)

## 技能工作流

### 步骤1：首次使用环境检查与凭证配置

首次操作 COS 时先运行环境检查：

```bash
{baseDir}/scripts/setup.sh --check-only
```

如果 Node.js 和 cos-nodejs-sdk-v5 已安装、环境变量已配置，直接进入步骤2。否则引导用户提供腾讯云凭证，并说明凭证安全保障：

> 🛡️ **凭证安全保障**
> - **默认不落盘**：凭证仅存于当前终端会话内存中，关闭终端即消失
> - **可选持久化**：如需保存，凭证写入项目本地 `.env` 文件（仅当前用户可读，权限 600）
> - **支持 AES-256 加密**：持久化后可一键加密为 `.env.enc`，明文自动删除，密钥绑定本机+本用户，拷贝到其他环境无法解密
> - **自动防误提交**：`.env` / `.env.enc` 自动添加到 `.gitignore`，不会进入版本控制
> - **永远不会在对话中回显你的密钥**
>
> 🔒 **推荐方案：STS 临时凭证（最安全，自带有效期）**：SecretId（TmpSecretId）、SecretKey（TmpSecretKey）、Token（SecurityToken）、Region（如 ap-guangzhou）、Bucket（格式 name-appid）
>
> ⚠️ **降级方案：永久密钥（必须使用子账号最小权限密钥）**：SecretId / SecretKey / Region / Bucket
>
> 可选配置：DatasetName（MetaInsight 检索需要）、Domain / ServiceDomain / Protocol（自定义域名）

拿到凭证后设置环境变量并运行安装：

```bash
export TENCENT_COS_SECRET_ID="<SecretId>"
export TENCENT_COS_SECRET_KEY="<SecretKey>"
export TENCENT_COS_TOKEN="<Token>"  # STS 临时凭证才需要
export TENCENT_COS_REGION="<Region>"
export TENCENT_COS_BUCKET="<Bucket>"

# 默认模式：凭证仅存于当前 session，关闭终端后需重新 export
{baseDir}/scripts/setup.sh --from-env

# 持久化模式：凭证写入项目本地 .env 文件，下次自动读取
{baseDir}/scripts/setup.sh --from-env --persist
```

脚本会自动安装 `cos-nodejs-sdk-v5` 到项目本地 `node_modules/` 并验证连接。

### 步骤2：执行存储与处理操作

存储和处理作业使用 `scripts/cos_node.mjs`：

```bash
node {baseDir}/scripts/cos_node.mjs <action> [--option value ...]
```

**全局可选参数**（所有 action 均支持，用于覆盖环境变量中的默认值）：
- `--bucket <BucketName>` — 指定操作的存储桶（覆盖 `TENCENT_COS_BUCKET`）
- `--region <Region>` — 指定地域（覆盖 `TENCENT_COS_REGION`）
- `--dataset-name <Name>` — 指定数据集名称（覆盖 `TENCENT_COS_DATASET_NAME`）

常用操作示例：

```bash
# 上传文件 / 下载文件 / 列出文件 / 获取签名链接
node {baseDir}/scripts/cos_node.mjs upload --key images/photo.jpg --file ./photo.jpg
node {baseDir}/scripts/cos_node.mjs download --key images/photo.jpg --file ./photo.jpg
node {baseDir}/scripts/cos_node.mjs list --prefix images/ --max-keys 100
node {baseDir}/scripts/cos_node.mjs sign-url --key images/photo.jpg
```

完整操作目录（存储桶管理、CI 各子服务、数据集、MetaInsight、知识库等全部 action）见 [references/actions-catalog.md](references/actions-catalog.md)；接口级命令参考见 [references/api_reference.md](references/api_reference.md)。

### 步骤3：数据集只读检索与结果预览

数据集只读检索优先使用 `scripts/ci_api.mjs`；检索结果预览使用 `scripts/preview_gen.mjs` 生成可交互 HTML。三个入口共享相同的凭证策略。删除数据集、删除绑定关系等删除语义操作没有专用 action，必须先向用户明确确认，且不得通过 `ci-request --method DELETE` 绕行。

### 步骤4：输出解读与控制台引导

- 脚本输出为 JSON，解读后向用户呈现关键信息（文件链接、任务状态、检索结果等）
- 上传完成后主动调用 `sign-url` 返回访问链接
- 如果用户需求无法由当前技能满足，但与迁移、导出、拓展功能、备份、SDK、具身智能生态或湖仓生态匹配，按 `references/console-feature-guides.md` 提供对应控制台链接；已有 action 优先，未命中映射时不要猜测链接

## 凭证与安全

| 模式 | 存储位置 | 安全性 | 用法 |
|------|---------|--------|------|
| **默认模式** | shell session 环境变量 | ⭐⭐⭐ 最安全（关闭终端即消失） | `{baseDir}/scripts/setup.sh --from-env` |
| **持久化模式** | 项目 `.env` 文件（权限 600） | ⭐⭐ 便捷但明文 | `{baseDir}/scripts/setup.sh --from-env --persist` |
| **加密持久化** | 项目 `.env.enc`（AES-256-GCM） | ⭐⭐⭐ 推荐 | 先 `--persist`，再 `encrypt-env` |

加密存储（推荐）：持久化后执行 `node {baseDir}/scripts/cos_node.mjs encrypt-env`，自动删除明文 `.env` 生成 `.env.enc`；算法 AES-256-GCM，密钥派生 `SHA-256(hostname + username + 项目绝对路径)`，加密文件绑定当前机器和用户，拷贝到其他环境无法解密。还原明文用 `decrypt-env`，清理凭证 `rm -f .env .env.enc`。

其他安全要求：

- **永远不要在对话中回显** SecretId/SecretKey
- **永远不要使用主账号密钥**，推荐专用子账号最小权限策略：
  - `QcloudCOSDataReadOnlyAccess` — 仅读取
  - `QcloudCOSDataFullControl` — COS 数据读写
  - 数据万象功能额外添加 `QcloudCIFullAccess`
- 推荐使用 **STS 临时凭证**（自带有效期，过期自动失效）
- 依赖仅 `cos-nodejs-sdk-v5`（腾讯云官方 Node.js SDK），安装到项目本地 `node_modules/`，不执行全局安装

## 分页与全量查询规范

任何列表/检索类接口都可能分页返回。**不得把第一页（或任何单页）结果说成「全部」，也不得隐去「还有后续数据」这一事实**：

1. **如实呈现分页状态**：响应中出现 `isTruncated: true`、`nextMarker`、`NextToken` / `nextToken`、`hasMore: true` 任一标志时，必须向用户明确说明——本次只返回了部分结果（已返回 N 条），还有更多数据可翻页；不得省略或弱化。
2. **禁止以偏概全**：只有确认翻完所有页（最后一页无续页标志）后，才能使用「全部」「共 X 个」这类全量表述；单页结果只能说「前 N 条」或「当前页 N 条」。
3. **用户要「全部」时必须翻页拉全**：用返回的 `nextMarker`（`list --marker`）或 `NextToken`（`dataset-simple-query --next-token`、`simple-query --body` 内 `NextToken`、`list-datasets --nexttoken`）循环请求，直到无续页标志。统计类需求（多少个、类型分布、总大小等）优先改走 `Aggregations` 聚合，让服务端全量统计，不逐页拉文件。
4. **安全上限**：循环翻页设上限（默认 1000 条 / 10 页），达到上限时停止并向用户如实说明：已拉取 X 条且仍有后续，建议缩小范围、加大单页 `--max-keys` / `MaxResults`，或改用聚合统计；若用户要对这些结果做批量操作，按下方「操作数量过多时引导控制台」处理。
5. **分页参数透传**：翻页时保持查询条件（`--prefix`、`Query`、排序等）与首页一致，只追加分页 token，避免每页筛选条件不一致导致漏数据或重复。

## 操作数量过多时引导控制台

当用户需求的操作对象数量过多、不适合由本技能逐条执行时，**不要在 CLI 里硬扛**，主动说明并引导到控制台批量能力：

- **触发标准**（满足其一即建议引导）：
  - 批量删除 / 批量上传 / 批量复制超过 100 个对象；
  - 批量数据处理（转码、水印、恢复归档等）超过 50 个对象；
  - 按分页拉全数据已超过安全上限（1000 条），且用户仍要逐条处理；
  - 清空存储桶、按前缀全量删除等大规模删除操作——一律引导控制台，本技能不执行。
- **引导方式**：如实说明当前规模下逐条执行耗时且易出错，控制台批量处理（或数据迁移）更高效；按 `references/console-feature-guides.md` 的「批量处理」「数据迁移」条目提供链接，并明确告知**本技能未执行任何实际操作**。
- 少量操作（如删除十几个文件）仍正常用 action 执行，不要动辄甩链接给用户。

## 使用规范

1. **首次使用先运行** `{baseDir}/scripts/setup.sh --check-only` 检查环境
2. **所有文件路径**（`--key`）为存储桶内的相对路径，如 `images/photo.jpg`
3. **异步任务**（文档转换、视频封面）脚本会自动轮询结果，也可通过 `--job-id` 手动查询
4. **上传后主动获取链接**：上传完成后调用 `sign-url` 返回访问链接
5. **错误处理**：调用失败时先用 `{baseDir}/scripts/setup.sh --check-only` 诊断环境问题
6. **扩展 CI 能力**：通过 `ci-request` action 调用尚未封装的 CI API
7. **能力不足时引导**：确认现有能力无法满足后，按 `references/console-feature-guides.md` 查找匹配功能并提供控制台链接
8. **脚本源码**见 `scripts/cos_node.mjs`；**命令参考**见 `references/api_reference.md`

使用说明

# 腾讯云COS对象存储与数据万象

一站式管理腾讯云对象存储（COS）与数据万象（CI）：文件上传下载、签名链接、存储桶管理，图片处理、文档转 PDF、媒体处理、内容审核、语音识别、OCR、以图搜图/以文搜图检索与知识库，全部通过统一的官方 SDK 脚本入口完成。

## 使用

```bash
# 首次使用：检查环境并配置腾讯云凭证（支持 STS 临时凭证）
<skill_dir>/scripts/setup.sh --check-only
<skill_dir>/scripts/setup.sh --from-env
```

```bash
# 上传文件并获取访问链接
node <skill_dir>/scripts/cos_node.mjs upload --key images/photo.jpg --file ./photo.jpg
node <skill_dir>/scripts/cos_node.mjs sign-url --key images/photo.jpg

# 图片加水印、文档转 PDF、语音识别等
node <skill_dir>/scripts/cos_node.mjs image-watermark --key images/photo.jpg --text "机密"
node <skill_dir>/scripts/cos_node.mjs doc-process --key docs/report.docx --task pdf
```

也可以直接对话：「把这张图传到 COS」「把这个视频提取智能封面」「以图搜图找类似的图」，技能会自动调用对应操作。

## 工作原理

三个脚本入口均输出 JSON：`cos_node.mjs` 负责 COS 存储与 CI 处理作业，`ci_api.mjs` 负责数据集只读检索与聚合，`preview_gen.mjs` 为检索结果生成本地 HTML 预览。凭证默认仅存于会话环境变量，可选 AES-256-GCM 加密持久化（`.env.enc`）。完整操作目录见 `references/actions-catalog.md`，接口参考见 `references/api_reference.md`。

如何安装此技能？

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