flowocr 0.1.0__py3-none-any.whl

flowocr/extract/ocr_complete.py

@@ -0,0 +1,231 @@
+"""OCR 产物"跑完没有"的判据。**单独放一个文件是为了让守卫够得着。**
+
+来历：C8 那次的教训（audit4-response 报告）——判据写在
+paddleocr 实验目录 里的脚本顶层，而那个文件 import cv2 和 paddleocr，
+**共享层的自检够不着，够不着就等于测不了**。这条判据同样属于"错了不会报错"
+的一类，所以照 `dev_tools/predet_stop.py` 的先例抽出来。
+"""
+from __future__ import annotations
+
+import os
+
+COVER_TOL = 0.98
+"""容器元数据允许虚报多少。`CAP_PROP_FRAME_COUNT` 在游戏切片上多报 1%
+（声称 36,361、实际 36,001）——这不是没跑完，是元数据不准。"""
+
+
+def is_complete(got: int, want: int, tol: float = COVER_TOL) -> bool:
+    """推进到的帧数够不够。
+
+    **不要再把"解码器提前返回"当成没跑完**（2026-09-08）：读到文件真正的结尾
+    也会提前返回，于是九段切片每次跑完都自称未完成、退出码 3，
+    驱动脚本会永远重跑它们。当时是把产物里的 `complete` 手工回填了——
+    **改数据没改代码**。
+
+    中途真断了这道门自己会拦：40% 处解码失败时 `got/want` 就是 0.4。
+    """
+    return got >= max(1, want) * tol
+
+
+def aux_shortfall(edge_meta: dict | None, last_idx: int | None, grid) -> str | None:
+    """辅助流（两遍合一遍的回抠证据）有没有**交够**：返回问题（None = 没问题）。**纯函数，守卫直接测。**
+
+    2026-09-24 审计（Claude / Codex 两份都指出）：辅助流出错原来只记进 `_meta.edge`、`complete` 照样为真，
+    于是回抠证据半路断掉的 obs 会被一直复用。**`aux_stopped_early` 不能当判据**——有丢帧缺口的素材上单路也会置上
+    （辅助流按数量收口、缺口处凑不够数，f3 / f4 每一臂都是 True）。判据是两条：
+    ①pts 和帧对不上（`aux_misaligned`，停下来的那一刻起证据就没了）；②**辅助流没盖到采样流的最后一帧**
+    （同一个 ffmpeg 出两路，最后一个辅助帧号不该早于 `grid.cover_floor(最后一个采样帧)`；`grid` 是 `AuxGrid`）。
+    `aux_last_key` 不在（旧产物 / 不经 `AuxReader` 的 nvdec / cuvid 那几路）就只判第①条。"""
+    e = edge_meta or {}
+    if "aux_sent" not in e:
+        return None
+    if e.get("aux_misaligned"):
+        return f"辅助流的 pts 和帧对不上、提前停了：{e['aux_misaligned']}"
+    if last_idx is None or "aux_last_key" not in e:
+        return None
+    k = e["aux_last_key"]
+    if k is None or k < grid.cover_floor(last_idx):
+        return f"辅助流只到帧 {k}、采样流到了帧 {last_idx}（辅助流半路断了，之后的回抠证据是缺的）"
+    return None
+
+
+def obs_reusable(path, argv=None) -> tuple[bool, str]:
+    """一份观测产物能不能直接复用。返回 `(能不能, 不能的话为什么)`。
+
+    **判据只有这一份**（audit-5）：三个驱动脚本以前各自内联一段
+    `python -c` 读 `_meta`，`run_full_ocr.sh` 那份甚至根本没读、只看
+    `[ -s ]`——一次中断留下的半截 jsonl 也是非空的，于是"一次中断变成
+    之后每次都已经做完"，而且不报错。
+
+    四个条件，缺一不可：
+    - `_meta.complete` 为真（跑完了）；
+    - **`_meta.timebase == "pts"`**（时间轴是新口径的）；
+    - **`_meta.decoder` 是当前默认**（`framesource.DEFAULT_DECODER`，两种解码器不混用）；
+    - 给了 `argv`（这一趟**要跑的** `run_ocr2` 命令行）时，**生效配置**对得上
+      （**跑的是同一段、同一条臂**——`--start` / `--end` 就在配置里）：用 `flowocr.extract.ocr_args` 那同一个解析器把 `argv` 解析出来，
+      和产物的 `_meta.config` 逐键比，`--out` / `--progress-every` 除外。
+      **缺键按 `ocr_args.ADDED_NOOP` 兜底**：后加的、默认空操作的旋钮不该让现成产物全部重建
+      （2026-09-18；进那张表的前提是"默认不开时产物逐字节相同"，见那段说明）。
+      比的是**解析后的值**，不是命令行字面——字面比不出"默认值翻了"：
+      `--rec-bucket` 一旦进默认，对照臂旧产物的 argv 一字不变，会被当成新默认复用
+      （2026-09-10 审查；旧版比的就是字面）。**没有 `config` 字段的产物一律重建**，
+      "没记"和"记的是别的"在后果上没区别。三个驱动（`sampleset.sh` / `run_full_ocr.sh` /
+      `run_gamestream_ocr.sh`）和 `ocr_ab.sh` 都传 `argv`。
+
+    **窗口只有这一种判法**（审查 2026-09-10）：原来另有一条"`start`/`end` 差 0.51 s 以内算同一窗口"
+    的容差判据，而给了 argv 时配置按值精确比 `start`/`end`，那条容差永远走不到——
+    同一件事两套判据，删掉了。驱动传给这里的和传给 run_ocr2 的是同一串参数，不需要容差。
+
+    timebase 那道门是 2026-09-10 补的。fps-and-rec-budget 报告 写的政策是
+    「**旧产物一律作废重跑**，不做兼容、不回填」，但这条政策**没有落到代码里**：
+    旧产物（`t_us = idx / src_fps`）的 `complete` 也是 true，于是
+    `sampleset.sh` 对 `out/samples/` 下那 6 份一份都不重跑，
+    代表性片段集会无限期停在旧时间轴上（f3 尾端差 5.1 s），**而且不报错**。
+    """
+    from flowocr.extract import ocr_args
+
+    # 先解析，再看文件：驱动拼错了参数，不管产物在不在都该当场炸
+    want_cfg = ocr_args.config_of(argv) if argv is not None else None
+    ok, why = obs_finished(path)
+    if not ok:
+        return False, why
+    meta = _read_meta(path)
+    if meta.get("timebase") != "pts":
+        return False, (f"时间轴不是 pts（产物记的是 {meta.get('timebase')!r}）"
+                       f"——旧口径 `idx / src_fps` 的产物一律重跑，回填补不回丢帧缺口")
+    # **解码器也要是当前默认那个**（owner 2026-09-10："不想有的用 cv2 有的用 ffmpeg"）。
+    # 两种解码器的产物不逐字节相同，不拦的话，默认一改，磁盘上旧默认产的那批仍然
+    # "已跑完"、被驱动脚本跳过——于是同一批里两种混着，而且不报错。和上面 timebase
+    # 那道门是同一个形状：写在文档里 ≠ 代码上拦得住。
+    from flowocr.extract import framesource
+
+    if meta.get("decoder") != framesource.DEFAULT_DECODER:
+        return False, (f"解码器是 {meta.get('decoder')!r}，当前默认是 "
+                       f"{framesource.DEFAULT_DECODER!r}——两种解码器的产物不混用")
+    if want_cfg is not None:
+        got = meta.get("config")
+        if got is None:
+            return False, "产物没有 config 字段（记不清是拿哪组生效参数跑的）"
+        if meta.get("region_crop_off") and got.get("region_crop") and want_cfg.get("region_crop") is False:
+            # 请求了 --region-crop、实际没裁（外接矩形就是全屏、或旧产物的 --no-fast-det；原因在 `_meta.region_crop_off`）：
+            # 产物和 --no-region-crop 跑的是同一条路，这次要的就是 --no-region-crop 时按实际比，不然回退臂会白重建一次。
+            # 这次仍按默认要裁时照记录比（同样的参数再跑一遍，照旧复用）。反过来（产物没裁、这次要裁）裁不裁得了要跑起来才知道，照旧重建
+            got = {**got, "region_crop": False}
+        diff = ocr_args.config_differs(got, want_cfg)
+        if diff:
+            return False, "参数对不上：" + "，".join(
+                f"{k} 产物 {got.get(k)!r} / 要的是 {want_cfg.get(k)!r}" for k in diff)
+        # **采样网格和辅助流网格按生效值比**（2026-09-24 时间网格）：两者都要结合素材的帧率才定得下来，
+        # 按产物自己的 `src_fps` 算要的网格。时间网格之前的产物只记整数步长：采样 `_meta.stride`；
+        # 辅助流 `_meta.aux_step_effective`（加 `--aux-max-fps` 之后）或 `config.refine_step`（更早，没封顶）
+        from flowocr.extract.framegrid import AuxGrid, TimeGrid
+
+        src = meta.get("src_fps") or 0.0
+        try:
+            want_s = ocr_args.sample_grid(src, want_cfg["fps"], want_cfg.get("frame_select", "pts"))
+            want_a = (ocr_args.aux_grid(src, want_cfg["fps"], want_cfg.get("aux_max_fps", ocr_args.AUX_MAX_FPS),
+                                        want_cfg.get("frame_select", "pts")) if want_cfg.get("refine_fused") else None)
+        except ValueError as exc:
+            return False, str(exc)
+        got_s = (TimeGrid(*meta["sample_grid"]) if meta.get("sample_grid")
+                 else TimeGrid.every(meta["stride"]) if meta.get("stride") else None)
+        if got_s != want_s:
+            return False, (f"采样网格对不上：产物 {got_s.describe(src) if got_s else '没记'} / "
+                           f"要的是 {want_s.describe(src)}（--fps）")
+        if want_a is not None:
+            got_a = (AuxGrid.from_list(meta["aux_grid"]) if meta.get("aux_grid")
+                     else AuxGrid(TimeGrid.every(meta.get("aux_step_effective", got.get("refine_step", 1))), got_s))
+            if got_a != want_a:
+                return False, (f"辅助流的生效网格对不上：产物 {got_a.describe(src)} / 要的是 {want_a.describe(src)}（--aux-max-fps）")
+    stale = seek_dropped_first(meta)
+    if stale:
+        return False, stale
+    # **代码指纹对不上时至少要吭一声**（2026-09-19 复审第 3 条）。
+    # `code_fp` **故意不进复用判据**——进了就等于"动一下 tools/ 就重跑所有整片"，代价和收益不成比例。
+    # 但"旋钮没变、代码变了"正是 09-06 / 09-10 那一族的形状：文件名和配置都没动，驱动静默复用旧产物。
+    # 这次就踩到了（固定滞后改完，沿用旧臂名会直接 [skip]）。所以：**判据不变，但把它喊出来**；
+    # 探索用的驱动可以 `FP_CHECK=1` 把它升级成"重建"。
+    fp_now, fp_got = ocr_args.code_fp(), meta.get("code_fp")
+    if fp_got and fp_got != fp_now:
+        msg = (f"⚠ 代码指纹不同（产物 {fp_got} / 现在 {fp_now}）：旋钮一样、**代码变了**。"
+               f"要重跑就换臂名，或者 FP_CHECK=1")
+        if os.environ.get("FP_CHECK") == "1":
+            return False, msg.replace("⚠ ", "").replace("要重跑就换臂名，或者 FP_CHECK=1",
+                                                        "FP_CHECK=1 要求重建")
+        return True, msg
+    return True, ""
+
+
+def seek_dropped_first(meta: dict) -> str:
+    """修之前的精确 seek 丢了窗口首格的产物（`framesource.SEEK_REV`）：返回作废的原因，不是就返回空串。
+
+    代码指纹故意不进复用判据（见 `obs_reusable` 末尾），所以一次改了"读哪一帧"的修复要自己认出受影响的旧产物，
+    否则沿用原臂名的驱动会一直复用坏的那份（2026-09-26 审计：`--fps 2.2` 的 yuka-f5 窗口）。认的是那个形状本身——
+    没有 `seek_rev`、窗口从片中起、记了缺格、首个采样点比起点晚了至少一个采样间隔；别的旧产物照旧复用。"""
+    if (meta.get("seek_rev") or 1) >= _seek_rev() or not (meta.get("start_sec") or 0) > 0:
+        return ""
+    fps, first = meta.get("sample_fps"), meta.get("pts_first_sec")
+    if not (meta.get("grid_skipped") or 0) > 0 or not fps or first is None:
+        return ""
+    late = first - meta["start_sec"]
+    if late < 1 / fps:
+        return ""
+    return (f"精确 seek 修之前的产物丢了窗口首格（首个采样点晚起点 {late:.3f} s ≥ 一个采样间隔、缺格 {meta['grid_skipped']}）"
+            f"——重跑（framesource.SEEK_REV）")
+
+
+def _seek_rev() -> int:
+    from flowocr.extract import framesource
+    return framesource.SEEK_REV
+
+
+def obs_finished(path) -> tuple[bool, str]:
+    """只问"写完了没有"——给**读**观测的下游用（`gametext_eval.sh`），不是给决定重不重跑的驱动用。
+
+    读的一侧不在乎时间轴口径和解码器（文本检索不看时间，老的 gamestream 观测也照读），
+    但**半截产物**照样要拦：整场 OCR 跑着的时候 `out/gamestream/<tag>.jsonl` 已经非空，
+    `[ -s ]` 会放它进去，量出来是"前二十分钟"的数、而且不报错（2026-09-11 起整场绝区零 /
+    星铁和评测同时在跑）。"""
+    try:
+        meta = _read_meta(path)
+    except Exception as exc:                       # 不在、空的、半行、没有 _meta
+        return False, f"读不到 _meta（{type(exc).__name__}）"
+    if not meta.get("complete"):
+        return False, "_meta.complete 不为真（还在跑，或者中途断了）"
+    return True, ""
+
+
+def _read_meta(path) -> dict:
+    import json
+
+    with open(path, encoding="utf-8") as fh:
+        return json.loads(fh.readline())["_meta"]
+
+
+def _main(argv: list[str] | None = None) -> int:
+    """`python -m flowocr.extract.ocr_complete <obs.jsonl> [--argv <run_ocr2 的参数…>]`。
+
+    能复用则退出码 0、不打印任何东西；不能则打印一行原因、退出码 1。
+    驱动脚本按退出码分支，**不要再自己解析 jsonl**。
+    """
+    import argparse
+
+    ap = argparse.ArgumentParser(
+        description="观测产物能不能复用（跑完了 + pts + 默认解码器 + 同一组生效参数，含窗口）")
+    ap.add_argument("obs")
+    ap.add_argument("--finished", action="store_true",
+                    help="只问写完了没有（读观测的下游用，见 obs_finished）；不能和 --argv 同给")
+    ap.add_argument("--argv", nargs=argparse.REMAINDER, default=None,
+                    help="这一趟要跑的 run_ocr2 argv，**必须放在最后**；"
+                         "给了就解析成生效配置，和产物 _meta.config 逐键比")
+    a = ap.parse_args(argv)
+    if a.finished and a.argv is not None:
+        ap.error("--finished 只问写完没有，给 --argv 说明你要的是复用判据")
+    ok, why = obs_finished(a.obs) if a.finished else obs_reusable(a.obs, a.argv)
+    if why:
+        print(why)                 # 能复用但有话说（代码指纹不同）时也打——驱动会把它跟在 [skip] 后面
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())

flowocr/extract/ocr_parallel.py

@@ -0,0 +1,208 @@
+"""`run_ocr2 --workers N` 里**不碰模型的那部分**：切段、给子进程改参数、把各段的 `_meta` 合成一份。
+
+放共享层是为了守卫够得着（audit-4 C8）。依据（fps-and-rec-budget 报告）：单进程时 GPU
+大半时间在等主线程的 CPU 活，N 个进程各跑一段能把空档填上——3 个 worker 在 quick 三段上 −26%~−47%。
+
+**切点对齐采样格**：切点帧号在采样网格上（`framegrid.TimeGrid`）。代价之一：每段开头没有"上一帧"，复用链从头开始、
+强制刷新换了相位——所以 `workers` 是**产物参数**（进 `_meta.config`），两种跑法的产物不混用。
+
+⚠ **有 pts 缺口 / 平均帧率偏离名义帧率的素材上不能开**（2026-09-10 审查）。子进程的起点是
+`切点帧号 / src_fps` 秒——和 `--start` 同一个"帧号 ÷ 平均帧率"的换算——而 `src_fps` 是容器的
+**平均**帧率。一段里若含丢帧缺口，它实际覆盖的时间比算出来的长，和下一段**重叠**（f3 实测 +4.65 s）；
+不含缺口时它比算出来的短，和下一段之间**漏一截**（f3 上按平均帧率推，每个切点可达数秒，没实测），
+而且 PTS 仍然递增、**段间递增判据拦不住**。所以两道门：
+父进程先按 `seam_drift_sec` 预估**整个文件**上的切点漂移，超过半个源帧就拒绝；
+拼的时候再逐个切点核首尾间隔（`seam_problems`），重叠和漏帧都判未完成。
+漂移**按整个文件**估、门限**半个源帧**（复审 2026-09-10）：按窗口长度估的话，f3 上 5 分钟窗口
+算出 0.109 s 会被放行，段与段之间静默差出好几个源帧——落在切点核对的容差里、拦不住。
+按整个文件估，有缺口的素材不论取哪段都拒；被放行的素材（f5 整片 0.001 s、游戏切片 0）
+切点漂移不到半帧，**采样帧和单进程逐帧相同**。
+`r_frame_rate` 当名义帧率在某些容器上可能是时基派生值、造成误拒；现有素材没撞上，报错里两个帧率都印着。
+根治要把窗口改成按 pts 定义（fps-and-rec-budget 报告第 1 条的待定项）。
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+
+from flowocr.extract import ocr_complete
+
+SUM_KEYS = ("frames_advanced", "frames_requested", "sampled_frames", "boxes", "rec_calls",
+            "rec_predict_calls", "reused_boxes", "dropped_dense", "dropped_tiny", "lost_rec", "grid_skipped")
+"""各段相加就是整体的计数。"""
+
+DICT_SUM_KEYS = ("reuse_v2", "reuse_v2_sec", "edge", "stage_sec", "rec_spec", "grid_off")
+"""各段里是"计数字典"的键，逐键相加进整体（数值型的键才加；bool 不算）。"""
+
+DICT_MAX_KEYS = frozenset({"cache_peak", "aux_shift"})
+"""这些键**不是计数，是峰值 / 偏移**：取各段的最大值，不然 `--reuse-cache-mb 8` 的三个 worker
+会被加成 21 MB（2026-09-17 审计时从产物里发现的口径错）。"""
+
+SEAM_TOL = 0.5
+"""切点处相邻两段首尾的间隔，允许偏离一个采样间隔多少（倍）。正常就是恰好一个采样间隔。"""
+
+DRIFT_MAX_FRAMES = 0.5
+"""整个文件上预估的切点漂移不许超过几个**源帧**。半帧以内，切点落在哪一帧和单进程一致。
+f5 整片 0.001 s（0.06 帧）、游戏切片 0；f3 12.1 s、f4 6.1 s。"""
+
+
+def split_frames(start_idx: int, end_idx: int, grid, n: int) -> list[int]:
+    """`[start_idx, end_idx)` 等分成 n 段，返回 n−1 个**内部切点帧号**（在采样网格 `grid` 上、严格递增；`start_idx` 在格上）。
+
+    段太短切不开时抛——那种窗口本来就不值得并行。
+    """
+    if n < 2:
+        return []
+    span = end_idx - start_idx
+    k0 = grid.index(start_idx)
+    cuts = [grid.at(k0 + round(span * k / n * grid.p / grid.q)) for k in range(1, n)]   # 等距时就是 start + round(…/步长) × 步长
+    pts = [start_idx, *cuts, end_idx]
+    if any(b <= a for a, b in zip(pts, pts[1:])):
+        raise ValueError(f"窗口太短，切不成 {n} 段：{pts}")
+    return cuts
+
+
+def strip_opts(argv: list[str], names: set[str]) -> list[str]:
+    """从 argv 里去掉这些**带值**的选项（`--x v` 和 `--x=v` 两种写法都认），其余原样保留。"""
+    out, skip = [], False
+    for tok in argv:
+        if skip:
+            skip = False
+            continue
+        name = tok.split("=", 1)[0]
+        if name in names:
+            skip = "=" not in tok
+            continue
+        out.append(tok)
+    return out
+
+
+def parse_rate(s: str) -> float | None:
+    """ffprobe 的 `60/1`、`60000/1001` → 浮点；`0/0`、`N/A`、空 → None。"""
+    try:
+        num, den = s.split("/") if "/" in s else (s, "1")
+        num, den = float(num), float(den)
+    except ValueError:
+        return None
+    return num / den if num > 0 and den > 0 else None
+
+
+def probe_rates(video: str) -> tuple[float | None, float | None]:
+    """`(名义帧率 r_frame_rate, 平均帧率 avg_frame_rate)`。探不到的给 None。"""
+    try:
+        out = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
+                              "stream=r_frame_rate,avg_frame_rate", "-of", "json", video],
+                             capture_output=True, text=True, timeout=60).stdout
+        st = json.loads(out)["streams"][0]
+    except Exception:
+        return None, None
+    return parse_rate(st.get("r_frame_rate", "")), parse_rate(st.get("avg_frame_rate", ""))
+
+
+def seam_drift_sec(span_frames: int, avg_fps: float, nominal_fps: float) -> float:
+    """按"帧号 ÷ 平均帧率"换算切点时，`span_frames` 帧上最多能漂出多少秒。
+    调用方传**整个文件**的帧数，门限才是素材的属性、不随窗口变。"""
+    return span_frames * abs(1.0 / avg_fps - 1.0 / nominal_fps)
+
+
+def seam_problems(metas: list[dict], interval: float, tol: float = SEAM_TOL) -> list[str]:
+    """逐个切点核：下一段的首帧 PTS − 上一段的末帧 PTS 应该恰好是一个采样间隔。
+    ≤ 0 是**重叠**，太大是**漏帧**——后者 PTS 仍递增，只有这里能拦。"""
+    out = []
+    for k in range(len(metas) - 1):
+        a, b = metas[k].get("pts_last_sec"), metas[k + 1].get("pts_first_sec")
+        if a is None or b is None:
+            out.append(f"切点 {k}：段首 / 段尾 PTS 缺失")
+            continue
+        d = b - a
+        if d <= 0:
+            out.append(f"切点 {k}：重叠 {-d:.3f} s（{a:.3f} → {b:.3f}）")
+        elif abs(d - interval) > tol * interval:
+            out.append(f"切点 {k}：间隔 {d:.3f} s，应为 {interval:.3f} s"
+                       + ("（漏帧）" if d > interval else ""))
+    return out
+
+
+CHILD_ARGS = ["--workers", "1", "--decode-shards", "0"]
+"""`--workers N` 的子进程**追加**的参数（排在父进程 argv 之后，同名的后者生效）。
+解码分片和多 worker 互斥（`ocr_args.resolve_split`），可子进程只看得见 `--workers 1`、会按默认再开几路——
+`--workers 3` 就成了 6~9 个解码上下文（2026-09-24 审计）。所以由父进程显式关掉；它们在 SCHEDULING 里，不改复用判据。"""
+
+
+def merge_metas(metas: list[dict], base: dict, *, wall: float, cuts_sec: list[float],
+                interval: float) -> dict:
+    """各段的 `_meta` → 整体的 `_meta`。`base` 是父进程按同一组参数建的那份（video / config / 模型…）。
+
+    **完成**按**整个窗口**判，和单进程同一把尺：
+    - 覆盖率：各段推进帧数之和 / 请求帧数之和过 `ocr_complete.is_complete`。
+      **不能要求每段各自过**——`end=0` 时容器多报的那 1% 帧数全压在最后一段上，
+      3 个 worker 时末段只有 97%，单进程是 99%（审查 2026-09-10）；
+    - **中间各段**必须各自完成（它们的请求帧数是切出来的，不含容器的虚报）；
+    - 没有坏 PTS，切点处首尾间隔恰好一个采样间隔（`seam_problems`）。
+    """
+    m = dict(base)
+    for k in SUM_KEYS:
+        m[k] = sum(x.get(k, 0) or 0 for x in metas)
+    for k in DICT_SUM_KEYS:                          # 各段的计数字典逐键相加（reuse_v2 / edge 的统计）
+        parts = [x[k] for x in metas if isinstance(x.get(k), dict)]
+        if parts:
+            def agg(kk: str, parts=parts):
+                vals = [d[kk] for d in parts if isinstance(d.get(kk), (int, float))]
+                # **峰值不能相加**（2026-09-17）：三个 worker 各自的 8 MB 上限被加成 21 MB，
+                # 看着像"上限没守住"，其实是口径错了。峰值取最大，其余相加
+                if kk in DICT_MAX_KEYS:
+                    return round(max(vals), 2) if any(isinstance(v, float) for v in vals) else max(vals)
+                return (round(sum(float(v) for v in vals), 2) if any(isinstance(v, float) for v in vals)
+                        else sum(int(v) for v in vals))
+            m[k] = {kk: agg(kk)
+                    for kk in dict.fromkeys(kk for d in parts for kk in d if isinstance(d.get(kk), (int, float)))}
+    # 实际用了几个 worker：退回单进程时 run_ocr2 自己写 1，并行跑完由这里写段数——
+    # 不写的话并行产物里这个键干脆没有，读的人分不出"三个 worker"和"旧产物"（2026-09-17）
+    m["workers_effective"] = len(metas)
+    splits = [x["proc_split"] for x in metas if "proc_split" in x]   # 拆进程的生效值（各段一样就记一份，不一样逐段列）
+    if splits:
+        m["proc_split"] = splits[0] if all(sp == splits[0] for sp in splits) else splits
+    # 硬解的生效值（2026-09-20 整体检查时补的）：父进程早早 `return run_parallel`、**不做**试解，
+    # 而这里又是从父进程那份 `base` 起步——不写的话各段 `hwaccel_effective` 全丢，
+    # 读的人分不出"真走了硬解"和"每段都退回了软解"（和上面 workers_effective 同一个形状）。
+    # 各段可能不一致（有前摇的 av1 只有**第一段**从文件开头起解，后面几段 seek 到非零位置都没事）
+    effs = [x.get("hwaccel_effective") for x in metas if "hwaccel_effective" in x]
+    if effs:
+        m["hwaccel_effective"] = (effs[0] if len(set(effs)) == 1
+                                  else "mixed:" + ",".join(e or "soft" for e in effs))
+    # 推理设备的生效值 / 用的模型文件同一个形状（2026-09-22 接手自查）：父进程不建模型、`base` 里没有，不抄就全丢。
+    # `--device auto` 由各段各自解析（各自试推理），可能不一致——不一致时逐段列出来
+    for key in ("device_resolved", "device_fallback", "device_effective", "models"):
+        vals = [x.get(key) for x in metas if key in x]
+        if vals:
+            m[key] = vals[0] if all(v == vals[0] for v in vals) else {"mixed": vals}
+    seams = seam_problems(metas, interval)
+    bad = next((x["bad_pts"] for x in metas if x.get("bad_pts")), None)
+    overlap = [s for s in seams if "重叠" in s]
+    if overlap and bad is None:
+        bad = "段间 PTS 不递增：" + "；".join(overlap)
+    complete = (all(x.get("complete") for x in metas[:-1])
+                and ocr_complete.is_complete(m["frames_advanced"], m["frames_requested"])
+                and bad is None and not seams)
+    firsts = [x.get("pts_first_sec") for x in metas]
+    lasts = [x.get("pts_last_sec") for x in metas]
+    m.update({
+        "complete": complete,
+        "stopped_early": any(x.get("stopped_early") for x in metas),
+        "bad_pts": bad,
+        "seam_problems": seams,
+        "reuse_rate": round(m["reused_boxes"] / max(1, m["boxes"]), 4),
+        "wall_sec": round(wall, 2),
+        "sec_per_frame": round(wall / max(m["sampled_frames"], 1), 3),
+        "start_sec": metas[0].get("start_sec"),
+        "seek_rev": metas[0].get("seek_rev"),
+        "end_sec": metas[-1].get("end_sec"),
+        "timebase": "pts",
+        "pts_first_sec": firsts[0],
+        "pts_last_sec": lasts[-1],
+        "cuts_sec": cuts_sec,
+        "part_wall_sec": [x.get("wall_sec") for x in metas],
+    })
+    span = (lasts[-1] - firsts[0]) if firsts[0] is not None and lasts[-1] is not None else 0.0
+    m["realtime_x"] = round(span / wall, 2) if wall else None
+    return m