前言¶
做电商主图、证件照换底或短视频封面时，经常要把人物从背景里抠出来。本地跑分割模型要配环境和算力；自己拼 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
