第一阶段修复说明

范围

本轮修复透明 GIF 调色板索引、旧绝对路径、五个 GIF 构建入口的覆盖风险，以及 v2 光流缓存。没有重建已有动画，没有替换原始图片或历史 GIF，没有发布 Python 包。

运行构建脚本时，终端会打印 New output directory。每次运行创建一个带随机后缀的新目录：

GIF 文件名不变，配套帧序列和构建计划也写入对应运行目录。旧目录与旧产物不会被这五个入口直接覆盖；v4 不再清空旧 seq_melee_v4 目录。runs 目录不自动清理，失败运行也可能留下目录。

输入素材仍从脚本所在目录读取。v1 依赖 mimo.png 和 _boxes.json；v2 依赖 v2/frames_key；v3 依赖 v3/frames_aligned；v4 依赖 v3/tiles。这不是通用素材 CLI，换素材仍需要案例参数。

在仓库根目录执行，例如：

python v3/build_melee_v4.py

前提是 v3/tiles 中所需素材已经存在。该命令会重新计算动画；本轮没有执行它。不要仅为检查安装而导入构建脚本，因为这些旧入口仍包含顶层处理代码。

重要：旧 verify.py、v2/verify_24.py、v3/verify_v3.py 等检查脚本尚未支持选择新运行目录，它们默认读取历史位置的产物，不会自动验证刚生成的 GIF。部分检查脚本还会写对照图或执行实验。不要把它们的输出当作新成品已验证的证据；后续应增加明确的输入目录参数。

环境需有 numpy、Pillow、scipy、scikit-image 和 pytest。本轮没有安装或升级依赖。

在仓库根目录运行：

python -B -m pytest tests/test_regressions.py -q -p no:cacheprovider --tb=short

本轮实际结果：15 passed。内容包括五个编码器的白底和透明 GIF 回读、缓存命中与输入变化、缓存损坏重算、禁用缓存、算法实现变化、27 个脚本的语法与旧路径检查、光流模块导入无目录创建，以及 v4 输出目录保留旧文件。

测试使用合成小图和临时目录；通过 AST 提取旧脚本中的编码函数，不执行顶层动画处理。缓存测试用替代光流函数验证缓存行为，不代表真实光流视觉效果或完整构建流程已通过验收。

v2/morph.py 的缓存键包含解码后的两帧内容、数组尺寸和类型、光流函数源码以及 NumPy/SciPy/scikit-image 版本。加载时验证数组尺寸和有限值；损坏缓存重新计算。写入先使用同目录临时文件，再替换目标文件。

旧的按帧编号命名的缓存不再命中，但不会自动删除。缓存文件创建被推迟到实际写入阶段，单独导入 morph 不再创建缓存目录。