腾讯云 COS 技能

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

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

所有操作通过

scripts/cos_node.mjs

单一脚本完成，输出 JSON 格式。

首次使用 — 自动设置

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

步骤 1：检查当前状态

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

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

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

告诉用户：

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

🛡️ 凭证安全保障
默认不落盘：凭证仅存于当前终端会话内存中，关闭终端即消失
可选持久化：如需保存，凭证写入项目本地
.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 — 自定义域名配置

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

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/

并验证连接。

持久化说明：

--persist

会将凭证写入项目目录下的

.env

文件（权限 600），并自动添加到

.gitignore

。

cos_node.mjs

启动时会自动读取

.env

（环境变量优先于

.env

文件）。清理凭证：

rm -f .env

。

操作指南

所有操作通过单一脚本

scripts/cos_node.mjs

完成，输出 JSON 格式。

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

）

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

COS 存储操作

# 上传文件
upload --file /path/to/file.jpg --key remote/path/file.jpg
上传字符串
put-string --content "文本内容" --key remote/file.txt --content-type "text/plain"
下载文件
download --key remote/path/file.jpg --output /path/to/save/file.jpg
列出文件
list --prefix "images/" --max-keys 100
获取签名 URL
sign-url --key remote/path/file.jpg --expires 3600
查看文件信息
head --key remote/path/file.jpg
删除文件
delete --key remote/path/file.jpg
批量删除
delete-multiple --keys '["file1.txt","file2.txt"]'
复制对象

copy-object --source bucket.cos.region.myqcloud.com/source.jpg --key dest.jpg

COS 存储桶管理

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

# 列出所有存储桶
list-buckets
创建存储桶
create-bucket --bucket mybucket-1250000000 --region ap-guangzhou
检查存储桶是否存在
head-bucket --bucket mybucket-1250000000
获取/设置存储桶 ACL
get-bucket-acl
put-bucket-acl --acl private
获取/设置跨域配置
get-bucket-cors
put-bucket-cors --origin "*" --methods "GET,POST,PUT"
获取/设置标签
get-bucket-tagging
put-bucket-tagging --tags '[{"Key":"env","Value":"prod"}]'
查询版本控制/生命周期/地域

get-bucket-versioning
get-bucket-lifecycle
get-bucket-location

CI 图片基础处理

# 获取图片元信息
image-info --key images/photo.jpg
图片缩放
image-thumbnail --key images/photo.jpg --width 200 --height 200
图片裁剪
image-crop --key images/photo.jpg --width 300 --height 300 --gravity center
图片旋转
image-rotate --key images/photo.jpg --degree 90
格式转换（webp/png/jpg/avif/heif/tpg）
image-format --key images/photo.jpg --format webp
添加文字水印（支持中文）

watermark-font --key images/photo.jpg --text "版权所有"

CI AI 图片处理

# 图片质量评估
assess-quality --key images/photo.jpg
AI 超分辨率
ai-super-resolution --key images/photo.jpg
AI 智能裁剪
ai-pic-matting --key images/photo.jpg --width 200 --height 200
二维码识别

ai-qrcode --key images/qrcode.jpg

CI 内容识别

# 图片标签识别
recognize-image --key images/photo.jpg
OCR 文字识别

ocr-general --key images/document.jpg

CI 文档处理

# 文档转 PDF（自动轮询等待结果）
create-doc-to-pdf-job --key docs/report.docx
查询文档处理任务
describe-doc-job --job-id <jobId>
文档预览（转图片）
doc-preview --key docs/report.docx --page 1 --format jpg
获取文档在线预览 HTML 链接

doc-preview-html-url --key docs/report.docx

CI 媒体处理

# 视频智能封面（自动轮询等待结果）
create-media-smart-cover-job --key videos/demo.mp4
查询媒体处理任务
describe-media-job --job-id <jobId>
视频转码
media-transcode-job --key videos/demo.mp4 --format mp4
视频截帧
media-snapshot --key videos/demo.mp4 --time 5 --format jpg
获取媒体文件信息

media-info --key videos/demo.mp4

CI 内容审核

# 图片同步审核
audit-image --key images/photo.jpg
图片异步审核任务
audit-image-job --key images/photo.jpg
视频审核任务
audit-video-job --key videos/demo.mp4
音频审核任务
audit-audio-job --key audio/song.mp3
文本审核任务
audit-text-job --content "待审核的文本内容"
文档审核任务
audit-document-job --key docs/report.docx
查询审核任务结果（--type 可选 image/video/audio/text/document）

describe-audit-job --job-id <jobId> --type image

CI 智能语音

# 语音识别
speech-recognition-job --key audio/meeting.mp3 --engine 16k_zh_video
语音合成（文字转语音）
tts-job --text "你好，欢迎使用腾讯云"
音频降噪
noise-reduction-job --key audio/noisy.mp3
人声分离

voice-separate-job --key audio/song.mp3

CI 文件处理

# 文件哈希计算（md5/sha1/sha256）
file-hash --key docs/report.docx --type md5
文件压缩
file-compress-job --prefix "images/" --format zip
文件解压
file-uncompress-job --key archive.zip --prefix "output/"
查询文件处理任务

describe-file-job --job-id <jobId>

CI MetaInsight

数据集管理

# 列出所有数据集
list-datasets
创建数据集（模板：Official:COSBasicMeta / Official:ImageSearch / Official:FaceSearch）
create-dataset --name my-dataset --template "Official:ImageSearch" --description "图片搜索"
查询数据集详情
describe-dataset --name my-dataset
绑定存储桶到数据集（默认 Mode=1 存量索引，自动索引桶内已有文件）
create-dataset-binding --name my-dataset
create-dataset-binding --name my-dataset --uri "cos://other-bucket-1250000000"
仅增量索引（Mode=0，只索引绑定后新上传的文件）
create-dataset-binding --name my-dataset --mode 0
查询数据集的绑定关系

describe-dataset-bindings --name my-dataset

索引管理

# 创建文件元数据索引
create-file-meta-index --name my-dataset --uri "cos://bucket/images/photo.jpg" --media-type image
查询文件元数据索引
describe-file-meta-index --name my-dataset --uri "cos://bucket/images/photo.jpg"
删除文件元数据索引

delete-file-meta-index --name my-dataset --uri "cos://bucket/images/photo.jpg"

检索（需预建数据集）

三种检索需要不同模板的数据集，通过环境变量或

--dataset

参数分别指定：

检索类型	所需数据集模板	环境变量
图片检索（以图搜图/文本搜图）	`Official:ImageSearch`	`TENCENT_COS_DATASET_IMAGE_SEARCH`
人脸搜索	`Official:FaceSearch`	`TENCENT_COS_DATASET_FACE_SEARCH`
元数据检索	`Official:COSBasicMeta`	`TENCENT_COS_DATASET_META`

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

# 以图搜图（ImageSearch 数据集）
image-search-pic --uri "https://example.com/query.jpg"
文本搜图（ImageSearch 数据集）
image-search-text --text "蓝天白云"
人脸搜索（FaceSearch 数据集）
face-search --uri "cos://bucket/photo.jpg" --max-face-num 1 --limit 10 --threshold 80
元数据检索 — 简单查询（任意数据集）
dataset-simple-query --dataset my-dataset --sort CustomId --order desc --max-results 50
dataset-simple-query --dataset my-dataset --query '{"Operation":"eq","Field":"ContentType","Value":"image/jpeg"}'
多模态检索 — 文档检索（DocSearch 数据集）

hybrid-search --text "包含一颗大树的文档" --dataset docsearch --templates DocSearch --limit 10
hybrid-search --text "关键词" --dataset docsearch --filter '{"$and":[{"MediaType":{"$in":["image","document"]}},{"Size":{"$gt":123}}]}'

🚀 知识库（快捷功能）

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

用户意图识别

用户可能的说法	对应操作
"帮我创建一个知识库" "建一个知识库" "我想做个文档库"	→ 执行 `create-knowledge-base`
"上传到知识库" "把文件放进知识库" "往知识库里加文档"	→ 执行 `upload` （指向知识库对应的桶）
"查询知识库" "从知识库找" "搜索知识库" "知识库里有没有关于XX的内容"	→ 执行 `hybrid-search` （指向知识库对应的数据集）

流程 1：创建知识库

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

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

create-knowledge-base --name <用户指定的名称>

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

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

你可以把文档（PDF、Word、Excel、PPT、TXT 等）上传到这个知识库

上传后系统会自动建立索引（需要几秒到几分钟）

之后你可以直接说"从知识库里搜一下XXX"来查询内容

流程 2：上传到知识库

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

判断使用哪个知识库：

如果本次对话中已创建/使用过知识库 → 直接使用该知识库的桶和地域
如果不确定 → 执行
```
list-datasets
```
列出所有数据集，筛选 TemplateId 为
```
Official:DocSearch
```
的数据集：
- 只有 1 个 DocSearch 数据集 → 直接使用它，通过数据集绑定关系推断对应的桶
- 有多个 DocSearch 数据集 → 列出让用户选择
- 没有 DocSearch 数据集 → 告诉用户"你还没有知识库，要帮你创建一个吗？"
确定知识库后，执行上传：

upload --file <用户的文件路径> --key <文件名> --bucket <知识库桶名> --region <知识库地域>

告诉用户：

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

流程 3：查询知识库

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

判断使用哪个知识库：

如果本次对话中已创建/使用过知识库 → 直接使用该知识库的数据集
如果不确定 → 执行
```
list-datasets
```
列出所有数据集，筛选 TemplateId 为
```
Official:DocSearch
```
的数据集：
- 只有 1 个 DocSearch 数据集 → 直接使用它
- 有多个 DocSearch 数据集 → 列出让用户选择（展示名称和文件数）
- 没有 DocSearch 数据集 → 告诉用户"你还没有知识库，要帮你创建一个吗？"
确定知识库后，执行检索：

hybrid-search --text "<用户的查询内容>" --dataset <知识库数据集名> --templates DocSearch

结果呈现（不要直接输出 JSON，用友好格式）：
- 按相关度排序展示检索结果
- 每条结果展示：相关度分数 + 来源文件名 + 匹配内容摘要
- 如果没有匹配结果 → 告诉用户"知识库中没有找到相关内容，你可以上传更多文档试试"

CI 通用请求（扩展入口）

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

ci-request --method POST --path "image/auditing" --body '<xml>...</xml>'
ci-request --method GET --path "jobs/<jobId>"

功能对照表

分类	action	说明
存储	`upload`	上传文件
	`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 环境变量

⭐⭐⭐ 最安全（关闭终端即消失）

setup.sh --from-env

持久化模式

项目

.env

文件（权限 600）

⭐⭐ 便捷但明文

setup.sh --from-env --persist

加密持久化

项目

.env.enc

（AES-256-GCM）

⭐⭐⭐ 推荐

先

--persist

，再

encrypt-env

加密存储（推荐）

持久化后执行

encrypt-env

即可加密凭证：

# 1. 先持久化
setup.sh --from-env --persist
2. 加密（自动删除明文 .env，生成 .env.enc）
node scripts/cos_node.mjs encrypt-env
3. 之后脚本自动从 .env.enc 解密读取，所有功能正常使用

node scripts/cos_node.mjs list

加密原理：

算法：AES-256-GCM（认证加密，防篡改）

密钥派生：

SHA-256(hostname + username + 项目绝对路径)

加密文件绑定当前机器和用户，拷贝到其他机器/用户无法解密
如需还原明文：
```
node scripts/cos_node.mjs decrypt-env
```
清理凭证：
```
rm -f .env .env.enc
```

其他安全要求：

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

最小权限与子账号密钥

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

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

```
QcloudCOSDataReadOnlyAccess
```
— 仅读取
```
QcloudCOSDataFullControl
```
— COS 数据读写
如需数据万象功能，额外添加
```
QcloudCIFullAccess
```

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

{
  "statement": [{
    "effect": "allow",
    "action": ["cos:*"],
    "resource": ["qcs::cos:<Region>::uid/<APPID>:<BucketName>/*"]
  }]
}

安装包说明

本技能通过 npm 安装

cos-nodejs-sdk-v5

（腾讯云 COS 官方 Node.js SDK），安装到项目本地

node_modules/

，不执行全局安装。

使用规范

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

Tencent COS

AI Skill Market Insights

Be Part of the 0+ Developer Community

腾讯云 COS 技能

首次使用 — 自动设置

步骤 1：检查当前状态

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

🛡️ 凭证安全保障

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

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

可选配置

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

默认模式：凭证仅存于当前 session，关闭终端后需重新 export

持久化模式：凭证写入项目本地 .env 文件，下次自动读取

操作指南

COS 存储操作

上传字符串

下载文件

列出文件

获取签名 URL

查看文件信息

删除文件

批量删除

复制对象

COS 存储桶管理

创建存储桶

检查存储桶是否存在

获取/设置存储桶 ACL

获取/设置跨域配置

获取/设置标签

查询版本控制/生命周期/地域

CI 图片基础处理

图片缩放

图片裁剪

图片旋转

格式转换（webp/png/jpg/avif/heif/tpg）

添加文字水印（支持中文）

CI AI 图片处理

AI 超分辨率

AI 智能裁剪

二维码识别

CI 内容识别

OCR 文字识别

CI 文档处理

查询文档处理任务

文档预览（转图片）

获取文档在线预览 HTML 链接

CI 媒体处理

查询媒体处理任务

视频转码

视频截帧

获取媒体文件信息

CI 内容审核

图片异步审核任务

视频审核任务

音频审核任务

文本审核任务

文档审核任务

查询审核任务结果（--type 可选 image/video/audio/text/document）

CI 智能语音

语音合成（文字转语音）

音频降噪

人声分离

CI 文件处理

文件压缩

文件解压

查询文件处理任务

CI MetaInsight

数据集管理

创建数据集（模板：Official:COSBasicMeta / Official:ImageSearch / Official:FaceSearch）

查询数据集详情

绑定存储桶到数据集（默认 Mode=1 存量索引，自动索引桶内已有文件）

仅增量索引（Mode=0，只索引绑定后新上传的文件）

查询数据集的绑定关系

索引管理

查询文件元数据索引

删除文件元数据索引

检索（需预建数据集）

文本搜图（ImageSearch 数据集）

人脸搜索（FaceSearch 数据集）