前言¶
要在业务里判断图片是否有人脸、框出位置，或顺带拿到年龄、质量分等信息，通常要自己查腾讯云 IAI 文档、拼 SDK 请求、处理 Base64 与 URL 两种入参。Coding Agent 若缺少固定指引，也容易漏配密钥或搞错可选参数。下面介绍 SkillHub 上的 @tencent-adm/tencentcloud-faceid-detectface：把 DetectFace 的用途、环境变量和脚本调用方式写进 SKILL.md，由 Agent 在「需要对图片做人脸检测」时按文档执行。
这是什么¶
tencentcloud-faceid-detectface 是面向开发场景的 Agent Skill（坐标 @tencent-adm/tencentcloud-faceid-detectface，当前版本 1.0.0，来源 enterprise），由 腾讯云慧眼人脸核身团队 发布，分类为 dev-programming。Skill 描述约定：当用户需要对图片进行人脸检测时，应使用此技能；底层对应腾讯云人脸识别（IAI）的 DetectFace 接口。接口说明见腾讯云文档：人脸检测与分析。
在 SkillHub 上该技能标记 requires_api_key=true，调用前需配置腾讯云 API 密钥。
核心功能¶
以下能力均来自 Skill 官方说明，与 DetectFace 能力一致：
- 人脸定位：返回人脸框坐标（X、Y）及宽高（Width、Height）。
- 多人脸：单张图最多检测 120 张人脸（通过
--max-face-num控制，默认 1）。 - 人脸属性（可选）：性别、年龄、表情、魅力、眼镜、口罩、头发、姿态（pitch / roll / yaw）。
- 质量信息（可选）：质量分、模糊分（sharpness）、光照分（brightness）、遮挡分（completeness）。
- 输入方式：图片 Base64 或 URL；传入本地路径时脚本会转为 Base64。
--url优先于--image。
图片规格（Skill 内写明）：PNG、JPG、JPEG、BMP，不支持 GIF；Base64 编码后不超过 5MB；分辨率等限制见 SKILL.md「图片输入规格」一节。
安装与启用¶
通过 SkillHub 安装¶
先确认本机已安装 skillhub CLI；安装与目录说明见 SkillHub 安装与优先源配置。安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。
skillhub install @tencent-adm/tencentcloud-faceid-detectface --dir <skills 目录>
常见路径示例（以 SkillHub 文档为准）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
也可将 SkillHub 页面提供的提示词发给 AI，让其按上述安装文档安装 @tencent-adm/tencentcloud-faceid-detectface。
运行依赖与密钥¶
Skill 要求 Python 3.6+，并安装腾讯云 Python SDK：
pip install tencentcloud-sdk-python
在环境中设置：
export TENCENTCLOUD_SECRET_ID="你的 SecretId"
export TENCENTCLOUD_SECRET_KEY="你的 SecretKey"
脚本默认地域为 ap-guangzhou，可通过 --region 修改。
典型用法¶
安装后，Agent 应进入技能目录，运行 scripts/main.py。主要参数如下（节选）：
| 参数 | 说明 |
|---|---|
--image |
本地路径、或 Base64 字符串（与 --url 二选一） |
--url |
图片 URL（优先级高于 --image） |
--max-face-num |
最多检测人脸数，默认 1，最大 120 |
--need-face-attributes |
0 不返回属性，1 返回，默认 0 |
--need-quality-detection |
0 关闭质量检测，1 开启，默认 0 |
--face-model-version |
2.0 或 3.0，默认 3.0 |
可复现示例（在技能包根目录下执行）：
# 仅检测人脸位置
python scripts/main.py --image ./face.jpg
# 使用图片 URL
python scripts/main.py --url "https://example.com/face.jpg"
# 开启属性与质量检测，最多 5 张人脸
python scripts/main.py --image ./face.jpg --need-face-attributes 1 --need-quality-detection 1 --max-face-num 5
成功时输出 JSON，包含 ImageWidth、ImageHeight、FaceCount、FaceInfos（含坐标及可选的 FaceAttributesInfo、FaceQualityInfo）和 RequestId。属性与质量字段含义见 SKILL.md 中的表格；质量分 Score 在文档中建议用于入库时参考是否大于 80。
在对话场景里，Skill 定义的触发时机包括：检测是否有人脸、获取坐标、统计人脸数量、评估图片质量、读取年龄性别表情等——Agent 识别到这类意图后加载本 Skill，再按上述脚本与参数调用即可。
适用场景与注意¶
适合谁：已在腾讯云开通人脸识别相关能力、希望在 Cursor / Claude Code / Codex 等环境中用自然语言驱动「上传一张图做人脸检测」的开发者；需要统一封装 DetectFace 参数与输出格式的团队也可直接复用技能包内的 scripts/main.py。
需要注意：
- 费用与配额：实际请求计费与限流以腾讯云账号与 DetectFace 产品规则为准，Skill 本身不替代控制台开通与权限配置。
- 密钥：勿把
TENCENTCLOUD_SECRET_ID/TENCENTCLOUD_SECRET_KEY写进仓库；仅通过环境变量或 Agent 安全配置注入。 - 图片限制：超限大小或不支持格式会导致脚本校验失败；大图建议先压缩（Skill 对约 3MB 以上会给出警告）。
- 属性与隐私：开启
--need-face-attributes会返回推断类信息，上线前需符合业务合规要求。
SkillHub 页面统计（以抓取资料为准）：评分 100000，下载 1132 次，安装 35 次——仅作商店热度参考，与接口可用性无直接关系。
结尾¶
经过上面的步骤，可以把 DetectFace 的检测、可选属性与质量评估收敛成 Agent 可执行的 SKILL.md 与 Python 脚本，减少重复查文档和手写 SDK 调用。官方入口：
- Skill API / 安装坐标：https://api.skillhub.cn/tencent-adm/tencentcloud-faceid-detectface
- SkillHub 展示页：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-faceid-detectface
