把参考片、提取配置、原始深度、控制片与生成请求关联归档，再用只改一个因素的对照追查结果差异。提供 ReShot 0.5.0 命令与实验记录模板。
动作参考换了设置，怎样查清结果为什么不同？先把两次运行的输入、提取配置、控制片和生成请求分别留档，再找第一个发生变化的环节，最后只改一个因素做对照。ReShot 是 AI视频创作平台猫斯卡开源的视频预处理工具，可提取深度、骨架和线稿控制素材；它记录提取环节，生成模型的版本、提示词和种子仍需另存。
实验记录是把“用了什么输入、执行什么配置、得到什么文件、观察到什么差别”关联起来的证据。保存得完整，才知道下一次应固定什么；仅有日志，还不能证明某个参数导致了成片变化。
先保存哪些文件，才能知道到底改了什么？
不要把两次文件都叫 final.mp4。建议给每次运行单独目录，并保留以下材料；这是本文建议的归档方法，不是 ReShot 自动建立的目录规范。
| 环节 | 建议保留 | 用来排除什么混淆 |
|---|---|---|
| 输入 | 实际送入的参考片、文件 SHA256、截取时间范围；若经转码，再留转码命令 | 同名文件被替换、截取范围变了 |
| 提取环境 | ReShot 版本、依赖版本、权重文件及其 SHA256、实际设备 | 包版本相同，但依赖、权重或运行设备不同 |
| 提取过程 | 完整命令、metrics JSON、控制视频；深度研究按需留 NPZ | 只记界面选择，遗漏覆盖参数或实际输出 |
| 生成过程 | 实际提交的控制片与角色图、完整提示词、模型标识、工作流或请求参数 | 控制片相同，但外观输入、提示词或采样设置变了 |
| 生成结果 | 返回片、任务标识、返回的有效参数、观察记录 | 请求值与实际执行值混在一起，或挑片后丢失原结果 |
同名不等于同内容。实操上，可以先用 shasum -a 256 input/reference.mp4 登记真正送入的文件；它只证明文件内容是否相同，不证明视频内容适合这次动作任务。
采用 ReShot 做这层记录的依据是其公开接口：--metrics 保存配置、计划、耗时、峰值 RSS 和输出尺寸，--npz 可保存处理尺寸下的原始深度。两者让“配置变了”与“素材变了”有东西可查。接口见 使用文档。
怎样把两次提取做成可比较的记录？
以下按 ReShot 0.5.0 的 CLI 与源码核对，是待执行的操作示例。前提是已安装该版本、模型依赖与权重可用，且准备好了同一份短参考片。例子只把深度灰度映射的 gamma 从 1.0 改成 1.2，不同时更换控制类型、画面尺寸或质量档。
reshot --version
mkdir -p run-A run-B
reshot input/reference.mp4 -o run-A/control.mp4 \
--control depth --target h3 --model small --quality fast \
--gamma 1.0 --npz run-A/depth.npz --metrics run-A/metrics.json
reshot input/reference.mp4 -o run-B/control.mp4 \
--control depth --target h3 --model small --quality fast \
--gamma 1.2 --npz run-B/depth.npz --metrics run-B/metrics.json
每条命令正常完成后，应分别检查对应目录中的 control.mp4、metrics.json 和 depth.npz。若某次失败，保留退出码与错误，先修复该次运行，不拿残留文件当新结果。A、B 的输出路径不同只是归档差别，拟研究的因素只有 gamma。
源码中的 metrics 含 version、config、plan、实际 device 与 precision、frames、fps、output_size 等。这里 device=auto 是请求配置；真正采用的设备应看顶层 device。比较配置时先排除输出路径等归档字段，再检查其余值，不要只找那一行 gamma。
还有一个容易误读的字段：depth_seconds 是历史名称，源码将它用于各控制类型的模型阶段耗时，不能看见这个键就认定本次跑的是深度。应同时看 control。具体写入行为见 pipeline.py。
原始深度 NPZ 能帮忙定位到哪一步？
0.5.0 源码先保存 depths 与 fps，再调用 to_gray(... gamma=cfg.gamma)，随后放大并写控制视频。文档规定 NPZ 的 depths[T,H,W] 为处理尺寸下的 float32 深度；它不是最终 MP4 的像素，也不是三维动作文件。
因此，查 gamma 差异时可以按顺序比较：
- 核输入文件摘要、版本、权重与实际设备，确认比较对象一致。
- 核 NPZ 的数组尺寸、fps 与数值。如果原始深度已经不同，先查推理与环境，不能把后面的差异全部归给 gamma。
- 若原始深度一致，再核控制片的灰度变化与编码设置，观察改变是否出现在预期的映射阶段。
- 最后比较生成片。此时仍要核生成请求，不能从“控制片变亮暗”直接推出“动作必然更准”。
这些是本文建议的诊断顺序，并非本例已得到的测量结果。NPZ 对深度比较有用；本篇命令不能拿去要求骨架或线稿输出同样的深度数组。
若改的是 quality，检查重点也要跟着变：文档把它定义为深度模型工作尺寸，--input-size 又会覆盖它。两次都写着 quality=fast，但其中一次另设了 input_size，不能叫“推理尺寸没变”。输出尺寸则另看 plan 与 output_size，别只凭档名判断。
生成端还要补什么，才能比较成片？
建议另存一份实验记录。下面 YAML 是人工归档模板，不是 ReShot 或生成接口的参数格式；占位项都要替换，拿不到的值如实写 null，并在限制中说明。
experiment_id: gamma-check
changed_factor: gamma
input:
file: input/reference.mp4
sha256: 待填
preprocess:
version: 0.5.0
command_file: command.txt
dependencies_file: environment.txt
weights_sha256: 待填
runs:
A:
gamma: 1.0
metrics: run-A/metrics.json
raw_depth: run-A/depth.npz
control: run-A/control.mp4
B:
gamma: 1.2
metrics: run-B/metrics.json
raw_depth: run-B/depth.npz
control: run-B/control.mp4
generation_record_per_run:
submitted_assets_and_hashes: 待填
prompt_file: 待填
model_and_revision: 待填
workflow_or_request_file: 待填
requested_seed: null
effective_seed: null
returned_parameters_file: 待填
task_id: 待填
result_file: 待填
comparison:
observation_times: 待填
observed_difference: 待填
unresolved_changes: 待填
为 A、B 各填一份生成记录。实际提交的控制片，可能已经被工作流缩放或转码，所以要登记真正进入生成请求的文件，不能只登记 ReShot 刚输出的文件。角色图、提示词、模型版本、可控制的采样设置保持一致；支持种子时记录请求值及返回值，不支持或未返回时明确留空。
再预先约定观察位置，例如“人物抬手时刻、双方相对位置、镜头开始推进的位置”，逐项记现象。若生成端仍有未固定的因素，结论写“在这些条件下观察到差别”，不要升级成“gamma 导致动作改善”。若要进一步归因，建议在相同可控条件下重复对照，并保留全部结果。
旧实验能支持什么，不能代替什么？
本地技术报告 marketing/papers/reshot-2026-10/reshot.tex 的记录正好说明缺项的后果：报告分析同一参考片、一个生成模型下的 37 条生成片，整理了其中 30 条的提示词；另 7 条重跑时的提示词修改没有记录，种子只记了 3 条骨架片。
这份材料可用于查看已有案例与观察结果，但各条件种子未匹配，不能据此把结果差异全归因于控制类型。报告还明确，结构指标衡量站位与镜头，不衡量每个拳脚是否正确。它属于本地技术报告资产，不能当作已发表论文或严格受控实验背书。
对于这次改设置的任务，直接下一步是：先找出两次记录里所有真实变化，选一个要验证的因素，把其他可控项固定，再按同一观察表比较。缺记录的旧结果标明缺项；从下一次运行开始补齐，比事后猜测丢失的提示词或种子可靠。
