前言¶
人臉覈驗、活體檢測上線後，攻擊手段也在變：AIGC 換臉、高清翻拍、批量黑產素材、帶水印的僞造圖頻，單靠業務側規則很難覆蓋。若要在對話式開發環境裏讓 Agent 直接發起防攻擊檢測，通常還要自己查接口文檔、拼 SDK 與參數。下面介紹 SkillHub 上的 TencentCloud FaceID DetectAIFakeFaces（座標 @tencent-adm/tencentcloud-faceid-detectaifakefaces），把騰訊雲人臉核身 DetectAIFakeFaces（AI 人臉防護盾） 的調用流程封裝成 Agent Skill，支持對人臉圖片或視頻做防攻擊檢測。
這是什麼¶
TencentCloud FaceID DetectAIFakeFaces 是騰訊雲慧眼人臉核身團隊發佈的企業來源（enterprise）Skill，當前版本 1.0.3，分類爲 professional，子類爲風險風控。Skill 的定位是：當用戶需要對人臉圖片或視頻進行防攻擊檢測時，由 Agent 按 SKILL.md 指引調用騰訊雲 DetectAIFakeFaces 接口；輸入支持圖片 Base64 與視頻 Base64（也可傳入本地文件路徑，由腳本按擴展名識別並編碼）。
官方 Skill 頁與 API 入口：
- SkillHub：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-faceid-detectaifakefaces
- API 地址：https://api.skillhub.cn/tencent-adm/tencentcloud-faceid-detectaifakefaces
接口產品說明見騰訊雲文檔：https://cloud.tencent.com/document/product/1007/101561
Skill 標籤標明 requires_api_key=true，實際調用需配置騰訊雲 API 密鑰。
核心功能¶
以下能力均來自 Skill 包內 SKILL.md 與官方簡介，已覈實：
- AIGC 換臉檢測：識別高仿真 AI 生成/合成換臉。
- 翻拍檢測：識別高清翻拍痕跡。
- 黑產攻擊檢測：識別批量黑產攻擊行爲。
- 水印檢測：識別圖片或視頻中的水印等攻擊痕跡。
- 多輸入方式：
FaceInput可爲本地路徑（jpg/png 圖片；mp4/avi/flv 視頻）或 Base64 字符串；FaceInputType可選1（圖片）/2（視頻），本地文件可省略類型由擴展名推斷。 - 結構化輸出：成功時返回 JSON，含
AttackRiskLevel、AttackRiskDetailInfos（攻擊類型與分項風險等級）、RequestId。
風險等級爲 Low / Mid / High；攻擊類型包括換臉攻擊、翻拍攻擊、活體僞造、黑產攻擊、水印攻擊等（以接口返回爲準）。
安裝與啓用¶
方式一：SkillHub CLI（推薦）¶
先按 SkillHub 安裝說明檢查或安裝 CLI（文檔：https://skillhub.cn/install/skillhub.md）。安裝 Skill 時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 可能不會被識別。
command -v skillhub && skillhub --version
skillhub install @tencent-adm/tencentcloud-faceid-detectaifakefaces --dir <你的 Agent skills 目錄>
常用路徑示例（以 SkillHub 安裝文檔爲準）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/
方式二：提示詞安裝¶
將下列說明發給支持 Skill 的 AI，讓其按 SkillHub 安裝文檔完成安裝：
請根據 https://skillhub.cn/install/skillhub.md，安裝 @tencent-adm/tencentcloud-faceid-detectaifakefaces。
方式三：Zip 包¶
SkillHub 頁面提供 1.0.3 版本 Zip 下載，包內包含 SKILL.md 與 scripts/main.py，可解壓到對應 Agent 的 skills 目錄。頁面亦提供「安裝到本地 Agent」入口（標註支持 WorkBuddy）。
運行依賴與密鑰¶
Skill 要求 Python 3.6+，並安裝 tencentcloud-sdk-python：
pip install tencentcloud-sdk-python
在環境中配置：
export TENCENTCLOUD_SECRET_ID="你的 SecretId"
export TENCENTCLOUD_SECRET_KEY="你的 SecretKey"
使用前請確認已按官網服務協議取得個人信息主體的合法同意或其他合法性基礎（Skill 內注意事項與官網約定一致）。
典型用法¶
安裝並配置密鑰後，在 Skill 目錄下通過 scripts/main.py 發起檢測。
本地圖片（自動識別類型並 Base64）：
python scripts/main.py --face-input ./face.jpg
本地視頻：
python scripts/main.py --face-input ./face_video.mp4
直接傳 Base64 並指定類型：
python scripts/main.py --face-input-type 1 --face-input "<base64_string>"
python scripts/main.py --face-input-type 2 --face-input "<base64_string>"
圖片建議 jpg/png，編碼後建議不超過 3MB、最大 10MB；視頻建議 mp4/avi/flv，時長約 2～5 秒、編碼後建議 8MB 以內、最大 10MB（細則見 Skill 內規格表）。返回示例結構：
{
"AttackRiskLevel": "Low",
"AttackRiskDetailInfos": [
{
"Type": "換臉攻擊",
"RiskLevel": "Low"
}
],
"RequestId": "xxx"
}
在 Cursor 等環境中，也可在自然語言中描述「檢測這張人臉圖是否爲 AI 換臉/翻拍」等需求，由 Agent 加載本 Skill 後選擇腳本或 Base64 入參；具體是否自動執行腳本取決於 Agent 與 Skill 的集成方式。
適用場景與注意¶
適合：
- 實人認證、風控、內容審覈鏈路中，需要在開發對話裏快速試跑人臉防攻擊檢測。
- 已開通騰訊雲人臉核身相關能力、具備 SecretId/SecretKey 的團隊。
注意：
- 必須配置
TENCENTCLOUD_SECRET_ID/TENCENTCLOUD_SECRET_KEY；Skill 爲雲端 API 調用，產生騰訊雲側費用與合規義務。 - 輸入格式、分辨率、時長、Base64 大小有明確上限，不符合規格可能導致調用失敗或效果下降。
- SkillHub 統計（頁面數據）：下載約 1211 次、安裝約 64 次；概述正文以 Skill 包與產品文檔爲準，頁面
overviewMd爲空時以SKILL.md爲準。
結尾¶
TencentCloud FaceID DetectAIFakeFaces 把 DetectAIFakeFaces 的入參約定、環境依賴和腳本入口寫進標準 Skill 格式，便於在 Agent 工作流裏做人臉圖片/視頻的防攻擊檢測，而不用每次從零對接 SDK。需要安裝或查看版本時，可訪問：https://api.skillhub.cn/tencent-adm/tencentcloud-faceid-detectaifakefaces
