ShawnmZhang

Tencent COS

ナレッジ管理v1.2.3
作者:ShawnmZhang更新日 2026-11-04全 16 バージョン · 最新版の公開日 2026-11-04tencent-cos-skill
#OCR#文档处理#知识库#安全#密钥

AlphaMoatによると、2026-10時点でTencent COSのダウンロード数は10,840、スター数は4で、累計ダウンロード数で今回のランキング対象AIスキル10,914件中2,516位、ナレッジ管理では745件中171位です。

一覧の初期表示は累計ダウンロード数順で、スター数順にも並べ替えできます。詳細ページの順位は累計ダウンロード数で計算しています。

ダウンロード数
1.1万
スター数
4
累計ダウンロード順位
#2,516
全体の上位 24% · ナレッジ管理の上位 23%
プラットフォームダウンロード数スター数コメント
ClawHub ↗1.1万4-

プラットフォームごとに集計方法と集計時点が異なります。

このスキルでできること

統一 Node.js SDK スクリプト(scripts/cos_node.mjs、ci_api.mjs、preview_gen.mjs)で以下を提供:ファイルストレージ(アップロード、ダウンロード、署名リンク、一括操作);バケット管理(ACL、CORS、タグ、ライフサイクルなど。バケットの削除/空化は禁止);画像処理(リサイズ、切り抜き、透かし、品質評価、AI 超解像、QR コード認識);コンテンツ認識(画像タグ、OCR、動画 ASR/OCR);ドキュメント処理(Word/Excel/PPT を PDF へ、プレビュー);メディア処理(スマートカバー、トランスコード、フレーム抽出);コンテンツ審査(画像/動画/音声/テキスト/文書);音声処理(認識、合成、ノイズ除去、ボーカル分離);MetaInsight 検索(画像→画像、テキスト→画像/動画、顔検索、マルチモーダル検索。北京/上海/成都の 3 リージョンのみ対応)とデータセット分析;ナレッジベースのワンクリック作成(バケット+データセット+バインド)とセマンティック検索。セキュリティ:STS 一時認証情報を推奨、最小権限のサブアカウントキー必須(ルートアカウントキーは禁止)、認証情報はデフォルトでディスクに書き込まず、AES-256-GCM による暗号化永続化に対応し、チャットで表示しません。KIKI=1 の厳格モードではすべての削除操作を禁止。注意:COS と CI は有料サービスです。バッチ操作が 100 オブジェクト超(データ処理は 50 超)の場合はコンソールを案内します。

資料公開日 2026-10-27

できること

  • ファイルのアップロード/ダウンロードと署名リンク取得(upload、download、sign-url)
  • 画像・メディア処理:リサイズ/透かし/超解像、PDF 変換、スマートカバー、トランスコード、審査
  • ナレッジベースを作成しドキュメントをアップロードしてセマンティック検索(create-knowledge-base、hybrid-search)
  • MetaInsight で画像検索・テキスト動画検索・データセット集計分析

使う場面

  • テンセントクラウド COS の管理や CI による画像/動画/文書処理が必要な場合
  • ナレッジベース構築、画像検索、バケット内ファイルの審査や文字起こしを行いたい場合

プロンプト例

スキルのドキュメントをもとに生成した例であり、実際の実行結果ではありません。

このファイルを COS にアップロードしてダウンロードリンクを作って
この画像を拡大してテキスト透かしを付けて
ナレッジベースを作って、この PDF を入れて

月次の推移

ダウンロード数1.1万
1万1.1万1.1万2026-09 · ダウンロード数 1万2026-10 · ダウンロード数 1.1万26-0926-10
スター数4
3452026-09 · スター数 42026-10 · スター数 426-0926-10
月ダウンロード数前月比スター数
2026-101.1万—4
2026-091万—4

SKILL.md 原文

作者が公開した元のファイルをテキストのまま表示しています。AlphaMoat による編集や審査はしていません。リンクはクリックできません。コマンドは内容を確認してから実行してください。取得日 2026-10-23。

53 KB・ClawHub v1.1.9
---
name: tencentcloud-cos
description: >
  腾讯云对象存储(COS)和数据万象(CI)集成技能。覆盖文件存储管理、AI处理和知识库三大核心场景。
  存储场景:上传文件到云端、下载云端文件、批量管理存储桶文件、获取文件签名链接分享、查看文件元信息、查询数据万象及子服务开通状态。
  图片处理场景:图片质量评估打分、AI超分辨率放大、AI智能裁剪、二维码/条形码识别、添加文字水印、获取图片EXIF信息、缩放、裁剪、旋转、格式转换。
  文档处理场景:Word/Excel/PPT等办公文档转PDF、文档预览。
  媒体处理场景:视频智能封面提取、视频转码、视频截帧、获取媒体信息。
  内容审核场景:图片/视频/音频/文本/文档内容审核,检测违规内容。
  智能语音场景:语音识别(音频转文字)、语音合成(文字转语音)、音频降噪、人声分离。
すべて表示(全 1022 行)
  文件处理场景:文件哈希计算、文件压缩打包、文件解压。
  内容识别场景:描述单个图片或视频文件的内容、图片标签识别、OCR文字识别、视频ASR/OCR和粗分类。
  知识库场景:一键创建知识库、上传文档到知识库、从知识库检索内容片段。
  智能检索场景:MetaInsight以图搜图、以文搜图、以文搜视频片段、人脸搜索、元数据检索、多模态检索(文档/图片/视频)。
  控制台功能引导场景:当前 Skill 无法直接满足时,为大量数据迁移、数据导出、拓展功能、数据备份、SDK、
  具身智能生态和湖仓生态提供对应的 COS 控制台入口。
  当用户提到以下关键词或口语化表述时应触发此技能:
  上传到COS、腾讯云存储、对象存储、云存储、存储桶、Bucket、
  图片处理、图片压缩、图片放大、超分辨率、抠图、裁剪、二维码识别、水印、
  文档转换、转PDF、视频封面、智能封面、以图搜图、图片搜索、MetaInsight、
  COS上传、COS下载、签名URL、腾讯云文件、数据万象、CI处理、
  内容审核、图片审核、视频审核、文本审核、语音识别、语音合成、降噪、人声分离、
  OCR、文字识别、图片标签、文件内容描述、这个文件讲了什么、图片里有什么、视频讲了什么、
  创建知识库、建一个知识库、上传到知识库、往知识库里加文件、查询知识库、
  从知识库找、搜索知识库、知识库检索、文档检索、文档搜索、数据迁移、批量迁移、
  数据导出、数据备份、COS SDK、具身智能生态、湖仓生态、COS 拓展功能。
  即使用户没有明确提到COS或腾讯云,只要涉及"把文件传到云上"、"生成下载链接"、
  "处理云端图片"、"帮我建个知识库"、"把文档放进知识库"、"从知识库里搜一下"、
  "加密COS凭证"、"COS密钥不安全"、"加密一下COS密钥"、"保护COS密钥"等意图,也应该触发此技能。
description_zh: "腾讯云 COS 对象存储、数据万象智能处理、MetaInsight 检索、知识库与控制台功能引导"
description_en: "Tencent Cloud COS Storage, CI Processing, MetaInsight Retrieval, Knowledge Base, and Console Feature Guidance"
message: >
  我是腾讯云 COS 与数据万象 Skill,提供对象存储管理、图片与媒体处理、内容审核、
  MetaInsight 数据检索、数据集分析、结果预览和知识库能力。例如可以帮你上传或下载文件、
  生成签名链接、处理图片、转换文档、检索桶内文件、查询数据集或创建知识库;
  当前能力无法满足时,也会提供匹配的 COS 控制台功能入口。
client_commands: true
conditions:
  - url: 'https://console.cloud.tencent.com/cos/**'
    mode: discover
defaultMode: discover
metadata:
  {
    "openclaw":
      {
        "emoji": "☁️",
        "requires":
          {
            "secrets":
              [
                "SecretId",
                "SecretKey"
              ],
            "optionalSecrets":
              [
                "Token"
              ],
            "config":
              [
                "Region",
                "Bucket"
              ],
            "optionalConfig":
              [
                "DatasetName",
                "Domain",
                "ServiceDomain",
                "Protocol"
              ],
            "envMapping":
              {
                "SecretId": "TENCENT_COS_SECRET_ID",
                "SecretKey": "TENCENT_COS_SECRET_KEY",
                "Token": "TENCENT_COS_TOKEN",
                "Region": "TENCENT_COS_REGION",
                "Bucket": "TENCENT_COS_BUCKET",
                "DatasetName": "TENCENT_COS_DATASET_NAME",
                "DatasetImageSearch": "TENCENT_COS_DATASET_IMAGE_SEARCH",
                "DatasetFaceSearch": "TENCENT_COS_DATASET_FACE_SEARCH",
                "DatasetMeta": "TENCENT_COS_DATASET_META",
                "MetaInsightRegion": "TENCENT_COS_METAINSIGHT_REGION",
                "Domain": "TENCENT_COS_DOMAIN",
                "ServiceDomain": "TENCENT_COS_SERVICE_DOMAIN",
                "Protocol": "TENCENT_COS_PROTOCOL"
              },
            "secretsDescription":
              {
                "SecretId":
                  {
                    "label": "腾讯云 API 密钥 ID",
                    "type": "cloud-credential",
                    "provider": "Tencent Cloud",
                    "sensitivity": "critical",
                    "scope": "COS object storage and CI data processing APIs"
                  },
                "SecretKey":
                  {
                    "label": "腾讯云 API 密钥 Key",
                    "type": "cloud-credential",
                    "provider": "Tencent Cloud",
                    "sensitivity": "critical",
                    "scope": "COS object storage and CI data processing APIs"
                  },
                "Token":
                  {
                    "label": "STS 临时安全令牌",
                    "type": "session-token",
                    "provider": "Tencent Cloud STS",
                    "sensitivity": "high",
                    "scope": "Time-limited access (default 1800s), auto-expires"
                  }
              }
          },
        "security":
          {
            "credentialStorage":
              {
                "default": "ephemeral",
                "ephemeral":
                  {
                    "description": "Credentials exist only in shell session environment variables; nothing written to disk",
                    "persistsToDisk": false,
                    "recommendation": "RECOMMENDED — use with STS temporary credentials"
                  }
              },
            "requirements": [
              "MUST use sub-account keys with least-privilege COS-only policy; root account keys are FORBIDDEN",
              "STS temporary credentials are recommended; default behavior is ephemeral (no disk persistence)",
              "Credentials are NEVER echoed back to the user in chat"
            ]
          },
        "install":
          [
            {
              "id": "node-cos-sdk",
              "kind": "node",
              "package": "cos-nodejs-sdk-v5",
              "label": "Install COS Node.js SDK"
            }
          ]
      }
  }
---

# 腾讯云 COS 技能

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

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

统一 Skill 提供三个入口,均输出 JSON:

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

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

## 运行模式与能力策略

每次执行前读取环境变量 `KIKI`:仅当 `KIKI=1` 时进入严格模式,其他值或未设置均为公开模式。

| 模式 | 判断 | 功能策略 |
| --- | --- | --- |
| **公开模式** | `KIKI` 不为 `1` | 提供全部功能 |
| **严格模式** | `KIKI=1` | 禁止所有删除操作,并隐藏本地凭证配置、持久化、`encrypt-env`、`decrypt-env` |

`KIKI` 只控制功能可见性,不参与身份认证或凭证选择。脚本优先使用运行时提供的 `TENCENTCLOUD_*` 凭证;未提供时使用公开环境的 `TENCENT_COS_*`、`.env` 或 `.env.enc`。严格模式只隐藏并拒绝删除类操作与本地凭证管理功能,其余 COS/CI 业务能力和执行逻辑完全一致;**这不表示任何数据万象(CI)能力可以豁免删除限制**。

严格模式下,**禁止一切删除语义的操作,COS 与数据万象(CI)同样生效,没有任何 CI 例外**。具体包括:

- 所有 `delete-*` action(删除对象、批量删除、CI 解绑、各处理服务关闭、删除文件索引等),均禁止执行并从可用 action 列表隐藏。
- **删除数据集、删除数据集绑定关系**等没有专用 action 的删除操作,同样禁止,不得通过 `ci-request`、`ci_api.mjs`、直接 HTTP/curl、内联脚本或任何其他入口绕行执行。
- `ci-request --method DELETE` 一律拒绝。

除了入口拦截,`scripts/lib/ci_client.mjs` 的 `cosRequest` 与 `scripts/cos_node.mjs` 的 `cosRequestPromise` 会在请求层再次拒绝 DELETE 请求,双重兜底避免绕过。需要调整隐藏列表时,修改其中的 `STRICT_HIDDEN_ACTIONS`,并同步本节说明与测试。

## 首次使用 — 自动设置

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

### 步骤 0:识别运行模式

先运行 `{baseDir}/scripts/setup.sh --check-only`。若 `KIKI=1`,本地凭证管理功能会被隐藏,直接跳到「操作指南」;否则继续公开模式设置流程。

### 步骤 1:检查当前状态

```bash
{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:公开模式设置环境变量并运行安装

```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/` 并验证连接。

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

---

## 操作指南

存储和处理作业使用 `scripts/cos_node.mjs`;数据集只读检索优先使用 `scripts/ci_api.mjs`;检索结果预览使用 `scripts/preview_gen.mjs`。三个入口共享相同的运行模式与凭证策略。

如果用户需求无法由当前 Skill 满足,但与迁移、导出、拓展功能、备份、SDK、具身智能生态或湖仓生态匹配,按 `references/console-feature-guides.md` 提供对应控制台链接。已有 action 优先,未命中映射时不要猜测链接。

```
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 存储操作

```bash
# 上传文件
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

# 列出文件(--marker 用于翻页:上一页返回 isTruncated=true 时,用 nextMarker 续页)
list --prefix "images/" --max-keys 100
list --prefix "images/" --max-keys 100 --marker "<上页返回的nextMarker>"

# 获取签名 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
```

补充对象只读 action:`list-object-versions`、`get-object-acl`、`get-object-tagging`、`get-object-retention`、`get-symlink`、`list-multipart-uploads`、`list-multipart-parts`、`options-object`。完整参数见 `references/api_reference.md`。

### COS 存储桶管理

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

```bash
# 列出所有存储桶
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
```

补充存储桶只读 action:`get-bucket-policy`、`get-bucket-replication`、`get-bucket-website`、`get-bucket-referer`、`get-bucket-domain`、`get-bucket-origin`、`get-bucket-logging`、`get-bucket-inventory`、`list-bucket-inventory`、`get-bucket-accelerate`、`get-bucket-encryption`、`get-bucket-intelligent-tiering`、`get-bucket-access-monitor`、`get-bucket-logging-analysis`、`get-bucket-notification`、`get-bucket-object-lock`、`get-bucket-domain-certificate`、`get-bucket-strict-signature`、`get-bucket-bandwidth-quota`、`get-bucket-response-control`。完整参数见 `references/api_reference.md`。

### 使用 CI 功能前:先查状态,未开通先确认

用户要使用数据万象处理能力(图片处理、内容识别、文档处理、媒体处理、内容审核、智能语音、文件处理、异步任务等)时,先查询该桶的 CI 服务状态,不要直接执行处理任务。所需服务未开通时,先说明情况并向用户确认,得到确认后再执行开通。

功能与所需服务映射:

| 用户需求 | 所需服务 | 未开通时的开通命令 |
| --- | --- | --- |
| 同步图片处理(缩放 / 裁剪 / 旋转 / 格式转换 / 水印 / AI 图片处理) | CI 绑定 | `create-ci-bucket` |
| 同步内容识别(图片标签 / OCR) | CI 绑定 | `create-ci-bucket` |
| 内容审核 | CI 绑定 | `create-ci-bucket` |
| 文档处理(转 PDF / 预览) | `documentProcessing` | `create-doc-process-bucket` |
| 媒体处理(封面 / 转码 / 截帧 / 媒体信息) | `mediaProcessing` | `create-media-bucket` |
| 智能语音(识别 / 合成 / 降噪 / 人声分离) | `voiceProcessing` | `create-asr-bucket` |
| 文件处理(哈希 / 压缩 / 解压) | `fileProcessing` | `create-file-process-bucket` |
| 图片处理异步任务 | `asyncImageProcessing` | `create-async-image-process-bucket` |
| AI 内容识别异步任务 | `asyncContentRecognition` | `create-ai-process-bucket` |

确认流程:

1. 先查询状态(命令见下一节「CI 服务开通状态」)。
2. `ciBucketStatus` 为 `off` / `unbinding`:CI 尚未绑定,所有 CI 能力不可用。告知用户并询问是否绑定数据万象,确认后执行 `create-ci-bucket`。
3. `ciBucketStatus` 为 `noAuth`:无法确认绑定状态,说明当前密钥缺少 `ci:DescribeCIBuckets` 权限,不要尝试开通。
4. CI 为 `on` 但目标子服务为 `disabled`:该子服务未单独开通。告知用户并询问是否开通,确认后执行对应的 `create-*` 命令。
5. **仅在用户明确确认后执行开通或绑定**。开通与绑定属于配置变更且可能产生费用,未确认时不得自动执行,也不要用创建处理任务的方式隐式触发开通。

### CI 服务开通状态

用户询问存储桶是否绑定数据万象,或文档处理、媒体处理、智能语音、文件处理、图片处理(异步)、AI 内容识别(异步)是否开通时,先查询状态,不要通过尝试创建处理任务来推断。同步图片处理和同步内容识别在 CI 绑定后默认可用。

```bash
node {baseDir}/scripts/ci_api.mjs ci-service-status \
  --bucket <bucket-appid> \
  --region <region>
```

查询顺序和结论解释:

1. 必须先查 CI 总开关。`off` / `unbinding` 时停止后续查询,全部子服务按未开启返回。
2. CI 为 `on` 时,继续查询文档处理、媒体处理、智能语音、文件处理、图片处理(异步)和 AI 内容识别(异步);异步图片处理通过 `GET /picbucket`、异步内容识别通过 `GET /ai_bucket` 独立判断。
3. CI 总开关无权限时映射为 `noAuth`,跳过四个数据处理查询,但仍独立查询图片处理(异步)和 AI 内容识别(异步)状态。
4. 同步图片处理与同步内容识别只要 CI 已绑定就默认可用;不要用同步能力推断对应异步服务已经开启。
5. `disabled`、`noAuth`、`error` 含义不同,回答时必须分别说明。

完整的查询接口、字段和错误映射见 `references/ci-service-status.md`。该查询完全只读,严格模式可用。

### CI 服务开通与关闭

服务开通和关闭必须使用专用 action,不要通过创建处理任务推断或代替。关闭服务、删除队列和 CI 解绑属于删除语义,严格模式下隐藏并拒绝执行。

```bash
# 绑定 / 解绑数据万象
create-ci-bucket --bucket <bucket-appid> --region <region>
delete-ci-bucket --bucket <bucket-appid> --region <region>

# 文档处理
create-doc-process-bucket --bucket <bucket-appid> --region <region>
delete-doc-process-bucket --bucket <bucket-appid> --region <region>

# 媒体处理
create-media-bucket --bucket <bucket-appid> --region <region>
delete-media-bucket --bucket <bucket-appid> --region <region>

# 智能语音
create-asr-bucket --bucket <bucket-appid> --region <region>
delete-asr-bucket --bucket <bucket-appid> --region <region>

# 文件处理
create-file-process-bucket --bucket <bucket-appid> --region <region>
delete-file-process-bucket --bucket <bucket-appid> --region <region>
```

`create-ci-bucket` 使用 `PUT /`,`delete-ci-bucket` 使用 `PUT /?unbind`;其余四类服务使用对应路径的 `POST` 开通和 `DELETE` 关闭。完整路径与 CAM Action 见 `references/ci-service-status.md`。

### CI 图片基础处理

同步图片处理在存储桶绑定 CI 后默认可用;异步图片处理需要单独开通。

```bash
# 查询已开通图片处理异步服务的存储桶
describe-async-image-process-buckets --bucket <bucket-appid> --region <region>

# 开通图片处理异步服务并创建队列
create-async-image-process-bucket --bucket <bucket-appid> --region <region>

# 关闭图片处理异步服务并删除队列(严格模式隐藏并拒绝执行)
delete-async-image-process-bucket --bucket <bucket-appid> --region <region>

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

```bash
# 图片质量评估
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 内容识别

同步内容识别在存储桶绑定 CI 后默认可用;AI 内容识别异步服务需要单独开通。

```bash
# 查询已开通 AI 内容识别异步服务的存储桶;--bucket 默认作为精确过滤条件
describe-ai-process-buckets --bucket <bucket-appid> --region <region>

# 开通 AI 内容识别异步服务并创建队列
create-ai-process-bucket --bucket <bucket-appid> --region <region>

# 关闭 AI 内容识别异步服务并删除队列(严格模式隐藏并拒绝执行)
delete-ai-process-bucket --bucket <bucket-appid> --region <region>

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

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

#### 单个文件内容描述

当用户问“这个文件里有什么”“描述这张图片”“这个视频讲了什么”时,先按文件类型和数据集状态选择能力,不要只返回文件元信息:

| 文件情况 | 优先能力 | 说明 |
| --- | --- | --- |
| 单张图片,需要自然语言描述 | `ci_api.mjs image-analysis` | 无需数据集;`ImageLabels` 返回整体描述和分层标签,`Custom` 可按用户问题分析 |
| 单张图片,只需标签或文字 | `recognize-image` / `ocr-general` | 分别用于图片标签和 OCR,不要把标签结果冒充完整内容描述 |
| 已进入智能检索、已完成入库,且属于 `ImageSearch` / `VideoSearch` 数据集的图片或视频 | `ci_api.mjs get-ai-media-info` | 仅在这三个条件同时满足时使用;按 URI 获取 AI 标签、ASR、OCR、粗分类 |
| 文档或纯文本文件 | 文档检索或直接读取文本 | `get-ai-media-info` 不支持 `DocSearch`;纯文本优先读取正文后总结 |

```bash
# 描述桶内单张图片
node {baseDir}/scripts/ci_api.mjs image-analysis \
  --bucket <bucket-appid> --region <region> \
  --object images/photo.jpg --type ImageLabels

# 按用户关注点分析图片
node {baseDir}/scripts/ci_api.mjs image-analysis \
  --bucket <bucket-appid> --region <region> \
  --object images/photo.jpg --type Custom --prompt '请描述图片中的人物、场景和正在发生的事情'

# 获取智能检索图片或视频数据集中已完成入库文件的 AI 详情
node {baseDir}/scripts/ci_api.mjs get-ai-media-info \
  --bucket <bucket-appid> --region <region> \
  --dataset-name <dataset> --uri 'cos://<bucket-appid>/<object-key>'
```

执行原则:

1. 图片内容描述优先使用 `image-analysis`;只有标签需求时才使用 `recognize-image`。
2. 只有文件已加入智能检索,并在 `ImageSearch` 或 `VideoSearch` 数据集中完成入库后,才能使用 `get-ai-media-info`。仅找到同桶数据集不代表该文件已经入库;无法确认时不要调用,图片回退到 `image-analysis`,视频则说明需要先完成智能检索入库。
3. 若用户已确认文件入库但不知道数据集名称,可用 `find-datasets-by-bucket` 查询候选数据集;不要臆造名称,也不要把 `DocSearch` 数据集用于该接口。
4. `get-ai-media-info` 返回的是结构化 AI 信息。回答用户时应综合标签、ASR、OCR 和粗分类生成友好描述,并说明缺失或尚未分析的字段。
5. 图片需要更完整说明时,可组合 `image-analysis` 的整体描述与 `get-ai-media-info` 的结构化信息,但后者仍必须满足智能检索入库前置条件。
6. 详细字段和前置条件见 `references/dataset-catalog.md` 的“媒资 AI 信息查询”和“图片理解”。

### CI 文档处理

```bash
# 文档转 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 媒体处理

```bash
# 视频智能封面(自动轮询等待结果)
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 内容审核

```bash
# 图片同步审核
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 智能语音

```bash
# 语音识别
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 文件处理

```bash
# 文件哈希计算(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 数据集只读检索与分析(推荐)

数据集筛选、聚合、语义检索、图片理解和 EXIF 查询优先使用 `scripts/ci_api.mjs`。它与 `cos_node.mjs` 共用运行模式和凭证解析,不创建、修改或删除资源。

```bash
node {baseDir}/scripts/ci_api.mjs help
node {baseDir}/scripts/ci_api.mjs list-datasets --appid <AppId> --region <region>
node {baseDir}/scripts/ci_api.mjs find-datasets-by-bucket --appid <AppId> --region <region> --bucket <bucket-appid>
node {baseDir}/scripts/ci_api.mjs simple-query --bucket <bucket> --region <region> --body '<json>'
node {baseDir}/scripts/ci_api.mjs image-search --bucket <bucket> --region <region> --dataset-name <name> --mode text --text '<query>'
```

按任务读取对应参考文件,不要臆造字段或操作符:

- 条件筛选与聚合:`references/dataset-simple-query.md`
- 图片、文档、视频和人脸检索:`references/dataset-search.md`
- 数据集字段与模板:`references/dataset-catalog.md`
- 桶内容总结与聚合:`references/bucket-content-summary.md`、`references/bucket-content-aggregation.md`

检索命中文件后保留原始 `cos://` URI。需要可视化时,按 `references/search-results-preview.md` 生成 spec,再执行:

```bash
node {baseDir}/scripts/preview_gen.mjs --spec-file <spec.json> --out <result.html>
```

宿主环境提供 `exportFile` 时可继续导出 HTML;不提供时直接返回生成路径,不得伪造 artifact ID。

宿主提供 `invokeClient` 时,可按 `references/query-spec.schema.json` 下发数据集信息查询。宿主不支持时,`describeDatasets` 回退到 `ci_api.mjs list-datasets`;`describeDatasetFields` 当前没有 CLI 回退,只能使用 `invokeClient`,不得伪造字段结果。

### CI MetaInsight

> **地域约束**:MetaInsight 数据集仅支持 `ap-chengdu`(成都)、`ap-beijing`(北京)、`ap-shanghai`(上海)三个地域。绑定数据集时,数据集必须与存储桶在同一地域,跨地域绑定会失败;如果桶所在地域不在上述列表,提示用户该地域暂不支持智能检索/数据集,建议改用支持地域的桶,不要强行绑定。
>
> **创建数据集 / 知识库时必须显式指定地域**:未通过 `--mi-region`(或 `--region`)/ `TENCENT_COS_METAINSIGHT_REGION` 指定时命令会直接报错,**不要默认使用成都等任何地域**——收到该报错时向用户说明「目前仅支持北京、上海、成都」并询问要使用哪个地域,确认后再带上地域参数重试。

#### 数据集管理

绑定存储桶到数据集前,**必须先询问用户采用增量索引还是存量索引**,不要默认选择:

| 模式 | 含义 | 适用场景 |
| --- | --- | --- |
| `Mode=1` 存量索引 | 绑定后自动索引桶内**已有全部文件** | 需要立即检索历史文件 |
| `Mode=0` 增量索引 | 只索引绑定后**新上传**的文件 | 历史文件量大或无需检索历史文件,节省索引成本与时间 |

> **注意**:存量/增量索引只能在**绑定存储桶与数据集时**设置一次,绑定完成后无法再修改。若绑定后想切换模式,只能删除绑定后重新绑定。

**若当前没有合适的数据集**(桶未绑定数据集,或已绑定但模板与需求不符),引导用户创建新数据集,不要直接失败:

1. 用 `find-datasets-by-bucket` 反查桶绑定,或用 `list-datasets` 列出全部数据集,按所需模板筛选。
2. 无合适数据集时,告知用户当前状态与所需模板,询问是否创建;确认后执行 `create-dataset`。
3. 创建后 `create-dataset-binding` 绑定目标桶,并询问增量/存量索引。
4. 需要检索或统计历史文件时选存量索引(`Mode=1`)。

> 示例:用户要「统计桶内文件的类型分布」→ 属于元数据聚合分析,需元数据数据集 `Official:COSBasicMeta` → 创建数据集 → 绑定并开启存量索引(`Mode=1`)→ 索引完成后用 `simple-query` 的 `Aggregations` 按 `MediaType` 分组统计。

```bash
# 列出所有数据集
list-datasets

# 创建数据集(模板:Official:COSBasicMeta / Official:ImageSearch / Official:VideoSearch / Official:FaceSearch)
# 地域必须显式指定(--mi-region,与要绑定的桶同地域);未指定会报错,需向用户确认(仅支持北京/上海/成都),不要默认成都
create-dataset --name my-dataset --template "Official:ImageSearch" --description "图片搜索" --mi-region ap-beijing

# 查询数据集详情
describe-dataset --name my-dataset

# 绑定存储桶到数据集(先询问用户增量/存量,再选 --mode;存量=1 默认索引已有文件,增量=0 只索引新文件)
# 注意:数据集必须与桶同地域,且地域需在 MetaInsight 支持列表(ap-chengdu/ap-beijing/ap-shanghai)内
create-dataset-binding --name my-dataset
create-dataset-binding --name my-dataset --mode 1          # 存量索引:索引桶内已有全部文件
create-dataset-binding --name my-dataset --uri "cos://other-bucket-1250000000" --mode 0  # 增量索引:只索引新上传文件

# 查询数据集的绑定关系
describe-dataset-bindings --name my-dataset
```

> **删除约束**:删除数据集、删除数据集绑定关系属于删除语义操作,与删除对象/解绑数据万象同级。公开模式下也必须先向用户明确确认;严格模式(`KIKI=1`)下一律禁止,且当前没有提供 `delete-dataset` / `delete-dataset-binding` action,**不要通过 `ci-request --method DELETE` 或任何其他方式绕行**。

#### 索引管理

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

#### 检索(需预建数据集)

检索前先确认桶已绑定对应数据集:用 `find-datasets-by-bucket` 反查桶绑定的数据集;若未绑定,先 `create-dataset-binding` 建立绑定;若也没有合适的数据集,引导用户创建新数据集(流程见「数据集管理」)。绑定数据集必须与桶同地域,且桶地域需在 MetaInsight 支持列表内;地域不支持时提示用户,不要强行绑定。绑定前同样需询问用户采用增量索引还是存量索引(见「数据集管理」)。

检索前必须确认数据集模板。图片和元数据检索可使用 `cos_node.mjs` 的兼容 action;当前人脸粗搜优先使用 `ci_api.mjs`,字段与限制以 `references/dataset-search.md` 为准。

| 检索类型 | 所需数据集模板 | 数据集选择 |
|---------|---------------|----------|
| 图片检索(以图搜图/文本搜图) | `Official:ImageSearch` | `--dataset` → `TENCENT_COS_DATASET_IMAGE_SEARCH` → `TENCENT_COS_DATASET_NAME` |
| 视频检索(以文搜视频片段) | `Official:VideoSearch` | `--dataset` → `TENCENT_COS_DATASET_VIDEO_SEARCH` |
| 人脸粗搜 | `ImageSearch` / `VideoSearch`(需开白) | `--dataset-name`,必要时先按桶反查 |
| 元数据检索 | `Official:COSBasicMeta` 或其他可检索模板 | `--dataset` → `TENCENT_COS_DATASET_META` |

`cos_node.mjs face-search` 是兼容旧 `Official:FaceSearch` 接口的 action,不要与 `ci_api.mjs face-search` 的人脸粗搜混用。

```bash
# 以图搜图(ImageSearch 数据集)
image-search-pic --uri "https://example.com/query.jpg"

# 文本搜图(ImageSearch 数据集)
image-search-text --text "蓝天白云"

# 当前人脸粗搜(ImageSearch / VideoSearch 数据集)
node {baseDir}/scripts/ci_api.mjs face-search --bucket <bucket-appid> --region <region> --dataset-name <name> --uri "cos://bucket/photo.jpg" --limit 10 --match-threshold 80

# 元数据检索 — 简单查询(任意数据集;返回含 nextToken 时表示还有下一页,须续页拉全)
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"}'
dataset-simple-query --dataset my-dataset --query '{"Operation":"eq","Field":"ContentType","Value":"image/jpeg"}' --next-token "<上页返回的nextToken>"

# 视频检索 — 以文搜视频片段(VideoSearch 数据集;视频检索仅支持文搜,不支持图搜)
video-search --text "骑行的片段" --dataset my-video-dataset --limit 10

# 多模态检索(hybrid-search 统一走 datasetquery/hybridsearch):文档检索默认 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:创建知识库

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

1. 如果用户没指定名称 → 询问用户想给知识库起什么名字
2. 如果用户没指定地域 → 向用户说明「目前仅支持北京、上海、成都」并询问使用哪个地域(未指定地域命令会报错,不要默认成都)
3. 执行创建:

```bash
create-knowledge-base --name <用户指定的名称> --region <ap-beijing | ap-shanghai | ap-chengdu>
```

4. 自动完成三步:创建存储桶 → 创建 DocSearch 数据集 → 绑定
5. **记住本次创建的知识库信息**(桶名、地域、数据集名),后续上传/查询时直接使用
6. 告诉用户:

> ✅ 知识库「<名称>」已创建!
> - 你可以把文档(PDF、Word、Excel、PPT、TXT 等)上传到这个知识库
> - 上传后系统会自动建立索引(需要几秒到几分钟)
> - 之后你可以直接说"从知识库里搜一下XXX"来查询内容

#### 流程 2:上传到知识库

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

**判断使用哪个知识库:**

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

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

4. 告诉用户:

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

#### 流程 3:查询知识库

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

**判断使用哪个知识库:**

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

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

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

### CI 通用请求(扩展入口)

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

```bash
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` | 查询存储桶地域 |
| **CI 服务绑定** | `create-ci-bucket` | 绑定存储桶并开通数据万象 |
| | `delete-ci-bucket` | 解绑数据万象(严格模式隐藏) |
| **图片基础** | `describe-async-image-process-buckets` | 查询已开通图片处理异步服务的存储桶 |
| | `create-async-image-process-bucket` | 开通图片处理异步服务并创建队列 |
| | `delete-async-image-process-bucket` | 关闭图片处理异步服务并删除队列(严格模式隐藏) |
| | `image-info` | 图片元信息 |
| | `image-thumbnail` | 缩放 |
| | `image-crop` | 裁剪 |
| | `image-rotate` | 旋转 |
| | `image-format` | 格式转换 |
| | `watermark-font` | 文字水印 |
| **AI图片** | `assess-quality` | 质量评估 |
| | `ai-super-resolution` | 超分辨率 |
| | `ai-pic-matting` | 智能裁剪 |
| | `ai-qrcode` | 二维码识别 |
| **内容识别** | `describe-ai-process-buckets` | 查询已开通 AI 内容识别异步服务的存储桶 |
| | `create-ai-process-bucket` | 开通 AI 内容识别异步服务并创建队列 |
| | `delete-ai-process-bucket` | 关闭 AI 内容识别异步服务并删除队列(严格模式隐藏) |
| | `recognize-image` | 图片标签识别 |
| | `ocr-general` | OCR 文字识别 |
| **文档处理** | `create-doc-process-bucket` | 开通文档处理服务并创建队列 |
| | `delete-doc-process-bucket` | 关闭文档处理服务并删除队列(严格模式隐藏) |
| | `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` | 查询审核结果 |
| **智能语音** | `create-asr-bucket` | 开通智能语音服务并创建队列 |
| | `delete-asr-bucket` | 关闭智能语音服务并删除队列(严格模式隐藏) |
| | `speech-recognition-job` | 语音识别 |
| | `tts-job` | 语音合成 |
| | `noise-reduction-job` | 音频降噪 |
| | `voice-separate-job` | 人声分离 |
| **文件处理** | `create-file-process-bucket` | 开通文件处理服务并创建队列 |
| | `delete-file-process-bucket` | 关闭文件处理服务并删除队列(严格模式隐藏) |
| | `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` | 兼容旧 FaceSearch 人脸搜索;当前粗搜优先使用 `ci_api.mjs` |
| | `dataset-simple-query` | 元数据检索 |
| | `hybrid-search` | 多模态检索(文档/图片/视频统一入口:文搜或图搜由 `--templates` 与 `--mode` 决定;注意视频/文档仅支持文搜,图搜仅 ImageSearch 支持) |
| | `video-search` | 视频检索(以文搜视频片段,需 VideoSearch 数据集;仅支持文搜) |
| **通用** | `ci-request` | 调用未封装的 CI API(严格模式禁止 DELETE) |
| **🚀 知识库** | `create-knowledge-base` | "创建知识库" → 一键创建桶+数据集+绑定 |
| | `upload` → 指向知识库桶 | "上传到知识库" → 上传文档 |
| | `hybrid-search` → 指向知识库数据集 | "查询知识库" → 语义检索文档内容 |
| **🚫 禁止** | ~~deleteBucket~~ | **不允许删除/清空存储桶** |
| **🔐 凭证管理** | `encrypt-env` | 加密 .env → .env.enc 并删除明文 |
| | `decrypt-env` | 解密 .env.enc → .env 还原明文 |

## 安全注意事项

### 凭证处理

公开模式可使用以下三种凭证存储方式;`KIKI=1` 时以下本地凭证管理功能会被隐藏:

| 模式 | 存储位置 | 安全性 | 用法 |
|------|---------|--------|------|
| **默认模式** | 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` |

#### 加密存储(推荐)

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

```bash
# 1. 先持久化
{baseDir}/scripts/setup.sh --from-env --persist

# 2. 加密(自动删除明文 .env,生成 .env.enc)
node {baseDir}/scripts/cos_node.mjs encrypt-env

# 3. 之后脚本自动从 .env.enc 解密读取,所有功能正常使用
node {baseDir}/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`

可进一步限制到具体存储桶:
```json
{
  "statement": [{
    "effect": "allow",
    "action": ["cos:*"],
    "resource": ["qcs::cos:<Region>::uid/<APPID>:<BucketName>/*"]
  }]
}
```

### 安装包说明

本技能通过 npm 安装 `cos-nodejs-sdk-v5`(腾讯云 COS 官方 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,避免每页筛选条件不一致导致漏数据或重复。

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

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

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

## 使用规范

1. **首次使用先运行** `{baseDir}/scripts/setup.sh --check-only` 检查模式和环境;`KIKI=1` 时不展示或调用 `--from-env` / `--persist`
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;严格模式禁止 `DELETE` 方法
7. **能力不足时引导**:确认现有能力无法满足后,按 `references/console-feature-guides.md` 查找匹配功能并提供控制台链接
8. **脚本源码**见 `scripts/cos_node.mjs`
9. **命令参考**见 `references/api_reference.md`

ナレッジ管理の人気スキル

搜索引擎ナレッジ管理

通过公开搜索URL在16个搜索引擎(7个国内直连+9个国际)中做跨引擎检索、结果去重与多源交叉验证,无需API Key,内置零依赖Python脚本。Use when 用户要求“搜一下/查资料/多找几个来源/核实消息/找公众号文章/排查报错/找论文或开源项目”时。输入自然语言查询词,输出带来源链接与可信度标注的结构化结果。不适用于私有数据检索、批量抓取、需要登录后可见的内容。

↓ 1075.9万★ 147u_8ee34d77
ima-skillsナレッジ管理

IMA OpenAPI を通じてノートとナレッジベースを操作します。

↓ 108.4万★ 566u_1742680f
Summarizeナレッジ管理

長いテキストや文書、ウェブページを要点とキーワードに圧縮する要約ツールです。

↓ 87.6万★ 1048paudyyin
全网搜索ナレッジ管理

通过“查一下、搜一下、搜索、找一下”等自然语言检索公开网页,整理来源并交付横版 PDF、Markdown 与标题链接表。支持用户主动开启、查看和取消技能收藏,保留原报告取回。

↓ 50.9万★ 2u_32d99f8a
web-tools-guideナレッジ管理

ウェブ要求に適切なツールを割り当てるための必読ガイドです。

↓ 40万★ 220user_ec205dbb
Aihot Skill Liteナレッジ管理

AI HOT (aihot.virxact.com) 中文 AI 资讯查询 Skill。当用户想知道"今天 AI 圈有什么"、"AI 日报"、"AI HOT"、"AI 资讯"、"AI 热点"、"最近 AI"、"OpenAI/Anthropic/Google 最近发布了什么"、"AI hot today"、"AI...

↓ 32.1万★ 92Khazix
全球12亿文献知识库(8千万中文期刊可下载)ナレッジ管理

全球12亿文献知识库(8千万中文期刊可下载)——通过 SmartLib 开放平台 API 提供中外文学术文献检索与下载能力,覆盖 8000 万篇授权中文期刊全文 + 12.28 亿条全球文献元数据(期刊 7.19 亿 / 专利 2.15 亿 / 会议 7155 万 / 学位论文 2473 万 / 标准 268 万)。 能力:中英文关键词检索、文献详情、中文期刊 PDF 全文下载、外文 OA 文献十级渠道免费下载(不消耗配额)、智能关键词扩展、核心期刊优先排序、相关性重排、引文追溯、分类号检索。 配额:首次使用自动注册,免费 100 次检索 + 10 次下载 / 月;耗尽自动弹出套餐(体验卡 / 个人版月 / 专业版月 / 单篇下载 / 下载包),可说「升级 / 充值」唤起;企业 / 机构定制联系 [email protected]。 触发:用户表达"查论文""找文献""检索学术""搜期刊""查专利""找标准""下论文""写文献综述""找参考文献""查 SCI/EI"等意图时启用;也适用"帮我找关于 XX 的论文""写文献综述""找几篇引用支撑论点"。英文:"find papers" "search literature" "write literature review" "find supporting citations"。 调用前必须先用 /consume 获取 consume_token,再凭 token 调 /search(每次计费接口调用都需一次 /consume)。

↓ 30.3万★ 189user_164f4c1f
Markdown Converterナレッジ管理

uvx 経由で markitdown を呼び、さまざまな形式のファイルを Markdown に変換します。

↓ 20.4万★ 256Peter Steinberger

データ月:2026-10 · ダウンロード数とスター数は公開スキルレジストリ(ClawHub、SkillHub)から月単位で集計しています。詳しくはデータの方法論をご覧ください。