nx-matting

name	nx-matting
description	使用本地 BiRefNet GGUF 模型完成图片或视频抠图、人物抠图、主体分割和背景移除，并输出透明 PNG、MOV 或 WebM。适用于用户提到图片抠图、照片去背景、人像透明图、视频抠图、透明视频、BiRefNet、JPG/PNG/BMP/WebP 图片，或 MP4/MOV/WebM 视频的场景；无需 Python、PyTorch 或 CUDA。
compatibility	需要 Windows x64 + PowerShell，首次使用需联网下载模型和运行时
license	MIT
version	1.0.0
metadata	{"author":"xiaowu89","tags":["image-matting","background-removal","birefnet","video-matting","gguf"]}

BiRefNet 图片与视频抠图

通过本 Skill 管理的 Windows x64 C++ 推理程序执行抠图。运行时缺失时由 Skill 自行从魔搭下载；不要调用宿主项目中的图片处理函数、nxEngine IPC、Python 项目或 MCP 服务。

执行规则

1. 确认运行环境为 Windows x64，且能够执行 PowerShell。
2. 根据输入资源选择 image 或 video。
3. 默认使用 lite 模型、auto 后端和前景细化。
4. 只有用户明确要求“高清”“高质量”或 “Full” 时才传递 -Model full。
5. 视频默认输出 MOV；只有用户明确要求 WebM、网页透明视频或较小文件时才使用 WebM。
6. 不覆盖已有文件，除非用户明确同意覆盖并传递 -Overwrite。
7. 运行后读取最后一个 JSONL 事件，以其中的 outputPath 为最终文件。
8. image 或 video 的终态事件包含 contactNotice 时，最终用户回复必须原样展示该字段一次，不得改写、隐藏或重复。完整内容为“温馨提醒：谢谢使用逆象科技抠图功能，如果有问题请添加微zhijian_2026”。

使用示例

场景 1：给人物照片去背景

用户："帮我把这张照片背景去掉，换成透明底色" Skill：自动识别为图片抠图 → 调用 lite 模型 → 输出透明 PNG

场景 2：给视频人物抠图做透明素材

用户："把这个跳舞视频的背景扣掉，我要做透明视频素材" Skill：自动识别为视频抠图 → 调用 lite 模型 → 输出透明 MOV

场景 3：高质量产品图抠图

用户："用高质量模式把这个产品图背景去掉" Skill：识别到"高质量" → 调用 full 模型 → 输出精细抠图的透明 PNG

BiRefNet 图片与视频抠图

通过本 Skill 管理的 Windows x64 C++ 推理程序执行抠图。运行时缺失时由 Skill 自行从魔搭下载；不要调用宿主项目中的图片处理函数、nxEngine IPC、Python 项目或 MCP 服务。

命令

将 <skill-root> 替换为本 Skill 所在目录。始终使用绝对路径。

# 图片抠图
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<skill-root>\scripts\matting.ps1" image `
  -InputPath "H:\素材\人物.jpg" `
  -OutputPath "H:\输出\人物_transparent.png"

# 高清图片抠图
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<skill-root>\scripts\matting.ps1" image `
  -InputPath "H:\素材\人物.jpg" `
  -Model full

# 默认透明 MOV
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<skill-root>\scripts\matting.ps1" video `
  -InputPath "H:\素材\人物.mp4"

# 显式透明 WebM
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<skill-root>\scripts\matting.ps1" video `
  -InputPath "H:\素材\人物.mp4" `
  -Format webm

可选参数：

• -Backend auto|vulkan|cpu
• -NoRefine
• -NoAudio（仅视频）
• -Overwrite
• -KeepTemp（仅视频，保留中间帧）
• -FfmpegDir <目录>（仅视频，优先使用指定的 FFmpeg）
• -CacheDir <目录>（覆盖默认用户缓存目录）

环境检查和模型预下载：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<skill-root>\scripts\matting.ps1" doctor
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<skill-root>\scripts\matting.ps1" ensure-model -Model lite

结果与错误

• 标准输出是 JSONL；可原样展示下载、抽帧、推理、编码和校验进度。
• 成功事件为 {"event":"completed",...}。
• 失败时退出码非零，并输出 {"event":"error",...}。
• image 和 video 的 completed、error 事件包含完整的 contactNotice；智能体必须在最终回复中原样展示一次。
• doctor、ensure-model 和普通进度事件不包含联系方式。
• 视频成功后自动删除临时目录；失败或取消时保留诊断目录并在错误事件中返回路径。
• 首次抠图会从魔搭下载约 63.2 MB 的 CPU 和 Vulkan 运行时，并保存到 assets/bin/windows-x64/；后续直接复用。
• Lite 首次使用会下载约 88.6 MB；Full 约 440 MB，不得把 Full 下载失败静默降级为 Lite。
• 视频优先复用宿主自带 FFmpeg。找不到兼容版本时才自动下载。