前言¶
做電商主圖、證件照換底或短視頻封面時，經常要把人物從背景裏摳出來。本地跑分割模型要配環境和算力；自己拼 HTTP 又要對着騰訊雲 BDA 文檔寫簽名與參數。若希望 Cursor、Claude Code 等 Agent 在對話裏直接處理用戶給的圖片，需要一套可執行的 Skill 規範，而不是讓模型「目測」輪廓。
下面介紹 SkillHub 上的 TencentCloud YT Segment Portrait（@tencent-adm/tencentcloud-yt-segment-portrait）：把騰訊雲人像分割 API 封裝成 Agent 可讀的 SKILL.md 與腳本，用二分類模型識別完整人體輪廓並返回摳圖結果。
這是什麼¶
TencentCloud YT Segment Portrait 是面向 design-media 類場景的 Agent Skill，當前版本 1.0.2，來源標註爲 enterprise，由 騰訊雲智能創作團隊 發佈。Skill 座標爲 @tencent-adm/tencentcloud-yt-segment-portrait，SkillHub 頁面標記 requires_api_key=true，使用前需配置騰訊雲 API 密鑰並開通人像分割服務。
一句話定位：基於二分類的人像分割，用於完整人體輪廓識別與圖像摳圖；底層對應騰訊雲 SegmentPortraitPic 接口（域名 bda.tencentcloudapi.com，版本 2020-03-24），通過 scripts/main.py 同步調用，單張圖片大小限制 ≤5MB。
核心功能¶
根據 Skill 包內說明與 API 參考，已覈實的能力如下：
- 人像分割與摳圖：對輸入圖片識別人體完整輪廓，返回透明背景摳圖與掩碼相關結果。
- 多種輸入方式：腳本支持圖片 URL、本地 文件路徑，或較長的 Base64 字符串（與官方 API 的
Url/Image參數對應）。 - URL 形式結果：腳本默認設置
RspImgType爲url，標準輸出 JSON 中包含ResultImageUrl（透明背景圖）與ResultMaskUrl（掩碼）；返回 URL 有效期爲 30 分鐘（以騰訊雲 API 文檔爲準）。 - 場景模式（API 層）：可選
Scene爲GEN（通用）或GS（綠幕場景，對綠幕人像分割效果更好），默認GEN。 - Agent 執行約束：Skill 要求 Agent 在用戶已提供圖片且意圖爲人像分割時直接執行腳本，不得在 API 失敗時用模型自行「編造」分割結果。
圖片側限制（API 文檔）：分辨率須小於 2000×2000；支持 PNG、JPG、JPEG、BMP，不支持 GIF；Url 與 Image 至少提供一個，若同時提供則優先使用 Url。
安裝與啓用¶
安裝 SkillHub CLI¶
若本機尚未安裝 skillhub，可先檢查版本；未安裝時按 SkillHub 官方安裝說明執行（完整安裝或僅 CLI）：
command -v skillhub && skillhub --version
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安裝本 Skill¶
安裝時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/，Agent 可能無法加載：
skillhub install @tencent-adm/tencentcloud-yt-segment-portrait --dir <你的 skills 目錄>
常見客戶端 skills 路徑（與 SkillHub 安裝文檔一致）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/
也可讓 Agent 按 SkillHub 頁面提示，參考 https://skillhub.cn/install/skillhub.md 完成安裝。
開通服務與配置密鑰¶
- 在 騰訊雲人像分割控制台 開通人像分割能力。
- 在 API 密鑰管理 獲取
SecretId與SecretKey。 - 設置環境變量（不要將密鑰寫進代碼倉庫）：
export TENCENTCLOUD_SECRET_ID="你的SecretId"
export TENCENTCLOUD_SECRET_KEY="你的SecretKey"
Windows PowerShell 可使用：
$env:TENCENTCLOUD_SECRET_ID = "你的SecretId"
$env:TENCENTCLOUD_SECRET_KEY = "你的SecretKey"
腳本依賴 Python 3.7+ 與 tencentcloud-sdk-python；main.py 在缺少 SDK 時會嘗試自動 pip install，也可手動安裝：
pip install tencentcloud-sdk-python requests
典型用法¶
Agent 或開發者可在配置好密鑰後，用 Skill 目錄下的腳本處理圖片。將 <SKILL_DIR> 替換爲安裝後的 Skill 根目錄（內含 scripts/main.py）：
python3 <SKILL_DIR>/scripts/main.py "https://example.com/human.png"
本地文件示例：
python3 <SKILL_DIR>/scripts/main.py /path/to/portrait.jpg
成功時 stdout 爲 JSON，字段包括摳圖與掩碼的臨時 URL，例如：
{
"ResultImageUrl": "https://...",
"ResultMaskUrl": "https://..."
}
在 Agent 會話中，用戶上傳或給出圖片地址並說明需要人像分割時，Skill 要求模型按上述方式調用腳本，讀取 JSON 後將鏈接或結果返回用戶，而不是僅打印腳本路徑或反覆確認是否執行。
更完整的參數、錯誤碼與輸出字段說明見 Skill 內 references/SegmentPortraitPicApi.md，對應騰訊雲文檔 人像分割 API。
適用場景與注意¶
適合誰
- 需要在 IDE Agent 工作流裏做摳圖、換底、人像素材預處理，且希望走騰訊雲線上能力的團隊。
- 已具備騰訊雲賬號、願意按量計費並管理 API 密鑰的開發者。
限制與注意
- 必須配置
TENCENTCLOUD_SECRET_ID/TENCENTCLOUD_SECRET_KEY；欠費、未開通服務或餘額不足會導致 API 報錯（如ResourceUnavailable.InArrears、FailedOperation.BalanceInsufficient等，以官方錯誤碼錶爲準）。 - 非騰訊雲對象存儲的圖片 URL 可能下載較慢或不穩定，文檔建議優先使用騰訊雲存儲的 URL。
- 返回的
ResultImageUrl/ResultMaskUrl有時效，下游流程應在有效期內拉取或轉存。 - SkillHub 統計（以頁面抓取爲準）：評分 100000，下載 1216，安裝 19；實際體驗取決於網絡、圖片規格與賬號計費狀態。
結尾¶
TencentCloud YT Segment Portrait 把騰訊雲人像分割 API 收斂成 Agent 可執行的 Skill：密鑰與環境變量就緒後，一條 main.py 調用即可拿到透明摳圖與掩碼 URL，並約束 Agent 在失敗時如實報錯。官方 Skill 入口：
- API / 安裝源：
https://api.skillhub.cn/tencent-adm/tencentcloud-yt-segment-portrait - SkillHub 展示頁：
https://www.skillhub.cn/skills/tencent-adm/tencentcloud-yt-segment-portrait
