matting

Imported from zrong/skills (matting/SKILL.md). Install upstream with npx skills add zrong/skills --skill matting. Copyright stays with the author.

Matting

通过严格、非交互的 CLI 调用独立 matting-api。算法名、模型名和运行状态以本次服务探测结果为准；不要把 Sorb 数据库配置、历史文档或模型名称猜测当作实时能力。

路径

• {SKILL_DIR}：本文件所在目录
• {SCRIPTS_DIR}：{SKILL_DIR}/scripts
• CLI 前缀：uv run --project {SCRIPTS_DIR} matting

必须遵守

1. 处理图片前先查看原图，确认主体、背景、半透明边缘和用户要求。
2. 每次推荐或执行前都调用实时状态与能力端点；只从返回的算法和模型交集中选择。
3. 自动推荐是技术启发式：它能判断已有 alpha、纯色边框、绿/蓝幕和亮度型素材，不能仅凭统计可靠识别人像、发丝、玻璃或烟雾。语义证据更强时可显式覆盖算法，但仍要通过能力校验。
4. 配置缺失、无效、服务不可达或能力为空时明确报告不可用。不得声称已使用 matting-api；由上层流程决定是否回退。
5. 服务已经通过探测后，任务提交、轮询或下载失败必须如实失败，不能静默换算法或换成本地处理。
6. 输出只写 .png，默认拒绝覆盖；用户明确要求覆盖时才使用 --force。
7. 不输出认证 header、API key 或环境变量值。

工作流

1. 检查配置与实时状态

uv run --project {SCRIPTS_DIR} matting status
uv run --project {SCRIPTS_DIR} matting algorithms

status 同时请求 /api/status 与 /api/capabilities。algorithms 会列出服务本次广告的 method/model，以及 CLI 能证明兼容的组合。若服务只返回独立列表而没有 model-method 映射，CLI 只对已知协议或配置中显式声明的组合做自动选择。

配置查找顺序为：当前工作目录、skill 目录、当前 Git 项目根目录、~/.agents/agent_config.toml。也可用 --config PATH 或 MATTING_CONFIG 显式指定；显式路径不存在时停止。配置字段见 references/configuration.md。

2. 检查图片并获取推荐

uv run --project {SCRIPTS_DIR} matting inspect --input ./source.png

结果包含服务状态、实时能力、图像技术统计、推荐 method/model、理由和默认参数。自动选择规则见 references/algorithm-selection.md。

如果图片语义与统计冲突，使用显式覆盖：

uv run --project {SCRIPTS_DIR} matting inspect \
  --input ./portrait.png \
  --method birefnet --model birefnet-auto-quality --reprocess

3. 执行抠图

uv run --project {SCRIPTS_DIR} matting remove \
  --input ./source.png --out ./source-transparent.png

CLI 会再次实时探测，检查输入，选择算法和模型，提交异步任务，轮询终态，下载并验证透明 PNG，再原子写入目标文件。已有有效 alpha 时默认保留并规范化为 PNG；明确要重抠时加 --reprocess。

参数覆盖使用 JSON 对象：

uv run --project {SCRIPTS_DIR} matting remove \
  --input ./green-screen.png --out ./subject.png \
  --parameters-json '{"halo_pixels":1,"despill_strength":0.85}'

也可用 --parameters-file ./params.json。显式 --method 与 --model 必须成对兼容且在实时能力中存在。

高成本请求可先 --dry-run；它会完成配置、服务、能力、输入和选择校验，但不提交任务、不写输出。

与 image-generation 配合

当生成图需要去背景时，优先使用 image-generation 的统一入口：

uv run --project /path/to/image-generation/scripts imggen remove-background \
  --input ./generated.png --out ./generated-transparent.png

该入口只有在 [matting] 配置有效且实时探测成功时才调用本 skill。配置缺失或服务不可用时，它会明确报告回退原因，并使用 image-generation 现有的 chroma-key；服务已可用但任务执行失败时不会静默回退。

交付

完成后报告：

• 实际 backend（matting-api、existing-alpha 或调用方回退）；
• 服务版本和状态；
• method、model、选择理由；
• 输入和输出绝对路径；
• 是否发生覆盖、回退或显式参数覆盖。

不要把 health/HTTP 200 单独说成抠图成功；只有下载结果通过图片与 alpha 校验并写入目标路径才算完成。API 结构见 references/api-contract.md。