# 首尾帧文件预检：尺寸、比例与角色绑定

确认绑定到 first、last 的文件确实是指定且可读的同尺寸图像。本检查不证明首尾语义连续，也不验证任何提供商的首尾帧能力。

完整包只使用 Node 标准库。FFmpeg 需使用自己已有的安装，本包不分发二进制；不在 PATH 时将 FFMPEG_BIN 设为其绝对路径。

在本目录运行，并选择不存在的新输出目录，脚本拒绝覆盖。受内存管理的工作站可在 Node 命令前加本地串行执行包装器。不需要提供商密钥，夹具不会向设备外发请求。

```sh
node run-recipe.mjs --out ./my-run
```

实际记录：7项检查通过，包含4项预期拒绝，Node v24.18.0。ffmpeg version 6.0 Copyright (c) 2000-2023 the FFmpeg developers

准备

- 准备 Node.js 与已有 FFmpeg；若不在 PATH，先将 FFMPEG_BIN 设为可执行文件绝对路径。本次夹具实际使用 FFmpeg 6.0。
- 查看 binding.json 与 executed/inputs 中的原创 first.png、last.png，尺寸均为 320×180；另有 180×320 竖图专门用作错误输入。
- 把角色名、文件 basename 与预期 SHA-256 一起保存，选择全新输出目录，避免旧清单悄悄指向已替换的文件。

## 01. 固定每个角色对应哪份文件

脚本创建两张小型原创 RGB 示意图并写出绑定清单。首尾图的字节与边缘标记各不相同。哈希来自实际文件，不通过上传次序或文件名包含 first 来猜测角色。

## 02. 同时核对画布与完整解码

逐项读取 PNG 签名和 IHDR 宽高，再由 FFmpeg 完整解码为一帧 RGB。两张都必须为 320×180，并符合本任务明确选定的 16:9 画布。只有头部尺寸正确，还不能证明压缩像素能解码。

## 03. 实跑四种不安全绑定

依次检查竖版尾图、交换文件名、缺少尾图及父目录路径。它们分别实际触发尺寸不匹配、哈希绑定失败、输入缺失与不安全 basename，failure-receipt.json 保留具体异常。

## 04. 把文件与绑定清单一起留档

检查 execution-receipt.json 的七项通过及脚本运行前后哈希。改成自己的上传流程时，把两张 PNG 与 binding.json 成套保存；相机、主体与首尾语义仍需独立审看。

验收

- 正确首尾图各完整解码为一帧 RGB。
- 两个角色都准确为 320×180，交叉相乘验证 16:9。
- 首尾图 SHA-256 不同，且分别匹配各自绑定文件。
- 180×320 的竖图替换会因尺寸不一致被拒绝。
- 把 last 文件名放入 first 但保留旧哈希，会被拒绝。
- 缺失文件与父目录路径均失败，七项检查写入回执。

排错

尾图主体正确但尺寸检查失败。只调整其实际像素画布到选定尺寸，重新导出并获取新哈希。改文件名不能改变竖图尺寸。

两份文件上传时顺序弄反。更正角色到 basename 的映射，再从所选文件重新生成预期哈希并复核绑定。

文件头正常，但解码中途失败。只把受损文件换成完整本地副本，再跑完整解码；不以 IHDR 宽高代替像素可读性。

公开回执副本仅归一化本地 checkout 路径，publicPathNormalization 保存原始回执 SHA-256；未改动原件保留在非公开资产之外。真实回执位于 executed/。failure-receipt.json 记录预期负向案例，不表示套件断言失败。原创新夹具会重新生成到指定新目录，包内保留实跑输入输出便于复核。子进程使用参数数组、禁用 shell，设15秒超时与8MB输出上限。临时原始数据和本机 HTTP 服务在 finally 清理。

checksums.json 覆盖自身与 ZIP 以外的全部分发文件，避免循环自引用；ZIP 内包含同份清单。下载后可重算，但比较前提是预期清单可信。execution-receipt.json 记录实际脚本运行前后哈希，ZIP 也会由发布目录的资产清单绑定。

这份清单记录文件就绪情况，不代表已生成首尾过渡、已兼容某个接口或已保留两端视觉状态。

2026-10-14 实际读取的来源

- Node.js filesystem API: local file inspection：https://nodejs.org/api/fs.html
- Node.js crypto API: SHA-256 hashing：https://nodejs.org/api/crypto.html
- FFmpeg command-line documentation: maps, codecs and error exit：https://ffmpeg.org/ffmpeg.html