前言¶
在智能体里做「两张图是不是同一个人」，常见做法是手写腾讯云 SDK 调用、自己维护参数表和阈值说明，再把结果解释给用户。每一步都要查 CompareFace 文档，本地路径、URL、Base64 的入参也容易写错。
下面介绍 SkillHub 上的 TencentCloud FaceID CompareFace（@tencent-adm/tencentcloud-faceid-compareface）。它把腾讯云人脸识别 CompareFace 封装成标准 Agent Skill：Agent 在需要 1:1 人脸相似度时按 SKILL.md 触发，通过脚本调用接口并返回相似度分数，便于判断是否同一人。
这是什么¶
TencentCloud FaceID CompareFace 是腾讯云人脸比对（CompareFace）的接口调用技能。发布方为 腾讯云慧眼人脸核身团队，在 SkillHub 上归类为 ai-agent，来源标注为 enterprise，当前版本 1.0.1。技能标签包含 requires_api_key=true，表示需要配置腾讯云 API 密钥后才能调用。
它解决的核心问题：对两张图片中的人脸做相似度比较，返回 0~100 分的人脸相似度分数；支持 图片 Base64 与 图片 URL 两种输入（本地文件可由脚本自动转 Base64），可用于判断两张人脸是否为同一人。
SkillHub 页面：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-faceid-compareface
官方索引：https://api.skillhub.cn/tencent-adm/tencentcloud-faceid-compareface
核心功能¶
以下能力来自技能说明与上游 SKILL.md（与腾讯云 CompareFace 产品一致）：
- 人脸相似度比对：对 A、B 两张图各自检出的人脸打分。
- 同一人判断：结合分数与算法版本给出是否同一人等结构化结果（脚本输出 JSON，含
Score、IsSamePerson等字段）。 - 多输入方式：
--image-a/--image-b（本地路径或 Base64 字符串），或--url-a/--url-b（图片 URL；URL 优先级高于同侧 image 参数）。 - 质量控制：可选
--quality-control（0~4）过滤低质量图。 - 算法版本：
--face-model-version支持 2.0、3.0，默认 3.0。 - 旋转检测：可选
--need-rotate-detection（0 关闭 / 1 开启）。
接口产品文档：https://cloud.tencent.com/document/product/867/44987
安装与启用¶
从 SkillHub 安装¶
在 SkillHub 技能页打开 TencentCloud FaceID CompareFace，按页面说明 将安装提示词发送给你使用的 AI 助手，由助手完成技能包拉取与目录落盘。包坐标：
@tencent-adm/tencentcloud-faceid-compareface
版本 1.0.1。页面未单独列出 Cursor、Codex CLI、Claude Code 的差异命令时，以「提示词 + 坐标」方式在各 Agent 中启用即可；具体落盘路径遵循你所用客户端的 Skills 配置。
运行环境与密钥¶
技能脚本依赖 Python 与腾讯云 SDK，需提前准备：
pip install tencentcloud-sdk-python
环境变量（调用前写入 shell 或 Agent 运行环境）：
TENCENTCLOUD_SECRET_ID=你的SecretId
TENCENTCLOUD_SECRET_KEY=你的SecretKey
要求：Python 3.6+。未配置密钥时，CompareFace 请求无法通过腾讯云鉴权。
典型用法¶
安装完成后，在技能目录下执行 scripts/main.py。下列示例与官方 SKILL.md 一致，可在技能根目录复现。
两张本地人脸图（自动转 Base64）：
python scripts/main.py --image-a ./face_a.jpg --image-b ./face_b.jpg
两张图片 URL：
python scripts/main.py --url-a "https://example.com/face_a.jpg" --url-b "https://example.com/face_b.jpg"
混合输入并指定 3.0 算法与质量控制：
python scripts/main.py --image-a ./face_a.jpg --image-b ./face_b.jpg --face-model-version 3.0 --quality-control 2
成功时脚本返回 JSON，例如：
{
"Score": 87.5,
"ScoreDesc": "高度相似，可认定为同一人（3.0版本）",
"IsSamePerson": true,
"FaceModelVersion": "3.0",
"RequestId": "xxx"
}
在 Agent 对话中，用户表达「比对两张人脸」「1:1 验证是否同一人」等意图时，模型应选用本技能并按上述参数调用脚本，而不是自行猜测相似度。
适用场景与注意¶
适合谁
- 已在用腾讯云人脸识别、需要在 Coding Agent 里做人脸 1:1 比对的开发者。
- 希望把 CompareFace 参数、阈值说明、合规提示写进
SKILL.md，减少重复查文档的团队。
输入与检出
- 格式：PNG、JPG、JPEG、BMP；不支持 GIF。
- Base64 编码后不超过 5MB；分辨率与人脸选取规则见技能文档（多脸时默认取置信度最高的一张）。
阈值参考（3.0 版本，来自技能文档）
| 分数范围 | 建议判断 |
|---|---|
| ≥ 40 分 | 疑似同一人 |
| ≥ 50 分 | 可认定为同一人（推荐阈值） |
| ≥ 60 分 | 高度确信为同一人 |
2.0 版本阈值更高（例如推荐认定阈值 ≥ 80 分），切换版本时需同步调整业务策略。
合规
技能明确要求：处理人脸等个人信息前，须取得个人信息主体合法、有效同意或其他合法性基础；具体以腾讯云官网服务协议为准。
平台侧信息
SkillHub 上该技能评分 100000，下载 1428 次，安装 38 次（以 SkillHub 页面展示为准，会随时间变化）。
结尾¶
TencentCloud FaceID CompareFace 把腾讯云 CompareFace 收敛成 Agent 可触发的标准技能：密钥配好、脚本参数清晰，即可在对话里完成双图人脸相似度比对。需要安装或查看说明时，请打开 SkillHub 官方页：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-faceid-compareface
