前言¶
人脸核验、活体检测上线后，攻击手段也在变：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
