SWF → 离线 HTML 交互动画
概述
把旧版 Flash SWF（Flash 6 时代 AVM1 脚本，也支持更高版本）转换为一个完全离线的单文件 HTML：内嵌 Ruffle 模拟器（WASM）与 SWF 本体，用户双击即可在 Edge/Chrome（80+，2020 年后版本）中播放并点击交互，不依赖网络、服务器或任何插件。典型产物约 6.5MB，适合分发课件、演示动画。
技术原理（遇到问题再读）
Ruffle 官方 selfhosted 包在 file:// 协议下无法工作（fetch 加载 wasm 被 CORS 拦截、script src 相对路径失效）。本技能的转换脚本通过三层手段绕过：
- 全部资源（ruffle.js + core.ruffle..js + .wasm + SWF）gzip 压缩后 base64 内嵌；
- 页面用浏览器原生
DecompressionStream解压（因此要求 Chrome/Edge 80+）； - 两个运行时钩子：hook
HTMLScriptElement.src把 core.js 重定向到 Blob URL；hookwindow.fetch拦截 wasm 请求并喂内嵌字节；SWF 用data:URL 加载。
只内嵌现代浏览器 SIMD 内核（一套 core+wasm），不嵌旧浏览器备用内核，体积从 38MB 级降到 6.5MB 级。
工作流程
第 0 步：确认运行时（仅首次需要）
运行时目录位于本技能目录下 runtime/。若该目录不存在或缺少文件（应有 ruffle.js、两个 core.ruffle.*.js、两个 *.wasm），先运行：
python <skill_dir>/scripts/fetch_runtime.py
下载约 28MB（走 jsdelivr / npmmirror 镜像，带断点续传），之后无限复用。不要尝试从 github.com/ruffle-rs/ruffle 的 release 页下载——沙箱/代理环境下基本会被拦断。
第 1 步：转换
python <skill_dir>/scripts/swf2html.py "输入.swf" ["输出.html"] [--title "标题"]
- 输出默认与 SWF 同目录同名（.html）。
- 脚本自动解析 SWF 头设置舞台宽高比、自动识别 SIMD 内核配对；仅用 Python 标准库。
- 批量转换（推荐，一轮对话处理全部文件更省额度）：
cd "<swf所在目录>"
for f in *.swf; do python <skill_dir>/scripts/swf2html.py "$f" "${f%.swf}.html"; done
第 2 步：验证（抽检即可）
批量转换时抽 2~3 个样本，用 headless Edge 以 file:// 打开并检查控制台（Windows）：
"<Edge路径>/msedge.exe" --headless=new --disable-gpu --hide-scrollbars \
--screenshot=out.png --window-size=1280,960 --virtual-time-budget=90000 \
--run-all-compositor-stages-before-draw --enable-logging=stderr --v=0 \
"file:///D:/path/to/动画.html" 2>console.log
Edge 路径通常为 C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe。中文文件名与空格需 URL 编码（空格→%20）。从 console.log 中 grep 以下 5 条日志，全部出现即验证通过：
[player] embedded assets decompressed[player] serving embedded wasm: <hash>.wasmRuffle WASM module has been initializedNew Ruffle instance created (Version: ... | WebAssembly extensions: ON)Loading SWF file data:application/x-shockwave-f...
同时确认无 ERROR:CONSOLE 级别的 [player] 错误。
第 3 步：交付
用 present_files 把生成的 HTML 交给用户，说明：双击即可在 Edge/Chrome 打开，完全离线可交互。若用户询问体积问题：做成 exe 不会更小（同一套 WASM 内核），已是最优方案。
常见问题与坑（详见 references/troubleshooting.md）
- headless 截图白屏 ≠ 失败：wgpu-webgl 在无头模式不刷帧是已知怪癖，以控制台日志为准。
- ZWS/LZMA 压缩的 SWF（Flash 13+）不支持：解析器仅支持 FWS/CWS，遇到时告知用户需先解压。
- 产物体积异常（远大于或小于 6.5MB）：检查 runtime 目录文件是否完整。
- 复杂排障、下载镜像细节、SWF 头解析细节见
references/troubleshooting.md。
资源
scripts/
swf2html.py— 核心转换脚本（SWF → 离线单文件 HTML）fetch_runtime.py— 一次性下载 Ruffle 运行时到runtime/
references/
troubleshooting.md— 完整踩坑记录：file:// 限制的绕过原理、镜像下载策略、SWF 头解析（RECT 字段顺序）、fetch 钩子细节、验证方法
