前言¶
要在業務裏判斷圖片是否有人臉、框出位置，或順帶拿到年齡、質量分等信息，通常要自己查騰訊雲 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
