一站式管理腾讯云对象存储(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 临时凭证（最安全，自带有效期）
1. SecretId — TmpSecretId
2. SecretKey — TmpSecretKey
3. Token — SecurityToken
4. Region — 存储桶区域（如 ap-guangzhou）
5. Bucket — 存储桶名称（格式 name-appid）

#### ⚠️ 降级方案：永久密钥（必须使用子账号最小权限密钥）
1. SecretId / SecretKey / Region / Bucket

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

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

export TENCENT_COS_SECRET_ID=""
export TENCENT_COS_SECRET_KEY=""
export TENCENT_COS_TOKEN=""  # STS 临时凭证才需要
export TENCENT_COS_REGION=""
export TENCENT_COS_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  [--option value ...]

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

• --bucket — 指定操作的存储桶（覆盖 TENCENT_COS_BUCKET）
• --region — 指定地域（覆盖 TENCENT_COS_REGION）
• --dataset-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 
# 文档预览（转图片）
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 
# 视频转码
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  --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 

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 参数分别指定：

# 以图搜图（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 --name <用户指定的名称>

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

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

ci-request --method POST --path "image/auditing" --body '...'
ci-request --method GET --path "jobs/"

# 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

{
  "statement": [{
    "effect": "allow",
    "action": ["cos:"],
    "resource": ["qcs::cos:::uid/:/*"]
  }]
}

安装包说明

本技能通过 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