flowocr 0.1.0__py3-none-any.whl

flowocr/extract/detpost.py

@@ -0,0 +1,215 @@
+"""det 的**模型配置**与 **DB 后处理**，不依赖 Paddle（2026-09-25）。
+
+为什么（decode-buffer 计划的审计余项"检测的模型配置、前后处理、执行后端解耦"）：det 推理换到 ORT 之后，管线进程原来仍要
+建一份完整的 Paddle det，只为借它两样东西——前处理参数（缩放上限、归一化系数）和后处理对象（`DBPostProcess`）。
+这里把那两样自己拿一份（2026-10 起运行时干脆没有 Paddle 了）：
+
+* `DetSpec`：一组前后处理参数。`from_yml` 从 ONNX 仓库自带的 `inference.yml` 读（PaddleX 就是从同一份 yml 建的，
+  缩放默认按模型名同 PaddleX 的 `_get_text_det_resize_defaults`）。读法照 PaddleX 的 `_build`：守卫拿冻结的 PaddleX 结果
+  （几种 yml 写法、全字段）做回归。
+* `DBPostProcess`：照抄 PaddleX `paddlex/inference/models/text_detection/processors.py` 的同名类（Apache-2.0，
+  `LICENSES/Apache-2.0.txt`），只保留管线用到的 `box_type=quad` + `score_mode=fast` + 不膨胀，算术逐行相同——
+  照抄时和 PaddleX 的原实现**逐字节相同**（随机概率图对拍；真帧上另有探针验过 det 的多边形逐个相同）；守卫现在对着
+  冻结的 PaddleX 输出（输入一起存着）做回归。
+
+这个模块只依赖 numpy / cv2 / pyclipper / pyyaml（都在 `pyproject.toml` 的主依赖里）。
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from pathlib import Path
+
+import cv2
+import numpy as np
+import pyclipper
+
+MAX_LIMIT_MODELS = frozenset({
+    "PP-OCRv5_server_det", "PP-OCRv5_mobile_det", "PP-OCRv4_server_det", "PP-OCRv4_mobile_det",
+    "PP-OCRv3_server_det", "PP-OCRv3_mobile_det", "PP-OCRv6_medium_det", "PP-OCRv6_small_det", "PP-OCRv6_tiny_det",
+})
+"""PaddleX 里缩放默认是"长边 ≤ 960"的那些模型（`predictor._TEXT_DET_MAX_LIMIT_MODELS`）；其余默认"短边 ≥ 736"。"""
+
+KNOWN_OPS = frozenset({"DecodeImage", "DetLabelEncode", "DetResizeForTest", "NormalizeImage", "ToCHWImage", "KeepKeys"})
+"""PaddleX det 的 `_FUNC_MAP` 认的前处理 op（`DetLabelEncode` / `KeepKeys` 在它那里是空操作）。"""
+
+
+def _parse_scale(v) -> float:
+    """`NormalizeImage.scale`：yml 里常写成字符串 `1./255.`。PaddleX 用 `eval`；这里只认数或 `a/b`，
+    按 `float(a) / float(b)` 算——和 `eval` 同一次浮点除法，结果逐位相同，不执行模型目录里的任意字符串。"""
+    if not isinstance(v, str):
+        return float(v)
+    a, sep, b = v.partition("/")
+    try:
+        return float(a) / float(b) if sep else float(a)
+    except ValueError:
+        raise ValueError(f"NormalizeImage.scale 只认数或 a/b：{v!r}") from None
+
+
+@dataclass(frozen=True)
+class DetSpec:
+    """det 的前后处理参数——`FastDet` 只认这一份，不认 predictor。"""
+
+    model_name: str
+    limit_side_len: int
+    limit_type: str
+    max_side_limit: int
+    img_mode: str
+    """`DecodeImage.img_mode`：BGR 就不换通道；RGB 才要 BGR->RGB。"""
+    alpha: tuple[float, float, float]
+    beta: tuple[float, float, float]
+    """归一化 `v * alpha[c] + beta[c]`（PaddleX `NormalizeImage`：alpha = scale / std、beta = −mean / std，Python 双精度）。"""
+    thresh: float
+    box_thresh: float
+    unclip_ratio: float
+    max_candidates: int
+
+    @classmethod
+    def from_yml(cls, path: str | Path) -> "DetSpec":
+        """从模型目录的 `inference.yml` 建（官方 ONNX 仓库自带；和 PaddleX 模型目录里的是同一份）。
+        **照 PaddleX `TextDetRunnerPredictor._build` 的读法**，包括它不看的键（守卫拿冻结的 PaddleX `_build` 结果对几种 yml 写法做回归）：
+        * 读图默认 RGB，`DecodeImage` 在才按它的 `img_mode`；
+        * `DetResizeForTest` 里的 `limit_side_len` / `limit_type` / `max_side_limit` PaddleX 都不看（前两个被 `build_resize` 的具名参数吃掉、
+          换成按模型名的默认；最后一个调用时被 predictor 的 4000 盖掉），只有 `resize_long` 改默认边长；`image_shape` 是另一种缩放，快路径没写；
+        * `NormalizeImage` 的 `order` 缺省是 `""`（按 hwc 走），只有 `chw` 快路径没写；
+        * 认不得的前处理 op PaddleX 会 KeyError，这里同样拒绝。"""
+        import yaml
+        cfg = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+        name = cfg["Global"]["model_name"]
+        ops: dict[str, dict] = {}
+        for op in cfg["PreProcess"]["transform_ops"]:
+            key = list(op)[0]
+            if key not in KNOWN_OPS:
+                raise ValueError(f"{path}：前处理 op {key} PaddleX 的 det 不认")
+            ops[key] = op[key] or {}
+        if "NormalizeImage" not in ops or "DetResizeForTest" not in ops:
+            raise ValueError(f"{path}：不是 DB det 的前处理（要 DetResizeForTest + NormalizeImage）")
+        norm = ops["NormalizeImage"]
+        if norm.get("order", "") == "chw":
+            raise ValueError("这个模型的 Normalize 是 chw 序，快路径只写了 hwc 序")
+        scale = _parse_scale(norm.get("scale", 1 / 255))
+        mean = norm.get("mean") or [0.485, 0.456, 0.406]
+        std = norm.get("std") or [0.229, 0.224, 0.225]
+        rz = ops["DetResizeForTest"]
+        if "image_shape" in rz:
+            raise ValueError(f"{path}：DetResizeForTest 给了 image_shape（定形缩放），快路径只写了按边长缩放")
+        side = rz.get("resize_long", 960 if name in MAX_LIMIT_MODELS else 736)
+        kind = "max" if name in MAX_LIMIT_MODELS else "min"
+        if "DecodeImage" in ops:
+            if "img_mode" not in ops["DecodeImage"]:
+                raise ValueError(f"{path}：DecodeImage 没写 img_mode（PaddleX 在这里直接报错）")
+            img_mode = str(ops["DecodeImage"]["img_mode"])
+        else:
+            img_mode = "RGB"
+        post = cfg["PostProcess"]
+        if post.get("name") != "DBPostProcess":
+            raise ValueError(f"{path}：后处理是 {post.get('name')}，只支持 DBPostProcess")
+        if post.get("box_type", "quad") != "quad" or post.get("score_mode", "fast") != "fast" or post.get("use_dilation", False):
+            raise ValueError(f"{path}：只支持 box_type=quad、score_mode=fast、不膨胀的 DBPostProcess")
+        return cls(model_name=name, limit_side_len=int(side), limit_type=kind, max_side_limit=4000, img_mode=img_mode,
+                   alpha=tuple(scale / std[i] for i in range(3)), beta=tuple(-mean[i] / std[i] for i in range(3)),
+                   thresh=float(post.get("thresh", 0.3)), box_thresh=float(post.get("box_thresh", 0.6)),
+                   unclip_ratio=float(post.get("unclip_ratio", 2.0)), max_candidates=int(post.get("max_candidates", 1000)))
+
+
+class DBPostProcess:
+    """DB 的后处理（概率图 -> 四点框 + 分数），照抄 PaddleX 的 `DBPostProcess`（quad / fast / 不膨胀那条路）。
+
+    调用形状和 PaddleX 一样：`post(preds, img_shapes, thresh=…, box_thresh=…, unclip_ratio=…)`，
+    `preds[0]` 是 `[N, 1, H, W]` 的概率图，`img_shapes[i] = (src_h, src_w, ratio_h, ratio_w)`；
+    返回 `(boxes 列表, scores 列表)`，每帧的 boxes 是 `int16` 的 `[k, 4, 2]`。
+    ⚠ 算术**一处都别"顺手改"**：`round` 是 Python 的银行家舍入、`box_score_fast` 的 floor / ceil 夹在 `w-1` 上、
+    `min_size` 的两道门一道 `< 3` 一道 `< 5`——每一处都决定框的像素坐标。
+    """
+
+    MIN_SIZE = 3
+
+    def __init__(self, spec: DetSpec) -> None:
+        self.thresh, self.box_thresh, self.unclip_ratio = spec.thresh, spec.box_thresh, spec.unclip_ratio
+        self.max_candidates = spec.max_candidates
+
+    def __call__(self, preds, img_shapes, thresh: float | None = None, box_thresh: float | None = None,
+                 unclip_ratio: float | None = None):
+        boxes, scores = [], []
+        for pred, img_shape in zip(preds[0], img_shapes):
+            b, s = self.process(pred, img_shape, thresh or self.thresh, box_thresh or self.box_thresh,
+                                unclip_ratio or self.unclip_ratio)
+            boxes.append(b)
+            scores.append(s)
+        return boxes, scores
+
+    def process(self, pred, img_shape, thresh: float, box_thresh: float, unclip_ratio: float):
+        pred = pred[0, :, :]
+        src_h, src_w, _ratio_h, _ratio_w = img_shape
+        return self.boxes_from_bitmap(pred, pred > thresh, src_w, src_h, box_thresh, unclip_ratio)
+
+    def boxes_from_bitmap(self, pred, bitmap, dest_width, dest_height, box_thresh: float, unclip_ratio: float):
+        height, width = bitmap.shape
+        width_scale = dest_width / width
+        height_scale = dest_height / height
+        # PaddleX 写的是 `(bitmap * 255).astype(np.uint8)`——bool 先升成 int64 再转回，一帧两次 50 万元素的临时数组。
+        # `findContours` 只看非零，bool 的 0 / 1 按字节看就是 uint8 的 0 / 1，轮廓逐点相同（随机图 + 真帧 120 帧对拍过）
+        contours, _ = cv2.findContours(bitmap.view(np.uint8), cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
+        boxes, scores = [], []
+        for index in range(min(len(contours), self.max_candidates)):
+            contour = contours[index]
+            points, sside = self.get_mini_boxes(contour)
+            if sside < self.MIN_SIZE:
+                continue
+            points = np.array(points)
+            score = self.box_score_fast(pred, points.reshape(-1, 2))
+            if box_thresh > score:
+                continue
+            box = self.unclip(points, unclip_ratio).reshape(-1, 1, 2)
+            box, sside = self.get_mini_boxes(box)
+            if sside < self.MIN_SIZE + 2:
+                continue
+            box = np.array(box)
+            for i in range(box.shape[0]):
+                box[i, 0] = max(0, min(round(box[i, 0] * width_scale), dest_width))
+                box[i, 1] = max(0, min(round(box[i, 1] * height_scale), dest_height))
+            boxes.append(box.astype(np.int16))
+            scores.append(score)
+        return np.array(boxes, dtype=np.int16), scores
+
+    @staticmethod
+    def unclip(box, unclip_ratio: float):
+        area = cv2.contourArea(box)
+        length = cv2.arcLength(box, True)
+        distance = area * unclip_ratio / length
+        offset = pyclipper.PyclipperOffset()
+        offset.AddPath(box, pyclipper.JT_ROUND, pyclipper.ET_CLOSEDPOLYGON)
+        try:
+            expanded = np.array(offset.Execute(distance))
+        except ValueError:
+            expanded = np.array(offset.Execute(distance)[0])
+        return expanded
+
+    @staticmethod
+    def get_mini_boxes(contour):
+        bounding_box = cv2.minAreaRect(contour)
+        points = sorted(list(cv2.boxPoints(bounding_box)), key=lambda x: x[0])
+        if points[1][1] > points[0][1]:
+            index_1, index_4 = 0, 1
+        else:
+            index_1, index_4 = 1, 0
+        if points[3][1] > points[2][1]:
+            index_2, index_3 = 2, 3
+        else:
+            index_2, index_3 = 3, 2
+        box = [points[index_1], points[index_2], points[index_3], points[index_4]]
+        return box, min(bounding_box[1])
+
+    @staticmethod
+    def box_score_fast(bitmap, _box):
+        h, w = bitmap.shape[:2]
+        box = _box.copy()
+        xmin = max(0, min(math.floor(box[:, 0].min()), w - 1))
+        xmax = max(0, min(math.ceil(box[:, 0].max()), w - 1))
+        ymin = max(0, min(math.floor(box[:, 1].min()), h - 1))
+        ymax = max(0, min(math.ceil(box[:, 1].max()), h - 1))
+        mask = np.zeros((ymax - ymin + 1, xmax - xmin + 1), dtype=np.uint8)
+        box[:, 0] = box[:, 0] - xmin
+        box[:, 1] = box[:, 1] - ymin
+        cv2.fillPoly(mask, box.reshape(1, -1, 2).astype(np.int32), 1)
+        return cv2.mean(bitmap[ymin: ymax + 1, xmin: xmax + 1], mask)[0]

flowocr/extract/edge_proc.py

@@ -0,0 +1,314 @@
+"""在线回抠放进**自己的进程**：辅助流接收（`framesource.AuxReader`）+ 辅助帧环（`FrameRing`）+ `EdgeRefiner`（`--edge-proc`）。
+
+为什么（decode-buffer 的 S2 第一刀）：同进程时回抠工作线程是 UI 密的素材上的瓶颈，而且是**被 GIL 饿着**的瓶颈——
+wuwa-s2 上它忙 24.9 s、自己的 CPU 只有 11.5 s；环放大只把等待从"det 等帧"挪到"落盘等回抠"。它和辅助流收帧都是碰像素的活，
+挪出去之后管线进程里少两个抢 GIL 的线程，它自己也有一把整的 GIL。
+
+**算法一行不动**：`EdgeRefiner` 原样跑在这边，只把它和管线进程之间的三样东西换成消息：
+
+* 链事件（`sample`）：行对象换成**行号**（管线进程里 `id(row)`，那边握着行、行活着号就不会被复用）；
+* 证据（`_settle` / `_end` 写 `row["edge"]["on" / "off"]`）：这边的行是 `RowRef` 替身，写进去就发 `("ev", 行号, 键, 证据)` 回去，
+  管线进程的收信线程挂到真的行上；
+* 进度（`done_seq`）：`EdgeRefiner.on_done` 每批发 `("done", 批号)`。**证据先于进度发出、同一条连接按序到达**，
+  所以管线进程看到"第 k 批做完"时，第 k 批及以前的证据都已经挂上了——延迟落盘（`wait_batch(settled_by)`）的规矩不用改。
+
+辅助流：ffmpeg 的第二路输出直接 connect 到**这边** listen 的端口（像素不经过管线进程）；它的 pts 在 ffmpeg 的 stderr 里，
+只能由管线进程读，所以逐行转发过来（每秒 60 条小消息）。⚠ **别攒批转发**：这边收一帧要先拿到它的 pts，攒着不发的话，
+这边不读 TCP -> ffmpeg 写不出 -> 不再吐 stderr 行 -> 批永远攒不满，互等。
+
+进程生命周期走 `childproc`（起子进程、口令、限时等连接、收尾，和只解码进程共用一份）。连接一断（管线进程死了）这边就退出。
+"""
+from __future__ import annotations
+
+import sys
+import threading
+import time
+import traceback
+from queue import Queue
+
+class _Slot:
+    """`row["edge"]` 的替身：往里写证据就是发回管线进程。"""
+    __slots__ = ("rid", "send")
+
+    def __init__(self, rid: int, send) -> None:
+        self.rid, self.send = rid, send
+
+    def __setitem__(self, key: str, rec: dict) -> None:
+        self.send(("ev", self.rid, key, rec))
+
+
+class RowRef:
+    """管线进程里一行的替身。`EdgeRefiner` 对行只做 `row.setdefault("edge", {})[键] = 证据` 这一件事（守卫核这一点）。"""
+    __slots__ = ("rid", "_slot")
+
+    def __init__(self, rid: int, send) -> None:
+        self.rid, self._slot = rid, _Slot(rid, send)
+
+    def setdefault(self, key: str, default=None):
+        if key != "edge":
+            raise KeyError(f"回抠只该往行里写 edge，碰了 {key!r}")
+        return self._slot
+
+
+def serve() -> int:
+    from flowocr.extract import childproc, edge_refine, framesource
+    from flowocr.extract import timeline as tl
+
+    conn, send = childproc.connect()
+    tl.start_from_env("edge")                        # --timeline：这个进程写 `<路径>.edge.jsonl`
+    try:
+        cfg = conn.recv()
+    except (EOFError, OSError):
+        return 0
+    if isinstance(cfg, tuple):                        # ("x",)：管线进程起不来 / 不用了（同 decode_proc）
+        return 0
+    edge = edge_refine.EdgeRefiner(**cfg["edge"])
+    if cfg.get("regions"):
+        from flowocr.extract import regions
+        g = regions.from_spec(cfg["regions"], cfg["W"], cfg["H"])
+        if not g.unrestricted:
+            edge.ring.premask = regions.aux_masker(g, edge.Ws, edge.Hs, cfg["src_fps"])
+    pts_q: Queue = Queue()
+    aux = framesource.AuxReader(start_idx=cfg["start_idx"], n_frames=cfg["aux_n"], step=edge.grid.step,
+                                width=edge.Ws, height=edge.Hs, sink=edge.ring, pts_q=pts_q,
+                                src_fps=cfg["src_fps"]).start()
+    edge.on_done = lambda seq: send(("done", seq))
+    edge.on_error = lambda exc: send(("err", "".join(traceback.format_exception(exc))))   # 带 traceback：回抠进程里的错管线进程那边要看得见在哪
+    # **pts 的第二个入口**（`--decode-shards`）：ffmpeg 跑在解码进程里时，stderr 也在那边读——让它直接连过来送 pts，
+    # 不绕管线进程转一道。消息同主连接的 "p" / "pe"
+    from multiprocessing.connection import Listener
+    import secrets
+    feed_key = secrets.token_bytes(16)
+    feed = Listener(("127.0.0.1", 0), authkey=feed_key)
+
+    def feeder() -> None:
+        try:
+            c = feed.accept()
+            while True:
+                m = c.recv()
+                if m[0] == "p":
+                    pts_q.put(m[1])
+                else:
+                    pts_q.put(framesource.QUEUE_SENTINEL)
+                    return
+        except (EOFError, OSError):
+            pts_q.put(framesource.QUEUE_SENTINEL)     # 解码进程没了：辅助流就此停（AuxReader 记 stopped_early）
+
+    threading.Thread(target=feeder, daemon=True, name="pts-feed").start()
+    send(("hello", {"url": aux.url, "Ws": edge.Ws, "Hs": edge.Hs, "cap": edge.ring.cap,
+                    "pts_addr": [feed.address[1], feed_key.hex()]}))
+    refs: dict[int, RowRef] = {}
+
+    def ref(rid: int) -> RowRef:
+        r = refs.get(rid)
+        if r is None:
+            r = refs[rid] = RowRef(rid, send)
+        return r
+
+    try:
+        while True:
+            try:
+                msg = conn.recv()
+            except (EOFError, OSError):
+                edge.abort()                     # 管线进程没了：不留孤儿
+                return 1
+            tag = msg[0]
+            if tag == "p":
+                pts_q.put(msg[1])
+            elif tag == "pe":
+                pts_q.put(framesource.QUEUE_SENTINEL)
+            elif tag == "s":
+                _, seq, idx, t_us, items, ended, stale, live = msg
+                edge.sample(seq, idx, t_us, [(k, ref(rid), box, text, kind) for k, rid, box, text, kind in items],
+                            [(k, ref(rid), box, text, li) for k, rid, box, text, li in ended], set(stale))
+                if live is not None:             # 替身表跟着管线进程那边的行号表剪（它隔一阵发来仍可能被写的行号）
+                    keep = set(live)
+                    for rid in [r for r in refs if r not in keep]:
+                        del refs[rid]
+            elif tag == "f":
+                stats = edge.finish(msg[1])
+                aux.join()
+                stats.update({"aux_sent": aux.sent, "aux_stopped_early": aux.stopped_early, "aux_last_key": aux.last_key,
+                              "aux_cpu_sec": round(aux.cpu_sec, 2), "aux_shift": 0,
+                              "ring_cap": edge.ring.cap, "proc": True})
+                if aux.misaligned:
+                    stats["aux_misaligned"] = aux.misaligned
+                tl.dump()                                # 在回 fin 之前：B 收到就收摊了
+                send(("fin", stats))
+                return 0
+            elif tag == "x":
+                edge.abort()
+                return 0
+    finally:
+        try:
+            conn.close()
+        except OSError:
+            pass
+
+
+class EdgeProxy:
+    """管线进程这边：和 `EdgeRefiner` 同一组接口（`sample` / `settled_by` / `wait_batch` / `finish` / `abort`），活在另一个进程里。"""
+
+    STALL_SEC = 60.0
+    """回抠进程多久没前进算卡住：**看进度、不看总等待**，和解码分片（`decode_shards` 的 `STALL_SEC`）同一个判据。
+    它落后管线很多批时一直在做（CPU 上、或收尾时积压一大截），等得再久也不算卡；做完的批号这么久不动才算。
+    原来是"这一批总共等了 300 s"，积压够长的正常收尾也会被判卡住，真卡住又要白等 5 分钟。"""
+
+    def __init__(self, *, edge_kwargs: dict, start_idx: int, end_idx: int, src_fps: float, width: int, height: int,
+                 regions_spec: dict | None = None, start_timeout: float = 120.0, stall_sec: float = STALL_SEC) -> None:
+        from types import SimpleNamespace
+
+        from flowocr.extract import childproc
+
+        self.child = childproc.Child("flowocr.extract.edge_proc", "回抠进程", timeout=start_timeout)
+        self.proc = self.child.proc
+        self.conn = self.child.conn                      # 限时等它连上（连不上就杀掉、抛）
+        from flowocr.extract.framegrid import AuxGrid
+
+        self.conn.send({"edge": edge_kwargs, "start_idx": start_idx, "src_fps": src_fps, "W": width, "H": height,
+                        "regions": regions_spec, "aux_n": AuxGrid.from_list(edge_kwargs["grid"]).n_frames(start_idx, end_idx)})
+        hello = self.conn.recv()
+        if hello[0] != "hello":
+            raise RuntimeError(f"回抠进程握手失败：{hello!r}")
+        h = hello[1]
+        self.url, self.Ws, self.Hs = h["url"], h["Ws"], h["Hs"]
+        self.pts_addr = h["pts_addr"]
+        """`[端口, 口令 hex]`：只解码进程（`--decode-shards`）直接把辅路 pts 送到这里（不经过管线进程）。"""
+        self.ring = SimpleNamespace(cap=h["cap"])
+        self.noop = bool(edge_kwargs.get("noop"))
+        self.stall_sec = stall_sec
+        self.rows: dict[int, tuple[dict, int]] = {}     # 行号 -> (行, 最近一次发出去时的批号)
+        self.done_seq = -1
+        self.cv = threading.Condition()
+        self.error: str | None = None
+        self.stats: dict | None = None
+        self.wait_sec = 0.0
+        self.last_seq = -1
+        self.th = threading.Thread(target=self._recv, daemon=True, name="edge-proxy")
+        self.th.start()
+
+    # ---------- 发 ----------
+    def _send(self, msg) -> None:
+        self.child.send(msg)
+
+    def pts_put(self, item) -> None:
+        """ffmpeg stderr 的辅路 pts（`framesource.FfmpegSource` 的 drain 线程逐行调）。"""
+        from flowocr.extract.framesource import QUEUE_SENTINEL
+        try:
+            self._send(("pe",) if item is QUEUE_SENTINEL else ("p", item))
+        except OSError:
+            pass                                          # 那边已经退了：错误在 wait_batch / finish 里报
+
+    def sample(self, seq: int, idx: int, t_us: int, items: list[tuple], ended: list[tuple],
+               stale: set[int] | tuple = ()) -> None:
+        its, ens = [], []
+        for k, row, box, text, kind in items:
+            self.rows[id(row)] = (row, seq)
+            its.append((k, id(row), list(box), text, kind))
+        for k, row, box, text, li in ended:
+            if row is None:
+                continue
+            self.rows[id(row)] = (row, seq)
+            ens.append((k, id(row), list(box), text, li))
+        self.last_seq = seq
+        live = None
+        if seq % 64 == 0:
+            # 行号表剪枝：证据最晚落在开段那一行上（段在 MAX_OPEN_SAMPLES 批内停变或放弃），再老的行不会再被写。
+            # 按**那边已经做完的批号**剪（它可能落后这边若干批），不按这边刚发的批号
+            from flowocr.extract.edge_refine import MAX_OPEN_SAMPLES
+            floor = self.done_seq - MAX_OPEN_SAMPLES - 16
+            for rid in [r for r, (_, s) in self.rows.items() if s < floor]:
+                del self.rows[rid]
+            live = list(self.rows)
+        self._send(("s", seq, idx, t_us, its, ens, list(stale), live))
+
+    # ---------- 收 ----------
+    def _recv(self) -> None:
+        try:
+            while True:
+                msg = self.conn.recv()
+                tag = msg[0]
+                if tag == "ev":
+                    _, rid, key, rec = msg
+                    hit = self.rows.get(rid)
+                    if hit is None:
+                        self.error = f"回抠进程发来的证据落在一行已经剪掉的行上（行号 {rid}、{key}）"
+                    else:
+                        hit[0].setdefault("edge", {})[key] = rec
+                elif tag == "done":
+                    with self.cv:
+                        self.done_seq = msg[1]
+                        self.cv.notify_all()
+                elif tag == "err":
+                    self.error = f"回抠进程出错：{msg[1]}"
+                elif tag == "fin":
+                    self.stats = msg[1]
+                if tag in ("err", "fin"):
+                    with self.cv:
+                        self.cv.notify_all()
+                    if tag == "fin":
+                        return
+        except (EOFError, OSError) as exc:
+            if self.stats is None and self.error is None:
+                self.error = f"回抠进程断开：{exc!r}（退出码 {self.proc.poll()}）"
+        finally:
+            with self.cv:
+                self.cv.notify_all()
+
+    def _check(self) -> None:
+        if self.error is not None:
+            raise RuntimeError(self.error)
+
+    # ---------- 和 EdgeRefiner 同名的几个 ----------
+    @staticmethod
+    def settled_by(seq: int) -> int:
+        from flowocr.extract.edge_refine import MAX_OPEN_SAMPLES
+        return seq + MAX_OPEN_SAMPLES + 1
+
+    def _wait(self, done, what: str) -> None:
+        """等到 `done()`；做完的批号 `stall_sec` 秒没动就记成出错（见 `STALL_SEC`）。出错 / 断开时 `_recv` 会叫醒这里。"""
+        last, t_last = self.done_seq, time.perf_counter()
+        with self.cv:
+            while not done() and self.error is None:
+                self.cv.wait(0.5)
+                now = time.perf_counter()
+                if self.done_seq != last:
+                    last, t_last = self.done_seq, now
+                elif now - t_last > self.stall_sec:
+                    self.error = f"{what}：回抠进程 {self.stall_sec:.0f} s 没前进（停在第 {self.done_seq} 批）"
+
+    def wait_batch(self, seq: int) -> None:
+        t0 = time.perf_counter()
+        self._wait(lambda: self.done_seq >= seq or self.stats is not None, f"等回抠进程做完第 {seq} 批")
+        from flowocr.extract import timeline as tl
+        self.wait_sec += tl.span("wait_batch", t0, a=seq) - t0
+        self._check()
+
+    FINISH_SEC = 300.0
+    """批号追到头之后回抠进程还要算结尾窗、汇总统计——这段**没有进度信号**，按 `STALL_SEC` 判会误伤（CPU 上尤其），给固定宽限（原来的 300 s）。"""
+
+    def finish(self, last_idx: int) -> dict:
+        self._send(("f", last_idx))
+        # 两段：先按进度等积压的批做完（和 wait_batch 同一个判据），再给收尾一段固定宽限
+        self._wait(lambda: self.done_seq >= self.last_seq or self.stats is not None or not self.th.is_alive(),
+                   "等回抠进程做完积压的批")
+        if self.error is None:
+            self.th.join(self.FINISH_SEC)
+            if self.th.is_alive() and self.stats is None:
+                self.error = f"回抠进程收尾（结尾窗 / 汇总）超过 {self.FINISH_SEC:.0f} s"
+        if self.error is not None or self.stats is None:
+            self.child.close(wait=10)                     # 出错也收掉子进程，不留给监督者按进程树收
+        self._check()
+        if self.stats is None:
+            raise RuntimeError("回抠进程没交回统计就断了")
+        self.child.close(wait=30)                         # 它发完 fin 就自己退了：告别发不出去也无妨，限时等、不退就杀
+        st = dict(self.stats)
+        st["wait_batch_sec"] = round(self.wait_sec, 2)    # 管线进程这边等它的时间（那边的 wait_batch 从来没人调）
+        return st
+
+    def abort(self) -> None:
+        self.child.close(wait=10)
+
+
+if __name__ == "__main__":
+    sys.exit(serve())