需求 slug：aurora-pet-and-interpolation ｜ 关联：迭代自 agent-task-monitor · multi-client-and-control-panel ｜ 版本：v0.6.0-dev

用户丢来一个全新素材包「极光罗盘猫」——单角色 8 套动作动画 + 12 个元素变体立绘（水/草/火/风/电/冰/幽灵/超能/岩石/光/暗/彩虹），要求换掉旧的「3 物种 × 4 阶段」桌宠并完善 UI。本文沉淀这次换装里三个真实问题的解法，以及一条重要的协作原则：先做门禁，再优化。

1. 素材模型不匹配：12 元素替换 3 物种

旧模型是 3 物种 × 4 阶段（蛋→成年）+ 毕业/衣柜/饿死生命周期；新包是一只猫、一套动画、12 个静态元素立绘——没有蛋/幼体/成年的分阶段美术。评审拍板：

• 12 元素替换 3 物种：单只极光猫做活体动画，8 动作映射状态（rest→idle / run→working / sleep→waiting / cheer→complete / happy→evolve / hungry→饿了）；12 元素作为可收藏皮肤，沿用「毕业解锁→图鉴收藏」。
• 成长改为「体型 + 光环」：既然没有分阶段立绘，就用 growth（0.55→1.0，由 level/graduationLevel 推导）缩放桌宠、脚下对齐（从脚下长大）+ 后期叠柔和辉光。幼年是小小一只，毕业时长到满型。
• manifest 升到 v2（actions + elements），RasterPetView 改为按动作直接取帧，不再查 species/stage。

2. 丢帧太卡 → 光流补帧（真·补帧，不是透明度混合）

新包每个动作只有 6 帧（旧包 30 帧），播起来明显卡顿。原来的「交叉溶解」是相邻帧透明度混合——在大幅度动作上会重影而非补帧，反而更糊。

正解是运动补帧：本机无 cv2/ffmpeg/RIFE，但有 numpy/scipy，遂用 scikit-image 的 optical_flow_tvl1 估计相邻帧双向光流，scipy.ndimage.map_coordinates 把两帧各自 warp 到中间时刻再按 t 混合（alpha 一并 warp，透明边缘不发虚），6 帧插到 ~24 帧。fps 按「一轮秒数」自动升到 17–30，节奏不变只更顺。

PEP 668 externally-managed 环境装不了 skimage，用隔离 venv（/tmp/aurora-venv）跑生成脚本；缺库自动回退不补帧。

3. 「不同动作的帧糊在一起」：其实是大位移重影

用户反馈某些动图像是把别的动作帧切了进来。查下来不是跨动作污染，而是 jump/skill 这种大位移动作光流插帧时的双重曝光重影（猫跳跃位移太大，光流跟不上，合成帧里两只猫叠一起）。

试过按「光流幅度」或「半透明占比」阈值做 per-pair 自适应，都不干净：jump 的位移幅度和 complete 相近（前者是整体平移、后者是原地摆手），闪光粒子又会把半透明指标抬高。最后用动作级自纠正——先 4× 补帧，若「半透明占比中位数」超阈值就逐级回退 2×→原帧。结果：live 用到的 6 个动作全 4×（顺滑），只有 jump 回退 2×（清晰不糊）。关键：流水线的回退判据 = 门禁的度量口径，天然过检。

4. 门禁优先（用户的原话：先做 harness 门禁再优化）

用户在报 bug 时特别要求「先做一个 harness 门禁再优化相关问题」——这是很对的工程直觉。于是先加 tests/integration/AssetIntegrityTests.swift（进 CI swift test），五道关：

1. manifest 结构 + 文件齐全；
2. strip 几何：宽 == frames×fw、高 == frameHeight（防丢帧/错位切片）；
3. 12 立绘尺寸完全一致（此前按各自内容 bbox 裁剪导致大小不一，改成取设定板规整 512×512 方格）；
4. 每帧非空（防空白/丢帧）；
5. 补帧重影检测：单动作「半透明像素占比」中位数 ≤ 0.33。

门禁写完一跑就当场逮到 jump 重影（中位数 0.464 > 0.33）——先立门禁、看它变红、再修到变绿，比"改完自己看几眼"靠谱得多。

5. 抠米白底

新帧是米白底（254,249,243）不是旧的洋红。猫体本身也偏浅，全局键色会误伤，故用四角边界连通泛洪：只把与边界相连的近米白像素判为背景，中心的浅色猫体不受影响。

6. 验证

• swift build / swift test（106→110，含 5 项门禁）/ swift-format lint --strict 全绿。
• 生成核对：对比图逐动作看抠图/补帧/循环；jump 回退后重影消失。
• 真机：本地 release 构建装到 /Applications，旧持久化物种 dog_cabbage 不在新 12 元素里 → 自动重掷为 wind，Lv4 → 成长度 ~0.89（成长中）。

7. 可复用经验

1. 6 帧靠透明度混合救不了：大幅度动作的交叉溶解是重影不是补帧，要真运动补帧（光流 warp + alpha）。
2. 门禁先行：把"看着不对"变成可度量的红灯（这里是"半透明占比中位数"），再让流水线用同一口径自纠正——修复和防回归一步到位。
3. 自纠正 > 调阈值：per-pair 魔法阈值区分不了「大平移」和「原地摆手 + 闪光」；按结果质量逐级回退更稳。
4. 抠浅色主体用边界泛洪，别全局键色。
5. 没有的美术不硬造：无分阶段立绘就用体型/光环表现成长，既省素材又保留养成正反馈。

---

📦 本文首发于开源项目 agentmon 仓库 · 查看原文