腾讯云 COS 技能

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

• - 文件存储：上传、下载、列出、删除文件，获取签名下载链接，批量操作，复制
• 存储桶管理：列出/创建存储桶，ACL、跨域、标签、版本控制、生命周期管理
• 图片处理：缩放、裁剪、旋转、格式转换、文字水印、质量评估、超分辨率、智能裁剪、二维码识别
• 内容识别：图片标签识别、OCR 文字识别
• 文档处理：办公文档转 PDF、文档预览（图片/HTML）
• 媒体处理：视频智能封面、转码、截帧、媒体信息
• 内容审核：图片/视频/音频/文本/文档违规检测
• 智能语音：语音识别、语音合成、音频降噪、人声分离
• 文件处理：哈希计算、压缩、解压
• 智能检索 MetaInsight：数据集管理、索引管理、以图搜图、文本搜图、人脸搜索、元数据检索、多模态文档检索
• 🚀 知识库：一键创建知识库（自动创建桶+数据集+绑定），上传文档到知识库，语义检索知识库内容

所有操作通过 scripts/cos_node.mjs 单一脚本完成，输出 JSON 格式。

首次使用 — 自动设置

当用户首次要求操作 COS 时，按以下流程操作：

步骤 1：检查当前状态

CODEBLOCK0

如果 Node.js 和 cos-nodejs-sdk-v5 已安装、环境变量已配置，跳到「操作指南」。

步骤 2：如果未配置，引导用户提供凭证

告诉用户：

我需要你的腾讯云凭证来连接 COS 存储服务。请放心，你的密钥会受到以下保护：

🛡️ 凭证安全保障

• - 默认不落盘：凭证仅存于当前终端会话内存中，关闭终端即消失
• 可选持久化：如需保存，凭证写入项目本地 .env 文件（仅当前用户可读，权限 600）
• 支持 AES-256 加密：持久化后可一键加密为 .env.enc，明文自动删除，密钥绑定本机+本用户，拷贝到其他环境无法解密
• 自动防误提交：.env / .env.enc 自动添加到 .gitignore，不会进入版本控制
• 永远不会在对话中回显你的密钥

🔒 推荐方案：STS 临时凭证（最安全，自带有效期）

1. 1. SecretId — TmpSecretId
2. SecretKey — TmpSecretKey
3. Token — SecurityToken
4. Region — 存储桶区域（如 ap-guangzhou）
5. Bucket — 存储桶名称（格式 name-appid）

⚠️ 降级方案：永久密钥（必须使用子账号最小权限密钥）

1. 1. SecretId / SecretKey / Region / Bucket

可选配置

• - DatasetName — 数据万象数据集名称（仅 MetaInsight 检索需要）
• Domain / ServiceDomain / Protocol — 自定义域名配置

步骤 3：设置环境变量并运行安装

CODEBLOCK1

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

持久化说明：--persist 会将凭证写入项目目录下的 .env 文件（权限 600），并自动添加到 .gitignore。
cos_node.mjs 启动时会自动读取 .env（环境变量优先于 .env 文件）。清理凭证：rm -f .env。

---

操作指南

所有操作通过单一脚本 scripts/cos_node.mjs 完成，输出 JSON 格式。

CODEBLOCK2

全局可选参数（所有 action 均支持，用于覆盖环境变量中的默认值）：

• - --bucket <BucketName> — 指定操作的存储桶（覆盖 TENCENT_COS_BUCKET）
• INLINECODE18 — 指定地域（覆盖 TENCENT_COS_REGION）
• INLINECODE20 — 指定数据集名称（覆盖 TENCENT_COS_DATASET_NAME）

初始配置的 Region、Bucket、DatasetName 只是默认值，每次调用都可以通过参数自由指定。

COS 存储操作

CODEBLOCK3

COS 存储桶管理

⚠️ 安全限制：本技能禁止删除存储桶和清空存储桶操作。

CODEBLOCK4

CI 图片基础处理

CODEBLOCK5

CI AI 图片处理

CODEBLOCK6

CI 内容识别

CODEBLOCK7

CI 文档处理

CODEBLOCK8

CI 媒体处理

CODEBLOCK9

CI 内容审核

CODEBLOCK10

CI 智能语音

CODEBLOCK11

CI 文件处理

CODEBLOCK12

CI MetaInsight

数据集管理

CODEBLOCK13

索引管理

CODEBLOCK14

检索（需预建数据集）

三种检索需要不同模板的数据集，通过环境变量或 --dataset 参数分别指定：

检索类型	所需数据集模板	环境变量
图片检索（以图搜图/文本搜图）	INLINECODE23	INLINECODE24
人脸搜索

Official:FaceSearch | TENCENT_COS_DATASET_FACE_SEARCH |
| 元数据检索 | Official:COSBasicMeta | TENCENT_COS_DATASET_META |

INLINECODE29 作为图片检索的兜底值。所有 action 都支持 --dataset 参数覆盖。

CODEBLOCK15

🚀 知识库（快捷功能）

重要：这是一组面向用户口语化描述的快捷流程。用户不需要知道底层命令，只需用自然语言描述意图。

用户意图识别

用户可能的说法	对应操作
"帮我创建一个知识库" "建一个知识库" "我想做个文档库"	→ 执行 INLINECODE31
"上传到知识库" "把文件放进知识库" "往知识库里加文档"

→ 执行 upload（指向知识库对应的桶） | | "查询知识库" "从知识库找" "搜索知识库" "知识库里有没有关于XX的内容" | → 执行 hybrid-search（指向知识库对应的数据集） |

流程 1：创建知识库

当用户说"创建知识库"/"建一个知识库"/"我想做个文档库"时：

1. 1. 如果用户没指定名称 → 询问用户想给知识库起什么名字
2. 执行创建：

CODEBLOCK16

1. 3. 自动完成三步：创建存储桶 → 创建 DocSearch 数据集 → 绑定
2. 记住本次创建的知识库信息（桶名、地域、数据集名），后续上传/查询时直接使用
3. 告诉用户：

✅ 知识库「<名称>」已创建！

• - 你可以把文档（PDF、Word、Excel、PPT、TXT 等）上传到这个知识库
• 上传后系统会自动建立索引（需要几秒到几分钟）
• 之后你可以直接说"从知识库里搜一下XXX"来查询内容

流程 2：上传到知识库

当用户说"上传到知识库"/"把文件放进知识库"/"往知识库里加文档"时：

判断使用哪个知识库：

1. 1. 如果本次对话中已创建/使用过知识库 → 直接使用该知识库的桶和地域
2. 如果不确定 → 执行 list-datasets 列出所有数据集，筛选 TemplateId 为 Official:DocSearch 的数据集：

- 只有 1 个 DocSearch 数据集 → 直接使用它，通过数据集绑定关系推断对应的桶 - 有多个 DocSearch 数据集 → 列出让用户选择 - 没有 DocSearch 数据集 → 告诉用户"你还没有知识库，要帮你创建一个吗？"

1. 3. 确定知识库后，执行上传：

CODEBLOCK17

1. 4. 告诉用户：

✅ 文件已上传到知识库「<名称>」，索引建立中，稍后即可检索。

流程 3：查询知识库

当用户说"查询知识库"/"从知识库找XX"/"搜索知识库"/"知识库里有没有关于XX的"/"从知识库里搜一下"时：

判断使用哪个知识库：

1. 1. 如果本次对话中已创建/使用过知识库 → 直接使用该知识库的数据集
2. 如果不确定 → 执行 list-datasets 列出所有数据集，筛选 TemplateId 为 Official:DocSearch 的数据集：

- 只有 1 个 DocSearch 数据集 → 直接使用它 - 有多个 DocSearch 数据集 → 列出让用户选择（展示名称和文件数） - 没有 DocSearch 数据集 → 告诉用户"你还没有知识库，要帮你创建一个吗？"

1. 3. 确定知识库后，执行检索：

CODEBLOCK18

1. 4. 结果呈现（不要直接输出 JSON，用友好格式）：

- 按相关度排序展示检索结果 - 每条结果展示：相关度分数 + 来源文件名 + 匹配内容摘要 - 如果没有匹配结果 → 告诉用户"知识库中没有找到相关内容，你可以上传更多文档试试"

CI 通用请求（扩展入口）

用于调用尚未封装为独立 action 的 CI 能力：

CODEBLOCK19

---

功能对照表

分类	action	说明
存储	INLINECODE38	上传文件

put-string | 上传字符串 |
| | download | 下载文件 |
| | list | 列出文件 |
| | sign-url | 获取签名链接 |
| | delete | 删除文件 |
| | delete-multiple | 批量删除 |
| | head | 文件元信息 |
| | copy-object | 复制对象 |
| 存储桶管理 | list-buckets | 列出所有存储桶 |
| | create-bucket | 创建存储桶 |
| | head-bucket | 检查存储桶是否存在 |
| | get-bucket-acl / put-bucket-acl | ACL 权限管理 |
| | get-bucket-cors / put-bucket-cors | 跨域配置 |
| | get-bucket-tagging / put-bucket-tagging | 标签管理 |
| | get-bucket-versioning | 查询版本控制 |
| | get-bucket-lifecycle | 查询生命周期 |
| | get-bucket-location | 查询存储桶地域 |
| 图片基础 | image-info | 图片元信息 |
| | image-thumbnail | 缩放 |
| | image-crop | 裁剪 |
| | image-rotate | 旋转 |
| | image-format | 格式转换 |
| | watermark-font | 文字水印 |
| AI图片 | assess-quality | 质量评估 |
| | ai-super-resolution | 超分辨率 |
| | ai-pic-matting | 智能裁剪 |
| | ai-qrcode | 二维码识别 |
| 内容识别 | recognize-image | 图片标签识别 |
| | ocr-general | OCR 文字识别 |
| 文档处理 | create-doc-to-pdf-job | 文档转 PDF |
| | describe-doc-job | 查询文档任务 |
| | doc-preview | 文档预览（转图片） |
| | doc-preview-html-url | 文档在线预览链接 |
| 媒体处理 | create-media-smart-cover-job | 智能封面 |
| | describe-media-job | 查询媒体任务 |
| | media-transcode-job | 视频转码 |
| | media-snapshot | 视频截帧 |
| | media-info | 媒体文件信息 |
| 内容审核 | audit-image | 图片同步审核 |
| | audit-image-job | 图片异步审核 |
| | audit-video-job | 视频审核 |
| | audit-audio-job | 音频审核 |
| | audit-text-job | 文本审核 |
| | audit-document-job | 文档审核 |
| | describe-audit-job | 查询审核结果 |
| 智能语音 | speech-recognition-job | 语音识别 |
| | tts-job | 语音合成 |
| | noise-reduction-job | 音频降噪 |
| | voice-separate-job | 人声分离 |
| 文件处理 | file-hash | 哈希计算 |
| | file-compress-job | 文件压缩 |
| | file-uncompress-job | 文件解压 |
| | describe-file-job | 查询文件任务 |
| MetaInsight 管理 | list-datasets | 列出数据集 |
| | create-dataset | 创建数据集 |
| | describe-dataset | 查询数据集详情 |
| | create-dataset-binding | 绑定存储桶 |
| | describe-dataset-bindings | 查询绑定关系 |
| MetaInsight 索引 | create-file-meta-index | 创建文件索引 |
| | describe-file-meta-index | 查询文件索引 |
| | delete-file-meta-index | 删除文件索引 |
| MetaInsight 检索 | image-search-pic | 以图搜图 |
| | image-search-text | 文本搜图 |
| | face-search | 人脸搜索 |
| | dataset-simple-query | 元数据检索 |
| | hybrid-search | 多模态检索（文档检索） |
| 通用 | ci-request | 调用任意 CI API |
| 🚀 知识库 | create-knowledge-base | "创建知识库" → 一键创建桶+数据集+绑定 |
| | upload → 指向知识库桶 | "上传到知识库" → 上传文档 |
| | hybrid-search → 指向知识库数据集 | "查询知识库" → 语义检索文档内容 |
| 🚫 禁止 | ~~deleteBucket~~ | 不允许删除/清空存储桶 |
| 🔐 凭证管理 | encrypt-env | 加密 .env → .env.enc 并删除明文 |
| | decrypt-env | 解密 .env.enc → .env 还原明文 |

安全注意事项

凭证处理

凭证存储有三种模式，安全性递增：

模式	存储位置	安全性	用法
默认模式	shell session 环境变量	⭐⭐⭐ 最安全（关闭终端即消失）	INLINECODE114
持久化模式

项目 .env 文件（权限 600） | ⭐⭐ 便捷但明文 | setup.sh --from-env --persist |
| 加密持久化 | 项目 .env.enc（AES-256-GCM） | ⭐⭐⭐ 推荐 | 先 --persist，再 encrypt-env |

加密存储（推荐）

持久化后执行 encrypt-env 即可加密凭证：

CODEBLOCK20

加密原理：

• - 算法：AES-256-GCM（认证加密，防篡改）
• 密钥派生：INLINECODE121
• 加密文件绑定当前机器和用户，拷贝到其他机器/用户无法解密
• 如需还原明文：INLINECODE122
• 清理凭证：INLINECODE123

其他安全要求：

• - 永远不要在对话中回显 SecretId/SecretKey
• 推荐使用 STS 临时凭证（自带有效期，过期自动失效）

最小权限与子账号密钥

⚠️ 永远不要使用主账号密钥。

推荐创建专用子账号并授予最小权限策略：

• - QcloudCOSDataReadOnlyAccess — 仅读取
• INLINECODE125 — COS 数据读写
• 如需数据万象功能，额外添加 INLINECODE126

可进一步限制到具体存储桶：
CODEBLOCK21

安装包说明

本技能通过 npm 安装 cos-nodejs-sdk-v5（腾讯云 COS 官方 Node.js SDK），安装到项目本地 node_modules/，不执行全局安装。

使用规范

1. 1. 首次使用先运行 {baseDir}/scripts/setup.sh --check-only 检查环境
2. 所有文件路径（--key）为存储桶内的相对路径，如 INLINECODE131
3. 异步任务（文档转换、视频封面）脚本会自动轮询结果，也可通过 --job-id 手动查询
4. 上传后主动获取链接：上传完成后调用 sign-url 返回访问链接
5. 错误处理：调用失败时先用 setup.sh --check-only 诊断环境问题
6. 扩展 CI 能力：通过 ci-request action 可调用任意 CI API（内容审核、文件处理等）
7. 脚本源码见 INLINECODE136
8. 命令参考见 INLINECODE137