[Bug]: 抠图在角色内部打洞，像素风深色区被打穿两成到三成

[johnnyzhang-eng]

问题

抠图会在角色内部打洞：alpha=0 的区域出现在四周被主体包围的位置，合成到画布上时洞里透出背景色，角色看起来像被漂白。

证据

生产 task 391「像素程序员法师角色」，256×256，auto_pixelate=true，32 帧。判据是纯拓扑的——从画布四边泛洪找真背景，剩下的透明区即内部洞：

帧	主体面积	内部洞	占主体
f00	11479px	2620px	22.8%
f08	11354px	2326px	20.5%
f16	8843px	2825px	31.9%

即五分之一到三分之一的角色被打穿，集中在黑头发、深色卫衣、裤子。同任务的参考首帧半透明像素占 16.5%，动作帧升到 23.9%~35.5%，沿时间轴单调上升。

已排除的原因（逐条做了对照，勿重复走一遍）

• 不是缺少填洞逻辑。 providers/matte.py 的 cutout() 里已有 _fill_enclosed_holes(alpha, rgb)，判据是连通性 + 颜色两条，且已处理「迈步时两靴交叠封死腿间空隙」那种情况。生产镜像里这段代码在。
• 不是精修被关掉。 生产 WINDUP_MATTE_REFINE=1，u2netp 与 u2net 两个权重都在 /root/.cache/windup/，取逐像素较大 alpha。
• 不是像素化那一步造的。 用生产同一份 cutout() + to_pixel_art() 跑真实 i2v 帧，全分辨率 2.2% → 像素化到 195 是 2.2% → 到 160 是 2.1%，各步不增。
• 不是底色识别失败。 同一帧上 _bg_key 返回 [128,128,126]，填洞那步没有被跳过。

尚未定位的部分（说明现状，不假装已知）

在我手上的 i2v 帧（银发法师，主体 562px）上，生产 cutout() 只留 2.2% 内部洞；task 391 的交付帧却是 20%~32%。两者差别可能在角色本身（391 是深色小体量 chibi，肢体细）或在它那条视频。task 391 的源视频没有持久化，只存了帧，因此无法直接复跑那一条。

要往下定位需要其中之一：

• 用同一角色母版重新生成一次动作，并保留源视频；
• 或在管线里把 i2v 源视频（或抽出的原始帧）也存一份，供事后归因。

顺带发现（另一个问题，不在本 Issue 修）

#686 已合入 BiRefNetMatteProvider，但没有任何调用点实例化它：bootstrap/worker.py:133、orchestrator/executor.py:865、executor.py:1197、view_sheet_executor.py:343 四处仍硬编码 OnnxU2NetMatteProvider()，也无配置开关。代码在仓里，生产跑的仍是 u2net。且不能直接切换：BiRefNet 单帧峰值实测 6.85GB，生产 worker 容器内存上限 5GiB（宿主 4 核 7GB）。

验收标准

• 能复跑出 20%~32% 那个量级的内部洞（先有可复现的坏例，再谈修）。
• 定位到它由哪一步产生。
• 修完在同一坏例上内部洞占比接近 0，且腿间空隙一类真空隙不被填实。

相关

• feat(matte): 引入 BiRefNet 抠图，解决主体内部半透明 #685 / feat(matte): 引入 BiRefNet 抠图 provider #686：BiRefNet provider 已合入但未接线。

[johnnyzhang-eng]

根因找到了：attack 与 jump 走 prepare_master → add_headroom，而它无条件 convert("RGB") 把带 alpha 的母版拍平成纯黑底，于是黑发黑裤与黑底同色、抠图无法分离。取回 task 391 attack 的真实源视频实测，生产 cutout 在它上面留 13.8%~31.7% 内部洞，而同一角色的母版（未经 add_headroom）只有 0.8%。已开 #801 与 PR #802。走路不受影响，因为它不走 add_headroom。

[johnnyzhang-eng]

#802 合入后的实测：内部洞 26.4% → 2.4%

用 task 391 的原母版与原提示词重跑了一条 attack，唯一变量是 add_headroom 的修复（首帧底色由纯黑变成声明的灰）。用生产同一份 cutout() 量：

帧	修复前 黑底	修复后 灰底
0	26.9%	1.6%
10	26.4%	3.9%
20	27.6%	1.0%
30	31.7%	2.5%
40	19.5%	2.9%
均值	26.4%	2.4%

只取构图可比的帧：修复后那条从第 60 帧起模型自己推镜（主体高 277 → 719），推镜帧的洞率不可比 —— 角色被放大十几倍后细结构相对分辨率变粗，洞自然变少，那是分辨率效应不是抠图变好。上表用的帧 040 两条主体高分别是 277292 与 281~288，可比。

2.4% 与走路视频实测的 2.2% 是同一水平。u2net 本身不是瓶颈，输入才是。

据此更新本 Issue 的判断：

• attack / jump 的内部洞由 [Bug]: add_headroom 丢弃 alpha，attack/jump 的 i2v 首帧变成黑底 #801 / fix(video): add_headroom 保住 alpha，attack/jump 的 i2v 首帧不再是黑底 #802 解决，已验证。
• 走路本来就在 2% 量级。
• 换抠图模型的优先级应当下调。 BiRefNet 在同一帧上把内部非实心从 5541 降到 106，但那是在一个输入正常的前提下的边际收益；而这次量到的是"修输入 = 11 倍"对"换模型 = 边际"，差一个数量级。服务器侧跑 BiRefNet 另有内存硬墙（6.85GB 峰值 vs worker 上限 5GiB），已在 feat(matte): 抠图 provider 加选择开关，让已合入的 BiRefNet 不再是死代码 #822 说明。

新发现，另外跟进：修复后那条出现了推镜（帧 60 起主体高 277 → 719），而修复前那条全程 281~288 不推。同母版同提示词，只差底色。可能是生成随机性，也可能与底色有关，样本只有一条，不足以判定。