极客豌豆 · 本地练习资源 · R1 / 2026-10-14
收到的素材，是否与发出时一致？
为两份目录生成相对路径清单，再核对缺失、额外、同名内容变化与可能重命名。所有样本均为程序自制的虚构练习；不含客户数据、第三方视频或音乐。
文件核对只是交接的一步。摘要一致不等于文件可播放、版权已获授权、素材齐全满足创意需求，也不等于 Premiere 等剪辑工程可重开。本包没有剪辑工程。
1. 先看一个有意制造的差异
样本各有一个 4 秒、640×360 的几何画面视频，以及 4 秒低音量合成音频。两份音频字节数相同，但频率分别为 440 Hz 与 660 Hz，用来展示“文件大小相同，内容仍可不同”。播放前请调低音量。
自制静态几何画面；无拍摄素材、无字幕烧录、无音轨。
基线音频 · 440 Hz
同名内容变化样例 · 660 Hz
本地 FFmpeg 8.1.2 对这些媒体解码成功；这是该解码器的检查结果，不能代替你的目标播放器、剪辑软件或其他设备实测。
2. 两条命令做一次练习
本工具使用 Python 标准库。需要 Python 3.9 或以上；本次仅在 macOS 实跑。代码使用 macOS / Linux 的安全文件读取能力，但未在 Linux 实测，不支持 Windows。本包没有自动安装程序。
- 把 ZIP 解压到普通本地目录。打开终端，输入
cd （后有空格），将解压目录拖入终端，按回车。这里应能看到 file_manifest.py 和本指南。 - 先停止样本目录的编辑、同步和复制，运行下面第一条命令。结果文件保存在包目录，位于被扫描的
samples/02-same 之外。 - 运行第二条命令，与包内基线清单比较。
(set -C; python3 file_manifest.py manifest samples/02-same > received-new.json)
python3 file_manifest.py compare expected/01-baseline.manifest.json received-new.json
set -C 只作用于这个括号内的子 shell，避免覆盖已经存在的结果文件。再次练习时改用新的输出名称；不要用 > 指向原素材或已存在的重要文件。工具只输出到终端，保存文件的是 shell 重定向。
成功时会看到 complete: true 和 same_inventory: true。也可以直接查看 本包的相同目录预期结果。其余四组只需把第一条命令的 02-same 换成下表目录，并给输出清单换一个新名称。
| 接收目录 | 故意制造的情况 | 预期结果 |
|---|
02-same | 全部相同 | 无差异；退出码 0 |
03-missing | 少了音频 | missing_paths 1 项 |
04-extra | 多了一份说明 | extra_paths 1 项 |
05-changed | 音频同路径、同大小、内容改变 | changed_same_path 1 项 |
06-renamed | 视频改名、字节不变 | missing 1 + extra 1 + possible_renames 1 |
最后四组退出码为 1，意思是比较完成且发现差异，不是脚本崩溃。2 表示读取或格式检查失败；不完整结果不能用于判断文件丢失。
3. 用在真实交接中
- 发出方先确定交接边界：哪些素材、版本、字幕、授权材料及工程应该包含；单靠目录扫描无法知道创意需求是否齐全。
- 停止编辑与同步，在要发送的素材目录上运行
manifest，将清单保存到目录之外。清单需与对应版本一起保存，并通过可信渠道确认来源；手动伪造的清单不能作为可信证据。 - 接收方下载并解压完成后，在接收目录上重新运行
manifest，使用 compare 与发出方清单核对。 - 先解决 missing / extra / changed，再逐项确认 possible_renames。相同摘要的新增和缺失也可能由复制产生，工具不推断真实操作历史；存在多个候选时归入
ambiguous_same_content_groups。 - 另做播放抽检、授权材料核对和剪辑工程重开；使用 人工检查记录 留证。
大素材默认上限为单文件 512 MiB、总量 2048 MiB、10000 个文件、20000 个目录条目、32 层递归。只有确认是你自己的目标目录、且理解读取成本后，才使用 --max-file-mib 与 --max-total-mib 提高字节上限。达到上限会整体停止，不会用“部分清单”报缺失。
4. 读取边界与限制
- 不联网、不上传、不删除、不自动修复，也不改写源文件。结果仅包含相对路径、字节数和 SHA256；不会输出所选根目录的绝对路径。文件名本身仍可能含业务信息，分享清单前请检查。
- 根目录和祖先路径、子目录、文件若包含符号链接则拒绝；特殊文件、权限不足、路径穿越、大小写或 Unicode 等价名称冲突、已观察到的扫描中变化都会停止。不会为了继续扫描而跳过问题文件。
- 扫描末尾会再次检查已读取对象的状态，但不是文件系统原子快照。核对期间应停止编辑、下载和同步；成功只说明本次完整遍历和复核完成，不能证明全目录所有文件来自同一瞬间。
- 隐藏普通文件也纳入核对；空目录、文件权限、所有者、扩展属性、资源叉和硬链接关系不在清单范围。macOS 下载、解压产生的额外元数据文件可能作为 extra 出现，需按真实交接要求判断，工具不会自动删除。
- 不提供版权判断、恶意文件扫描或素材来源认证。SHA256 用于内容一致性核对，不能说明谁创作或是否取得商用许可。
- 本次只验证这组自制样本。没有用真实客户数据，也没有验证 Premiere、Final Cut 或剪辑工程重新链接成功。