SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillstencentcloud-cos

tencentcloud-cos

Data & analytics

View repository

Updated 10-15 17:26

About this skill

Tencent Cloud COS Skill

One-stop management of Tencent Cloud Object Storage (COS) and Data万象 (CI), providing the following capabilities through a unified Node.js SDK script:

  • File Storage: upload, download, list, delete files, obtain signed download links, batch operations, copy
  • Bucket Management: list/create buckets, ACL, CORS, tags, versioning, lifecycle management
  • Image Processing: scaling, cropping, rotation, format conversion, text watermark, quality assessment, super resolution, smart cropping, QR code recognition
  • Content Recognition: image tag recognition, OCR text recognition
  • Document Processing: convert office documents to PDF, document preview (image/HTML)
  • Media Processing: video smart cover, transcoding, frame capturing, media information
  • Content Moderation: image/video/audio/text/document violation detection
  • Smart Speech: speech recognition, speech synthesis, audio noise reduction, vocal separation
  • File Processing: hash calculation, compression, decompression
  • Smart Retrieval MetaInsight: dataset management, index management, image search by image, text search by image, face search, metadata retrieval, multimodal document retrieval
  • 🚀 Knowledge Base: one-click knowledge base creation (automatically create bucket + dataset + binding), upload documents to the knowledge base, semantic retrieval of knowledge base content

All operations are completed through scripts/cos_node.mjs a single script, outputting in JSON format.

First Use — Automatic Setup

When the user requests a COS operation for the first time, follow the process below:

Step 1: Check current status

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

If Node.js and cos-nodejs-sdk-v5 are installed and the environment variables are configured, skip to "Operation Guide".

Step 2: If not configured, guide the user to provide credentials

Tell the user:

I need your Tencent Cloud credentials to connect to the COS storage service. Please rest assured that your keys will be protected as follows:

🛡️ Credential Security Guarantee

  • Not persisted to disk by default: credentials are only stored in the memory of the current terminal session and disappear when the terminal is closed
  • Optional persistence: if saving is needed, credentials are written to the project's local .env file (readable only by the current user, permission 600)
  • Supports AES-256 encryption: after persistence, it can be encrypted with one click into .env.enc, the plaintext is automatically deleted, and the key is bound to this machine + this user, so it cannot be decrypted if copied to another environment
  • Automatic prevention of accidental commits：.env / .env.enc automatically added to .gitignore, and will not enter version control
  • Your keys will never be echoed back in the conversation

🔒 Recommended solution: STS temporary credentials (most secure, with built-in validity period)

  1. SecretId — TmpSecretId
  2. SecretKey — TmpSecretKey
  3. Token — SecurityToken
  4. Region — bucket region (e.g. ap-guangzhou)
  5. Bucket — bucket name (format name-appid)

⚠️ Fallback solution: permanent key (must use a sub-account least-privilege key)

  1. SecretId / SecretKey / Region / Bucket

Optional configuration

  • DatasetName — Data万象 dataset name (only required for MetaInsight retrieval)
  • Domain / ServiceDomain / Protocol — Custom domain configuration

Step 3: Set environment variables and run the installation

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

The script will automatically install cos-nodejs-sdk-v5 to the project's local node_modules/ and verify the connection.

Persistence notes：--persist will write the credentials to the .env file in the project directory (permissions 600), and automatically add it to .gitignore。 cos_node.mjs On startup, .envwill be read automatically (environment variables take precedence over the .env file). Clean up credentials:rm -f .env。

Operations guide

All operations are performed through a single script scripts/cos_node.mjs , with output in JSON format.

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

Global optional parameters(supported by all actions, used to override the default values in environment variables):

  • --bucket <BucketName> — Specify the bucket for the operation (overrides TENCENT_COS_BUCKET）
  • --region <Region> — Specify the region (overrides TENCENT_COS_REGION）
  • --dataset-name <Name> — Specify the dataset name (overrides TENCENT_COS_DATASET_NAME）

The Region, Bucket, and DatasetName in the initial configuration are only default values; each call can freely specify them via parameters.

COS storage operations

# 上传文件
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 bucket management

⚠️ Security restriction: This skill prohibits deleting buckets and emptying buckets.

# 列出所有存储桶
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 basic image processing

# 获取图片元信息
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 image processing

# 图片质量评估
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 content recognition

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

# OCR 文字识别
ocr-general --key images/document.jpg

CI document processing

# 文档转 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 media processing

# 视频智能封面（自动轮询等待结果）
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 content moderation

# 图片同步审核
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 intelligent speech

# 语音识别
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 file processing

# 文件哈希计算（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

Dataset management

# 列出所有数据集
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

Index management

# 创建文件元数据索引
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"

Retrieval (requires a pre-built dataset)

The three retrieval types requiredifferent templatesdatasets, specified separately via environment variables or the --dataset parameter:

Retrieval type Required dataset template Environment variable
Image retrieval (image search by image/text search by image) Official:ImageSearch TENCENT_COS_DATASET_IMAGE_SEARCH
Face search Official:FaceSearch TENCENT_COS_DATASET_FACE_SEARCH
Metadata retrieval Official:COSBasicMeta TENCENT_COS_DATASET_META

TENCENT_COS_DATASET_NAME as the fallback value for image retrieval. All actions support the --dataset parameter override.

# 以图搜图（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}}]}'

🚀 Knowledge base (quick feature)

Important: This is a set of quick workflows oriented toward colloquial user descriptions. Users do not need to know the underlying commands; they only need to describe their intent in natural language.

User intent recognition

Possible user phrasing Corresponding operation
"Help me create a knowledge base" "Build a knowledge base" "I want to make a document library" → Execute create-knowledge-base
"Upload to the knowledge base" "Put files into the knowledge base" "Add documents to the knowledge base" → Execute upload(pointing to the bucket corresponding to the knowledge base)
"Query the knowledge base" "Find from the knowledge base" "Search the knowledge base" "Does the knowledge base have content about XX" → Execute hybrid-search(pointing to the dataset corresponding to the knowledge base)

Workflow 1: Create a knowledge base

When the user says "create a knowledge base"/"build a knowledge base"/"I want to make a document library":

  1. If the user did not specify a name → ask the user what name they want to give the knowledge base
  2. Execute creation:
create-knowledge-base --name <用户指定的名称>
  1. Automatically complete three steps: create storage bucket → create DocSearch dataset → bind
  2. Remember the knowledge base information created this time(bucket name, region, dataset name), and use it directly for subsequent uploads/queries
  3. Tell the user:

✅ Knowledge base "<name>" has been created!

  • You can upload documents (PDF, Word, Excel, PPT, TXT, etc.) to this knowledge base
  • After uploading, the system will automatically build an index (it takes a few seconds to a few minutes)
  • After that, you can directly say "search the knowledge base for XXX" to query content

Process 2: Upload to the knowledge base

When the user says "upload to the knowledge base"/"put the file into the knowledge base"/"add documents to the knowledge base":

Determine which knowledge base to use:

  1. If a knowledge base has already been created/used in this conversation → directly use that knowledge base's bucket and region
  2. If uncertain → execute list-datasets to list all datasets and filter datasets whose TemplateId is Official:DocSearch :
    • Only 1 DocSearch dataset → directly use it, and infer the corresponding bucket through the dataset binding relationship
    • Multiple DocSearch datasets → list them for the user to choose
    • No DocSearch dataset → tell the user "you don't have a knowledge base yet, do you want me to help you create one?"
  3. After determining the knowledge base, execute the upload:
upload --file <用户的文件路径> --key <文件名> --bucket <知识库桶名> --region <知识库地域>
  1. Tell the user:

✅ The file has been uploaded to the knowledge base "<name>", the index is being built, and it will be searchable shortly.

Process 3: Query the knowledge base

When the user says "query the knowledge base"/"find XX from the knowledge base"/"search the knowledge base"/"does the knowledge base have anything about XX"/"search the knowledge base for", etc.:

Determine which knowledge base to use:

  1. If a knowledge base has already been created/used in this conversation → directly use that knowledge base's dataset
  2. If uncertain → execute list-datasets to list all datasets and filter datasets whose TemplateId is Official:DocSearch :
    • Only 1 DocSearch dataset → directly use it
    • Multiple DocSearch datasets → list them for the user to choose (show names and file counts)
    • No DocSearch dataset → tell the user "you don't have a knowledge base yet, do you want me to help you create one?"
  3. After determining the knowledge base, execute the retrieval:
hybrid-search --text "<用户的查询内容>" --dataset <知识库数据集名> --templates DocSearch
  1. Result presentation(do not output JSON directly; use a friendly format):
    • Present retrieval results sorted by relevance
    • Each result shows:relevance score + source file name + matching content summary
    • If there are no matching results → tell the user "no related content was found in the knowledge base, you can try uploading more documents"

CI general request (extension entry)

Used to call CI capabilities that have not yet been encapsulated as independent actions:

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

Feature comparison table

Category action Description
Storage upload Upload file
put-string Upload string
download Download file
list List files
sign-url Get signed URL
delete Delete file
delete-multiple Batch delete
head File metadata
copy-object Copy object
Bucket management list-buckets List all buckets
create-bucket Create bucket
head-bucket Check if bucket exists
get-bucket-acl / put-bucket-acl ACL permission management
get-bucket-cors / put-bucket-cors CORS configuration
get-bucket-tagging / put-bucket-tagging Tag management
get-bucket-versioning Query versioning
get-bucket-lifecycle Query lifecycle
get-bucket-location Query bucket region
Image basics image-info Image metadata
image-thumbnail Resize
image-crop Crop
image-rotate Rotate
image-format Format conversion
watermark-font Text watermark
AI image assess-quality Quality assessment
ai-super-resolution Super resolution
ai-pic-matting Smart crop
ai-qrcode QR code recognition
Content recognition recognize-image Image tag recognition
ocr-general OCR text recognition
Document processing create-doc-to-pdf-job Convert document to PDF
describe-doc-job Query document task
doc-preview Document preview (convert to image)
doc-preview-html-url Document online preview link
Media processing create-media-smart-cover-job Smart cover
describe-media-job Query media task
media-transcode-job Video transcoding
media-snapshot Video frame capture
media-info Media file information
Content moderation audit-image Image synchronous moderation
audit-image-job Image asynchronous moderation
audit-video-job Video moderation
audit-audio-job Audio moderation
audit-text-job Text moderation
audit-document-job Document moderation
describe-audit-job Query moderation result
Smart voice speech-recognition-job Speech recognition
tts-job Speech synthesis
noise-reduction-job Audio noise reduction
voice-separate-job Vocal separation
File processing file-hash Hash calculation
file-compress-job File compression
file-uncompress-job File decompression
describe-file-job Query file task
MetaInsight management list-datasets List datasets
create-dataset Create dataset
describe-dataset Query dataset details
create-dataset-binding Bind bucket
describe-dataset-bindings Query binding relationship
MetaInsight index create-file-meta-index Create file index
describe-file-meta-index Query file index
delete-file-meta-index Delete file index
MetaInsight search image-search-pic Search by image
image-search-text Text-to-image search
face-search Face search
dataset-simple-query Metadata search
hybrid-search Multimodal search (document search)
General ci-request Call any CI API
🚀 Knowledge base create-knowledge-base "Create knowledge base" → one-click creation of bucket + dataset + binding
upload → points to knowledge base bucket "Upload to knowledge base" → upload document
hybrid-search → Points to knowledge base dataset "Query knowledge base" → Semantic retrieval of document content
🚫 Prohibited deleteBucket Deleting/clearing buckets is not allowed
🔐 Credential Management encrypt-env Encrypt .env → .env.enc and delete plaintext
decrypt-env Decrypt .env.enc → .env to restore plaintext

Security Notes

Credential Handling

There are three credential storage modes, with increasing security:

Mode Storage Location Security Usage
Default Mode shell session environment variables ⭐⭐⭐ Most secure (disappears when terminal is closed) setup.sh --from-env
Persistent Mode Project .env file (permissions 600) ⭐⭐ Convenient but plaintext setup.sh --from-env --persist
Encrypted Persistence Project .env.enc（AES-256-GCM） ⭐⭐⭐ Recommended First --persist, then encrypt-env

Encrypted Storage (Recommended)

After persisting, run encrypt-env to encrypt credentials:

# 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

Encryption Principle：

  • Algorithm: AES-256-GCM (authenticated encryption, tamper-proof)
  • Key Derivation:SHA-256(hostname + username + 项目绝对路径)
  • The encrypted file is bound to the current machine and user, and cannot be decrypted if copied to another machine/user
  • To restore plaintext:node scripts/cos_node.mjs decrypt-env
  • To clean up credentials:rm -f .env .env.enc

Other Security Requirements：

  • Never echo in conversations SecretId/SecretKey
  • It is recommended to use STS temporary credentials(with a built-in validity period, automatically expiring when expired)

Least Privilege and Sub-account Keys

⚠️ Never use the root account key。

It is recommended to create a dedicated sub-account and grant a least-privilege policy:

  • QcloudCOSDataReadOnlyAccess — Read-only
  • QcloudCOSDataFullControl — COS data read/write
  • If you need Data万象 features, additionally add QcloudCIFullAccess

It can be further restricted to specific buckets:

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

Installation Package Description

This skill installs via npm cos-nodejs-sdk-v5(Tencent Cloud COS official Node.js SDK), installed locally in the project node_modules/, without performing a global installation.

Usage Guidelines

  1. For first-time use, first run {baseDir}/scripts/setup.sh --check-only to check the environment
  2. All file paths（--key) are relative paths within the bucket, such as images/photo.jpg
  3. Asynchronous tasks(document conversion, video covers) scripts will automatically poll for results, and you can also use --job-id to query manually
  4. Actively obtain links after upload: After the upload is complete, call sign-url to return the access link
  5. Error handling: When a call fails, first use setup.sh --check-only to diagnose environment issues
  6. Extend CI capabilities: Through ci-request action, any CI API can be called (content moderation, file processing, etc.)
  7. Script source codeSee scripts/cos_node.mjs
  8. Command referenceSee references/api_reference.md