flowocr 0.1.0__py3-none-any.whl

flowocr/paths.py

@@ -0,0 +1,168 @@
+"""代码在哪、产物和素材在哪——**这两件事分开**。
+
+照搬另一个项目（finesub）的做法：
+
+> Running from a checkout uses the checkout's own data …
+> **A git worktree resolves to the main checkout.**
+
+理由在这个项目里更硬：`out/`、`tmp/`、`data/` 里的素材和 explore 下各实验的 venv 都是
+**ignore 的**，linked worktree 里根本不存在。所以：
+
+* **代码**从这份文件所在的 checkout 走（槽里改的代码就是跑的代码，`git_head` 也从这里算）；
+* **产物与素材**走 `data_root()`——在 worktree 里就是它背后的**主 checkout**。
+
+这样"在槽里改完直接跑整片"不需要建 junction、不需要手抄绝对路径，
+而 provenance 里的 `git_head` 仍然是**槽自己的**那棵干净的树。
+
+**三种运行形态**（2026-09-21 迁进正式包时加的第三种）：
+
+| 形态 | 判据 | `CODE_ROOT` | `data_root()` |
+| --- | --- | --- | --- |
+| 源码 checkout | `<root>/.git` 存在（目录）且有 `pyproject.toml` | 那个 checkout | 同 `CODE_ROOT` |
+| linked worktree | `<root>/.git` 是个 `gitdir:` **文件** | 槽 | **主 checkout** |
+| 安装后运行 | 上面两条都不成立（包在 site-packages 里） | 无意义（只剩 `PACKAGE_ROOT`） | 用户数据目录（下表） |
+
+安装态的用户数据目录：Windows `%LOCALAPPDATA%/flowocr`，其余 `$XDG_DATA_HOME/flowocr`
+或 `~/.local/share/flowocr`。`FLOWOCR_DATA_ROOT` 在三种形态下都能覆盖
+（对应 finesub 的 `FINESUB_ROOT`）。⚠ 装进 `<checkout>/.venv` 的**非** editable 安装也算安装态：
+判据看的是包文件自己往上三层有没有 checkout，不看 venv 在哪。
+
+    python -m flowocr.paths            # 打印产物根（驱动脚本 cd 到这里）
+    python -m flowocr.paths --code     # 打印代码根
+    flowocr-paths                      # console script，同一份实现（`tools/paths.py` 那个 shim 2026-09-22 已删）
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+"""包自己所在的目录（`src/flowocr/` 或 `site-packages/flowocr/`）。"""
+
+CODE_ROOT = PACKAGE_ROOT.parents[1]
+"""这份代码所在的 checkout（`src/flowocr/` 往上两层）。**只在源码 / worktree 形态下有意义**，
+安装态下它指向 site-packages 的上一层，别拿它拼路径——先问 `is_checkout()`。"""
+
+
+def main_checkout(root: Path) -> Path | None:
+    """`root` 是 linked worktree 的话，返回它背后的主 checkout；否则 `None`。
+
+    linked worktree 的 `.git` 是**一个文件**，内容形如
+    `gitdir: <main>/.git/worktrees/<slot>`；主 checkout 就在它上面三层
+    （去掉 `<slot>`、`worktrees`、`.git`）。这段判据抄自 finesub 的
+    `_main_worktree_root`，连"要检查倒数第二、三段是不是 worktrees/.git"都一样——
+    少了那一步，`gitdir:` 指向别处的仓库也会被当成主 checkout。
+    """
+    pointer = root / ".git"
+    if not pointer.is_file():
+        return None
+    try:
+        body = pointer.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    if not body.startswith("gitdir:"):
+        return None
+    recorded = Path(body.removeprefix("gitdir:").strip())
+    if not recorded.is_absolute():
+        recorded = (root / recorded).resolve()
+    if (recorded.parent.name, recorded.parent.parent.name) != ("worktrees", ".git"):
+        return None
+    return recorded.parents[2]
+
+
+def is_linked_worktree(root: Path | None = None) -> bool:
+    return main_checkout(root or CODE_ROOT) is not None
+
+
+def is_checkout(root: Path | None = None) -> bool:
+    """`root` 是不是一份源码 checkout（主 checkout 或 linked worktree）。
+
+    两个条件都要：`.git`（目录或 `gitdir:` 文件）+ `pyproject.toml`。只看 `.git` 不够——
+    site-packages 的上一层碰巧在某个别的仓库里时也有 `.git`。
+    """
+    root = root or CODE_ROOT
+    return (root / ".git").exists() and (root / "pyproject.toml").is_file()
+
+
+def user_data_root() -> Path:
+    """安装态的产物 / 缓存根。不建目录，只算路径。"""
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+        return Path(base) / "flowocr"
+    base = os.environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+    return Path(base) / "flowocr"
+
+
+def data_root(root: Path | None = None) -> Path:
+    """产物与素材的根。**worktree 解析回主 checkout；安装态落到用户数据目录。**"""
+    configured = os.environ.get("FLOWOCR_DATA_ROOT", "").strip()
+    if configured:
+        return Path(configured).expanduser().resolve()
+    root = root or CODE_ROOT
+    if not is_checkout(root):
+        return user_data_root()
+    return main_checkout(root) or root
+
+
+def models_root() -> Path:
+    """ONNX 模型的根：`FLOWOCR_MODELS` > 数据根的 `models/`（源码态是主 checkout 的 `models/`，已 ignore；安装态是用户数据目录）。
+    2026-09-22 起两种状态同一个位置：模型改成官方发布的（`flowocr.models`），不再依赖按约定随时可删的 onnxrt 实验目录下的 `models/`——
+    那里还躺着以前自己转的几份，给历史臂用（显式路径照样认，见 `resolve_model`）。"""
+    configured = os.environ.get("FLOWOCR_MODELS", "").strip()
+    if configured:
+        return Path(configured).expanduser().resolve()
+    return data_root() / "models"
+
+
+def gametext_root() -> Path:
+    """游戏文本包（`gtd-bundle/1`，`flowocr.analyze.gtdbundle`）的默认位置：`FLOWOCR_GAMETEXT` > 数据根的 `gametext/`
+    （源码态是主 checkout 的 `gametext/`，已 ignore；安装态是用户数据目录）。包是私下拿到的，放进来即可，不用解压。"""
+    configured = os.environ.get("FLOWOCR_GAMETEXT", "").strip()
+    if configured:
+        return Path(configured).expanduser().resolve()
+    return data_root() / "gametext"
+
+
+def resolve_model(path: str) -> str:
+    """模型文件 / 目录的路径。给的路径存在（绝对，或相对当前目录——驱动脚本 cd 到产物根的老规矩）就原样用；
+    不存在就按**文件名**到 `models_root()` 里找；没有就原样返回，让打开它的那一步报清楚。
+
+    默认值字符串（`ocr_args.OLD_DET_ONNX` / `OLD_REC_ONNX`，旧的自转模型路径）**不动**：它写进 obs 的 `config`，换了会让磁盘上的现成产物全部对不上。"""
+    p = Path(path)
+    if p.exists():
+        return str(p)
+    cand = models_root() / p.name
+    return str(cand) if cand.exists() else path
+
+
+def child_env(env: dict | None = None) -> dict:
+    """给要 `-m flowocr.…` 的子进程用的环境：把装着 `flowocr` 的那个目录放进 `PYTHONPATH` 最前面。
+
+    源码 checkout 里那是 `<root>/src`（默认不在 sys.path 上，父进程靠脚本开头的引导行放进去的，
+    子进程继承不到）。**安装态什么都不加**：包在 site-packages 里本来就找得到，而把 site-packages 塞进 `PYTHONPATH`
+    会泄漏给**别的解释器**起的子进程——2026-09-22 nightly 用 `FLOWOCR_ORT_PYTHON` 把 ORT worker 钉到另一个 venv，
+    那个解释器却先 import 到了本 venv 的 onnxruntime 和 CUDA 库（PYTHONPATH 排在它自己的 site-packages 前面）。
+    `run_ocr2` 的监督者起 worker、`--workers N` 切段都走这里。"""
+    env = dict(os.environ if env is None else env)
+    if not is_checkout():
+        return env
+    here = str(PACKAGE_ROOT.parent)
+    old = env.get("PYTHONPATH", "")
+    if here not in old.split(os.pathsep):
+        env["PYTHONPATH"] = here + (os.pathsep + old if old else "")
+    return env
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    ap = argparse.ArgumentParser(description="打印代码根 / 产物根")
+    ap.add_argument("--code", action="store_true", help="打印代码根（默认打印产物根）")
+    a = ap.parse_args(argv)
+    print(CODE_ROOT if a.code else data_root())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flowocr/provenance.py

@@ -0,0 +1,119 @@
+"""产物要能追溯到是哪一版代码产的：`git_head()` 和 `code_fp()`，**全仓库只有这一份实现**。
+
+原来 `build_tracks.py` 里那份（`gamescript` / `scriptmatch` / `refine_boundaries` 都借它用）
+和 `ocr_args.py` 里那份各算各的，文件表一个记 basename、一个记 `dir/name`。
+2026-09-21 搬进正式包时并成一份，**文件表统一记仓库相对路径**（`src/flowocr/analyze/build_tracks.py`、
+`src/flowocr/paths.py`），于是搬目录之后表里写的就是代码真正所在的位置，
+守卫不再读已迁走的旧路径（project-structure 计划第 1 条）。
+
+⚠ 这次统一让所有产物的 `code_fp` 都变了（表的格式变了，不只是内容）。它证明的是代码身份，
+证明不了新旧代码行为等价——迁移验收靠产物级对账（同一份 obs 重建、`obs_identical` / `obs_textdiff`），
+不靠指纹相同。改动前的五个指纹记在 project-structure 账本。
+
+`git_head` 只在源码 checkout / worktree 里有意义；安装态下没有仓库，返回 `"?"`。
+"""
+from __future__ import annotations
+
+import hashlib
+import subprocess
+from pathlib import Path
+
+from flowocr.paths import CODE_ROOT, PACKAGE_ROOT, data_root, is_checkout
+
+
+def version() -> str | None:
+    """flowocr 的发行版本（包元数据）。安装态没有 git，`git_head` 是 `"?"`，靠它看出是哪个发行版；取不到记 None。
+    源码态以 `git_head` / `code_fp` 为准：这里读的是 venv 里登记的版本，可能落后于 `pyproject.toml`（改了版本号没重新 `uv sync`），别拿它对账。"""
+    import importlib.metadata
+    try:
+        return importlib.metadata.version("flowocr")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def portable(p) -> str | None:
+    """产物里**记**的路径：绝对路径在数据根下的记成相对数据根、在用户目录下的记成 `~/…`，其余与相对路径原样。
+    产物会被分享，绝对路径会带出用户名（release-plan F8）。**只用于记**；按记下的路径去开文件用 `local()`。
+    相对路径不动：驱动都 cd 到数据根、传的就是相对路径，改它只会让参数值（`0`、`off`…）被误当路径。"""
+    if p is None:
+        return None
+    s = str(p)
+    q = Path(s)
+    if not q.is_absolute():
+        return s
+    q = q.resolve()
+    for base, prefix in ((data_root(), ""), (Path.home(), "~/")):
+        try:
+            return prefix + q.relative_to(base.resolve()).as_posix()
+        except ValueError:
+            continue
+    return s
+
+
+def local(p) -> Path:
+    """`portable()` 记下的路径 -> 这台机器上的路径：`~` 展开；相对路径在当前目录不存在就按数据根拼。"""
+    if not str(p):
+        return Path("")
+    q = Path(str(p)).expanduser()
+    if q.is_absolute() or q.exists():
+        return q
+    return data_root() / q
+
+
+def file_of(name: str, root: Path | None = None) -> Path:
+    """指纹表里的仓库相对路径 -> 真文件。`src/flowocr/...` 按**包自己的位置**解析（安装态没有 `src/`，包在 site-packages；
+    源码态 `PACKAGE_ROOT.parent` 就是 `<root>/src`，同一个文件）；其余（`tools/`、`explore/`）只在 checkout 里有。
+    `root` 给了就只在它下面找（自检用）。2026-09-22 安装态第一次跑就在这里 FileNotFoundError。"""
+    if root is not None:
+        return root / name
+    if name.startswith("src/"):
+        return PACKAGE_ROOT.parent / name[len("src/"):]
+    return CODE_ROOT / name
+
+DIRTY_PATHS = ("src", "dev_tools", "explore")
+"""`git_head()` 判 `+dirty` 时看哪些目录。**别在别处抄第二份**——
+只看**产得出产物的代码**：正式包、`tools/`、`explore/`（`dev_tools/reference/match_ref.py` 是产
+`ours*_jp.ass` 的一级代码，audit-5 点名要纳入）。文档和 `tests/` 不看——
+改它们不影响产物，缀上去只会天天是 dirty。"""
+
+
+def git_head(root: Path | None = None) -> str:
+    """`HEAD` 的短 sha；**代码目录有未提交改动时后面缀 `+dirty`**。
+
+    为什么必须缀（2026-09-08 自己踩的）：跑一批产物的中途我提交了一次，
+    于是同一批 11 份产物的 provenance 里躺着两个 `git_head`——
+    而**跑的代码自始至终是同一份**（那次提交没有改工作树的内容）。
+    反过来更危险：`HEAD` 记的是"最后一次提交是谁"，改了没提交就跑，
+    provenance 会**言之凿凿地指向一个并没有产生这份产物的 commit**。
+    这和 09-06 那次"照着文档的复现命令跑打出另一张表"是同一个形状。
+    """
+    if root is None and not is_checkout():
+        return "?"                                   # 安装态：没有仓库，别去问 cwd 碰巧所在的别人家的 git
+    root = root or CODE_ROOT
+    try:
+        head = subprocess.run(["git", "rev-parse", "HEAD"], capture_output=True,
+                              text=True, cwd=root, check=True).stdout.strip()[:12]
+    except Exception:
+        return "?"
+    try:
+        dirty = subprocess.run(["git", "status", "--porcelain", "--", *DIRTY_PATHS],
+                               capture_output=True, text=True, cwd=root,
+                               check=True).stdout.strip()
+    except Exception:
+        return head + "+?"
+    return head + ("+dirty" if dirty else "")
+
+
+def code_fp(files: tuple[str, ...], root: Path | None = None) -> str:
+    """`files`（仓库相对路径）的**内容指纹**：sha256 前 12 位，换行统一成 LF。
+
+    `git_head` 回答"最后一次提交是谁"，回答不了"这份代码是不是同一份"：HEAD 移动而代码没变时它会不同
+    （feat/game-text 默认臂混了两个 git_head，靠人去 `git diff` 解释），`+dirty` 相同时它又证明不了相同。
+    指纹两件都能回答，报表机械地比它（audit-6）。换行统一是因为主 checkout 和槽的
+    `core.autocrlf` 可能不同，同一份代码不该因此两个指纹。`root` 只给自检用（默认代码根）。
+    路径进 hash（不只内容）：同一份内容换了位置也算换了代码。"""
+    h = hashlib.sha256()
+    for name in sorted(files):
+        h.update(name.encode("utf-8") + b"\0")
+        h.update(file_of(name, root).read_bytes().replace(b"\r\n", b"\n") + b"\0")
+    return h.hexdigest()[:12]

flowocr/typeset/__init__.py

@@ -0,0 +1,9 @@
+"""阶段 4：特效渲染。读阶段 3 的字幕稿（`*.script.ass`，能在 Aegisub 里预览、编辑），生成最终的叠加 ASS。
+
+    python -m flowocr.typeset out/x/x-cn-main.script.ass                  # -> x-cn-main.ass
+    python -m flowocr.typeset x.script.ass --preset dev                   # 开发看：UI 黄字、非主轨浅蓝、区域号
+    python -m flowocr.typeset x.ass --restore                             # 阶段 4 的输出还原成字幕稿
+
+方案：script-fx 计划；约定在 artifacts.md 的字幕稿一节；实现在 `core`，ASS 读写在 `assfile`，
+扩展效果（`--fx`）是 `flowocr.extensions` 的 `fx` 种类，内置的放在 `flowocr.typeset.fx`。
+"""

flowocr/typeset/__main__.py

@@ -0,0 +1,38 @@
+"""`python -m flowocr.typeset`：阶段 4 的命令行。见包的文件头。"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from flowocr.typeset import core
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="阶段 4：字幕稿 -> 最终叠加 ASS（可以反复重跑；--restore 还原字幕稿）")
+    ap.add_argument("ass", help="字幕稿（*.script.ass），或阶段 4 自己的输出")
+    ap.add_argument("-o", "--out", default="", help="默认 x.script.ass -> x.ass，其余 x.ass -> x.fx.ass；--restore 时 -> x.script.ass")
+    ap.add_argument("--preset", default="default", choices=list(core.LOOKS), help="长什么样")
+    ap.add_argument("--opt", action="append", default=[], metavar="K=V",
+                    help="plate（box / rows / text）、plate_alpha（如 0x20）、typewriter（on / dim / off）、fade（on / off）、"
+                         "unknown（error / ignore：不认识的 fo 参数）")
+    ap.add_argument("--fx", action="append", default=[], metavar="模块",
+                    help="扩展效果：内置名 / 模块名 / .py 路径，可多次（见 flowocr.typeset.fx）")
+    ap.add_argument("--restore", action="store_true", help="只还原：删掉生成行，把源行恢复成字幕稿")
+    ap.add_argument("--force", action="store_true", help="--restore 时输出的字幕稿已经在也覆盖（默认不覆盖：可能是改过的）")
+    a = ap.parse_args(argv)
+    if a.restore:
+        out, n = core.restore_file(Path(a.ass), Path(a.out) if a.out else None, a.force)
+        print(f"-> {out}（还原 {n} 条源行）")
+        return 0
+    opts = {}
+    for kv in a.opt:
+        if "=" not in kv:
+            ap.error(f"--opt 要 K=V：{kv}")
+        k, v = kv.split("=", 1)
+        opts[k] = v
+    core.typeset_file(Path(a.ass), Path(a.out) if a.out else None, a.preset, opts, a.fx)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flowocr/typeset/assfile.py

@@ -0,0 +1,216 @@
+"""ASS 文件的读写：**按字节保留**不认识的东西，只改自己动过的字段。
+
+为什么不用 pysubs2（script-fx 计划第 0 步）：它读成对象再整份重写，时间、样式数值按它的格式重出；
+`restore` 要还原出逐字节相同的字幕稿、别人的行（kara-templater 的 `fx`、`Banner;`）要原样留着，做不到。
+Aegisub 保存时会加 BOM 和它自己的节（`[Aegisub Project Garbage]` 等），这里一律原样保留。
+
+另有两样字幕稿专用的：Effect 字段里 `fo:…` 参数的编解码（`encode_fo` / `parse_fo`），和正文里几个 tag 的读取。
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+EVENT_KINDS = ("Dialogue", "Comment")
+
+
+@dataclass
+class Section:
+    """一节：`name` 是方括号里的名字（文件开头 `[` 之前的内容是 name=None 的一节），`lines` 是节头之后的原始行。"""
+    name: str | None
+    head: str
+    lines: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Doc:
+    sections: list[Section]
+    nl: str = "\n"
+    bom: bool = False
+
+    def section(self, name: str) -> Section | None:
+        low = name.lower()
+        return next((s for s in self.sections if s.name and s.name.lower() == low), None)
+
+    def dumps(self) -> str:
+        out: list[str] = []
+        for s in self.sections:
+            if s.name is not None:
+                out.append(s.head)
+            out.extend(s.lines)
+        text = self.nl.join(out)
+        return ("\ufeff" if self.bom else "") + text
+
+
+def loads(text: str) -> Doc:
+    bom = text.startswith("\ufeff")
+    if bom:
+        text = text[1:]
+    nl = "\r\n" if "\r\n" in text else "\n"
+    sections = [Section(None, "")]
+    for ln in text.split(nl):
+        m = re.fullmatch(r"\s*\[([^\]]+)\]\s*", ln)
+        if m:
+            sections.append(Section(m[1], ln))
+        else:
+            sections[-1].lines.append(ln)
+    return Doc(sections, nl, bom)
+
+
+def format_of(sec: Section) -> list[str] | None:
+    """一节的 `Format:` 字段名（去掉空白）。"""
+    for ln in sec.lines:
+        if ln.startswith("Format:"):
+            return [x.strip() for x in ln.split(":", 1)[1].split(",")]
+    return None
+
+
+@dataclass
+class Row:
+    """一条 `Style:` / `Dialogue:` / `Comment:` 行：`kind` + 冒号后的空白 + 按 `Format` 切开的字段（最后一个字段吃掉剩下的逗号）。
+    字段保留原样（含空白），`str()` 拼回去逐字节相同。"""
+    kind: str
+    ws: str
+    fields: list[str]
+    names: list[str]
+
+    def __str__(self) -> str:
+        return f"{self.kind}:{self.ws}{','.join(self.fields)}"
+
+    def get(self, name: str) -> str:
+        return self.fields[self.names.index(name)]
+
+    def set(self, name: str, value: str) -> None:
+        self.fields[self.names.index(name)] = value
+
+
+def parse_row(line: str, names: list[str], kinds: tuple[str, ...]) -> Row | None:
+    m = re.match(r"(\w+):(\s*)(.*)\Z", line, re.S)
+    if not m or m[1] not in kinds:
+        return None
+    return Row(m[1], m[2], m[3].split(",", len(names) - 1), names)
+
+
+# ---- Effect 字段里的 fo:… 参数 ----
+
+FO_PREFIX = "fo:"
+FO_ESC = "%;,{}\\\n\r"
+"""值里要按百分号编码的字符：`;` 是项的分隔；`,` 会切断 ASS 行的字段（Effect 不是最后一个字段，Aegisub 保存时还会把逗号换成分号）；
+`{` `}` `\\` 放进正文会被 libass 当成 tag（第 0 步探针：`{\\p1}` 会进绘图模式），Effect 里用不着也一并编码；`%` 本身；换行。
+数值列表用空格分隔（`box=374 891 1588 931|…`），所以正常的参数里没有要编码的字符。"""
+
+
+def fo_escape(v: str) -> str:
+    return "".join(f"%{ord(c):02X}" if c in FO_ESC else c for c in v)
+
+
+def fo_unescape(v: str) -> str:
+    return re.sub(r"%([0-9A-Fa-f]{2})", lambda m: chr(int(m[1], 16)), v)
+
+
+def encode_fo(params: dict) -> str:
+    """`{"box": "…", "plate": True}` → `fo:box=…;plate`（写进 Effect 字段）。值为 True 的只写名字，None / False 的不写。"""
+    items = []
+    for k, v in params.items():
+        if v is None or v is False:
+            continue
+        items.append(k if v is True else f"{k}={fo_escape(str(v))}")
+    return FO_PREFIX + ";".join(items)
+
+
+FO_AT = re.compile(r"(?:^|;)\s*fo:")
+
+
+def parse_fo(effect: str) -> dict | None:
+    """Effect 字段里的 `fo:…` → 参数（只有名字的项值为 True）；没有是 None。
+    `fo:` 可以跟在别的内容后面（`备注;fo:…`、`Banner;10;fo:…`），它之后到末尾都是参数；前面那段只留在源行上，阶段 4 不看。"""
+    m = FO_AT.search(effect)
+    if not m:
+        return None
+    params: dict = {}
+    for item in effect[m.end():].strip().split(";"):
+        if not item:
+            continue
+        k, eq, v = item.partition("=")
+        params[k] = fo_unescape(v) if eq else True
+    return params
+
+
+# ---- 正文里的 tag ----
+
+def blocks(text: str) -> list[tuple[str, str]]:
+    """正文切成 [("tags", 花括号里的内容) | ("text", 文字)]。没配对的 `{` 当文字（libass 也这样）。"""
+    out, i = [], 0
+    while i < len(text):
+        j = text.find("{", i)
+        k = text.find("}", j) if j >= 0 else -1
+        if j < 0 or k < 0:
+            out.append(("text", text[i:]))
+            break
+        if j > i:
+            out.append(("text", text[i:j]))
+        out.append(("tags", text[j + 1:k]))
+        i = k + 1
+    return out
+
+
+TAG_RE = {
+    "an": r"\\an(\d)",
+    "pos": r"\\pos\(([^)]*)\)",
+    "move": r"\\move\(([^)]*)\)",
+    "fs": r"\\fs(?=[\d.])([\d.]+)",
+    "fad": r"\\fad\(([^)]*)\)",
+}
+"""阶段 4 要读的几个 tag（整个 tag 匹配，见 `tag_of`）。`\\fs` 后面必须紧跟数字（不是 `\\fsp` / `\\fscx`）。"""
+
+KARAOKE_RE = r"\\(?:ko|kf|K|k)(\d+)"
+
+
+def split_tags(block: str) -> list[str]:
+    """一个花括号块的内容切成**顶层**的 tag（`\\t(0,1000,\\fs80)` 是一个，里面的 `\\fs80` 不单算）；
+    第一个 `\\` 之前的文字（注释）单独一项。拼回去和原内容相同。"""
+    out, cur, depth = [], "", 0
+    for c in block:
+        if c == "\\" and depth == 0 and cur:
+            out.append(cur)
+            cur = ""
+        cur += c
+        if c == "(":
+            depth += 1
+        elif c == ")" and depth:
+            depth -= 1
+    if cur:
+        out.append(cur)
+    return out
+
+
+def tag_of(tag: str) -> tuple[str, str] | None:
+    """一个顶层 tag 是不是阶段 4 要读的那几种：(名字, 参数)；卡拉OK 的名字是 `k`、参数是厘秒。别的是 None。"""
+    for name, pat in TAG_RE.items():
+        m = re.fullmatch(pat, tag.rstrip())
+        if m:
+            return name, m[1]
+    m = re.fullmatch(KARAOKE_RE, tag.rstrip())
+    return ("k", m[1]) if m else None
+
+
+def first_tag(text: str, name: str, lead_only: bool = False) -> str | None:
+    """整行里第一次出现的某个顶层 tag 的参数（libass 对 `\\pos` / `\\move` / `\\an` / `\\fad` 也只认第一个）。
+    `lead_only`：只看正文开头那个 tag 块（`\\fs` 这类局部生效的：行内的 `A{\\fs80}B` 只管后面那几个字，不是整行的字号）。"""
+    for i, (kind, s) in enumerate(blocks(text)):
+        if kind != "tags":
+            if lead_only:
+                return None
+            continue
+        for t in split_tags(s):
+            got = tag_of(t)
+            if got and got[0] == name:
+                return got[1]
+        if lead_only:
+            return None
+    return None
+
+
+def numbers(s: str) -> list[float]:
+    """`"1,2"`（tag 的参数）或 `"1 2"`（`fo` 里的数值列表）→ [1.0, 2.0]。"""
+    return [float(x) for x in re.split(r"[,\s]+", s.strip()) if x]