flowocr 0.1.0__py3-none-any.whl

flowocr/analyze/gtdbundle.py

@@ -0,0 +1,306 @@
+"""游戏文本包（`gtd-bundle/1`）：找包、校验、读表。
+
+包由 game-text-data 项目 `uv run gametext <游戏> bundle` 出（协议在那边 `docs/architecture.md` 的"产物包协议"一节），一款游戏一个：
+`<game>-<version>-<指纹前 12 位>.zip`，里面 `<game>/manifest.json` + 数据文件 + `report.json` + `NOTICE.txt`。
+不公开分发，用户私下拿到后放进 `paths.gametext_root()`（默认数据根的 `gametext/`）即可，**不用解压**；解压了也认。
+
+- **找**：`--gametext` / `FLOWOCR_GAMETEXT` / 默认位置可以是一个 `.zip`、一个带 `manifest.json` 的目录（开发机直接指
+  `../game-text-data/corpus/<游戏>`），或一个装着若干包的目录（按清单的 `game` 挑；解压出的目录往下找两层，见 `candidates`）。
+  同一款游戏找到指纹不同的多份就报错列出来，不按版本号猜；指纹相同的几份是同一份语料，用排在前面的那份。
+  没有清单的目录不认——不留旧格式的读法。
+- **校验**：清单 `schema` 要认得、要有调用方要的表和语种（`ja` / `zh-Hans`）、指纹按清单重算要对上；
+  调用方要的每张表还要带调用方认得的**内容契约主版本**（清单 `tables.<表>.contract`，形如 `genshin.reminders/1`，
+  字段的类型、能否为 null、取值写在 game-text-data 那边的契约声明里）：缺 `contract` 是加契约之前打的旧包，
+  主版本不同是字段含义变了，都拒绝；每个读到的文件
+  边读边算存储字节的 `sha256` 与解压后的 `content_sha256`，读完和清单比。缓存命中不读数据时用 `verify_stored`
+  只核存储字节（每款几十 MB）。哈希防的是拷坏和版本对不上，不是安全机制。
+- **身份**：下游只认 `fingerprint`（按内容算，换压缩、改文件名都不变）。`provenance()` 是剧本里记的那一份。
+  清单的 `rev` 是 game-text-data 发布时记进指纹表的提取行为版本（整数；本地包是 `<rev>+<指纹前 8 位>`），
+  只抄下来给人看——核"是不是维护者发出的那份"是拿指纹去对那边公开的指纹表，这里不联网、不校验它。
+  命令行（`main`）打印指纹之前先 `verify` 全部文件的两种哈希，否则内容被换过的包也能打印出一个对得上表的指纹。
+"""
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import sys
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from flowocr import paths
+
+SCHEMA = "gtd-bundle/1"
+MANIFEST = "manifest.json"
+CHUNK = 1 << 20
+
+
+class BundleError(SystemExit):
+    """找不到包、包坏了、和清单对不上。继承 SystemExit：CLI 直接带着这句话退出，守卫里照样能 catch。"""
+
+
+def fingerprint_of(files: list[dict]) -> str:
+    """协议里的指纹：按 `(table, lang)` 排序的 `table\\tlang\\tcontent_sha256\\n` 串接的 sha256，只算数据表。"""
+    items = sorted((f["table"], f["lang"], f["content_sha256"]) for f in files if "table" in f)
+    return "sha256:" + hashlib.sha256("".join("%s\t%s\t%s\n" % it for it in items).encode("utf-8")).hexdigest()
+
+
+class _Tee:
+    """读的同时喂哈希（给 zstd 的 stream_reader 当源）。"""
+
+    def __init__(self, f, h):
+        self.f, self.h = f, h
+
+    def read(self, n: int = -1) -> bytes:
+        b = self.f.read(n)
+        self.h.update(b)
+        return b
+
+
+@dataclass
+class Bundle:
+    source: Path          # .zip 或目录
+    manifest: dict
+    prefix: str = ""      # zip 里的成员前缀（`<game>/`）；目录形态为空
+
+    @property
+    def game(self) -> str:
+        return self.manifest["game"]
+
+    @property
+    def fingerprint(self) -> str:
+        return self.manifest["fingerprint"]
+
+    def provenance(self) -> dict:
+        """剧本 provenance 里的 `gametext`。`source` 只记文件 / 目录名，不记绝对路径（产物会被分享）。"""
+        m = self.manifest
+        up = m.get("upstream") or {}
+        return {"game": m["game"], "fingerprint": m["fingerprint"], "rev": m.get("rev"), "version": up.get("version"),
+                "upstream": {k: up.get(k) for k in ("repo", "commit", "version")},
+                "extractor": m.get("extractor") or {},
+                "integrity_checked": bool(up.get("integrity_checked")),
+                "source": self.source.name}
+
+    def _files(self) -> dict[tuple[str, str], dict]:
+        return {(f["table"], f["lang"]): f for f in self.manifest["files"] if "table" in f}
+
+    def _open(self, rel: str):
+        if self.source.suffix.lower() == ".zip":
+            zf = zipfile.ZipFile(self.source)
+            try:
+                raw = zf.open(self.prefix + rel)
+            except KeyError:
+                zf.close()
+                raise BundleError(f"文本包 {self.source.name} 里缺 {self.prefix + rel}（清单里有）")
+            return _Closing(raw, zf)
+        p = self.source / rel
+        if not p.is_file():
+            raise BundleError(f"文本包 {self.source} 里缺 {rel}（清单里有）")
+        return open(p, "rb")
+
+    def has(self, tables, langs=("ja", "zh-Hans")) -> bool:
+        """可选的表：这几张表 × 语种都在清单里就 True（旧包没有的表调用方自己跳过，不报错）。"""
+        have = self._files()
+        return all((t, lang) in have for t in tables for lang in langs)
+
+    def require(self, tables: dict[str, int], langs=("ja", "zh-Hans")) -> None:
+        """调用方要的表（{表: 认得的契约主版本}）× 语种都得在清单里，每张表的契约主版本要对上——
+        缺了就报缺什么（`--langs chs` 收窄跑出的包会缺日文），版本不对就报是哪张表、包里是几、这里要几。"""
+        have = self._files()
+        miss = [f"{t}×{lang}" for t in tables for lang in langs if (t, lang) not in have]
+        if miss:
+            raise BundleError(f"文本包 {self.source.name}（{self.game}）缺 {', '.join(miss)}："
+                              f"清单里的语种是 {sorted(self.manifest.get('langs') or {})}")
+        for t, major in tables.items():
+            label = ((self.manifest.get("tables") or {}).get(t) or {}).get("contract")
+            if label is None:
+                raise BundleError(f"文本包 {self.source.name}（{self.game}）的 {t} 没有内容契约版本：这是加契约之前打的包，"
+                                  f"game-text-data 那边用新代码重新 bundle")
+            if label != f"{self.game}.{t}/{major}":
+                raise BundleError(f"文本包 {self.source.name} 的 {t} 是契约 {label}，这里只认 {self.game}.{t}/{major}："
+                                  f"字段含义变了，flowocr 要先跟上（看 game-text-data 的 CHANGELOG）")
+
+    def _chunks(self, f: dict):
+        """逐块给出清单里这个文件解压后的字节，边读边算两种哈希；**读完**和清单比，对不上就报错
+        （读到一半就停的调用方不做这次核对）。解压 / zip 的 CRC 出错都算"包坏了"，不让用户看底层栈。"""
+        import zstandard
+        raw_h, con_h = hashlib.sha256(), hashlib.sha256()
+        zst = f["path"].endswith(".zst")
+        try:
+            with self._open(f["path"]) as raw:
+                src = _Tee(raw, raw_h)
+                stream = zstandard.ZstdDecompressor().stream_reader(src) if zst else src
+                for chunk in iter(lambda: stream.read(CHUNK), b""):
+                    if zst:
+                        con_h.update(chunk)
+                    yield chunk
+                while src.read(CHUNK):      # zstd 帧后面若还有字节，也要进存储哈希
+                    pass
+        except (zstandard.ZstdError, zipfile.BadZipFile) as exc:
+            raise self._broken(f, exc)
+        content = con_h if zst else raw_h
+        if raw_h.hexdigest() != f["sha256"] or content.hexdigest() != f.get("content_sha256", f["sha256"]):
+            raise BundleError(f"文本包 {self.source.name} 的 {f['path']} 和清单对不上（sha256）——包坏了或被改过，重新拿一份")
+
+    def _broken(self, f: dict, exc: Exception) -> BundleError:
+        return BundleError(f"文本包 {self.source.name} 的 {f['path']} 读不下去（{type(exc).__name__}: {exc}）"
+                           f"——包坏了或被改过，重新拿一份")
+
+    def iter_rows(self, table: str, lang: str):
+        """逐行读一张表（`_chunks`：边读边核两种哈希）。JSON 解码出错也算包坏了（UnicodeDecodeError 是 ValueError）。"""
+        f = self._files()[(table, lang)]
+        pending = b""
+        try:
+            for chunk in self._chunks(f):
+                lines = (pending + chunk).split(b"\n")
+                pending = lines.pop()
+                rows = [json.loads(ln) for ln in lines if ln.strip()]
+                yield from rows
+            if pending.strip():
+                yield json.loads(pending)
+        except ValueError as exc:
+            raise self._broken(f, exc)
+
+    def verify(self) -> None:
+        """清单里的每个文件都核一遍：存储字节的 `sha256`，数据文件再核解压后的 `content_sha256`。
+        拿指纹去对指纹表之前用——只核存储字节的话，改了内容、同时改掉清单里存储哈希的包照样过，
+        而指纹（只由内容哈希算）还和表对得上。"""
+        for f in self.manifest["files"]:
+            for _ in self._chunks(f):
+                pass
+
+    def verify_stored(self, tables, langs=("ja", "zh-Hans")) -> None:
+        """只核存储字节的 sha256（缓存命中、不解压时用）。"""
+        have = self._files()
+        for t in tables:
+            for lang in langs:
+                f = have[(t, lang)]
+                h = hashlib.sha256()
+                with self._open(f["path"]) as raw:
+                    for chunk in iter(lambda: raw.read(CHUNK), b""):
+                        h.update(chunk)
+                if h.hexdigest() != f["sha256"]:
+                    raise BundleError(f"文本包 {self.source.name} 的 {f['path']} 和清单对不上（sha256）——包坏了或被改过，重新拿一份")
+
+
+class _Closing(io.RawIOBase):
+    """zip 成员 + 它的 ZipFile，一起关。"""
+
+    def __init__(self, raw, zf):
+        self.raw, self.zf = raw, zf
+
+    def read(self, n: int = -1) -> bytes:
+        return self.raw.read(n)
+
+    def readable(self) -> bool:
+        return True
+
+    def close(self) -> None:
+        try:
+            self.raw.close()
+        finally:
+            self.zf.close()
+            super().close()
+
+
+def _load_manifest(text: str, where: str) -> dict:
+    try:
+        m = json.loads(text)
+    except ValueError as exc:
+        raise BundleError(f"{where} 的清单不是合法 JSON：{exc}")
+    if m.get("schema") != SCHEMA:
+        raise BundleError(f"{where} 的清单 schema 是 {m.get('schema')!r}，这里只认 {SCHEMA}（game-text-data 那边重新 bundle）")
+    for k in ("game", "fingerprint", "files", "langs"):
+        if k not in m:
+            raise BundleError(f"{where} 的清单缺 {k}")
+    if fingerprint_of(m["files"]) != m["fingerprint"]:
+        raise BundleError(f"{where} 的清单自相矛盾：按文件重算的指纹不是它记的 {m['fingerprint']}")
+    return m
+
+
+def open_bundle(p: Path) -> Bundle:
+    """一个包：`.zip`，或带 `manifest.json` 的目录。"""
+    if p.is_file() and p.suffix.lower() == ".zip":
+        try:
+            with zipfile.ZipFile(p) as zf:
+                names = [n for n in zf.namelist() if n.count("/") == 1 and n.endswith("/" + MANIFEST)]
+                if len(names) != 1:
+                    raise BundleError(f"{p.name} 不是文本包：顶层目录下应当恰好一份 {MANIFEST}，找到 {len(names)} 份")
+                m = _load_manifest(zf.read(names[0]).decode("utf-8"), p.name)
+                prefix = names[0][: -len(MANIFEST)]
+        except zipfile.BadZipFile as exc:
+            raise BundleError(f"{p} 不是有效的 zip：{exc}")
+        if prefix != m["game"] + "/":
+            raise BundleError(f"{p.name}：成员目录 {prefix!r} 和清单的 game {m['game']!r} 不一致")
+        return Bundle(p, m, prefix)
+    if (p / MANIFEST).is_file():
+        return Bundle(p, _load_manifest((p / MANIFEST).read_text(encoding="utf-8"), str(p)))
+    raise BundleError(f"{p} 既不是文本包（.zip），也不是带 {MANIFEST} 的目录")
+
+
+def _has_manifest(p: Path) -> bool:
+    try:
+        with zipfile.ZipFile(p) as zf:
+            return any(n.count("/") == 1 and n.endswith("/" + MANIFEST) for n in zf.namelist())
+    except zipfile.BadZipFile:
+        return False
+
+
+def candidates(root: Path) -> list[Path]:
+    """`root` 下可能是包的东西：它自己；或它下面一层的 `.zip` 与带清单的子目录，以及再下一层带清单的目录——
+    包解压出来是 `<game>/manifest.json`，而 Windows 的"全部解压缩"默认再套一层以 zip 命名的文件夹。"""
+    if root.is_file() or (root / MANIFEST).is_file():
+        return [root]
+    if not root.is_dir():
+        return []
+    found = list(root.glob("*.zip"))
+    for q in root.iterdir():
+        if not q.is_dir():
+            continue
+        if (q / MANIFEST).is_file():
+            found.append(q)
+        else:
+            found += [s for s in q.iterdir() if s.is_dir() and (s / MANIFEST).is_file()]
+    return sorted(found)
+
+
+def locate(game: str, where: str | Path | None = None) -> Bundle:
+    """找 `game` 的包。`where` 不给就用 `paths.gametext_root()`。"""
+    root = Path(where).expanduser().resolve() if where else paths.gametext_root()
+    bundles = []
+    for q in candidates(root):
+        if q.is_file() and q.suffix.lower() == ".zip" and not _has_manifest(q):
+            # 只给人看的一行（驱动里 same_ref 那段也会打出来）：别拿 stdout 解析
+            print(f"  [文本包] 跳过 {q.name}：不是文本包（顶层目录下没有 {MANIFEST}）", file=sys.stderr, flush=True)
+            continue
+        bundles.append(open_bundle(q))          # 有清单但清单坏了的照样报错
+    found = [b for b in bundles if b.game == game]
+    if not found:
+        raise BundleError(f"没找到 {game} 的游戏文本包（在 {root} 找的）。包从 game-text-data 的 `bundle` 来，"
+                          f"放进这个目录即可，或用 --gametext / FLOWOCR_GAMETEXT 指过去")
+    # 指纹相同就是同一份语料（例如 zip 和它解压出的目录并存），用排在前面的那份；内容不同才要用户挑
+    if len({b.fingerprint for b in found}) > 1:
+        listing = [f"{b.source.name}（{b.fingerprint.removeprefix('sha256:')[:12]}）" for b in found]
+        raise BundleError(f"{root} 下 {game} 的文本包有 {len(found)} 份、内容不同：{listing}——"
+                          f"用 --gametext 指定其中一份")
+    return found[0]
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+    ap = argparse.ArgumentParser(prog="python -m flowocr.analyze.gtdbundle",
+                                 description="找游戏文本包、核对包里每个文件的哈希，再打印它的身份（指纹 / 位置 / 全部来源信息）")
+    ap.add_argument("game")
+    ap.add_argument("--gametext", default=None, help="包 / 包目录（默认 paths.gametext_root()）")
+    ap.add_argument("--field", choices=("fingerprint", "source", "json"), default="fingerprint")
+    a = ap.parse_args(argv)
+    b = locate(a.game, a.gametext)
+    b.verify()      # 打印出的指纹是拿去对指纹表的，先证明包里的内容就是清单说的那份
+    print(json.dumps(b.provenance(), ensure_ascii=False) if a.field == "json"
+          else b.fingerprint if a.field == "fingerprint" else str(b.source))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flowocr/analyze/match.py

@@ -0,0 +1,67 @@
+"""阶段 2 的**匹配**入口：拿一份 `*-tracks.json`，跑一个匹配器（内置的或用户自己写的），写出匹配产物。
+
+    python -m flowocr.analyze.match out/gs-hsr/hsr-tracks.json --matcher gametext \\
+        --ctx ref=out/gametext/hsr-ref.json --out out/gametext/hsr-matched.json --opt lang=cn
+    python -m flowocr.analyze.match out/x/x-tracks.json --matcher D:/mine/matcher.py --out tmp/x-matched.json
+
+匹配器从哪来、入口长什么样：`flowocr.extensions`（`match(document, context, options) -> dict`，
+`cluster_patch` 是可选的另一半，由 `build_tracks --matcher` 在聚类那一步用）。
+`--ctx k=v` 进 `context`（`tracks_path` / `tag` / `argv` 自动带上），`--opt k=v` 进 `options`，值都是字符串、匹配器自己解释。
+
+产物拿去阶段 3：`python -m flowocr.output.render <out.json> --preset matched_srt|default|dev`
+（内置匹配器 `gametext` 写的是 `flowocr-matched/2`；用户匹配器写自己的格式，配自己的预设）。
+⚠ 换预设不重跑匹配、换匹配器不重跑提取——这就是三个阶段各写一份产物的意义。
+
+`scriptmatch` 的 CLI 仍在（它带着评测口径的报表和一堆 ASS 旋钮）；这里是**通用**那条，
+内置和用户实现走同一条路。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from flowocr import extensions
+from flowocr.artifacts import tracksio
+
+
+def kv(pairs: list[str], what: str) -> dict:
+    out = {}
+    for x in pairs:
+        if "=" not in x:
+            raise SystemExit(f"{what} 要 K=V：{x}")
+        k, v = x.split("=", 1)
+        out[k] = v
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="跑一个匹配器（阶段 2）",
+                                 formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__)
+    ap.add_argument("tracks", help="*-tracks.json（阶段 2 的聚类产物）")
+    ap.add_argument("--matcher", required=True,
+                    help="内置名（%s）/ 模块名 / .py 路径" % "、".join(extensions.builtin_names("matcher")))
+    ap.add_argument("--out", required=True, help="匹配产物 JSON")
+    ap.add_argument("--ctx", action="append", default=[], metavar="K=V",
+                    help="给匹配器的上下文，可多次（内置 gametext 要 `ref=<gamescript 的剧本 JSON>`）")
+    ap.add_argument("--opt", action="append", default=[], metavar="K=V", help="给匹配器的选项，可多次")
+    a = ap.parse_args(argv)
+
+    src = Path(a.tracks)
+    doc = tracksio.load(src)
+    context = {"tracks_path": str(src), "tag": src.stem.removesuffix("-tracks"),
+               "argv": list(sys.argv[1:] if argv is None else argv), **kv(a.ctx, "--ctx")}
+    matcher = extensions.load(a.matcher, "matcher")
+    out_doc = matcher.match(doc, context, kv(a.opt, "--opt"))
+    if not isinstance(out_doc, dict):
+        raise SystemExit(f"匹配器 `{a.matcher}` 的 match() 要返回 dict，给的是 {type(out_doc).__name__}")
+    p = Path(a.out)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(out_doc, ensure_ascii=False, indent=1), encoding="utf-8")
+    print(f"-> {p}（schema {out_doc.get('schema', '<无>')}，{len(out_doc.get('cues') or ())} 条）")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flowocr/analyze/matchers/__init__.py

@@ -0,0 +1,5 @@
+"""内置匹配器。一个模块一个匹配器，入口形状见 `flowocr.extensions`（`match` 必有、`cluster_patch` 可选）。
+
+现在只有 `gametext`（游戏文本库：原神 / 星铁 / 绝区零）。用户自己写的匹配器不必放进来——
+`extensions.load("<路径或模块名>", "matcher")` 同样能加载。
+"""

flowocr/analyze/matchers/gametext.py

@@ -0,0 +1,70 @@
+"""内置匹配器：**游戏文本库**（原神 / 星铁 / 绝区零的文本包，`gtd-bundle/1`，由 `gamescript` 读成剧本；game-text-corpus 报告）。
+
+两个入口（`flowocr.extensions`）：
+
+* `cluster_patch(context, options)`：按游戏给默认聚类器（build_tracks）的参数覆盖。表就是 `PATCHES`
+  （原 `tools/game_patches.py`，2026-09-22 搬进来；那个文件现在是把字典翻成 CLI 参数的薄适配）。
+  `context` 给 `game`（`genshin` / `starrail` / `zzz`）或 `tag`（素材标签，前缀认游戏，同 `gamescript.TAG_GAME`）。
+* `match(document, context, options)`：`document` 是 `*-tracks.json` 的 dict；`context["ref"]` 是 `gamescript` 产的剧本 JSON 路径，
+  `context["tracks_path"]` 是那份 tracks 的路径（记进 provenance；`feed == "main"` 时从它取主轨 SRT）。
+  返回 `*-matched.json` 的 dict（`scriptmatch.SCHEMA`）。判据和 CLI `scriptmatch.py` 是同一份 `run_match`。
+
+`options` 的键和默认值同 `scriptmatch.py` 的旋钮：`feed`（nonoise）、`feed_panel`（keep）、`fuzzy`（0.75）、
+`merge_gap`（`scriptmatch.MERGE_GAP`）、`overlay`（True）、`readable_textmap` / `obs`（None）。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from flowocr.analyze import game_align as GA
+from flowocr.analyze import gamescript as GS
+from flowocr.analyze import scriptmatch as SM
+
+PATCHES: dict[str, dict] = {
+    # 星铁：窗内并区的时间门。遗器故事的阅读面板和字幕带**从不同屏**，却因为空间上挨着被并查集
+    # 串成一块（game-text-corpus 报告）；这道门要求"同屏过 or 时段交错 ≥2 次"才连边。
+    # 整场 hsr +34 条命中，cue 1,645 → 1,450、对不上剧本 344 → 269、重复认领 811 → 654，两段切片 ±0。
+    # **原神 / 绝区零不开**：那两款上是 −49 / −58 / −30，病在"主轨只能挑一个区域"接不住被分开的带。
+    "starrail": {"region_time_gate": 2},
+}
+"""游戏 -> build_tracks 的参数覆盖。键是参数名（`region_time_gate`），不是 CLI 旗标。"""
+
+
+def _flag(v) -> bool:
+    """`options` 的值可能是命令行来的**字符串**（`--opt overlay=0`）——`bool("0")` 是 True，
+    静默把"关掉"读成"开着"。这里按字面认（2026-09-22）。"""
+    if isinstance(v, str):
+        return v.strip().lower() not in ("", "0", "false", "no", "off")
+    return bool(v)
+
+
+def game_of(context: dict) -> str | None:
+    """`context["game"]` 优先；否则按素材标签前缀认（`gi-s1` → genshin），认不出就 None。"""
+    game = context.get("game")
+    if game:
+        return str(game)
+    tag = str(context.get("tag") or "")
+    return GS.TAG_GAME.get(tag.split("-")[0].rstrip("0123456789")) if tag else None
+
+
+def cluster_patch(context: dict, options: dict | None = None) -> dict:
+    """这款游戏要给默认聚类器的参数覆盖；没有就是空字典（不改默认）。"""
+    return dict(PATCHES.get(game_of(context) or "", {}))
+
+
+def match(document: dict, context: dict, options: dict | None = None) -> dict:
+    """见文件头。`document` 不动；返回新的 matched dict。"""
+    o = dict(options or {})
+    ref_path = context.get("ref")
+    if not ref_path:
+        raise ValueError("gametext 匹配器要 context['ref']（gamescript 产的剧本 JSON 路径）")
+    ref = GA.load_ref(Path(ref_path))
+    tracks_path = str(context.get("tracks_path") or "")
+    params = {"feed": o.get("feed", "nonoise"), "feed_panel": o.get("feed_panel", "keep"),
+              "fuzzy": float(o.get("fuzzy", 0.75)), "merge_gap": float(o.get("merge_gap", SM.MERGE_GAP))}
+    res = SM.run_match(ref, tracks_path, params["feed"], params["feed_panel"], params["fuzzy"], params["merge_gap"],
+                       overlay=_flag(o.get("overlay", True)), readable_textmap=o.get("readable_textmap"),
+                       obs=o.get("obs"), doc=document)
+    st = SM.match_stats(ref, res["recs"], res["suspect_raw"])
+    return SM.matched_doc(ref, res["recs"], res["n_raw"], st, str(ref_path), res["subs_path"], res["tp"],
+                          list(context.get("argv") or []), params, res["items"], res["ov_stats"])

flowocr/analyze/merge_nameplate.py

@@ -0,0 +1,178 @@
+"""把**名牌区域**并进主轨，产出一条给匹配器用的 SRT。
+
+来历（methodology-audit-2 报告）：input1 上四组对照里，只有"并名牌"这一组
+能同时拉动两个指标——命中 5,814 → **5,880（+66）**、疑似真漏 133 → **94**，
+而且**纯标点行的漏条率 97.6% → 52.4%**。owner 说的"上下文 momentum"就是这个：
+名牌把"去掉标点一个字不剩"的 cue 撑成一条有边界、有判别力的条目。
+
+那次挑名牌用的是**角色名表**（探针能用、修法不能用）。这个工具消费的是
+`nameplate.py` 的几何判据，**一个字都不看**，所以换素材也能跑。
+
+判据的准确性（`probe_nameplate_geom.py` 拿名表离线量的，五部整片，
+产物用 `--slot-span-ratio 2.0` 建）：精确率 55–72%、召回 74–90%。
+**精确率不到 100% 是这条路的成本**：挑中的 run 里有三成不是名字，
+它们会作为多余条目进匹配器——代价只能靠端到端的命中/漏条量，不能靠"看着像"。
+
+用法：
+    python -m flowocr.analyze.merge_nameplate out/yuka-f1-sr20/f1-tracks.json \
+        --out tmp/match/ours1-merged.srt
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from flowocr.analyze import build_tracks as bt  # noqa: E402   （只借 git_head，别再抄一份）
+from flowocr.artifacts import evalkit  # noqa: E402
+from flowocr.analyze import nameplate  # noqa: E402
+from flowocr.artifacts import tracksio  # noqa: E402
+from flowocr.artifacts import srtio  # noqa: E402
+
+
+def region_srt(outdir: Path, doc: dict, r: dict) -> Path:
+    """区域的 SRT 文件名**从产物里读**，不用 tag+index+label 拼。
+
+    拼出来的名字和磁盘上的名字是两回事：label 一变就是新文件名，
+    2026-09-07 那次整部 input4 量错就是拼/猜文件名的同一形状。
+    """
+    for tr in doc["tracks"]:
+        if tr["kind"] == "region" and tr["region"] == r["i"]:
+            return outdir / tr["srt"]
+    raise SystemExit(f"tracks.json 里没有 region{r['i']:02d} 这条轨")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("tracks", help="build_tracks 产的 *-tracks.json")
+    ap.add_argument("--out", required=True, help="并好的 SRT 写到哪")
+    ap.add_argument("--no-band-repair", dest="band_repair", action="store_false",
+                    help="**默认开**：把和主轨同一条带的碎片也并回来（cy 差 ≤--band-dy、"
+                         "字高比在 --band-h 之间）。收紧 --slot-span-ratio 会把主字幕带"
+                         "切下来一块——f5 的 region07 里有 328 种内容字 ≥6 的真台词，"
+                         "命中因此掉了 261；并回来是 2,534 → 2,835。"
+                         "五部里只有 f2/f5 真有碎片可并，另外三部开不开都一样，"
+                         "**所以默认开是安全的**。这个开关是留给对照实验的")
+    ap.add_argument("--paste", action="store_true",
+                    help="**把名牌贴进时间重叠最大的那条正文 cue 的首行**，"
+                         # `%%`：argparse 对 help 串做 % 格式化，单个 `%` 会让
+                         # `--help` 抛 ValueError（这一处一直是坏的，2026-09-09 修）
+                         "而不是让它单独成条（`nameplate.attach`，贴法 99.8%% 准）。"
+                         "存在的理由（methodology-audit-3 报告）："
+                         "单独成条时，只有名字的 cue 在匹配器眼里就是一条短台词，"
+                         "会去抢剧本里那些含名字的行——五部实测**超额认领**"
+                         "（输出里比整部剧本多出来的条目——**报警，不是已确认的错**）"
+                         "从 81/138/140/68/39 "
+                         "涨到 546/540/360/257/126。贴进正文则不产生新条目。"
+                         "同带碎片不受影响（那是真台词，照旧独立成条）")
+    ap.add_argument("--band-dy", type=float, default=0.02)
+    ap.add_argument("--band-h", type=float, nargs=2, default=[0.75, 1.35])
+    nameplate.add_args(ap)
+    ap.add_argument("--np-source", default="track", choices=("track", "geom"),
+                    help="名牌从哪来：`track` = build_tracks 打标投影的那条名牌轨"
+                         "（默认，判据在 flowocr.analyze.uigate）；`geom` = nameplate.py 的七条阈值挑区域"
+                         "（五部里四部挑中 0 个，留作对照）")
+    a = ap.parse_args()
+
+    tp = Path(a.tracks)
+    tag = tp.name.removesuffix("-tracks.json")
+    d = tracksio.load(tp)
+    d["regions"] = tracksio.regions_with_runs(d)
+    regs = nameplate.region_stats(d)
+    evalkit.require_nonzero(len(regs), "有 run 的区域")
+    main_r = max(regs, key=lambda x: x["score"])
+    # **名牌从哪来**（2026-09-20 起默认走第一条）：
+    #   `track`：`build_tracks` 打好标、投影成的那条 `kind="nameplate"` 轨——
+    #            判据是 `tools/uigate.pick_nameplates`（框位 + 相对位置 + 时长 ≥ 台词）。
+    #   `geom` ：`nameplate.py` 的七条阈值挑**区域**——五部里**四部挑中 0 个**（ui-gate 计划），
+    #            而且病根在输入：三部的名牌 run 被巨型区域吞了，区域侧根本没得挑。
+    np_track = next((t for t in d["tracks"] if t.get("kind") == "nameplate"), None)
+    if a.np_source == "track" and np_track is None:
+        raise SystemExit("这份 tracks.json 里没有名牌轨——用新版 build_tracks 重建，"
+                         "或者显式 `--np-source geom` 走旧的七条阈值")
+    picked = [] if a.np_source == "track" else nameplate.pick(regs, a)[1]
+    geo_picked = list(picked)   # 几何判据挑的那些；下面 band_repair 还会往里加
+
+    main_srt = region_srt(tp.parent, d, main_r)
+    if not main_srt.exists():
+        raise SystemExit(f"主轨 SRT 不在：{main_srt}（tracks.json 和产物目录对不上？）")
+    cues = srtio.read_srt(main_srt, sort=True)
+    print(f"主轨 region{main_r['i']:02d}（{main_r['label']}）{len(cues)} 条")
+
+    if not picked and a.np_source == "geom":
+        print("**没挑中任何名牌区域**——七条阈值在这部素材上不成立，原样输出主轨。"
+              "⚠ 五部整片里**四部**是这个结果（ui-gate 计划）："
+              "病根多半在输入——名牌的 run 被巨型区域吞了。默认的 `--np-source track` 不吃这一套。")
+    if a.band_repair:
+        band = [r for r in regs
+                if r["i"] != main_r["i"] and r not in picked and r["n"] >= a.min_runs
+                and abs(r["cy"] - main_r["cy"]) <= a.band_dy
+                and a.band_h[0] <= r["h"] / main_r["h"] <= a.band_h[1]]
+        if band:
+            print(f"  同带碎片 {len(band)} 个（收紧闸门切下来的那些）")
+        picked = picked + band
+
+    extra, plates = [], []
+    if a.np_source == "track":
+        np_srt = tp.parent / np_track["srt"]
+        if not np_srt.exists():
+            raise SystemExit(f"名牌轨的 SRT 不在：{np_srt}")
+        plates = srtio.read_srt(np_srt, sort=True)
+        print(f"  名牌轨 {np_track['srt']}：{len(plates)} 条"
+              + ("" if a.paste else "  ⚠ 没给 --paste，它们会独立成条——"
+                                    "**别这么喂给匹配器**（methodology-audit-3：会去抢含名字的剧本行）"))
+        if not a.paste:
+            extra, plates = plates, []
+    for r in picked:
+        p = region_srt(tp.parent, d, r)
+        if not p.exists():
+            print(f"  ⚠ region{r['i']:02d} 的 SRT 不在（{p.name}），跳过")
+            continue
+        cs = srtio.read_srt(p, sort=True)
+        # --paste 下，**几何判据挑中的名牌**贴进正文；同带碎片是真台词，照旧独立成条
+        (plates if (a.paste and r in geo_picked) else extra).extend(cs)
+        print(f"  + region{r['i']:02d}（{r['label']}）{len(cs)} 条"
+              f"  cy={r['cy']:.3f} 字高 {r['h']:.0f} 时长中位 {r['dur']:.1f}s"
+              + ("  [贴进正文]" if a.paste and r in geo_picked else ""))
+
+    allc = sorted(cues + extra, key=lambda c: (c.start, c.end))
+    if plates:
+        plates.sort(key=lambda c: c.start)
+        blocks, tagged = nameplate.attach(allc, plates)
+        print(f"  名牌 {len(plates)} 条按**时间重叠最大**贴进正文："
+              f"{evalkit.denom(tagged, len(blocks))} 的 cue 贴上了名字"
+              f"（贴法 99.8% 准，speaker-name-line 报告）")
+    else:
+        blocks = [(int(round(c.start * 1e6)), int(round(c.end * 1e6)), list(c.lines))
+                  for c in allc]
+    n = srtio.write_srt_blocks(a.out, blocks)
+    # **写完自己数一遍**：这个项目在"条数口径"上栽过一次 30 小时的错
+    got = srtio.count_cues(a.out)
+    if got != n:
+        raise SystemExit(f"写了 {n} 条但文件里数出 {got} 条——不要拿这份数据继续算")
+    print(f"-> {a.out}：{len(cues)} + {len(extra)} = **{n} 条**"
+          + (f"（另有 {len(plates)} 条名牌贴进了正文，不单独成条）" if plates else "")
+          + f"（`grep -c -- '-->' {a.out}` 数得到同一个数）")
+
+    # **这一级也要能追溯到是哪一版代码、哪些参数产的**（methodology-audit-3 报告）：
+    # 它和 build_tracks 一样是"产出匹配器输入"的一级代码，可之前既不写 provenance、
+    # 也不落日志——挑中了哪几个区域、有没有打出"没挑中任何名牌区域"，只在终端上闪过。
+    prov = tp.parent / f"{tag}-nameplate.json"
+    prov.write_text(json.dumps({
+        "tool": "merge_nameplate.py", "git_head": bt.git_head(),
+        "argv": sys.argv[1:], "tracks": str(tp), "out": str(a.out),
+        "main_region": main_r["i"], "main_cues": len(cues),
+        "picked": [{"i": r["i"], "label": r["label"], "cy": round(r["cy"], 3),
+                    "h": r["h"], "dur": r["dur"], "n_runs": r["n"],
+                    "band_repair": r not in geo_picked} for r in picked],
+        "extra_cues": len(extra), "cues": n,
+        "args": {k: v for k, v in sorted(vars(a).items())},
+    }, ensure_ascii=False, indent=1), encoding="utf-8")
+    print(f"   版本与选区 -> {prov.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())