docvortex 0.5.6__tar.gz → 0.5.8__tar.gz

{docvortex-0.5.6 → docvortex-0.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.5.6
+Version: 0.5.8
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex

docvortex-0.5.8/docs/rust-pdf-stage18-22-repair-handoff.md

@@ -0,0 +1,67 @@
+# Rust 阶段 18～22 修复任务交接状态（2026-09-30，已完成）
+
+用户更换模型后要求“继续任务”，本次已恢复并完成全部实现与验收。**没有待运行的验收任务，也没有应继续推进的性能目标。** 以下先记录最终状态，再保留暂停时的历史交接记录；正式结论见 [rust-pdf-stage18-22-repair.md](rust-pdf-stage18-22-repair.md)。
+
+## 最终完成状态
+
+- 五处行为差异全部修复，Python／Rust 私有协议 29；按三链路完整消融结果，已回退阶段 20 Rust textpage 生命周期迁移，保留字符几何物化优化。
+- 最终对 v0.5.7 三轮配对改善中位数：公开 **9.473%**、Flash **10.207%**、shared **4.367%**。285 对正式配对及 2 对反序复测业务输出全部一致，无持续单文档退化、无链路净退化，RSS 均低于 130%。
+- 32 份 shared、两构建共 64 个严格模型输入审计全部通过，不计入性能数字。
+- Rust/session 完整 pytest：**5479 passed / 14 skipped**；Python/legacy：**4765 passed / 728 skipped**，未 deselect 用例。Rust 相关回归 264 passed；Python 相关回归 120 passed / 144 skipped。
+- Cargo workspace 15 passed；Clippy、rustfmt、全仓 Ruff check、src 与修改测试 Ruff format、证据脚本 Ruff check、`git diff --check` 全部通过。
+- ABI3 wheel 在独立 CPython 3.14.4 venv 安装，不借用 `.venv4` site-packages。auto／rust 均实际命中协议 29、各 13 次文本快照命中；Python／Rust 完整输出一致，auto／rust 输出一致，安装版相关回归 **264 passed**。
+- wheel：`docvortex-0.5.7-cp310-abi3-macosx_11_0_arm64.whl`，SHA-256 `63f5327fb7f4b3c835923644fd750347eea7c161264092049784016925cb9d6c`。wheel 内扩展与最终性能版 SHA 相同：`a7e86593dc078d50bbe3fe52cad5ca1154453a7e5daeeb41a507cbaac1a24029`。
+- 工作区路径与下文相同。本文件记录发版前的修复验收，用户随后要求提交、推送并发布 0.5.8；远端状态以 main 历史、`v0.5.8` 标签和 GitHub Release／PyPI 为准。原阶段报告未修改，完整证据保留在修复工作区 `output/pdf/rust-stage18-22-repair/`。
+- 新增 `final-audit.json`、`model-input-audit.json`、`wheel-audit.json`、`wheel-{auto,rust}-protocol.json`，以及完整 pytest、Cargo、Clippy、Ruff、rustfmt、构建和安装日志。原暂停目录和日志继续保留，未计入正式结果。
+
+---
+
+以下为暂停时的历史交接记录，验收中的描述已由上述最终状态取代。
+
+## 工作区与源码
+
+- 主修复工作区：`/Users/myhloli/.codex/worktrees/rust-stage18-22-repair/docvortex`，从 `main@efc7bad2070fbfb8a442910ff084917ecef93f66` 创建，当前为 detached HEAD，改动尚未提交。所有后续命令明确以此目录为 `workdir`；不要改动原仓工作区。
+- 阶段 20 消融的 Python 包装持有变体：`/Users/myhloli/.codex/worktrees/rust-stage20-wrapper/docvortex`。它与消融时主修复版只在 textpage 调用链不同，两个变体分别独立构建协议 29 扩展。消融已完成，不再用它作为最终候选。
+- `v0.5.7@5d2162a` 独立对照：`/Users/myhloli/.codex/worktrees/rust-stage057-baseline/docvortex`，已构建并实际命中 Rust 私有协议 24。最终修复版已重新构建并实际命中协议 29，扩展 SHA-256 为 `a7e86593dc078d50bbe3fe52cad5ca1154453a7e5daeeb41a507cbaac1a24029`。
+- 主要报告：[rust-pdf-stage18-22-repair.md](rust-pdf-stage18-22-repair.md)。消融结果已填入，最终性能和完整验证仍标注待完成。完整机器证据在主修复工作区的 `output/pdf/rust-stage18-22-repair/`，该目录被 Git 忽略。
+- 用户要求所有新增函数／测试辅助方法有中文注释。已按此执行；后续新增函数继续遵守。Python 环境为 `/Users/myhloli/projects/20240809magic_pdf/Magic-PDF/.venv4/bin/python`（CPython 3.14.4，pypdfium2 5.13.0）。MinerU 源码固定为 `/Users/myhloli/projects/20240809magic_pdf/Magic-PDF@f504cff8b07776760c673023fab8847085158be0`，其原有未跟踪 `examples/` 不要改动。
+
+## 已完成实现
+
+1. 阶段 19：开放四角填充 Path 使用宿主 Python `round(x, 3)`；颜色查询失败保留 `fill_rgba=None`，仅可见性判断把未知 alpha 按 255 处理。真实 PDF 差分检查绘图线、Path 摘要和页面矢量结果。
+2. 阶段 21：自有几何证据分别保存原始字号与 run 分组的取整字号；样式阈值仅用原始字号；Unicode 锚点判定独立缓存 `_is_anchor_text` 结果，不由 `script_group` 推断。新增字号 9.9／10.1 和日文中点 `・` 差分。
+3. 阶段 22：`Bbox` 快路径先验证内部列表长度、确切 float 类型和有限性，再比较坐标；覆盖 `None` 与可转换字符串。
+4. Python 与 Rust 私有协议同步升至 29；旧协议 28 在 `auto` 下回退、显式 `rust` 下报错的测试已加入。
+5. 阶段 20 消融后按预定门槛回退页面级 Rust textpage 生命周期迁移：已删除 Rust `read_pdfium_page_text_snapshot` 注册及实现、Python 页面级 bridge，恢复 Python 包装持有 textpage 并调用 `read_text_snapshot(textpage, …)`；保留有效的字符几何物化优化。生命周期测试改为验证 Python 包装在快照后关闭。
+
+## 已完成验证与消融
+
+- 最终回退形态的定向 Rust 后端测试：**264 passed**；Cargo workspace tests、Clippy `-D warnings`、rustfmt、改动文件 Ruff check、`git diff --check` 均通过。此前针对回退调用链的 45 项定向测试也通过。完整 Rust／Python 后端 pytest、全仓 Ruff、ABI3 wheel 独立 Python 3.14 安装验证仍未做。
+- 阶段 20 消融：公开 32 PDF 三轮 Rust 持有相对 Python 包装持有改善 `+0.147%、+0.015%、+0.056%`，中位 `+0.056%`；Flash 31 eligible 为 `+0.147%、−0.251%、−0.036%`，中位 `−0.036%`；medium shared 32 PDF 为 `+0.707%、−0.118%、−1.329%`，中位 `−0.118%`。各轮完整输出均一致，没有反序复测仍超过 5% 的单文档退化或超过 130% 的 RSS。没有链路达到“中位改善至少 1% 且三轮均改善”，因此回退。详细逐文档比率、哈希、协议及 RSS 在 `ablation-public/`、`ablation-flash/`、`ablation-shared/` 的 `report.json`。
+
+## 历史暂停点：最终版对 v0.5.7
+
+恢复说明：已重新核对协议 24／29 与扩展 SHA。为避免跨暂停间隔组成一对，`demo4.pdf` 已完成的基线计时和内存目录另存为 `first.before-pause`／`first-memory.before-pause`（对应日志和配置同样另存），整对重新测量。前六份完整配对保留；公开链路三轮验收已恢复。
+
+- 最终公开 parse 三轮配对已启动，**仅第一轮前 6／32 份完成**；这 6 份完整输出均一致，实际扩展协议为基线 24／最终版 29。进度为 `output/pdf/rust-stage18-22-repair/final-public/progress.json`；原日志 `final-public.log` 包含人为 `KeyboardInterrupt` 尾迹，属于暂停操作，不是算法错误。
+- 第 7 份 `demo4.pdf` 的基线计时与 RSS 已完成；最终版计时当时尚未生成正式结果。该未完成目录和日志已保留为 `final-public/round-1/06-demo4/second-interrupted/` 与 `second-interrupted.log`，原 `second/` 路径已腾空。配对脚本支持从已完成的计时／内存报告恢复；不要删除已完成证据。
+- 运行中的父进程已收到 SIGINT，检查时无 `paired_compare.py`、`rust_pdf.py` 或 `pdf_memory.py` 残留进程。恢复前可再用 `ps` 确认。
+
+恢复公开链路（在主修复工作区运行；日志用追加，保留暂停记录）：
+
+```sh
+/Users/myhloli/projects/20240809magic_pdf/Magic-PDF/.venv4/bin/python output/pdf/rust-stage18-22-repair/paired_compare.py \
+  --first /Users/myhloli/.codex/worktrees/rust-stage057-baseline/docvortex \
+  --second /Users/myhloli/.codex/worktrees/rust-stage18-22-repair/docvortex \
+  --suite public --rounds 3 --output output/pdf/rust-stage18-22-repair/final-public \
+  >> output/pdf/rust-stage18-22-repair/final-public.log 2>&1
+```
+
+之后使用同一命令将 `--suite`／`--output` 分别改为 `flash`／`final-flash`、`shared`／`final-shared`，相应日志名也改为 `final-flash.log`、`final-shared.log`。三条链路勿并行，避免计时互相干扰。`paired_compare.py` 每文档各变体预热一次、热运行五次，逐轮平衡 AB／BA，独立进程树 RSS，超 5% 耗时或 130% RSS 自动反序复测；`shared` 使用同一冻结模型录制。
+
+## 暂停时的剩余任务（现已全部完成）
+
+1. 完成三条最终对照的三轮完整语料；核对每轮总耗时、逐文档比率、进程树 RSS、完整输出哈希和真实协议。若任何完整输出不同，逐字段解释；若某链路有可重复净退化，定位并回退相关优化后重新验收。本轮不以原定 2 倍目标为验收条件。
+2. 对最终形态运行 Rust 与 Python 后端的相关及完整 pytest、Cargo tests、Clippy、rustfmt、Ruff，并保留日志和准确计数。定向 264 项和 Cargo／Clippy 已过，源码变化后要按实际需要复测。
+3. 构建协议 29 的 ABI3 wheel，在独立 CPython 3.14 环境中安装并证明 `auto`／`rust` 实际命中扩展；核对输出。可参考旧阶段报告中的 wheel 验证方法，但要记录当前 wheel 的真实 SHA 和协议。
+4. 将最终配对、差异裁决、完整测试、wheel 验证和剩余风险写入 [rust-pdf-stage18-22-repair.md](rust-pdf-stage18-22-repair.md)，保留原阶段报告为历史。最后检查 `git diff --check` 与工作区状态；当前未提交、未推送、未建 PR、未发布。

docvortex-0.5.8/docs/rust-pdf-stage18-22-repair.md

@@ -0,0 +1,116 @@
+# Rust 阶段 18～22 行为修复与性能复验
+
+## 范围与基线
+
+本轮从 `main@efc7bad` 出发，修复阶段 19、21、22 已复现的五处 Python/Rust 差异；单独消融阶段 20 的 textpage 生命周期迁移，并与 `v0.5.7@5d2162a` 重新做完整语料配对对照。原阶段报告保留为历史记录，原定 2 倍目标不作为本轮验收条件。
+
+## 行为修复
+
+- 开放四点填充 Path 的角点按宿主 `round(x, 3)` 判断，修复临界坐标下 Rust 漏掉绘图线的问题。颜色查询失败时，Path 摘要保留 `fill_rgba=None`；可见性仍按未知 alpha 为 255 判断。
+- 自有几何证据分别保留 PDFium 原始字号与字体 run 分组所用的四分之一取整字号。样式风险阈值只消费原始字号；锚点由参考实现的 Unicode 字母／数字、可打印且非空白规则独立判断，不能由 `script_group` 推导。
+- `Bbox` 快路径先校验内部列表长度、元素确切类型和有限性，再比较坐标；不满足条件的输入继续走通用转换。
+- Python 与 Rust 私有协议同步升至 29。旧协议 28 在 `auto` 下回退，在显式 `rust` 下报告扩展不兼容。公开 SDK、输出 schema 与后端选择保持原状。
+
+回归差分覆盖开放 Path 的舍入边界、颜色查询失败、字号 9.9/10.1 的双向样式风险、日文中点 `・` 的布局锚点以及含 `None`、可转换字符串的 `Bbox`。定向 Rust 测试与 Cargo workspace tests、Clippy、rustfmt、Ruff 检查已通过；完整验收状态和计数见下文。
+
+| 已复现差异 | 回归输入与修复后的行为 |
+| --- | --- |
+| 开放 Path 舍入 | 角点 `20.0625` 与 `20.062498` 使用宿主三位舍入后归入同一 x 坐标；绘图线、Path 信息和页面矢量结果逐字段一致。 |
+| 填充颜色失败 | 以真实 C ABI 回调返回失败；仍判为可见，`fill_rgba=None` 与参考一致，下游不误认为存在可见非白填充。 |
+| 字号阈值 | 字号 `9.9`／行高 `14.925` 应有样式风险，字号 `10.1`／行高 `15.075` 应无风险；两页差分覆盖取整导致的漏报和误报。 |
+| 日文中点锚点 | 六个真实 PDF 字符 `・` 归入 cjk 组，但不是 Unicode 字母／数字；布局风险与参考一致。 |
+| Bbox 异常类型 | 内部含 `None` 时走通用转换并返回无效结果，可转换字符串坐标按原逻辑转换，均不在快路径比较时抛出类型错误。 |
+
+## 阶段 20 消融
+
+两个独立构建使用同一修复源码与协议 29；只切换调用链中 textpage 由 Rust 加载／关闭，还是由 Python 包装持有。32 份公开 PDF、31 份 eligible Flash 和 32 份冻结 medium shared 样本分别进行三轮配对；每轮逐文档平衡 AB／BA，每个变体独立预热一次、热运行五次。进程树 RSS 在独立进程采样，完整输出逐样本核对。只有某链路总耗时中位改善至少 1%、该链路三轮均改善，且无反序复测仍超过 5% 的单文档退化或超过 130% 的资源占用，才保留 Rust 生命周期迁移。
+
+总耗时以每文档五次热运行的中位数求和，表中“改善”均为 Rust 持有相对 Python 包装持有的变化：
+
+| 链路 | 轮次 | Python 包装持有 | Rust 持有 | 改善 | 输出一致 |
+| --- | ---: | ---: | ---: | ---: | :---: |
+| 公开 parse，32 PDF | 1 | 13.895563 s | 13.875193 s | +0.147% | 是 |
+| | 2 | 13.922553 s | 13.920490 s | +0.015% | 是 |
+| | 3 | 14.072387 s | 14.064450 s | +0.056% | 是 |
+| Flash，31 eligible | 1 | 13.909381 s | 13.888866 s | +0.147% | 是 |
+| | 2 | 13.823132 s | 13.857865 s | −0.251% | 是 |
+| | 3 | 13.813139 s | 13.818152 s | −0.036% | 是 |
+| medium shared，32 PDF | 1 | 14.614840 s | 14.511583 s | +0.707% | 是 |
+| | 2 | 14.539901 s | 14.557028 s | −0.118% | 是 |
+| | 3 | 14.692728 s | 14.887990 s | −1.329% | 是 |
+
+三条链路改善中位数依次为 **+0.056%、−0.036%、−0.118%**，没有一条满足预设 1% 与三轮同向的保留条件。初测超过 5% 的样本均执行反序复测，没有持续超限：公开 `demo4.pdf` 为 `1.1301 → 0.9826`；Flash 两份分别为 `1.0552 → 1.0227`、`1.0600 → 0.9931`；shared 三份分别为 `1.0887 → 1.0078`、`1.0986 → 0.9846`、`1.0644 → 0.9814`。三条链路最大 RSS 比率为 `1.1599`、`1.0029`、`1.1211`，均低于 130%。两构建均实际命中协议 29，逐文档完整结果一致。依照预先确定的规则，**移除页面级 Rust 加载入口并恢复 `read_text_snapshot(textpage, …)` 调用链**；保留字符几何物化改进。
+
+## 最终版本相对 v0.5.7
+
+两版使用同一 CPython 3.14、PDFium、MinerU 源码和冻结模型录制；三条链路均逐文档双向配对，分别预热一次、热运行五次，RSS 独立进程树采样。逐轮总耗时、逐文档比率、完整输出哈希、实际扩展协议与源指纹保存在证据目录。完整输出差异须逐项解释，不因速度改善而放行。
+
+公开 parse 比较 model、middle、诊断和全部素材摘要；Flash／shared 比较完整业务返回值，仅去除每次运行必变的 `elapsed` 计时字段。文本、字号、坐标、页面、模型结果及素材字段均不忽略。shared 只回放模型调用边界，分类、栅格化、文本与表格证据、素材及页面几何仍执行真实入口。
+
+三条链路均已完成三轮，完整输出均一致。总耗时采用逐文档热运行中位数之和：
+
+| 链路 | 轮次 | v0.5.7 | 最终修复版 | 改善 | 输出一致 |
+| --- | ---: | ---: | ---: | ---: | :---: |
+| 公开 parse，32 PDF | 1 | 16.104086 s | 14.589224 s | +9.407% | 是 |
+| | 2 | 15.412777 s | 13.911730 s | +9.739% | 是 |
+| | 3 | 15.722997 s | 14.233506 s | +9.473% | 是 |
+| Flash，31 eligible | 1 | 15.547422 s | 13.892804 s | +10.642% | 是 |
+| | 2 | 15.408338 s | 13.835638 s | +10.207% | 是 |
+| | 3 | 15.410612 s | 13.867554 s | +10.013% | 是 |
+| medium shared，32 PDF | 1 | 15.997826 s | 15.180352 s | +5.110% | 是 |
+| | 2 | 15.859730 s | 15.246385 s | +3.867% | 是 |
+| | 3 | 15.955903 s | 15.259034 s | +4.367% | 是 |
+
+公开链路改善中位数为 **9.473%**，96 对输出全部一致，最高 RSS 比率为 `1.044127`；Flash 为 **10.207%**，93 对 eligible 输出全部一致，最高 RSS 比率为 `1.043778`；shared 为 **4.367%**，96 对输出全部一致，最高 RSS 比率为 `1.024588`。公开与 Flash 未触发反序复测；shared 的 `flash_table_annotations_synthetic.pdf` 第二轮初测 `1.119975`，反序为 `0.880830`，第三轮初测 `1.061502`，反序为 `1.022380`，均未形成持续退化，复测输出也一致。三个链路的三轮总耗时均改善，资源均低于 130%，没有可重复净退化，因此不追加回退。
+
+`small_ocr.pdf` 在两版 Flash 中均分类为 OCR，每轮排除，31 份 eligible 集合稳定；在 medium shared 中正常测量。285 对正式配对及 2 对反序复测业务输出全部一致，没有需要解释或豁免的业务字段差异。实际命中协议与源码／扩展指纹跨文档、跨三条链路和三轮均保持稳定，见 `final-audit.json`。
+
+计时之外，32 份 shared 文档在基线与修复版各执行一次独立严格输入审计（一次预热、一次检查调用），验证每个模型事件的数组／图像像素、参数类型、标量及顺序与冻结录制一致，且消费全部事件。**64 个构建／文档审计全部通过**，输出同时与正式计时产物一致；这些带输入哈希的运行明确标为 `timing_eligible=False`，不计入性能数字，见 `model-input-audit.json`。
+
+## 测试与 wheel 验证
+
+| 验证 | 结果 |
+| --- | --- |
+| 源码 Rust 相关回归 | 264 passed |
+| 源码 Python 相关回归 | 120 passed / 144 skipped（Rust 专属差分与接口用例不在 Python 模式运行） |
+| Rust/session 完整 pytest，4 workers | 5479 passed / 14 skipped，46.87 s |
+| Python/legacy 完整 pytest，4 workers | 4765 passed / 728 skipped，81.73 s |
+| Cargo workspace tests，`--locked` | 15 passed，0 failed |
+| Clippy，`--workspace --all-targets -- -D warnings` | 通过 |
+| rustfmt，`--all --check` | 通过 |
+| Ruff check 全仓及五份证据脚本 | 通过 |
+| Ruff format check，全部 src 与五份修改测试 | 406 files already formatted |
+| 独立安装 wheel 的相关回归 | 264 passed，5.19 s |
+| `git diff --check` | 通过 |
+
+完整 pytest 没有 deselect 用例，包括 CI 单列诊断的少线表 manifest 测试。两种后端各有 6 个 WMF／Pillow 相关警告，均无失败。Rust 完整测试的 14 个跳过与阶段 22 历史验收计数相同；本轮新增的 Rust 行为差分全部执行通过。
+
+构建产物为 `docvortex-0.5.7-cp310-abi3-macosx_11_0_arm64.whl`，实际 WHEEL tag 为 `cp310-abi3-macosx_11_0_arm64`，wheel SHA-256 为 `63f5327fb7f4b3c835923644fd750347eea7c161264092049784016925cb9d6c`。wheel 内扩展 SHA 与最终性能测试扩展完全相同：`a7e86593dc078d50bbe3fe52cad5ca1154453a7e5daeeb41a507cbaac1a24029`。
+
+在新建 CPython 3.14.4 venv 中安装 wheel 及完整依赖，清除 `PYTHONPATH`，不引入 `.venv4` 的 site-packages；包和扩展均实际从该 venv 加载。`demo1.pdf` 的 Python／Rust 完整解析输出一致，`auto`／显式 `rust` 均实际命中协议 **29**，各记录 13 次文本快照命中，两者输出一致，且页面级 Rust textpage 加载接口已不存在。安装环境另执行本轮相关回归 264 项全部通过，详见 `wheel-audit.json`、`wheel-auto-protocol.json`、`wheel-rust-protocol.json` 与 `wheel-regression-tests.log`。在线依赖安装的 TLS 连接中断后，使用本机 uv 缓存离线安装成功，未改变验收用 `.venv4` 环境。
+
+## 环境与证据
+
+测试环境为 macOS 26.6.2 arm64、CPython 3.14.4、pypdfium2 5.13.0、PDFium 153.0.7999.0、Pydantic 2.13.5、NumPy 2.5.3、ONNX Runtime 1.30.0。同一 PDFium 动态库 SHA-256 为 `33c98063af28c0b7cbf8227f4422bf5c15942df2455cf7f0a5dce3dc601d52b0`。MinerU 源码固定为 `f504cff8b07776760c673023fab8847085158be0`。基线实际命中协议 24，最终版实际命中协议 29。
+
+| 构建 | 源码及构建配置 SHA-256 | 扩展 SHA-256 |
+| --- | --- | --- |
+| v0.5.7 | `16d875a36632a37279125c26a52b6eac0392954f02ecd25fd2b334ee713f782c` | `9449a4ca67394f24f446b49de4de0f769a7ac15757db48b39f156a3401f11ad1` |
+| 最终修复版 | `4d3e87afd3692566bb3f7ab12e5e1eb972c1aeb572a721a3dc09d70728d3048b` | `a7e86593dc078d50bbe3fe52cad5ca1154453a7e5daeeb41a507cbaac1a24029` |
+
+`environment.json` 保存依赖版本、语料和冻结模型录制清单的哈希；`paired_compare.py` 与 `audit_reports.py` 保存运行和复核方法。`ablation-wrapper.patch`／`ablation-rust-owned.patch` 可在 `efc7bad` 上重建消融两变体，其间只有 textpage 调用链不同；原逐文档报告记录各变体实际扩展指纹。
+
+恢复时保留前六份已经完整结束的配对，暂停中断的 `demo4.pdf` 整对重新测量。中断目录与日志另存，未计入正式结果。
+
+修复工作区为 `/Users/myhloli/.codex/worktrees/rust-stage18-22-repair/docvortex`；独立基线为 `/Users/myhloli/.codex/worktrees/rust-stage057-baseline/docvortex`；消融包装变体为 `/Users/myhloli/.codex/worktrees/rust-stage20-wrapper/docvortex`。原仓工作区保持干净，原阶段报告未修改。本报告记录 0.5.8 发版前的修复验收；随后提交、推送及发布状态以 main 历史、`v0.5.8` 标签和 GitHub Release／PyPI 为准。验收期间的包版本仍为 0.5.7，发版仅更改版本元数据。
+
+证据目录：`output/pdf/rust-stage18-22-repair/`（被 Git 忽略，保留在修复工作区）。全量测试、静态检查、输入审计、构建及安装日志均在该目录。复验配对可运行：
+
+```sh
+/Users/myhloli/projects/20240809magic_pdf/Magic-PDF/.venv4/bin/python output/pdf/rust-stage18-22-repair/paired_compare.py \
+  --first /Users/myhloli/.codex/worktrees/rust-stage057-baseline/docvortex \
+  --second /Users/myhloli/.codex/worktrees/rust-stage18-22-repair/docvortex \
+  --suite public --rounds 3 --output output/pdf/rust-stage18-22-repair/recheck-public
+```
+
+Flash／shared 将 suite 和新输出目录对应改为 `flash`／`recheck-flash`、`shared`／`recheck-shared`，三条链路串行运行。已有正式报告由 `audit_reports.py --group final` 复核；冻结模型输入由 `audit_model_inputs.py` 复核。性能数字是上述冻结模型环境中的端到端对照，本轮未达到或宣称达到原定 2 倍目标。

docvortex-0.5.8/docs/rust-pdf-stage18-evidence.md

@@ -0,0 +1,37 @@
+# PDF 原生内核阶段 18：文本可见性与证据复用
+
+## 实现边界
+
+私有协议 25 将 Flash 可见文本对象遍历、render mode、颜色 alpha 和裁剪转换合并到一次 Rust 读取。颜色读取失败仍按 Python 参考语义处理为 alpha 255；模式 3/7 隐藏；空裁剪置不可见；ABI、非标准页面对象或扩展能力不匹配时整页回退参考实现。`bridge_info()` 新增 `pdfium_text_visibility_bridge_calls` 与回退原因，公开 `auto|python|rust` 和渲染选择不变。
+
+自有视觉证据减少临时复制：`statistics::typography()` 直接借用字体族数组，median 输入不再克隆切片；视觉 run 的成员、bbox、字体 ID 和字重集合按容量预分配；Rust 预计算正数字体尺寸中位数并随私有 metrics 传给 `_LineItem`，后续上下标配对不再逐字符重扫 Python 字典。该缓存字段不参与数据类相等比较，公共输出形状不变。
+
+Path 双侧消费改为 `_path_object_evidence()`：每个 Path 只读取一次绘制状态、描边宽和原始子路径，只执行一次对象到页面视觉坐标转换，同时生成绘图线候选与 `PDFPathInfo`。独立入口保留，测试注入的非标准提取器仍走旧分支；单个损坏 Path 继续被隔离。本阶段没有迁移链接判断、复杂 Path 全量算法或最终 Flash 规则。
+
+## 验证
+
+- 新增/更新的焦点检查覆盖 TEXT 可见性与 Python 参考在 0/90/180/270、嵌套 Form、裁剪、ABI 回退、错误传播和无效地址下逐字段一致；Path 联合消费确认每对象绘制状态只读取一次；字号缓存验证异常值回退。
+- Rust/session 完整测试：5473 passed / 1 skipped。Python/legacy 参考完整测试：4768 passed / 706 skipped。Cargo workspace tests、Clippy `-D warnings`、rustfmt、Ruff check/format 均通过。
+- 32 PDF／299 页公开回放各两次，基线 `5d2162a` 与候选完整 ModelJson、MiddleJson、素材哈希、诊断逐字段一致；候选 598 次实际命中 Rust TEXT visibility，无回退。
+- MinerU 当前 `dev@ee87e8e`：31 份 eligible Flash 文本完整输出一致；32 份实际 medium 共享链路完整输出一致。共享链路沿用 Stage 5 真实模型调用录制，但不再把候选输出强制比作 0.5.2 前录制哈希，而是直接比较当前 0.5.7 基线与候选输出。
+- ABI3 wheel 构建为 `docvortex-0.5.7-cp310-abi3-macosx_11_0_arm64.whl`；CPython 3.14 ABI/kernel 检查通过，独立安装环境中 Python/auto 与 Rust 输出一致。最终源码扩展与 wheel 二进制 SHA-256 均为 `60fad12cebd42332cbc436091de3c7a169b8f4b1ca02ba6ebb20d4a02abf1371`。
+
+## 性能与资源
+
+所有正式计时为每文档一次预热、五次热运行，基线/候选按文档交替，并独立采样进程树 RSS。结果仅代表本机与当前 PDFium 环境。
+
+| 链路 | 基线合计 | 候选合计 | 降幅 | 最大单档结果 |
+| --- | ---: | ---: | ---: | --- |
+| DocVortex 公开 parse，32 PDF | 15.621533 s | 15.318385 s | 1.94% | 耗时 1.0309；RSS 1.0023 |
+| MinerU Flash 文本，31 PDF | 15.698599 s | 15.233064 s | 2.97% | RSS 1.0084 |
+| MinerU medium 共享，32 PDF | 14.827323 s | 14.760071 s | 0.45% | 首轮耗时 1.0754，反序 1.0113，非持续 |
+
+公开 parse 首轮最大耗时退化 3.09%、最大 RSS 增加 0.23%，均低于 5% 持续门槛。共享链路 `caibao1.pdf` 和 `fund_manager_profile_table.pdf` 首轮超过 5% 后反序复测分别降至 1.13% 和 2.19%，判为非持续；`pollutant_discharge_tables.pdf` RSS 为基线 104.28%，低于既有 130% 资源门槛。八样本焦点集公开 parse 合计降低 3.38%。
+
+来源收集独立诊断显示：`_extract_owned_text_snapshot` 从 0.8347 s 降至 0.5448 s，`_extract_page_paths_and_lines` 从 0.4046 s 降至 0.3354 s，`_build_native_line_items_from_records` 从 0.1507 s 降至 0.1043 s，全阶段 `_collect_document_sources` 从 0.7928 s 降至 0.7514 s。单次 cProfile 不替代正式中位数。
+
+## 下一批优先级
+
+候选 cProfile 中最大项仍是 `NativeTextSnapshot.prepare_visual_evidence()`（约 0.693 s）、Path 联合证据（约 0.489 s）和原始 text snapshot 读取（约 0.347 s）。下一轮应先细分 `prepare_visual_evidence()` 内的字体归一化、Unicode 属性、行分组和最终 Python 物化，再将 Path 子路径/属性批量化；继续保留同一 PDFium 库和串行调用边界，不凭阶段总量预设可消除成本。
+
+证据目录为 `output/pdf/native-kernel-20260929-stage18/`。分支未合并、未发布；原始 2 倍目标仍未完成。

docvortex-0.5.8/docs/rust-pdf-stage19-evidence.md

@@ -0,0 +1,40 @@
+# PDF 原生内核阶段 19：Path 双侧证据批量化
+
+## 实现边界
+
+本阶段以已完成的 Stage 18 分支提交 `634aabe` 为基线，不重做 TEXT 可见性、render-session、tight spacing 或 Stage 18 的视觉证据复用。私有协议从 25 升到 26，公开 `auto|python|rust` 和渲染 `auto|legacy|session` 选择保持不变；旧扩展在 `auto` 下仍显式回退，`rust` 下继续报协议不匹配。
+
+新增原生 Path evidence bridge：一次遍历页面/Form 内全部 PATH 叶子，复用同一组 PDFium 函数指针，批量读取子路径、绘制状态、填充/描边颜色、描边宽、Form 矩阵与累积裁剪。Rust 内一次完成对象坐标到页面视觉坐标转换，同时产出未合并绘图线和 `PDFPathInfo`；Python 只物化公开 dataclass 并保留既有共线合并规则。描边宽度中的 `hypot` 调用绑定当前解释器的 `math.hypot`，避免跨实现最后一位的浮点差异。颜色读取失败沿用 alpha 255；损坏 Path 段按参考实现跳过；ABI、非标准页面或旧扩展缺失时整页回退既有 Python 参考。诊断新增 `pdfium_path_evidence_bridge_calls` 与回退原因。
+
+`NativeTextSnapshot.prepare_visual_evidence()` 增加仅在 `DOCVORTEX_PROFILE_VISUAL_EVIDENCE` 显式开启时累计的阶段计时，可区分字体归一化、Unicode 属性、视觉 run、字符几何物化和最终 run 物化。正式路径不输出计时，不改变公共 SDK、输出 schema 或行/字符成员关系。
+
+## 验证
+
+- Path 联合证据新增原生/Python 参考逐字段且按顺序一致的差分；Python 双消费测试继续禁用原生桥接，验证每个对象解码一次；原生桥接报告区分真实执行与回退。
+- 32 PDF／299 页逐页调用原生 Path evidence 后强制走 Python 参考：绘图线与 `PDFPathInfo` 全量相等，原生命中 299 次、无回退。
+- 32 PDF／299 页公开回放各两次，Stage 18 `634aabe` 与本阶段完整 ModelJson、MiddleJson、素材哈希和诊断摘要全部一致。
+- MinerU 当前 `dev@ee87e8e`：31 份 eligible Flash 文本完整输出一致；32 份实际 medium 共享链路完整输出一致。共享链路继续直接比较当前双源输出，不误称匹配 Stage 5 旧录制哈希。
+- Rust/session 完整测试：5474 passed / 1 skipped。Python/legacy 完整测试：4769 passed / 706 skipped。Cargo workspace tests、Clippy `-D warnings`、rustfmt、Ruff check 和改动文件 format check 均通过。
+- ABI3 wheel 构建为 `docvortex-0.5.7-cp310-abi3-macosx_11_0_arm64.whl`；独立安装环境中 CPython 3.14 的 Python/auto 与 Rust 输出一致，协议 26，Path bridge 实际命中。源码扩展与 wheel 扩展 SHA-256 均为 `f6dcdb5654cd30c3617aecbc22fd57ec3c1a49b8aa6d1e13ef2e3df062ec0ab2`。
+
+## 性能与资源
+
+正式计时均为每文档一次预热、五次热运行；公开 parse 按文档先基线后候选交替执行，MinerU 按文档交替方向执行，并另用独立进程采样进程树 RSS。结果仅代表本机语料与当前 PDFium 环境。
+
+| 链路 | Stage 18 基线 | Stage 19 候选 | 降幅 | 最大单档结果 |
+| --- | ---: | ---: | ---: | --- |
+| DocVortex 公开 parse，32 PDF | 15.484642 s | 15.202684 s | 1.82% | 耗时 1.0020；RSS 1.0330 |
+| MinerU Flash 文本，31 PDF | 15.335368 s | 15.045106 s | 1.89% | 耗时 1.0266；RSS 1.0165 |
+| MinerU medium 共享，32 PDF | 15.531999 s | 14.566413 s | 6.22% | 耗时 1.0411；RSS 1.0142 |
+
+公开 parse 无任何首轮超过 5% 的耗时退化；最大耗时比率 0.20%，最大 RSS 增加 3.30%，低于持续退化与资源门槛。Flash 最大耗时比率 2.66%，无持续退化；medium 最大首轮耗时比率 4.11%，未触发反序复测。完整输出均相等。
+
+同一 32 PDF cProfile 对照显示，`_extract_page_paths_and_lines()` 从 0.940791 s 降至 0.129739 s（约 86.2%）；Stage 18 的 `_path_object_evidence()` 逐对象热点在本阶段候选中消失。`_collect_document_sources()` 从 4.119941 s 降至 3.171536 s。单次 cProfile 不替代正式中位数。
+
+对八样本焦点集显式开启 `DOCVORTEX_PROFILE_VISUAL_EVIDENCE` 后，161 次调用累计：字体准备 0.008330 s、Unicode 属性 0.043204 s、视觉 run 0.041006 s、字符几何物化 0.257527 s、最终 run 物化 0.008681 s，总耗时 0.319887 s。字符几何物化约占 80.5%，是 Stage 20 的首要候选；原始 text snapshot 读取约 0.349 s 仍是第二大候选。
+
+## 后续状态
+
+- 原始 2 倍性能目标仍未完成；本报告不把正确性或单阶段收益表述为该目标完成。
+- Stage 20 不应继续扩大 Path 范围。优先研究延迟/分批物化 `PDFPageTextGeometry.chars`，并细分 `Bbox`/字典构造与后续消费者是否可共享原生字符对象；其次研究直接持有 PDFium textpage 的原生 snapshot 读取。
+- 证据目录为 `output/pdf/native-kernel-20260929-stage19/`。本阶段分支不自动合并、发版或发布 PyPI。

docvortex-0.5.8/docs/rust-pdf-stage20-evidence.md

@@ -0,0 +1,37 @@
+# PDF 原生内核阶段 20：textpage 生命周期与字符几何物化
+
+## 实现边界
+
+本阶段以 Stage 19 提交 `be0b1a1` 为基线，只处理 Stage 19 报告确认的两个候选，不继续扩大 Path 迁移。私有协议从 26 升到 27；公开 `auto|python|rust` 计算选择和 `auto|legacy|session` 渲染选择保持不变。旧扩展在 `auto` 下仍显式回退，`rust` 下继续报协议不匹配。
+
+新增页面级自有文本快照入口：Python 仅核验 `FPDFText_LoadPage`、`FPDFText_ClosePage`、`FPDFText_CountChars` 与既有字符/颜色函数 ABI，并把当前同库 page 句柄交给 Rust；Rust 在宿主 PDFium 锁内短暂加载、计数、读取并关闭 textpage，产物仍只保存纯数值，不延长 PDFium 句柄生命周期。原 textpage 参数入口保留为兼容测试和参考路径；非标准 page、旧扩展、ABI 不匹配或异常数值时继续返回能力选择并走既有 Python 参考。
+
+`NativeTextSnapshot.geometry()` 的兼容 Python 字符物化保留完整字典形状、插入顺序和可变语义，同时减少重复工作：字体字典按 Rust 字体索引一次构建，字段名一次缓存，bbox 输入直接构造列表，origin/loose/tight 坐标一次转换为 Python 对象并由字符字段和对应侧表共享同一对象。公开 `PDFPageTextGeometry.chars`、tight/loose/origin 字典、行成员身份、pickle 结果和独立副本行为不变。
+
+## 验证
+
+- 新增页面级 textpage 入口与既有 textpage 入口的完整快照等价测试，覆盖真实加载/关闭路径和命中诊断；协议注册测试更新到 27。
+- 32 PDF／299 页公开输出双跑 Stage 20 后与 Stage 19 保存的完整 ModelJson、MiddleJson、素材哈希和诊断逐字段一致，报告为 `public-correctness.json`。
+- MinerU 当前 `dev@f504cff`：31 份 eligible Flash 文本完整输出一致；32 份实际 medium shared 完整输出一致。未修改 MinerU，未跟踪 `examples/` 保持原状。
+- Rust/session 完整测试：5475 passed / 1 skipped。Python/legacy 完整测试：4769 passed / 707 skipped。Cargo workspace tests、Clippy `-D warnings`、rustfmt、Ruff check 和改动文件 format check 均通过。
+- ABI3 wheel 为 `docvortex-0.5.7-cp310-abi3-macosx_11_0_arm64.whl`。在 CPython 3.14 独立依赖环境中，DocVortex 核心路径和 MinerU Flash 文本路径的 `auto|rust` 输出一致，协议 27，页面级 bridge 可调用。源码扩展与 wheel 扩展 SHA-256 均为 `77c16ff6c926daea4b8ec631f192ba0f3593791cd885391cbe13d4cdf6d862d8`。
+
+## 性能与资源
+
+正式计时均为每文档一次预热、五次热运行；公开 parse 按文档先基线后候选，MinerU 按文档交替方向执行，RSS 使用独立进程树采样。结果仅代表本机语料与当前 PDFium 环境，不外推托管环境。
+
+| 链路 | Stage 19 基线 | Stage 20 候选 | 降幅 | 首轮最大耗时比 | 首轮最大 RSS 比 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| DocVortex 公开 parse，32 PDF | 14.966399 s | 14.923734 s | 0.29% | 1.06446 | 1.00480 |
+| MinerU Flash 文本，31 PDF | 14.827657 s | 14.759856 s | 0.46% | 1.02284 | 1.00549 |
+| MinerU medium shared，32 PDF | 14.738283 s | 14.601869 s | 0.93% | 1.07333 | 1.12712 |
+
+首轮超过 5% 耗时的样本均反序复测：公开 parse 的 `annual_report_management_roles_table.pdf` 复测比 0.99650；shared 的 `demo2.pdf`、`mixed_elements_pages_03_06.pdf`、`中文论文3.pdf` 复测比分别为 1.01313、1.00109、0.97148。shared 首轮唯一 RSS 超过 5% 的 `mixed_text_layout_sample.pdf.xor` 反序复测比为 1.02646。所有退化均未持续超过 5%，完整输出均相等。
+
+诊断层面，同一 32 PDF cProfile 中 `prepare_visual_evidence()` 从 0.703 s 降至 0.612 s；八样本焦点集的字符几何物化阶段从 Stage 19 记录的 0.257527 s 降至 0.226503 s（约 12.0%）。页面级 snapshot 在该焦点集实际执行 161 次、无回退。`_extract_owned_text_snapshot()` 本轮约为 0.529 s，与 Stage 19 的 0.525 s 接近，说明 textpage Python 包装不是原始快照的主要成本；后续应把字符 FFI 读取和规范化本身作为 Stage 21 候选。
+
+## 后续状态
+
+- 原始 2 倍性能目标仍未完成；本报告不把正确性或小幅实际收益表述为该目标完成。
+- Stage 21 不应继续优化 textpage 包装层。剩余更大热点包括 `_detect_table_candidates()`／表格物化、`_document_requires_full_geometry()` 的逐行 Python 输入打包，以及 `_plain_source_records()`；应在新的 profile 基础上选择下一批批量迁移。
+- 证据目录为 `output/pdf/native-kernel-20260929-stage20/`。本阶段分支不自动合并、发版或发布 PyPI。

docvortex-0.5.8/docs/rust-pdf-stage21-evidence.md

@@ -0,0 +1,55 @@
+# PDF 原生内核阶段 21：表格脚本与全文几何边界批量化
+
+## 实现边界
+
+本阶段以 Stage 20 提交 `d504c5e` 为基线，不再继续 textpage 或 Path 迁移。私有协议从 27 升到 28；公开 `auto|python|rust` 计算选择、`auto|legacy|session` 渲染选择、公共 SDK 和输出 schema 均保持不变。
+
+表格 HTML 物化复用页面级 `NativeScriptEvidence`：`_collect_document_sources()` 已生成的 owned 身份映射继续传入表格恢复链路。普通 0 度、无 fraction/inline 特殊证据且字符身份完整的 cell visual line 被合并为最多 8192 字的 Rust 批次；原生角色只要出现非 body，整 cell 回退既有 `_script_line_char_roles()` 参考路径，避免改变表格二维行合并后的精炼语义。诊断新增表格 owned 批次、命中行数和回退 cell 数。
+
+表格候选的 marker 输入校验从每个 corridor 改为每个 `_RuleCandidateContext` 一次。同一方向候选组共享 marker-safe 结果和 source line 索引；重复 row、特殊字符、非有限坐标和 Python backend 仍走原参考路径。
+
+新增页面级 `NativeGeometryEvidence`：Rust 一次从自有 text snapshot 准备 source/loose/tight/origin、rotation、字体 run key、字号、宽粒度文字类别和 anchor 标记。Python 主链路只传行成员索引和行元数据；`NativeGeometryRuns` 在全文内分配稳定 run ID，`NativeGeometryRisk` 连续累积布局/样式风险。解释器相关的字体族归一化、字号/字重取整和 Unicode 文字类别只在不同值上调用。身份缺失、特殊输入、旧扩展或规则替换时整本文档回退原逐行参考路径。
+
+## 验证
+
+- 32 PDF／299 页公开回放每份双跑；ModelJson、MiddleJson、素材哈希和诊断与 Stage 20 完整输出完全一致。
+- MinerU 当前 `dev@f504cff`：31 份 eligible Flash 文本完整输出一致；32 份实际 medium shared 完整输出一致。MinerU 工作区仅保留原有未跟踪 `examples/`，未修改其源码。
+- Rust/session 完整测试：5465 passed / 14 skipped。
+- Python/legacy 完整测试：4756 passed / 723 skipped。
+- Cargo workspace tests、Clippy `-D warnings`、rustfmt、Ruff check 和改动文件 format check 均通过。
+- ABI3 wheel 为 `docvortex-0.5.7-cp310-abi3-macosx_11_0_arm64.whl`。CPython 3.14 独立环境中 DocVortex 核心路径和 MinerU Flash 文本路径的 `auto|rust` 输出一致，协议 28，geometry evidence API 可用。源码扩展与 wheel 扩展 SHA-256 均为 `6266f409337d742153dc5bc0727d3b28f32a8f4cb210d8a5ea6e06cc650d3deb`。
+
+公开正确性诊断中，表格 owned 路径执行 368 批／27,602 行／932 个 cell 回退；geometry evidence 执行 598 页／34,990 行／0 回退。32 PDF 单遍完整 cProfile 中，geometry evidence 执行 299 页／17,495 行，表格 owned 执行 184 批／13,801 行。
+
+## 性能与资源
+
+正式计时均为每文档一次预热、五次热运行；公开 parse 按文档先基线后候选，MinerU 按文档交替方向，RSS 使用独立进程树采样。结果仅代表本机语料与当前 PDFium 环境。
+
+| 链路 | Stage 20 基线 | Stage 21 候选 | 首轮总降幅 | 首轮最大耗时比 | 首轮最大 RSS 比 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| DocVortex 公开 parse，32 PDF | 15.943439 s | 15.513413 s | 2.70% | 1.02077 | 1.03600 |
+| MinerU Flash 文本，31 PDF | 15.746155 s | 15.304521 s | 2.80% | 1.02846 | 1.04413 |
+| MinerU medium shared，32 PDF | 16.010728 s | 17.845207 s | -11.46% | 1.58188 | 1.00490 |
+
+shared 首轮有 4 个样本耗时超过 5%，均已按脚本自动反序复测：
+
+- `small_ocr.pdf`: `1.09802 → 0.98395`
+- `engineering_process_restrictions_table.pdf`: `1.51380 → 0.99771`
+- `pollutant_discharge_tables.pdf`: `1.58188 → 0.88237`
+- `quarterly_report_financial_tables.pdf`: `1.12287 → 0.90017`
+
+四个样本均无持续退化。仅把这四个已触发样本替换为反序复测值作诊断汇总时，shared 总时间为 `16.174975 s → 15.777589 s`，约 2.46% 改善；该补充口径不替代首轮正式总表。所有 benchmark 完整输出均相等，公开 parse、Flash 和 shared 均无持续超过 5% 的耗时或 RSS 退化。
+
+十样本表格重载焦点 profile 中：
+
+- 墙钟：`11.889497 s → 10.338891 s`，约 13.03%。
+- `_cell_script_roles`: `1.969974 s → 0.040009 s`
+- `_prepare_table_core_rows`: `0.542125 s → 0.026794 s`
+- `_document_requires_full_geometry`: `0.467145 s → 0.050283 s`
+- 三项合计：`2.979244 s → 0.117086 s`，低于 `2.80 s` 门槛。
+
+## 后续状态
+
+原始 2 倍性能目标仍未完成。Stage 21 后的 32 PDF cProfile 主要剩余热点为 `_detect_table_candidates()` 约 `6.821 s`、`_materialize_table_blocks()` 约 `5.384 s`、`_infer_text_lanes()` 约 `3.252 s`、`build_document_geometry_plan()` 约 `3.626 s` 和 `_merge_owned_table_candidates()` 约 `2.224 s`。其中 geometry plan 的准入扫描已下降，剩余成本主要在确认布局风险后的 canonical 样本构造。Stage 22 应优先从表格候选合并/物化与 lane inference 重新 profile 后选择，不应继续扩大本轮 owned script/geometry 范围。
+
+证据目录为 `output/pdf/native-kernel-20260929-stage21/`。本阶段不自动合并、发版或发布 PyPI。

docvortex-0.5.8/docs/rust-pdf-stage22-evidence.md

@@ -0,0 +1,46 @@
+# PDF 原生内核阶段 22：表格网格复用与栏带扫描降重
+
+## 实现边界
+
+本阶段以 `main@878870f`（包含 Stage 21 合并与开放 Path 修复）为基线，只减少既有 Python 边界的重复工作；私有协议保持 28，不修改 Rust ABI、公开 SDK、`auto|python|rust` 计算选择、`auto|legacy|session` 渲染选择或输出 schema。
+
+表格检测侧新增同一候选上下文的网格连通分量冻结：延迟候选先计算一次 `_connected_rule_grid_components()`，闭合网格检测和 owned merge 只复用该分量重建 bbox。直接调用旧内部函数时仍按原签名即时计算；owned merge 对复用分量执行普通 `_LocalAxisLine` 与有限 bbox 校验，特殊输入仍回退完整参考路径。marker-safe 上下文校验改为单次顺序扫描，同一字符/字典字段不再被多层生成式重复读取，特殊 char/Bbox 仍整体回退。
+
+栏带推断侧保留算法语义，但删除三类重复扫描：只有一个 lane 时短尾不可能跨栏，直接跳过校验和前序扫描；lane 分配前一次排序栏带，`_fits_only_one_lane_ordered()` 不再为每个 bbox 重复排序；最佳/次高覆盖在一次遍历中求得，平局仍保留首个最佳 lane。表格 cell glyph 已由 `_cell_glyphs()` 全局排序，visual row 分组后不再重复稳定排序。自有 `Bbox` 增加 exact-type 快路径，仅当内部是四个有限 float 且坐标正向时直接返回 tuple，反向、非有限、int 或子类仍走原通用转换。
+
+## 正确性
+
+- 32 PDF／299 页公开回放每份双跑；ModelJson、MiddleJson、素材哈希和诊断与 Stage 21 正式候选输出完全一致。
+- MinerU 当前 `dev@f504cff`：31 份 eligible Flash 文本完整输出一致；32 份实际 medium shared 完整输出一致。MinerU 工作区仅保留原有未跟踪 `examples/`，未修改其源码。
+- Rust/session 完整测试：5472 passed / 14 skipped。
+- Python/legacy 完整测试：4762 passed / 724 skipped。
+- Cargo workspace tests、Clippy `-D warnings`、rustfmt、Ruff check 均通过；本仓既有 20 个无关测试/工具文件不符合当前 ruff format，未纳入本阶段 patch，改动文件 format check 通过。
+- ABI3 wheel 为 `docvortex-0.5.7-cp310-abi3-macosx_11_0_arm64.whl`。CPython 3.14.4 独立环境中 DocVortex 核心路径和 MinerU Flash 文本路径的 `auto|rust` 输出一致，协议 28。源码扩展与 wheel 扩展 SHA-256 均为 `bc42f1546006c340cb7175b5bbfa6698641a59057758c046a8f5f4c0bf5a222e`。
+
+## 性能与资源
+
+正式计时均为每文档一次预热、五次热运行，基线/候选执行方向逐文档交替；RSS 使用独立进程树采样。首轮任一样本耗时超过 5% 时均按相反方向复测，复测均无持续退化。结果仅代表本机语料与当前 PDFium 环境。
+
+| 链路 | main 基线 | Stage 22 候选 | 首轮总降幅 | 首轮最大耗时比 | 首轮最大 RSS 比 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| DocVortex 公开 parse，32 PDF | 16.535675 s | 16.049855 s | 2.94% | 1.19798 | 1.00948 |
+| MinerU Flash 文本，31 PDF | 16.379259 s | 15.990359 s | 2.37% | 1.10413 | 1.05150 |
+| MinerU medium shared，32 PDF | 19.056479 s | 18.956444 s | 0.52% | 1.26994 | 1.04256 |
+
+公开 parse 中 `demo4.pdf`、`mixed_text_layout_sample.pdf.xor` 和 `quarterly_report_financial_tables.pdf` 首轮耗时触发复测，反序比例分别为 `0.94217`、`1.04183` 和 `0.98873`，无持续退化。Flash 中 `demo4.pdf`、`annual_report_research_projects_table.pdf` 和 `fund_asset_and_transaction_tables.pdf` 触发复测，反序比例分别为 `0.96987`、`0.93490` 和 `1.01703`，无持续退化。shared 中 `mixed_elements_pages_03_06.pdf`、`small_ocr.pdf` 和 `pollutant_discharge_tables.pdf` 触发复测，反序耗时比例分别为 `1.00299`、`0.98000` 和 `0.95873`，无持续退化。
+
+一轮 32 PDF cProfile 中，本轮针对的累计热点下降如下：
+
+- `_detect_table_candidates()`: `6.821288 s → 4.258895 s`
+- `_materialize_table_blocks()`: `5.383532 s → 3.768801 s`
+- `_infer_text_lanes()`: `3.251807 s → 2.474491 s`
+- `_build_rule_table_candidates()`: `3.227190 s → 2.065146 s`
+- `_merge_owned_table_candidates()`: `2.223635 s → 1.366970 s`
+- `_reattach_cross_lane_short_tails()`: `1.293215 s → 0.971536 s`
+- `_connected_rule_grid_components()`: `0.851147 s → 0.487159 s`
+- `_cell_visual_lines()`: `0.786876 s → 0.455115 s`
+- `_prepare_marker_line_context()`: `0.615293 s → 0.249741 s`
+
+原始 2 倍性能目标仍未完成。Stage 23 需重新从最终 cProfile 选择，主要候选包括 `_detect_table_candidates()` 约 `4.259 s`、`_materialize_table_blocks()` 约 `3.769 s`、`build_document_geometry_plan()` 约 `3.435 s`、`detect_pdf_text_script_lines()` 约 `2.385 s`、`_infer_text_lanes()` 约 `2.474 s`，以及 geometry canonical 样本的 `metadata()`／`_plain_source_records()` 剩余打包成本。不应把正确性通过或本阶段局部热点下降表述为 2 倍目标完成。
+
+证据目录为 `output/pdf/native-kernel-20260930-stage22/`。本阶段不自动合并、发版或发布 PyPI。

{docvortex-0.5.6 → docvortex-0.5.8}/rust/docvortex-core/src/geometry_risk.rs

@@ -8,6 +8,7 @@ use crate::{
 };
 
 pub type Entry = (usize, Box4, Box4, Size, f64);
+pub type RunKey = (String, u64, i32, i32, i32, String);
 
 /// 保留线性插值分位数，不复用其他模块的取整采样规则。
 pub(crate) fn quantile(mut values: Vec<f64>, fraction: f64) -> f64 {

{docvortex-0.5.6 → docvortex-0.5.8}/rust/docvortex-core/src/lib.rs

@@ -1,6 +1,6 @@
 //! 不访问 Python 对象或 PDFium 的单线程批量计算内核。
 
-pub const PROTOCOL_VERSION: u32 = 24;
+pub const PROTOCOL_VERSION: u32 = 29;
 pub mod columns;
 pub mod note_index;
 pub mod row_geometry;

{docvortex-0.5.6 → docvortex-0.5.8}/rust/docvortex-core/src/statistics.rs

@@ -50,6 +50,11 @@ pub fn ordered_clusters(
 use crate::geometry::Box4;
 use crate::median;
 
+/// 按调用方提供的值计算中位数，避免为了切片临时克隆整份向量。
+fn median_values<I: IntoIterator<Item = f64>>(values: I) -> f64 {
+    crate::median(values.into_iter().collect())
+}
+
 pub type Typography = (
     f64,
     Option<f64>,
@@ -65,7 +70,7 @@ pub fn typography(
     boxes: Vec<Option<Box4>>,
     fonts: Vec<Option<usize>>,
     weights: Vec<Option<f64>>,
-    families: Vec<Option<usize>>,
+    families: &[Option<usize>],
     fallback_height: f64,
 ) -> Option<Typography> {
     if boxes.len() != fonts.len()
@@ -77,12 +82,13 @@ pub fn typography(
     {
         return None;
     }
-    let mut heights = Vec::new();
-    let mut widths = Vec::new();
+    let glyph_count = boxes.len();
+    let mut heights = Vec::with_capacity(glyph_count);
+    let mut widths = Vec::with_capacity(glyph_count);
     let mut counts = vec![0usize; families.len()];
     let mut font_weights = vec![Vec::new(); families.len()];
     let mut seen = Vec::new();
-    let mut glyphs = Vec::new();
+    let mut glyphs = Vec::with_capacity(glyph_count);
     for ((raw, font), weight) in boxes.into_iter().zip(fonts).zip(weights) {
         let Some(b) = raw else {
             continue;
@@ -103,12 +109,12 @@ pub fn typography(
     let height = if heights.is_empty() {
         fallback_height
     } else {
-        median(heights)
+        median_values(heights)
     };
     let width = if widths.is_empty() {
         None
     } else {
-        Some(median(widths))
+        Some(median_values(widths))
     };
     let mut winner = None;
     for id in seen {
@@ -123,7 +129,7 @@ pub fn typography(
         if font_weights[id].is_empty() {
             None
         } else {
-            Some(median(font_weights[id].clone()))
+            Some(median_values(font_weights[id].iter().copied()))
         }
     });
     let mut emphasis = None;
@@ -147,8 +153,8 @@ pub fn typography(
                 let prefix: Vec<_> = glyphs[..split].iter().filter_map(|g| g.2).collect();
                 let body: Vec<_> = glyphs[split..].iter().filter_map(|g| g.2).collect();
                 if !prefix.is_empty() && !body.is_empty() {
-                    let p = median(prefix);
-                    let b = median(body);
+                    let p = median_values(prefix);
+                    let b = median_values(body);
                     // 中位数相加可能溢出，保留 Python 两个小于判断的否定，不能改写为大于等于。
                     if !(p - b < 100.0 || p < 1.15 * 1.0_f64.max(b)) {
                         emphasis = Some(prefix_width);