orisys-app/apps/studio/docs/replay-field-experiment.zh.md

Studio 回放：场加权实验模型

用途：reference。范围：Studio 回放分析对 SDK field_gain/1（输入 profile hhd_normal_l1_field/1）的接线、缓存身份、逐帧质量诊断与实时拒绝边界。 格式、完整性、失效键与播放语义分别由replay-analysis.md与 replay-analysis-part-b.md负责；模型语义见 场模型契约，任务范围见 实施计划。

缓存身份

场加权模型是新的分析行为，但不是新的二进制格式。result_key 的 sensor_config 分量在 标定文件实际为 field_gain/1 时追加 ;field-weighted=1；spatial/global 模型与旧结果的键 不变，因此旧回放结果仍能命中。标定内容身份仍来自 schema 3 指纹（含 pipeline.field、 几何与坐标附件），算法版本不因本功能整体升级。

provenance 另存 field 块：profile、strategy、实验来源、baseline_N、 reference_id、参与统计帧数、extrapolated_mean/max 与运行时实际的 hhd.downsample、hhd.grid_shape。缓存键只用标定指纹与配置内容哈希，不用声明值假装实际值； 实际网格只进 provenance。

回放 pass

• 打开链后读 sensor.calibration.input_profile 判定模型；field 模型只在显式 cal_path 下使用，profile 默认文件不假定为实验模型。
• 新模型要求单 segment 录像：加权基线无法在段边界重建，多 segment 直接 ValueError 并留下原因，不静默丢基线。
• 空载窗口仍需操作员在分析设置里声明（30 帧）；每个 pass 在参考帧 reset 之后、该帧 process_chain 之前调用一次 declare_unloaded_reference(reference_id="video-unloaded-<id>")。 SDK 累计连续 30 个有效加权 P 并取中位数；前 30 帧状态 zero_unavailable， 没有牛顿值但保留 raw 读数。不得调用 set_calibration_reference 传旧 raw 标量零点， 也不得把 centroid_found 当门槛。
• 第 30 个有效帧后确认 baseline_N 已就绪；视频结束仍未就绪沿用现有 ValueError 语义。
• 逐帧质量取自 sensor.calibration_result.diagnostics：extrapolated_fraction、 coverage_fraction、pending_reference_frames、baseline_N、reference_id、 model_fingerprint。质量是估计证据，不参与 calibration_status，不得因此丢弃牛顿值。

逐帧存储与读取

场加权质量追加在帧记录最后：FRAME_FLAG_FIELD 后接 extrapolated_fraction 与 coverage_fraction 两个 float32，沿用 FRAME_FLAG_FORCE 的追加先例，格式版本不变。 AnalysisReader.frame().field_quality 返回二元组；旧结果没有该 flag 时返回 None， 上层显示“未知”，不得补零或拒绝结果。counts.field_quality_frames 记录带质量帧数。

ForceSample.from_reading 继续只凭 raw 有限性判断 valid；质量缺失或外推比例高低都不改变 有效性。out_of_range 与负的基线差保留数值。

显示与实时拒绝

• replay_controller 在曲线来源与提示中使用 provenance 的 field 块：实验模型标签、 加权基线、平均外推比例；缺字段显示未知。中英 locales 成对新增键。
• 实时入口未接入该模型：SdkAcquisitionWorker.start()/FingerAcquisitionWorker.start() 与热切换 _consume_pending_calibration() 在打开设备前检查显式 cal_path，遇 schema 3 field_gain/1 抛可诊断的 RuntimeError；由现有运行错误处理显示。 calibration_service/实时 UI 若继续重构，保留同一检查函数供调用。

验收与限制

回归见 shared/tests/test_field_calibration_app.py、apps/studio/tests/test_field_experiment_display.py 及扩展现有四件套：窗口只声明一次、前 30 帧无牛顿值、第 30 帧后就绪、无接触仍有效、 多 segment 拒绝、质量 round-trip 与旧结果未知、field 键与 spatial 键不同、实时入口拒绝。 本次不宣称物理精度或在先模型的精度改善；基线窗口是否平稳、外推比例大小都必须随结果如实报告。