BG-Removal-Sharpen Skill

抠图（背景移除）工具，支持本地模型和在线 API 双模式，自动选择最优方案。

> 默认优先使用统一入口：scripts/run_bg_removal.py
> 标准抠图 / 发丝精修 / 定向提取 / BRIA 超精度尽量都走这一个脚本。
> 若需求是“放大 / 锐化 / 增强”，则走 scripts/upscale_image.py / scripts/sharpen_image.py / scripts/enhance_image.py。

能力范围

• 人像抠图（证件照、头像、全身照）
• 商品/电商图片抠图
• 通用任意图片主体提取
• 多主体图片中单独抠出左/右/中间目标主体
• 自动补回佩剑、头绳、飘带、尾巴等离散附件
• 图片放大（2x / 4x / 自定义倍数）
• 图片锐化（light / medium / strong）
• 放大 + 锐化一体增强，适合抠图后角色 PNG
• 单张处理 & 批量处理
• 输出透明背景 PNG

工作流程

第 1 步：确定输入

从用户消息中提取：
- 输入图片路径（必填）
- 输出路径（可选，默认同名 + _no_bg.png）
- 批量模式：用户提到"批量"、"多张"、"文件夹"时，扫描目录下所有图片
- 若为批量任务：默认在输出目录额外生成 batch_summary.md + batch_summary.json，把成功/失败清单一起交付
- 若用户明确说“抠右边角色 / 左边角色 / 中间人物 / 单独抠某个角色”：不要只做整图去背景，要切到“多主体目标提取”流程

支持图片格式：.png, .jpg, .jpeg, .webp, .bmp

第 2 步：选择处理方式

三档精度选择：

何时用精修：
- 用户提到"发丝"、"头发不干净"、"边缘糊"、"精修"、"细节"、"半透明"
- 上一次抠图后不满意，要求重做
- 抠人像/宠物/毛绒玩具等带毛发的主体

何时用超精度（BRIA）：
- 二次元角色、游戏海报、复杂服饰、武器、长发飘带等轮廓细节很多
- 用户明确要求"再干净一点"、"像 Clipdrop 一样"、"边缘更利索"
- 愿意接受首次下载模型和 Hugging Face 授权流程

处理来源优先级：

1. BRIA 已授权且用户要求极致边缘？ → 用 BRIA
2. 需要发丝/半透明？              → 用 pymatting 精修
3. 普通抠图？                      → 用 rembg 标准
4. 本地都不可用 + 有 API Key？      → 调在线 API
5. 以上都不可用？                  → 提示安装或授权

检测本地 rembg

/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  -c "import rembg; print('rembg available')" 2>/dev/null && echo "OK"

若输出 OK 则本地可用。

> 注意：系统 /usr/bin/python3 依赖 Xcode 工具链（未安装时无法使用）。
> 必须使用 managed venv 下的 python3 路径。

检测 API Key

检查环境变量（按优先级）：
- REMOVE_BG_API_KEY — Remove.bg API（通用）
- CLIPDROP_API_KEY — Clipdrop API（通用，高精度）
- TENCENT_SECRET_ID + TENCENT_SECRET_KEY — 腾讯云（仅人像）
- 三家对比、申请方式、定价详见 references/api_config.md

第 3 步：执行抠图

推荐主入口：统一调度脚本 run_bg_removal.py

# 普通抠图（默认标准模式）
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/run_bg_removal.py <input_path> [output_path]

# 发丝精修
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/run_bg_removal.py <input_path> [output_path] --quality refine

# 超精度（BRIA，失败自动降级）
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/run_bg_removal.py <input_path> [output_path] --quality best

# 单独抠右边角色 / 左边角色 / 中间角色
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/run_bg_removal.py <input_path> [output_path] --subject right

# 整个目录批量抠右边角色
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/run_bg_removal.py <input_dir> <output_dir> --batch --subject right

自然语言 → 参数映射：
- “帮我抠图” → 直接跑默认命令
- “发丝再精修一下” → --quality refine
- “像 Clipdrop 一样再干净一点” → --quality best
- “只要右边角色 / 左边那个角色 / 中间人物” → --subject right|left|center
- “武器别漏掉 / 头绳也带上” → --subject ...，必要时补 --subject-models birefnet-portrait,birefnet-general,u2net

方式 A：本地 rembg（推荐）

# 单张
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/remove_bg.py <input_path> [output_path]

# 批量
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/remove_bg.py <input_dir> <output_dir> --batch

# 或直接使用 rembg CLI（已安装于 managed venv）
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/rembg i \
  -o <output_path> <input_path>

scripts/remove_bg.py 是核心脚本，自动下载所需模型（首次运行）。
默认模型：birefnet-general-v3（通用高精度），人像场景自动切换 u2net_human_seg。

方式 A+：发丝级精修（推荐用于人像/毛发）

# 全图精修
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/refine_matting.py <input_path> [output_path] \
  --model birefnet-portrait \
  --kernel 15 \
  --method cf

# 发丝特别多 → 把 kernel 加大（例如 20）
# 追求速度 → --method knn
# 调试模式 → --debug（保存中间 mask/trimap）

原理（给调用者的认知模型）：

rembg 语义分割 → 只输出 0/1 硬边缘（发丝被一刀切）
      ↓
trimap 生成：前景核心(255) + 未知区(128) + 背景(0)
      ↓
pymatting Closed-form / KNN Matting → 求解 alpha 值
      ↓
连续 0~255 的透明度 → 发丝、纱、烟雾的半透明细节全部保留

参数调优指南：
- --kernel 10：发丝少（短发、商品）
- --kernel 15：正常人像（默认推荐）
- --kernel 20-25：长发飘逸、毛发丰富
- --method cf：精度优先（默认，适合静态高质量输出）
- --method knn：速度优先（效果略差，批量用）

模型选择（--model）：
- birefnet-portrait：人像、卡通角色 ⭐ 默认推荐
- birefnet-general：通用物体
- birefnet-massive：最高精度，最慢
- birefnet-general-lite：轻量快速

方式 A++：多主体目标提取（补回武器/头绳/飘带）

适用场景：
- 双人海报里“只要右边角色 / 左边角色”
- 游戏角色有 佩剑、头绳、头饰、飘带、尾巴 等离散附件
- 单一 portrait 模型把主体抠出来了，但把附件一起抠掉了

/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/extract_target_subject.py <input_path> [output_path] \
  --target right \
  --models birefnet-portrait,birefnet-general

策略：

portrait 模型：主体边缘更干净
        +
general 模型：更容易识别武器/头饰/飘带等附件
        ↓
对目标侧主体做多模型 alpha 融合
        ↓
输出单独角色 PNG（比单模型少漏件）

推荐参数：
- --target right|left|center：提取目标方位
- --models birefnet-portrait,birefnet-general：默认推荐组合
- --models birefnet-portrait,birefnet-general,u2net：附件特别多时再加 u2net
- --max-gap 140：允许把与主体近邻的离散附件并入
- --debug：保存各模型 mask 和融合结果，定位为什么漏件

> 经验：动漫/游戏海报不要只用 birefnet-portrait，它容易把远离身体的武器和头饰忽略；至少和 birefnet-general 融一次。

方式 A+++：BRIA RMBG-2.0（本地超精度）

# 单张
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/remove_bg_bria.py <input_path> [output_path]

# 批量
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/remove_bg_bria.py <input_dir> <output_dir> --batch

# 调试：若想强制只测 BRIA、不允许回退
/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/remove_bg_bria.py <input_path> [output_path] --no-fallback

自动回退策略：

BRIA 可用        → 直接输出超精度结果
BRIA 下载/授权失败 → 自动回退到方式 A+（refine_matting.py）
精修也失败       → 自动回退到方式 A（remove_bg.py）

注意：
- 首次运行会从 Hugging Face 下载 briaai/RMBG-2.0
- 需要先在模型页登录并同意条款：https://huggingface.co/briaai/RMBG-2.0
- 许可为 CC BY-NC 4.0（仅非商用）
- 默认开启自动回退，避免用户因为授权问题直接卡死

方式 B：Remove.bg API

/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/remove_bg_api.py <input_path> [output_path] --api remove_bg

方式 C：腾讯云 API

/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/remove_bg_api.py <input_path> [output_path] --api tencent

方式 D：Clipdrop API（通用高精度）

/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/remove_bg_api.py <input_path> [output_path] --api clipdrop

申请 Key：发邮件到 contact@clipdrop.co（注册送 100 credits 一次性）。

第 3.5 步：执行图片增强（放大 / 锐化 / 一体增强）

方式 E：本地图片放大

/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/upscale_image.py <input_path> [output_path] \
  --scale 2 \
  --mode illustration

• --scale 2：默认推荐，适合抠图后 PNG
• --scale 4：小图素材、头像、立绘二次处理
• --mode illustration：角色图 / 二次元 / 游戏海报 ⭐ 默认
• --mode photo：写实照片
• --mode lineart：线稿 / UI 图标 / 矢量风截图

方式 F：本地图片锐化

/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/sharpen_image.py <input_path> [output_path] \
  --preset medium

• light：轻锐化，安全保守
• medium：默认推荐
• strong：线条更利，但容易过冲，适合插画和游戏角色

方式 G：放大 + 锐化一体增强（推荐）

/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  scripts/enhance_image.py <input_path> [output_path] \
  --scale 2 \
  --mode illustration \
  --preset light

自然语言 → 参数映射：
- “把这张图放大 2 倍” → upscale_image.py --scale 2 --mode illustration
- “锐化一下” → sharpen_image.py --preset medium
- “放大后再清晰一点” → enhance_image.py --scale 2 --preset light
- “这张角色图做高清版” → enhance_image.py --scale 2 --mode illustration --preset light
- “线条再利一点” → sharpen_image.py --preset strong

第 4 步：输出结果

• 输出路径告知用户
• 如为批量处理，除了处理摘要（成功/失败数量），还要明确告知：
• batch_summary.md：人类可读报告
• batch_summary.json：机器可读清单
• BRIA 批量报告里要展示 实际使用的引擎（bria / fallback-refine / fallback-standard）
• 图片增强任务也要明确说明使用了什么参数（scale / mode / preset）
• 预览图片（如适用）

安装依赖

本地 rembg + pymatting + BRIA + 图片增强依赖（已完成安装）

所有依赖已安装在 managed venv 中：

/Users/dayviwang/.workbuddy/binaries/python/envs/default/
├── rembg[cpu]                 # 语义分割
├── pymatting                  # Alpha Matting 精修（发丝级）
├── numba / scipy              # matting 加速与图像处理
├── torch / torchvision        # BRIA 推理
├── transformers / kornia      # BRIA 模型加载与预处理
└── pillow                       # 放大 / 锐化 / PNG 处理

验证：

/Users/dayviwang/.workbuddy/binaries/python/envs/default/bin/python3 \
  -c "import rembg, pymatting, scipy, torch, torchvision, kornia, transformers; print('all ready')"

首次跑 refine_matting.py 时若缺模型，rembg 会自动下载到 ~/.u2net/（已预先下载完成）。
首次跑 remove_bg_bria.py 时会尝试下载 briaai/RMBG-2.0，但 需要先在 Hugging Face 登录并同意模型条款。

> 如需在其他环境重新安装：
> bash > /Users/dayviwang/.workbuddy/binaries/python/versions/3.13.12/bin/python3 \ > -m pip install "rembg[cpu]" pymatting numba scipy pillow torch torchvision kornia transformers safetensors >

API Key 配置（在线模式）

在 ~/.workbuddy/skills/bg-removal/references/api_config.md 查看各平台 API Key 申请方式。

配置方式（写入 shell profile 或 .env）：

export REMOVE_BG_API_KEY="your_key_here"

文件结构

bg-removal-sharpen/
├── SKILL.md                  # 本文件
├── scripts/
│   ├── run_bg_removal.py         # 🎛️ 抠图统一入口（标准 / 精修 / 定向提取 / BRIA）
│   ├── remove_bg.py              # 标准抠图（rembg 粗分割）
│   ├── refine_matting.py         # 🎯 发丝级精修（rembg + pymatting）
│   ├── extract_target_subject.py # 🧩 多主体角色定向提取（补回武器/头绳/飘带）
│   ├── remove_bg_bria.py         # 🚀 BRIA RMBG-2.0 本地超精度模式
│   ├── upscale_image.py          # 🔍 本地图片放大
│   ├── sharpen_image.py          # ✨ 本地图片锐化
│   ├── enhance_image.py          # 🪄 放大 + 锐化一体增强
│   ├── enhance_common.py         # 公共增强工具函数
│   └── remove_bg_api.py          # 在线 API 调用（Remove.bg / 腾讯云 / Clipdrop）
├── references/
│   └── api_config.md         # API Key 申请指南
└── assets/                   # 预留（示例图片等）

注意事项

• 本地 rembg 首次运行需下载模型，耗时取决于网速
• BRIA 首次运行除下载模型外，还可能要求先在 Hugging Face 页面同意条款
• BRIA 权重为 CC BY-NC 4.0，仅适合个人/非商用
• 在线 API 有免费额度限制（Remove.bg 免费版 50 次/月）
• 批量处理大图片时注意磁盘空间
• 输出均为 PNG 格式（保留透明度）