前言¶

做監控回放摘要、新聞片剪輯說明、或產品演示視頻的要點提取時，常見做法是自己接多模態 API、寫上傳與鑑權、再拼 prompt。媒體格式、本地文件與公網 URL 的處理規則也容易在業務代碼裏散落。下面介紹 SkillHub 上的 TencentCloud VITA（座標 @tencent-adm/tencentcloud-vita）：把騰訊雲 VITA 的圖像與視頻理解能力封裝成 Agent 可讀的 SKILL.md 與 scripts/main.py，由 Agent 按規範調用腳本並回傳結果，而不是在對話裏「目測」編造分析。

這是什麼¶

TencentCloud VITA 是騰訊雲內容識別團隊發佈的企業來源 Skill（SkillHub 分類 design-media，當前版本 1.0.9）。它面向 圖片理解、視頻理解 及描述生成，官方簡介中列出的場景包括：圖像/視頻分析、監控錄像分析、體育高光提取、直播理解、新聞視頻摘要、產品演示視頻分析，以及設置或更新持久化的 vita prompt。

輸入形態支持 單張圖片、多張圖片（按時序）、視頻 URL；Skill 標籤標明 requires_api_key=true，需配置騰訊雲 VITA 的 API Key 後才能調用後端服務。

核心功能¶

以下能力均來自 Skill 包內 SKILL.md 與官方頁面簡介，可按輸入類型對照使用。

媒體輸入與限制¶

處理規則要點：

1. 遠程圖片、遠程視頻的 URL 須 可公開訪問。
2. 本地圖片可由腳本讀取並轉爲 base64 data URL 後調用 API。
3. 本地視頻腳本不直接上傳；需先通過其他工具（如 COS 相關 Skill）得到可訪問 URL，再傳入 --video。
4. 調用失敗時，Agent 規範要求 不得自行編造分析結果，應返回明確錯誤。

Prompt 與編排¶

• 用戶可通過寫入 <SKILL_DIR>/prompt/vita_prompt.txt 持久化自定義 prompt（無需跑腳本）。
• 運行時優先級：--prompt 參數 > 持久化文件 > 默認文案「請描述這段媒體內容」。
• 腳本支持非流式 JSON 輸出、--stream 流式文本，以及 --stdin 讀取 JSON。

依賴與環境¶

• Python 3.7+，pip install openai（OpenAI 兼容 SDK）。
• 環境變量 TENCENTCLOUD_VITA_API_KEY：在騰訊雲控制台 VITA 服務管理 開通服務並創建 API KEY 後配置。

計費（Skill 文檔記載）：輸入 token 1.2 元/百萬，輸出 token 3.5 元/百萬；默認併發 5，超出可能返回 429。

安裝與啓用¶

SkillHub 官方安裝說明：先閱讀 SkillHub 安裝與優先源配置，再安裝本 Skill。頁面提供的安裝座標爲 @tencent-adm/tencentcloud-vita。

使用 SkillHub CLI¶

未安裝 CLI 時可執行完整安裝（文檔推薦）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

安裝 Skill 時 必須 用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 可能無法被識別：

skillhub install tencent-adm/tencentcloud-vita --dir <你的 Agent skills 目錄>

常用目錄（摘自 SkillHub 安裝文檔）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下 .agents/skills/

Zip 包安裝¶

SkillHub 詳情頁提供 1.0.9 的 Zip 下載地址：

https://api.skillhub.cn/api/v1/download?slug=@tencent-adm/tencentcloud-vita

解壓到上述 skills 目錄對應子路徑後，重啓或刷新 Agent 即可加載。

配置 API Key¶

Linux / macOS 示例：

export TENCENTCLOUD_VITA_API_KEY="your_api_key_here"

Windows PowerShell：

$env:TENCENTCLOUD_VITA_API_KEY = "your_api_key_here"

典型用法¶

將 <SKILL_DIR> 替換爲本 Skill 在本地 skills 目錄中的實際路徑（例如 ~/.cursor/skills/tencentcloud-vita）。

單張遠程圖片：

python3 <SKILL_DIR>/scripts/main.py \
  --image "https://example.com/image.jpg" \
  --prompt "描述這張圖片中的內容"

本地圖片（腳本自動轉 base64）：

python3 <SKILL_DIR>/scripts/main.py \
  --image "./demo.png" \
  --prompt "描述這張圖片中的內容"

多張圖片按時序分析：

python3 <SKILL_DIR>/scripts/main.py \
  --image "https://example.com/frame1.jpg" \
  --image "./frame2.png" \
  --prompt "分析這些圖片中發生了什麼變化"

視頻理解（僅 URL）：

python3 <SKILL_DIR>/scripts/main.py \
  --video "https://example.com/video.mp4" \
  --prompt "總結這段視頻的主要內容"

流式長文本輸出：

python3 <SKILL_DIR>/scripts/main.py \
  --video "https://example.com/video.mp4" \
  --prompt "詳細描述視頻內容" \
  --stream

非流式默認返回 JSON，包含 result 與 usage（token 統計）。--image 與 --video 互斥，不可同時指定。

Skill 內還提供了監控、新聞、帶貨、體育高光、直播質量等場景的 prompt 模板推薦，可按業務改寫後寫入 prompt/vita_prompt.txt 或通過 --prompt 傳入。

適用場景與注意¶

適合誰：需要在 Cursor、Claude Code、Codex 等 Agent 工作流裏統一接入騰訊雲 VITA、且希望由 Skill 約束「必須跑腳本、禁止幻覺式視頻描述」的團隊；SkillHub 側統計顯示下載約 2171 次、安裝約 141 次（頁面數據，會隨時間變化）。

需要注意：

1. 無 API Key 或 Key 無效時，腳本無法調用服務，應排查環境變量與控制台開通狀態。
2. 本地視頻必須先解決 公網 URL，本 Skill 不內置 COS 上傳。
3. 圖片體積、分辨率張數、視頻時長與編碼需滿足上表限制，否則易在 API 層失敗。
4. 企業來源 Skill，使用前可在 SkillHub 詳情頁查看安全掃描報告鏈接（頁面展示 Keen、三不等相關結果）。

結尾¶

TencentCloud VITA Skill 把「圖像/視頻理解 + prompt 持久化 + 腳本調用約定」收攏到一套 Agent 可執行規範裏，適合把 VITA 從零散腳本升級爲可複用的 Skill 能力。官方入口：

• SkillHub 頁面：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-vita
• API 座標頁：https://api.skillhub.cn/tencent-adm/tencentcloud-vita