# Studio 回放：场加权实验模型

用途：reference。范围：Studio 回放分析对 SDK `field_gain/1`（输入 profile
`hhd_normal_l1_field/1`）的接线、缓存身份、逐帧质量诊断与实时拒绝边界。
格式、完整性、失效键与播放语义分别由[replay-analysis.md](replay-analysis.md)与
[replay-analysis-part-b.md](replay-analysis-part-b.md)负责；模型语义见
[场模型契约](../../../orisys-sdk/docs/field-gain-model.zh.md)，任务范围见
[实施计划](../../../docs/workflow/field-weighted-calibration-plan.zh.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 键不同、实时入口拒绝。
本次不宣称物理精度或在先模型的精度改善；基线窗口是否平稳、外推比例大小都必须随结果如实报告。