前言¶
做人臉與模板圖融合時，常見做法是自己在項目裏接騰訊雲 FuseFaceUltra 接口、處理鑑權與參數，再讓 Coding Agent 只能「寫調用代碼」而不能直接出圖。若希望 Agent 在對話裏拿到模板圖和用戶臉圖後就能同步返回融合結果，需要把開通服務、密鑰、腳本入口和模型類型選擇寫進可執行的 Skill 規範。
下面介紹 SkillHub 上的 TencentCloud Image Face Fusion（座標 @tencent-adm/tencentcloud-image-face-fusion，版本 1.0.0）：由騰訊雲智能創作團隊發佈，歸類爲 design-media，來源爲 enterprise，並標註 requires_api_key=true。
這是什麼¶
TencentCloud Image Face Fusion 是一個基於通用 SKILL.md 格式的 Agent Skill，封裝騰訊雲圖片人臉融合（專業版）能力：將用戶人臉與素材模板圖中的人臉融合，通過同步接口 FuseFaceUltra（域名 facefusion.tencentcloudapi.com，版本 2022-09-27）返回結果。
SkillHub 頁面簡介與技能包內描述一致：支持自定義美顏、人臉增強、牙齒增強、拉臉等效果參數（對應 API 的 FusionUltraParam），最高支持 8K 分辨率（單邊小於 8000 像素），並提供多種融合模型類型（SwapModelType 1–6）。
核心功能¶
經覈對技能包與 API 參考文檔，可確認的能力如下。
- 同步人臉融合：場景爲「人臉融合（專業版）」，腳本爲
scripts/main.py，返回方式爲同步；圖片限制爲 base64 編碼後 ≤10M，URL ≤20M。 - 輸入方式：
--model爲素材模板圖，--face爲用戶人臉圖，均支持 URL 或本地路徑。 - 模型類型：
--swap-model-type可選 1–6，覆蓋泛娛樂、影視自然/高清、證件照、閉眼遮擋友好、電商/文旅等高相似度場景；默認 1。 - 合規標識：
--logo-add控制是否在結果圖添加 AI 合成標識（0 不添加，1 添加，默認 1）。 - 進階 API 參數：通過
FusionUltraParam可配置拉臉（WarpRadio）、人臉增強（EnhanceRadio）、磨皮（MpRadio）、牙齒增強（TeethEnhanceRadio）、妝容遷移（MakeupTransferRadio）等；模板圖最多支持融合 6 張人臉（MergeInfos）。 - Agent 執行約定：安裝後 Skill 要求 Agent 在用戶已提供模板圖與人臉圖且意圖爲融合時直接執行腳本，失敗時返回錯誤說明，不得用模型自行「編造」融合圖。
安裝與啓用¶
方式一：SkillHub CLI¶
先確認本機是否已有 skillhub（安裝說明見 SkillHub 安裝文檔）：
command -v skillhub && skillhub --version
未安裝時可按官方文檔執行完整安裝或僅 CLI 安裝，例如：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安裝技能時必須用 --dir 指向當前 Agent 的 skills 目錄。常用路徑包括：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/
示例（將 <skills 目錄> 替換爲實際路徑）：
skillhub install @tencent-adm/tencentcloud-image-face-fusion --dir <skills 目錄>
方式二：讓 AI 按官方提示安裝¶
SkillHub 技能頁給出的提示爲：根據 https://skillhub.cn/install/skillhub.md，安裝 @tencent-adm/tencentcloud-image-face-fusion。
密鑰與環境變量¶
- 在 騰訊雲人臉融合控制台 開通服務。
- 在 API 密鑰管理 獲取
SecretId與SecretKey。 - 設置環境變量（Linux / macOS 示例）：
export TENCENTCLOUD_SECRET_ID="你的SecretId"
export TENCENTCLOUD_SECRET_KEY="你的SecretKey"
技能包要求勿將密鑰硬編碼進代碼。運行 main.py 依賴 Python 3.7+ 與 tencentcloud-sdk-python（腳本可自動安裝依賴）。
典型用法¶
安裝並配置密鑰後，Agent 應按 Skill 內規範調用 main.py。命令形式如下（<SKILL_DIR> 爲技能安裝目錄）：
python3 <SKILL_DIR>/scripts/main.py --model "<MODEL_PIC_INPUT>" --face "<USER_FACE_INPUT>" [--swap-model-type <1-6>] [--logo-add <0|1>]
技能包中的可復現示例：
# 基本用法：素材模板圖 + 用戶人臉圖（URL）
python3 /path/to/scripts/main.py --model "https://example.com/template.png" --face "https://example.com/user_face.png"
# 證件照等場景：影視級高清、高人臉相似度
python3 /path/to/scripts/main.py --model "/path/to/template.jpg" --face "/path/to/face.jpg" --swap-model-type 4
# 不添加 AI 合成標識
python3 /path/to/scripts/main.py --model "https://example.com/template.png" --face "https://example.com/face.png" --logo-add 0
成功時腳本輸出 JSON，其中 FusedImage 爲結果圖 URL（或 base64，取決於 API 的 RspImgType）；URL 有效期爲 1 天。更完整的字段與錯誤碼見技能內 references/FuseFaceUltraApi.md，對應騰訊雲文檔 圖片人臉融合（專業版）。
在 Cursor 等客戶端中，也可直接用自然語言描述需求（提供模板圖與人臉圖路徑或 URL、是否需要特定 swap-model-type），由 Agent 讀取已安裝的 SKILL.md 後執行上述命令。
適用場景與注意¶
適合誰：需要在設計/媒體類 Agent 工作流裏做人臉模板融合、且希望走騰訊雲官方接口與計費體系的團隊；SkillHub 上該技能評分 100000，下載約 1949 次、安裝約 41 次（數據以 SkillHub 頁面統計爲準）。
使用注意：
- 必須配置騰訊雲 API 密鑰；未開通人臉融合服務會導致調用失敗。
- 圖片格式爲 jpg/png，面部與分辨率需滿足 API 文檔中的最小/最大邊長要求。
SwapModelType6 與部分FusionUltraParam的適用範圍以 API 文檔爲準（例如部分參數僅對類型 1–5 生效）。- 融合失敗時 Agent 應如實報錯，不應改用大模型生成替代圖。
結尾¶
TencentCloud Image Face Fusion 把騰訊雲圖片人臉融合（專業版）的同步調用、模型選擇與合規標識寫進 Agent 可執行的 Skill，減少重複對接 FuseFaceUltra 的成本。官方入口：https://api.skillhub.cn/tencent-adm/tencentcloud-image-face-fusion；SkillHub 展示頁：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-image-face-fusion。
