多镜参考匹配
使用场景与参考选择
多机位、不同批次或用户指定的多个成功镜头需要统一影调时，执行一次参考匹配。只有一个镜头且用户没有要求匹配时，直接沿用它或执行明确调色请求。
参考镜由请求指定。可参考以下工艺原则：主体与光线接近目标片、具有已知中性物或肤色、能代表本片基调。YAVG 90–120 是显式诊断的参考，不能成为参考镜合格闸，更不能因缺少“合格”参考而重生成片子。
SOP 与接口
color-cli match --ref hero.mp4 --in a.mp4 --in b.mp4 --out-dir matched-v2/ --json
- 触发为明确匹配请求；核对一个参考、至少一个目标、允许输出目录、真实来源和当前 SHA256。参考缺失、越界或权限不符时失败，保留真实回执。
- 读取参考与每个目标的必要统计，派生曝光、饱和与色度轴校正量；这些读数用于执行变换，不用于评审源镜接受。
- 每项执行一次本地变换，产出新文件。不存在的目标与 FFprobe/FFmpeg 加工错误写入该项
ok=false、错误码和原因，后续可处理目标继续执行。 - 返回完整
results；全成功 CLI 退出 0，任一项失败退出 3。普通输出与 JSON 具有同一失败语义，不能只看文件数量判断完成。 - 成功项核对输出 SHA256，未测残差为 null，
qualityReviewed=false。保留原片 SHA256 与历史品质失败；没有残差再评审或自动第二轮。
参数边界
| 参数 | 边界 | 处理方式 |
|---|---|---|
reference | 恰好一个实际可读参考 | 缺失明确失败 |
targets | 至少一个；逐项目保留结果 | 空数组为用法错误 |
intensity | 大于 0 且不超过 1 | 控制 look 混合 |
profile | 支持的 profile 或省略 | 不自动替换未知配方 |
outDir | 合法新输出目录 | 原片只读，不覆盖输入 |
histogramCheck | 旧 off/warn/fail 参数兼容 | 不恢复成片品质否决 |
denoise | 显式请求才执行 | 不因默认噪点审查拒绝原镜 |
可选诊断工艺表
| 指标 | 原工艺参考 | 当前用途 |
|---|---|---|
| ΔYAVG | 不超过 5 | 明确诊断时说明亮度差 |
| ΔUAVG / ΔVAVG | 不超过 3 | 明确诊断时说明色度差 |
| 肤色 HSV | 20–40° | 诊断参考，显式肤色 patch 优先 |
| 连播跳变 | 用户审看意见 | 形成明确反馈，不自动重做 |
默认不测成片残差；严重欠曝、高光裁切、柔焦等已有成功镜头同样进入请求加工。工具不能将 null 当 0，也不能写“匹配品质已通过”。用户重新选择参考属于新本地请求，不由诊断分数触发。
失败模式（症状 → 原因 → 处置）
| 症状 | 首查原因 | 处置 |
|---|---|---|
| 参考路径缺失 | 文件或来源登记不符 | 停止批次，返回实际错误，不猜其他参考 |
| 部分目标不存在 | results[].error=not_found | 保留完整结果和成功输出，进程非零 |
| 目标容器损坏 | FFprobe 非零退出/无视频轨 | 指名失败项与真实 stderr，继续其他项，不伪造源成功 |
| 加工或磁盘写入失败 | FFmpeg、可写目录、余量 | 标记该项失败，不以原片复制冒充匹配结果 |
| 用户觉得参考选择不符 | 用户反馈与当前参考 ID | 记录新的明确参考请求，保留上轮结果 |
| 不同机型色域不同 | 明确 transfer/gamut 元数据 | 按支持转换处理；无法表达的参数明确失败，禁止猜 log |
回执与知识引用
参考路径、必要的参考统计和选择理由，逐项 target/ok/output/实际 SHA256/校正量/错误，未测 after/residual 和品质未评审声明一起留痕。断点执行以完整失败清单为输入，不自动重新付费。
知识入口：library/color-kb/_INDEX.md，CGRADE-007 镜间匹配方法论与 CGRADE-005 示波器判读。历史诊断阈值仍能用于显式分析，但不接入正式素材接受条件。