docparser_pdf/

lib.rs

//! docparser PDF 后端：`pdfium-worker`（PDFium 常驻 worker 线程 + 通道请求/响应）。
//!
//! 架构（发布形态 06 + PDF_TODO"native 调用进 worker 线程"）：
//!   * 一条 worker 线程独占持有 `Pdfium`（含裸指针，非 Sync），进程内只此一处 native
//!     状态；能力对象经 `mpsc` 通道发路径、收 `RawDoc`——避开了在 trait 对象里持有
//!     Pdfium 的 Send/Sync 困境，也与 Python 参考实现的 PDF-0.1 语义对齐。
//!   * 逐行抽取 text + bbox（pt，左上原点）：走 text page 的 rect 分段
//!     （`FPDFText_CountRects` / `FPDFText_GetBoundedText`），与 Python 参考实现同粒度，
//!     且**包含 Form XObject 内文本**（代码清单/图表标注/水印——页对象列表看不到这些）；
//!     支持 CJK CID 字体（PDFium 内建 CMap，不依赖 ToUnicode），解决 pdf-extract v1 的中文盲区。
//!   * 运行时 PDFium 库发现：`DOCPARSER_PDFIUM_LIB` → `<exe>/../lib` → home 下 conda 布局
//!     → 扫描常见 Python site-packages（Windows 上 `HOME` 往往为空，需 `USERPROFILE`）。
//!   * 错误分类：ENCRYPTED / CORRUPT。
//!   * 兜底后端 `pdfium-text-v1`（pdf-extract，纯 Rust）：worker 缺失或解析失败时
//!     按 BackendPolicy 链回退（encrypted/unsupported 为终止码，不回退）。
//!
//! # 示例
//!
//! ```no_run
//! use docparser_core::{plugins, DocumentEngine, Registry};
//! use docparser_pdf::{LayoutMode, PdfOptions};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let mut registry = Registry::new();
//! plugins::text::register_defaults(&mut registry);
//!
//! // 不重排版式 + 只解析前 20 页（等价 CLI `--layout-mode raw --max-pages 20`）
//! let options = PdfOptions::new()
//!     .with_layout_mode(LayoutMode::Raw)
//!     .with_max_pages(20);
//! docparser_pdf::register_with(&mut registry, &options);
//!
//! let doc = DocumentEngine::new(registry).parse("report.pdf")?;
//! println!("{} 页 / {} 字符", doc.pages.len(), doc.meta.text_length);
//! if let Some(pdf) = doc.meta.extra.get("pdf") {
//!     println!("pdf 元数据: {pdf}"); // pdf_version / complexity / truncated / layout_modes
//! }
//! # Ok(())
//! # }
//! ```

use std::sync::mpsc;
use std::sync::{Arc, Mutex, OnceLock};

use pdfium_render::prelude::*;

use docparser_core::error::{DocError, ErrorCode, Result};
use docparser_core::model::{BlockKind, Document, Page, Rect};
use docparser_core::plugin::{
    BackendKind, FormatPlugin, ParseCapability, RawDoc, RawImage, RawPage, RawTextItem,
};
use docparser_core::registry::Registry;

type Resp = Result<RawDoc>;

/// 版式模式（对齐 Python `layout_mode`：`auto` / `rebuild` / `raw`）。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum LayoutMode {
    /// 自动（默认）：行归并 + 表格识别 + 多栏排序。
    ///
    /// Rust 逐文本对象取 bbox，没有 Python 的「整页文本直取」路径，因此
    /// `Auto` 与 `Rebuild` 行为一致（保留三档是为了 CLI/配置与 Python 对齐）。
    #[default]
    Auto,
    /// 强制重排版式（同 `Auto`）。
    Rebuild,
    /// 不重排：按内容流顺序输出段落，不做行归并 / 表格 / 分栏。
    Raw,
}

impl LayoutMode {
    /// 模式名（CLI、日志、`meta.extra.pdf.layout_modes` 用）。
    pub fn as_str(self) -> &'static str {
        match self {
            LayoutMode::Auto => "auto",
            LayoutMode::Rebuild => "rebuild",
            LayoutMode::Raw => "raw",
        }
    }

    /// 解析模式名（大小写不敏感）；非法值返回 `None`。
    pub fn parse(s: &str) -> Option<Self> {
        match s.trim().to_ascii_lowercase().as_str() {
            "auto" => Some(LayoutMode::Auto),
            "rebuild" => Some(LayoutMode::Rebuild),
            "raw" => Some(LayoutMode::Raw),
            _ => None,
        }
    }

    /// 是否做版式重排（`raw` 为 false）。
    pub fn reflows(self) -> bool {
        !matches!(self, LayoutMode::Raw)
    }
}

/// PDF 解析选项：后端（页数截断）与插件（版式模式）共享同一份配置。
#[derive(Debug, Clone, Default)]
pub struct PdfOptions {
    /// 版式模式，默认 `Auto`
    pub layout_mode: LayoutMode,
    /// 只解析前 N 页（对齐 Python `max_pages`）；超出时结果标 `truncated`
    pub max_pages: Option<usize>,
}

impl PdfOptions {
    /// 默认选项（`Auto` + 不限页数）。
    pub fn new() -> Self {
        Self::default()
    }

    /// 设置版式模式（链式）。
    pub fn with_layout_mode(mut self, mode: LayoutMode) -> Self {
        self.layout_mode = mode;
        self
    }

    /// 设置页数上限（链式）。
    pub fn with_max_pages(mut self, pages: usize) -> Self {
        self.max_pages = Some(pages);
        self
    }
}

/// 运行时 PDFium 库发现：`DOCPARSER_PDFIUM_LIB` → 发布 bundle → 开发环境
/// pypdfium2 / liteparse 自带 → 扫描常见 Python site-packages → 无。
pub fn find_library() -> Option<std::path::PathBuf> {
    if let Ok(p) = std::env::var("DOCPARSER_PDFIUM_LIB") {
        let p = std::path::PathBuf::from(p);
        if p.exists() {
            return Some(p);
        }
    }
    #[cfg(target_os = "macos")]
    let name = "libpdfium.dylib";
    #[cfg(target_os = "linux")]
    let name = "libpdfium.so";
    #[cfg(target_os = "windows")]
    let name = "pdfium.dll";
    // P7 自包含发布：<exe>/../lib/<libpdfium> 优先（bundle 无 env 也可跑）
    if let Ok(exe) = std::env::current_exe() {
        if let Some(dir) = exe.parent() {
            let p = dir.join("..").join("lib").join(name);
            if p.exists() {
                return Some(p);
            }
        }
    }
    // 开发环境：miniconda 固定布局（历史路径，保留）+ 各 home 目录下的 conda 环境
    for home in home_dirs() {
        for base in [
            // liteparse 附带库（实测可与 pdfium-render 绑定成功）
            home.join("miniconda3/lib/python3.13/site-packages/liteparse"),
            // pypdfium2 v5 原生库独立分发包
            home.join("miniconda3/lib/python3.13/site-packages/pypdfium2_raw"),
            home.join("miniconda3/envs/kb/lib/python3.13/site-packages/pypdfium2_raw"),
            home.join("anaconda3/lib/python3.13/site-packages/pypdfium2_raw"),
        ] {
            let p = base.join(name);
            if p.exists() {
                return Some(p);
            }
        }
    }
    // 通用兜底：扫常见 Python 安装根下的 site-packages（Windows 上 HOME 常常为空，
    // 只有 USERPROFILE；pypdfium2_raw 自带 pdfium.dll，可直接绑定）
    for sp in python_site_packages() {
        for pkg in ["pypdfium2_raw", "liteparse"] {
            let p = sp.join(pkg).join(name);
            if p.exists() {
                return Some(p);
            }
        }
    }
    None
}

/// 可能的用户主目录：`HOME`（Unix/部分 Windows 配置）、`USERPROFILE`（Windows）、
/// `HOMEDRIVE`+`HOMEPATH`。去重且只保留存在的目录。
fn home_dirs() -> Vec<std::path::PathBuf> {
    let mut out: Vec<std::path::PathBuf> = Vec::new();
    for key in ["HOME", "USERPROFILE"] {
        if let Ok(v) = std::env::var(key) {
            let p = std::path::PathBuf::from(v);
            if p.is_dir() && !out.contains(&p) {
                out.push(p);
            }
        }
    }
    if let (Ok(drive), Ok(path)) = (std::env::var("HOMEDRIVE"), std::env::var("HOMEPATH")) {
        let p = std::path::PathBuf::from(format!("{drive}{path}"));
        if p.is_dir() && !out.contains(&p) {
            out.push(p);
        }
    }
    out
}

/// 常见 Python site-packages 目录（存在才返回），用于自动发现 pypdfium2 自带库。
fn python_site_packages() -> Vec<std::path::PathBuf> {
    let mut roots: Vec<std::path::PathBuf> = Vec::new();
    for home in home_dirs() {
        for conda in ["miniconda3", "anaconda3", "miniforge3"] {
            roots.push(home.join(conda).join("lib"));
            roots.push(home.join(conda).join("Lib"));
        }
        roots.push(home.join("AppData/Local/Programs/Python"));
        roots.push(home.join("AppData/Roaming/Python"));
        roots.push(home.join(".local/lib"));
        roots.push(home.join("Library/Python"));
    }
    #[cfg(target_os = "windows")]
    for key in ["LOCALAPPDATA", "PROGRAMFILES", "PROGRAMFILES(X86)"] {
        if let Ok(v) = std::env::var(key) {
            // `...\Programs\Python\Python312\Lib\site-packages` 与 `...\Python312\Lib\...`
            roots.push(std::path::PathBuf::from(&v).join("Programs/Python"));
            roots.push(std::path::PathBuf::from(&v));
        }
    }
    roots.push(std::path::PathBuf::from("/usr/lib"));
    roots.push(std::path::PathBuf::from("/usr/local/lib"));

    // 逐层展开：root 自身与其下形如 `pythonX.Y` / `Python3xx` 的子目录 → site-packages
    let mut out: Vec<std::path::PathBuf> = Vec::new();
    let mut push = |p: std::path::PathBuf| {
        if p.is_dir() && !out.contains(&p) {
            out.push(p);
        }
    };
    for root in roots {
        if !root.is_dir() {
            continue;
        }
        push(root.join("site-packages"));
        let Ok(entries) = std::fs::read_dir(&root) else {
            continue;
        };
        for e in entries.flatten() {
            let p = e.path();
            if !p.is_dir() {
                continue;
            }
            let name = p.file_name().and_then(|s| s.to_str()).unwrap_or_default();
            if name.starts_with("python") || name.starts_with("Python") {
                push(p.join("site-packages"));
                push(p.join("Lib/site-packages"));
            } else if name == "Lib" || name == "lib" {
                push(p.join("site-packages"));
            }
        }
    }
    out
}

fn classify(e: &PdfiumError) -> DocError {
    let msg = format!("{e}").to_lowercase();
    if msg.contains("password") || msg.contains("encrypt") || msg.contains("permission") {
        DocError::encrypted(format!("PDF 加密或权限受限: {e}"))
    } else {
        DocError::corrupt(format!("PDF 打开/解析失败: {e}"))
    }
}

static RENDER_SEQ: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);

pub fn find_ocr_binary() -> Option<std::path::PathBuf> {
    if let Ok(p) = std::env::var("DOCPARSER_OCR_BIN") {
        let p = std::path::PathBuf::from(p);
        if p.exists() {
            return Some(p);
        }
    }
    // 平台可执行后缀：Windows 是 `.exe`，其余为空（漏掉后缀会导致 OCR 永远「未找到」）
    let name = format!("docparser-ocr{}", std::env::consts::EXE_SUFFIX);
    // P7 自包含发布：与 CLI 同 bin 目录的 docparser-ocr
    if let Ok(exe) = std::env::current_exe() {
        if let Some(dir) = exe.parent() {
            let p = dir.join(&name);
            if p.exists() {
                return Some(p);
            }
        }
    }
    // 开发环境：workspace target（CARGO_MANIFEST_DIR 相对 = rust/pdf → rust/target）
    let target = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../target");
    let cands = [
        target.join("release").join(&name),
        target.join("debug").join(&name),
        std::path::PathBuf::from("rust/target/release").join(&name),
        std::path::PathBuf::from("rust/target/debug").join(&name),
    ];
    cands.into_iter().find(|c| c.exists())
}

pub fn find_ocr_models() -> Option<std::path::PathBuf> {
    if let Ok(p) = std::env::var("DOCPARSER_OCR_MODELS") {
        let p = std::path::PathBuf::from(p);
        if p.is_dir() {
            return Some(p);
        }
    }
    // P7 自包含发布：<exe>/../models/ocr/ppocrv5
    if let Ok(exe) = std::env::current_exe() {
        if let Some(dir) = exe.parent() {
            let p = dir.join("..").join("models/ocr/ppocrv5");
            if p.is_dir() {
                return Some(p);
            }
        }
    }
    let cands = [
        std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../models/ocr/ppocrv5"),
        std::path::PathBuf::from("models/ocr/ppocrv5"),
    ];
    cands.into_iter().find(|c| c.is_dir())
}

/// 乱码字符判定（对齐 Python `_is_garbled_char`）：替换符 U+FFFD 与私用区 U+E000–U+F8FF。
fn is_garbled_char(ch: char) -> bool {
    let cp = ch as u32;
    ch == '\u{fffd}' || (0xE000..=0xF8FF).contains(&cp)
}

/// 页级复杂度判定（对齐 Python `compute_complexity`）：
/// needs_ocr = chars<10（no-text / sparse-text）或 garbled_ratio>0.3。
fn page_needs_ocr(texts: &[String]) -> bool {
    let chars: usize = texts.iter().map(|t| t.trim().chars().count()).sum();
    if chars < 10 {
        return true;
    }
    let garbled: usize = texts
        .iter()
        .flat_map(|t| t.chars())
        .filter(|c| is_garbled_char(*c))
        .count();
    garbled as f32 / chars as f32 > 0.3
}

/// 常见位图扩展名嗅探（png/jpg/bmp/gif/webp）；否则 None（走位图回退）。
fn sniff_ext(data: &[u8]) -> Option<&'static str> {
    if data.len() >= 8 && data.starts_with(&[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A]) {
        return Some("png");
    }
    if data.len() >= 3 && data[0] == 0xFF && data[1] == 0xD8 && data[2] == 0xFF {
        return Some("jpg");
    }
    if data.len() >= 2 && data.starts_with(b"BM") {
        return Some("bmp");
    }
    if data.len() >= 4 && data.starts_with(b"GIF8") {
        return Some("gif");
    }
    if data.len() >= 12 && data.starts_with(b"RIFF") && &data[8..12] == b"WEBP" {
        return Some("webp");
    }
    None
}

/// 嵌入图去重键（对齐 Python `_page_images` 的 `dedup_key`）：有字节 → **md5 十六进制**
/// （同一页里重复出现的 logo/水印出同键，消费方据此只存一份）；无字节（lazy 路径未解码）
/// → `"{w}x{h}"` / `"{w}x{h}@{ext}"` 兜底，与 Python 的 `f"{px_w}x{px_h}@{fmt}"` 同形。
///
/// 注：md5 只在**同为原始流**时与 Python 逐字节一致（两侧都优先 `get_raw_image_data` /
/// `obj.extract()`）；位图回退路径两侧的 PNG 编码器不同（Rust `image` vs Pillow），
/// 键会不同——同进程内去重仍然正确，跨载体只保证「有键、键形态一致」。
fn image_dedup_key(im: &RawImage) -> Option<String> {
    if im.data.is_empty() {
        let (w, h) = im.px?;
        // Python 恒为 `f"{px_w}x{px_h}@{fmt}"`（fmt 可能是空串）——保留尾部 `@` 以便逐键对齐
        return Some(format!("{w}x{h}@{}", im.ext));
    }
    use md5::Digest as _;
    Some(format!("{:x}", md5::Md5::digest(&im.data)))
}

/// 嵌入图 OCR 过滤（对齐 Python `_ocrable_image`）：ext 白名单 + min(px)≥50。
fn ocrable_image(im: &RawImage) -> bool {
    if im.data.is_empty() {
        return false;
    }
    if !matches!(
        im.ext.as_str(),
        "png" | "jpg" | "jpeg" | "bmp" | "gif" | "webp"
    ) {
        return false;
    }
    if let Some((w, h)) = im.px {
        return w.min(h) >= 50;
    }
    false
}

/// 收集页内嵌入图片（含 Form XObject 嵌套，深度≤2，对齐 Python `_page_images`）。
/// bbox 换算页面 pt（左上原点）。
///
/// lazy 语义：默认（`ocr_images=false`）只取元数据（bbox/px）不解码字节，避免文本优先
/// 路径为图付解码成本（liteparse 关 OCR 语义）；`extract_data=true` 时才取原始流/回退
/// 处理位图转 PNG（供嵌入图 OCR 使用）。
fn collect_page_images(
    doc: &PdfDocument,
    page: &PdfPage,
    h: f32,
    extract_data: bool,
) -> Vec<RawImage> {
    let mut out: Vec<RawImage> = Vec::new();
    descend(doc, page.objects().iter(), h, 0, extract_data, &mut out);
    out
}

fn descend<'a>(
    doc: &'a PdfDocument,
    objs: impl Iterator<Item = PdfPageObject<'a>>,
    h: f32,
    depth: usize,
    extract_data: bool,
    out: &mut Vec<RawImage>,
) {
    if depth > 2 {
        return;
    }
    for obj in objs {
        if let Some(img) = obj.as_image_object() {
            let bbox = obj.bounds().ok().map(|q| Rect {
                x0: q.left().value,
                y0: h - q.top().value,
                x1: q.right().value,
                y1: h - q.bottom().value,
            });
            let (px_w, px_h) = (
                img.width().ok().unwrap_or(0) as u32,
                img.height().ok().unwrap_or(0) as u32,
            );
            let mut data: Vec<u8> = Vec::new();
            let mut ext: String = String::new();
            if extract_data {
                // 原始流优先；未命中则回退处理位图 → PNG
                if let Ok(raw) = img.get_raw_image_data() {
                    if let Some(e) = sniff_ext(&raw) {
                        data = raw;
                        ext = e.to_string();
                    }
                }
                if data.is_empty() {
                    if let Ok(dyn_img) = img.get_processed_image(doc) {
                        let rgba = dyn_img.to_rgba8();
                        let (bw, bh) = rgba.dimensions();
                        let mut buf: Vec<u8> = Vec::new();
                        {
                            use image::ImageEncoder as _;
                            let enc = image::codecs::png::PngEncoder::new(std::io::BufWriter::new(
                                &mut buf,
                            ));
                            if enc
                                .write_image(&rgba, bw, bh, image::ExtendedColorType::Rgba8)
                                .is_ok()
                            {
                                data = buf;
                                ext = "png".to_string();
                            }
                        }
                    }
                }
            }
            out.push(RawImage {
                data,
                bbox,
                ext,
                px: Some((px_w, px_h)),
                ocr_text: None,
            });
        } else if let Some(form) = obj.as_x_object_form_object() {
            descend(doc, form.iter(), h, depth + 1, extract_data, out);
        }
    }
}

/// `DOCPARSER_OCR_IMAGES=1` → 开嵌入图 OCR（对齐 Python `policy.ocr_images` / bench env）。
fn ocr_images_enabled() -> bool {
    std::env::var("DOCPARSER_OCR_IMAGES").as_deref() == Ok("1")
}

/// OCR 总开关：`DOCPARSER_OCR_ENABLED=0/false` → 关闭（纯文本路径，与 lp OCR-off 同口径）。
/// 默认开启（对齐既有行为：needs_ocr 页自动整页渲染 OCR）。
fn ocr_enabled() -> bool {
    !matches!(
        std::env::var("DOCPARSER_OCR_ENABLED").as_deref(),
        Ok("0") | Ok("false")
    )
}

/// 逐行抽取页面文本，返回 `(items, texts)`。
///
/// 走 text page 的 rect 分段（`FPDFText_CountRects` / `FPDFText_GetBoundedText`），
/// 与 Python 参考实现同粒度；关键是**能拿到 Form XObject 内的文本**（代码清单、
/// 图表标注、印章/水印）——`page.objects()` 的页对象列表不含嵌入表单内部对象。
///
/// 对齐 Python `_page_text_rebuild`：rect 高度超过页高 25% 视为跨高条块
/// （页边徽标 / 竖排水印）跳过，否则 `get_text_bounded` 会把叠压正文一并吞入。
/// text page 不可用或分段为空时回退旧路径（逐对象），再退回整页文本。
fn extract_text_items(page: &PdfPage<'_>, page_h: f32) -> (Vec<RawTextItem>, Vec<String>) {
    let mut items: Vec<RawTextItem> = Vec::new();
    let mut texts: Vec<String> = Vec::new();

    if let Ok(text_page) = page.text() {
        for seg in text_page.segments().iter() {
            let s = seg.text();
            if s.trim().is_empty() {
                continue;
            }
            texts.push(s.clone());
            let b = seg.bounds();
            let height = (b.top().value - b.bottom().value).abs();
            if page_h > 0.0 && height > page_h * 0.25 {
                continue;
            }
            items.push(RawTextItem {
                text: s,
                bbox: Some(Rect {
                    x0: b.left().value,
                    y0: page_h - b.top().value,
                    x1: b.right().value,
                    y1: page_h - b.bottom().value,
                }),
                ..Default::default()
            });
        }
        if items.is_empty() {
            // 整页都是跨高条块 / 无 rect：整页文本兜底（对齐 Python 的回退分支）
            let whole = text_page.all();
            if !whole.trim().is_empty() {
                if texts.is_empty() {
                    texts.push(whole.clone());
                }
                items.push(RawTextItem {
                    text: whole,
                    bbox: None,
                    ..Default::default()
                });
            }
        }
    }

    if texts.is_empty() {
        // text page 不可用：回退逐对象（无 Form XObject 覆盖，但保住基础文本）
        for obj in page.objects().iter() {
            let Some(t) = obj.as_text_object() else {
                continue;
            };
            let s = t.text();
            if s.trim().is_empty() {
                continue;
            }
            texts.push(s.clone());
            let bbox = obj.bounds().ok().map(|q| Rect {
                x0: q.left().value,
                y0: page_h - q.top().value,
                x1: q.right().value,
                y1: page_h - q.bottom().value,
            });
            items.push(RawTextItem {
                text: s,
                bbox,
                ..Default::default()
            });
        }
    }

    (items, texts)
}

fn parse_one(pdfium: &Pdfium, path: &str, options: &PdfOptions) -> Resp {
    let doc = pdfium
        .load_pdf_from_file(path, None)
        .map_err(|e| classify(&e))?;
    let dpi = 200.0_f32;
    let mut meta: std::collections::HashMap<String, String> = std::collections::HashMap::new();
    meta.insert("pdf.version".into(), pdf_version_str(doc.version()));
    for (key, tag) in [
        ("pdf.title", PdfDocumentMetadataTagType::Title),
        ("pdf.author", PdfDocumentMetadataTagType::Author),
        ("pdf.producer", PdfDocumentMetadataTagType::Producer),
        ("pdf.creator", PdfDocumentMetadataTagType::Creator),
    ] {
        if let Some(tag_value) = doc.metadata().get(tag) {
            let v = tag_value.value().trim().to_string();
            if !v.is_empty() {
                meta.insert(key.into(), v);
            }
        }
    }
    // max_pages（对齐 Python）：只解析前 N 页，超出标 truncated
    let total_pages = doc.pages().len() as usize;
    let limit = options.max_pages.unwrap_or(total_pages).min(total_pages);
    meta.insert("pdf.page_count".into(), total_pages.to_string());
    meta.insert("pdf.truncated".into(), (limit < total_pages).to_string());
    let mut complexity: Vec<serde_json::Value> = Vec::new();
    let mut page_errors: Vec<serde_json::Value> = Vec::new();
    let mut pages = Vec::new();
    let mut render_dir: Option<std::path::PathBuf> = None;
    let mut render_files: Vec<(usize, std::path::PathBuf)> = Vec::new();
    // 嵌入图 OCR 任务：全局序号 → (page_idx, images 内 idx, 临时文件)
    let mut img_dir: Option<std::path::PathBuf> = None;
    let mut img_seq = 0usize;
    let mut img_jobs: Vec<(usize, usize, usize)> = Vec::new();
    let mut img_files: Vec<(usize, std::path::PathBuf)> = Vec::new();
    let ocr_images = ocr_images_enabled();
    let ocr_on = ocr_enabled();
    for (pi, page) in doc.pages().iter().take(limit).enumerate() {
        let w = page.width().value;
        let h = page.height().value;
        // 逐行 rect 抽取（含 Form XObject 内文本；PDF 左下原点 → 左上原点已在函数内换算）
        let (items, texts) = extract_text_items(&page, h);
        let images = collect_page_images(&doc, &page, h, ocr_images);
        // 扫描/稀疏/乱码页：整页渲染（供 OCR 兜底，对应 Python needs_ocr 页）；
        // OCR 总开关关闭时跳过（纯文本路径）
        if ocr_on && page_needs_ocr(&texts) {
            if render_dir.is_none() {
                let d = std::env::temp_dir().join(format!(
                    "docparser_pdf_render_{}_{}",
                    std::process::id(),
                    RENDER_SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed),
                ));
                let _ = std::fs::create_dir_all(&d);
                render_dir = Some(d);
            }
            let dir = render_dir.as_ref().unwrap();
            let fn_name = format!("page-{pi:04}.png");
            let out_path = dir.join(&fn_name);
            let wpx = (w * dpi / 72.0).round() as i32;
            let hpx = (h * dpi / 72.0).round() as i32;
            match page.render(wpx, hpx, None) {
                Ok(bitmap) => {
                    let bw = bitmap.width() as u32;
                    let bh = bitmap.height() as u32;
                    let rgba = bitmap.as_rgba_bytes();
                    use image::ImageEncoder as _;
                    let Ok(file) = std::fs::File::create(&out_path) else {
                        page_errors.push(serde_json::json!({
                            "page": pi, "error": "无法创建渲染临时文件",
                        }));
                        continue;
                    };
                    let enc = image::codecs::png::PngEncoder::new(std::io::BufWriter::new(file));
                    if enc
                        .write_image(&rgba, bw, bh, image::ExtendedColorType::Rgba8)
                        .is_ok()
                    {
                        render_files.push((pi, out_path));
                    }
                }
                // 单页渲染失败不拖垮整篇（对齐 Python `page_errors`）
                Err(e) => page_errors.push(serde_json::json!({
                    "page": pi, "error": format!("{e}"),
                })),
            }
        } else if ocr_on && ocr_images {
            // 非扫描页嵌入图 OCR：needs_ocr 页整页渲染已覆盖图内容，跳过避免重复
            for (ki, im) in images.iter().enumerate() {
                if !ocrable_image(im) {
                    continue;
                }
                if img_dir.is_none() {
                    let d = std::env::temp_dir().join(format!(
                        "docparser_pdf_img_{}_{}",
                        std::process::id(),
                        RENDER_SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed),
                    ));
                    let _ = std::fs::create_dir_all(&d);
                    img_dir = Some(d);
                }
                let dir = img_dir.as_ref().unwrap();
                let fn_name = format!("img-{img_seq:05}.{}", im.ext);
                let out_path = dir.join(&fn_name);
                if std::fs::write(&out_path, &im.data).is_ok() {
                    img_files.push((img_seq, out_path));
                    img_jobs.push((pi, ki, img_seq));
                    img_seq += 1;
                }
            }
        }
        // 页级复杂度（对齐 Python `compute_complexity`：chars / garbled_ratio / needs_ocr）
        let chars: usize = texts.iter().map(|t| t.trim().chars().count()).sum();
        let garbled = texts
            .iter()
            .flat_map(|t| t.chars())
            .filter(|c| is_garbled_char(*c))
            .count();
        complexity.push(serde_json::json!({
            "page": pi,
            "chars": chars,
            "garbled_ratio": if chars == 0 { 0.0 } else { garbled as f64 / chars as f64 },
            "needs_ocr": page_needs_ocr(&texts),
        }));
        // 旋转角（对齐 Python `page.rotation`）
        let rotation = page.rotation().ok().map(|r| match r {
            PdfPageRenderRotation::None => 0,
            PdfPageRenderRotation::Degrees90 => 90,
            PdfPageRenderRotation::Degrees180 => 180,
            PdfPageRenderRotation::Degrees270 => 270,
        });
        pages.push(RawPage {
            name: None,
            items,
            images,
            width: Some(w),
            height: Some(h),
            rotation,
            ..Default::default()
        });
    }

    // OCR 回填（needs_ocr 页）：调 docparser-ocr（子进程，模型常驻于其自身）
    let mut any_ocr = false;
    if !render_files.is_empty() {
        if let Some(lines) = run_ocr(render_dir.as_ref().unwrap(), &render_files) {
            let scale = 72.0 / dpi;
            for (pi, items) in lines {
                if let Some(pg) = pages.get_mut(pi) {
                    pg.items = items
                        .into_iter()
                        .map(|(text, quad)| RawTextItem {
                            text,
                            bbox: Some(Rect {
                                x0: quad.iter().map(|p| p[0]).fold(f32::MAX, f32::min) * scale,
                                y0: quad.iter().map(|p| p[1]).fold(f32::MAX, f32::min) * scale,
                                x1: quad.iter().map(|p| p[0]).fold(f32::MIN, f32::max) * scale,
                                y1: quad.iter().map(|p| p[1]).fold(f32::MIN, f32::max) * scale,
                            }),
                            ..Default::default()
                        })
                        .collect();
                    any_ocr = true;
                }
            }
        }
    }

    // 嵌入图 OCR 回填（非 needs_ocr 页，opt-in：DOCPARSER_OCR_IMAGES=1）
    if !img_files.is_empty() {
        if let Some(lines) = run_ocr(img_dir.as_ref().unwrap(), &img_files) {
            for (gi, line_items) in lines {
                let Some(&(pi, ki, _)) = img_jobs.iter().find(|(_, _, g)| *g == gi) else {
                    continue;
                };
                let Some(pg) = pages.get_mut(pi) else {
                    continue;
                };
                let Some(im) = pg.images.get_mut(ki) else {
                    continue;
                };
                let ocr: Vec<&str> = line_items
                    .iter()
                    .map(|(s, _)| s.as_str())
                    .filter(|s| !s.trim().is_empty())
                    .collect();
                if !ocr.is_empty() {
                    im.ocr_text = Some(ocr.join("\n"));
                    any_ocr = true;
                }
            }
        }
    }

    // 跨页页眉页脚剔除（多页 stateful，顶/底 7% 边带 + 数字归一化重复）
    let hf = strip_headers_footers(&mut pages);

    let mut raw = RawDoc {
        pages,
        meta,
        needs_ocr: false,
    };
    if !hf.is_empty() {
        raw.meta.insert("headers_footers".into(), hf.join(" | "));
    }
    if let Ok(s) = serde_json::to_string(&complexity) {
        raw.meta.insert("pdf.complexity".into(), s);
    }
    if !page_errors.is_empty() {
        if let Ok(s) = serde_json::to_string(&page_errors) {
            raw.meta.insert("pdf.page_errors".into(), s);
        }
    }
    raw.needs_ocr = !any_ocr
        && raw.pages.iter().all(|p| {
            p.items
                .iter()
                .map(|i| i.text.chars().count())
                .sum::<usize>()
                < 10
        });
    Ok(raw)
}

/// `PdfDocumentVersion` → `"1.7"` 形式（对齐 Python `pdf_version`）；未知返回空串。
fn pdf_version_str(v: PdfDocumentVersion) -> String {
    match v {
        PdfDocumentVersion::Unset => String::new(),
        PdfDocumentVersion::Pdf1_0 => "1.0".into(),
        PdfDocumentVersion::Pdf1_1 => "1.1".into(),
        PdfDocumentVersion::Pdf1_2 => "1.2".into(),
        PdfDocumentVersion::Pdf1_3 => "1.3".into(),
        PdfDocumentVersion::Pdf1_4 => "1.4".into(),
        PdfDocumentVersion::Pdf1_5 => "1.5".into(),
        PdfDocumentVersion::Pdf1_6 => "1.6".into(),
        PdfDocumentVersion::Pdf1_7 => "1.7".into(),
        PdfDocumentVersion::Pdf2_0 => "2.0".into(),
        PdfDocumentVersion::Other(n) => format!("{}.{}", n / 10, n % 10),
    }
}

fn _norm_repeat(text: &str) -> String {
    let mut out = String::with_capacity(text.len());
    let mut last_digit = false;
    for ch in text.chars() {
        if ch.is_ascii_digit() {
            if !last_digit {
                out.push('#');
                last_digit = true;
            }
        } else {
            last_digit = false;
            if !ch.is_whitespace() {
                out.push(ch);
            }
        }
    }
    out
}

/// 剔除在多页顶部/底部窄边带内重复出现的行；返回被剔除的去重文本。
/// 无 bbox / 单页 / 边带外不动作。band = 0.07 页高（与 Python `_strip_headers_footers` 一致）。
///
/// 注意：**先收集再重建**，不能边算边 `Vec::remove`——同一条边带内往往有多个重复文本
/// （页眉左标题 + 右页码、页脚作者 + 页码），第一个文本删完后面的索引就整体前移，
/// 第二个文本按旧索引再删会越界 panic（真实语料 2610.32982v1：`removal index (is 80)
/// should be < len (is 79)`）。Python 侧用 `(page, text, bbox)` 集合 + 重建，这里等价处理。
fn strip_headers_footers(pages: &mut [RawPage]) -> Vec<String> {
    if pages.len() < 2 {
        return Vec::new();
    }
    let n_with_h = pages.iter().filter(|p| p.height.is_some()).count();
    if n_with_h == 0 {
        return Vec::new();
    }
    let mut removed: Vec<String> = Vec::new();
    for zone in ["top", "bottom"] {
        let mut occ: std::collections::HashMap<String, Vec<(usize, usize)>> =
            std::collections::HashMap::new(); // (page_idx, item_idx)
        for (pi, page) in pages.iter().enumerate() {
            let Some(h) = page.height else { continue };
            let band = if zone == "top" { h * 0.07 } else { h * 0.93 };
            for (ii, it) in page.items.iter().enumerate() {
                let Some(bb) = it.bbox else { continue };
                let hit = if zone == "top" {
                    bb.y1 <= band
                } else {
                    bb.y0 >= band
                };
                if hit {
                    occ.entry(_norm_repeat(&it.text))
                        .or_default()
                        .push((pi, ii));
                }
            }
        }
        // 按「首次出现位置」排序处理，输出顺序与 Python 的 dict 插入顺序一致（可复现）
        let mut keys: Vec<(&String, &Vec<(usize, usize)>)> = occ.iter().collect();
        keys.sort_by_key(|(_, hits)| hits.first().copied().unwrap_or((usize::MAX, usize::MAX)));
        let mut drop: Vec<std::collections::BTreeSet<usize>> =
            vec![std::collections::BTreeSet::new(); pages.len()];
        for (norm, hits) in keys {
            if norm.is_empty() {
                continue;
            }
            let mut hit_pages: Vec<usize> = hits.iter().map(|(p, _)| *p).collect();
            hit_pages.sort_unstable();
            hit_pages.dedup();
            if hit_pages.len() >= 2 && hit_pages.len() as f32 >= 0.5 * n_with_h as f32 {
                for (pi, ii) in hits {
                    drop[*pi].insert(*ii);
                }
                if !removed.iter().any(|r| r == norm) {
                    removed.push(norm.clone());
                }
            }
        }
        for (pi, page) in pages.iter_mut().enumerate() {
            if drop[pi].is_empty() {
                continue;
            }
            let keep = std::mem::take(&mut page.items)
                .into_iter()
                .enumerate()
                .filter(|(i, _)| !drop[pi].contains(i))
                .map(|(_, it)| it)
                .collect();
            page.items = keep;
        }
    }
    removed
}

/// 常驻 OCR 引擎（`docparser-ocr serve`，stdin/stdout 行协议，模型只加载一次）。
/// 与 Python `_ResidentEngine` 同一契约：写一行图片路径 → 读一行
/// `{"file":..., "lines":[{box,text,score}...]}`。
struct ResidentOcr {
    child: std::process::Child,
    stdin: std::process::ChildStdin,
    stdout: std::io::BufReader<std::process::ChildStdout>,
}

impl ResidentOcr {
    fn spawn() -> Option<Self> {
        let bin = find_ocr_binary()?;
        let mut cmd = std::process::Command::new(&bin);
        cmd.arg("serve")
            .stdin(std::process::Stdio::piped())
            .stdout(std::process::Stdio::piped())
            .stderr(std::process::Stdio::null());
        if let Some(m) = find_ocr_models() {
            cmd.env("DOCPARSER_OCR_MODELS", m);
        }
        let mut child = cmd.spawn().ok()?;
        let stdin = child.stdin.take()?;
        let stdout = std::io::BufReader::new(child.stdout.take()?);
        Some(Self {
            child,
            stdin,
            stdout,
        })
    }

    fn recognize(&mut self, path: &std::path::Path) -> Option<Vec<serde_json::Value>> {
        use std::io::{BufRead as _, Write as _};
        writeln!(self.stdin, "{}", path.display()).ok()?;
        self.stdin.flush().ok()?;
        let mut line = String::new();
        if self.stdout.read_line(&mut line).ok()? == 0 {
            return None;
        }
        let v: serde_json::Value = serde_json::from_str(&line).ok()?;
        if v.get("error").is_some() {
            return Some(Vec::new());
        }
        Some(
            v.get("lines")
                .and_then(|l| l.as_array())
                .cloned()
                .unwrap_or_default(),
        )
    }
}

static OCR_SERVE: OnceLock<Mutex<Option<ResidentOcr>>> = OnceLock::new();

/// 用常驻引擎识别一批图片；任一环节失败返回 None（调用方回退批量子进程）。
fn serve_ocr(
    files: &[(usize, std::path::PathBuf)],
) -> Option<Vec<(usize, Vec<serde_json::Value>)>> {
    let lock = OCR_SERVE.get_or_init(|| Mutex::new(None));
    let mut guard = lock.lock().ok()?;
    if guard.is_none() {
        *guard = ResidentOcr::spawn();
    }
    let srv = guard.as_mut()?;
    let mut out = Vec::with_capacity(files.len());
    for (key, path) in files {
        match srv.recognize(path) {
            Some(lines) => out.push((*key, lines)),
            None => {
                // 进程异常：丢弃，让调用方回退批量模式
                if let Some(mut dead) = guard.take() {
                    let _ = dead.child.kill();
                }
                return None;
            }
        }
    }
    Some(out)
}

/// OCR 行解析：score ≥0.8 过滤 + 按 min-y 排序 → (text, quad)。
fn lines_from_entries(entries: &[serde_json::Value]) -> Vec<(String, Vec<[f32; 2]>)> {
    let mut items = Vec::new();
    for ent in entries {
        if let Some(s) = ent.get("score") {
            if s.as_f64().unwrap_or(0.0) < 0.8 {
                continue;
            }
        }
        let text = ent
            .get("text")
            .and_then(|t| t.as_str())
            .unwrap_or("")
            .to_string();
        if text.trim().is_empty() {
            continue;
        }
        let mut quad: Vec<[f32; 2]> = Vec::new();
        if let Some(boxes) = ent.get("box").and_then(|b| b.as_array()) {
            for p in boxes {
                let mut pt = [0.0_f32; 2];
                if let (Some(x), Some(y)) = (
                    p.get(0).and_then(|x| x.as_f64()),
                    p.get(1).and_then(|y| y.as_f64()),
                ) {
                    pt = [x as f32, y as f32];
                }
                quad.push(pt);
            }
        }
        items.push((text, quad));
    }
    items.sort_by(|a, b| {
        let ay = a.1.iter().map(|p| p[1]).fold(f32::MAX, f32::min);
        let by = b.1.iter().map(|p| p[1]).fold(f32::MAX, f32::min);
        ay.total_cmp(&by)
    });
    items
}

/// 一行 OCR 结果：文本 + 四边形（图像像素坐标，左上原点）。
type OcrLine = (String, Vec<[f32; 2]>);

/// 一次 OCR 调用的结果：输入序号 → 该页/该图的识别行。
type OcrPageLines = Vec<(usize, Vec<OcrLine>)>;

/// 对渲染出的扫描页/嵌入图批量 OCR：返回 (page_idx, [(text, quad), ...])。
/// quad 为图像像素坐标（左上原点），由调用方换算页面 pt。
/// 优先常驻 serve（模型只加载一次），不可用/失败回退批量子进程。
fn run_ocr(dir: &std::path::Path, files: &[(usize, std::path::PathBuf)]) -> Option<OcrPageLines> {
    if let Some(served) = serve_ocr(files) {
        let mut out = Vec::new();
        for (key, entries) in served {
            let items = lines_from_entries(&entries);
            if !items.is_empty() {
                out.push((key, items));
            }
        }
        return Some(out);
    }
    batch_ocr(dir, files)
}

fn batch_ocr(dir: &std::path::Path, files: &[(usize, std::path::PathBuf)]) -> Option<OcrPageLines> {
    let bin = find_ocr_binary()?;
    let out_json = dir.join("ocr.json");
    let mut cmd = std::process::Command::new(&bin);
    cmd.arg(dir).arg("--out").arg(&out_json);
    if let Some(m) = find_ocr_models() {
        cmd.env("DOCPARSER_OCR_MODELS", m);
    }
    let ok = cmd.output().map(|o| o.status.success()).unwrap_or(false);
    if !ok {
        return None;
    }
    let text = std::fs::read_to_string(&out_json).ok()?;
    let v: serde_json::Value = serde_json::from_str(&text).ok()?;
    let arr = v.as_array()?;
    let mut by_file: std::collections::HashMap<String, Vec<serde_json::Value>> =
        std::collections::HashMap::new();
    for ent in arr {
        if let (Some(f), Some(s)) = (ent.get("file"), ent.get("score")) {
            if s.as_f64().unwrap_or(0.0) >= 0.8 {
                by_file
                    .entry(f.as_str().unwrap_or("").to_string())
                    .or_default()
                    .push(ent.clone());
            }
        }
    }
    let mut out = Vec::new();
    for (pi, fp) in files {
        let key = fp
            .file_name()
            .and_then(|n| n.to_str())
            .unwrap_or("")
            .to_string();
        let Some(entries) = by_file.get(&key) else {
            continue;
        };
        let mut items = Vec::new();
        for ent in entries {
            let text = ent
                .get("text")
                .and_then(|t| t.as_str())
                .unwrap_or("")
                .to_string();
            if text.trim().is_empty() {
                continue;
            }
            let mut quad: Vec<[f32; 2]> = Vec::new();
            if let Some(boxes) = ent.get("box").and_then(|b| b.as_array()) {
                for p in boxes {
                    let mut pt = [0.0_f32; 2];
                    if let (Some(x), Some(y)) = (
                        p.get(0).and_then(|x| x.as_f64()),
                        p.get(1).and_then(|y| y.as_f64()),
                    ) {
                        pt = [x as f32, y as f32];
                    }
                    quad.push(pt);
                }
            }
            items.push((text, quad));
        }
        items.sort_by(|a, b| {
            let ay = a.1.iter().map(|p| p[1]).fold(f32::MAX, f32::min);
            let by = b.1.iter().map(|p| p[1]).fold(f32::MAX, f32::min);
            ay.total_cmp(&by)
        });
        if !items.is_empty() {
            out.push((*pi, items));
        }
    }
    Some(out)
}

/// worker 请求：PDF 路径 + 回包通道。
type WorkerReq = (String, PdfOptions, mpsc::Sender<Resp>);

/// worker 发送端（进程内单例持有，长驻线程消费）。
type WorkerTx = Arc<Mutex<mpsc::Sender<WorkerReq>>>;

fn worker_sender() -> Result<WorkerTx> {
    static WORKER: OnceLock<std::result::Result<WorkerTx, String>> = OnceLock::new();
    WORKER
        .get_or_init(|| {
            let file = find_library().ok_or_else(|| {
                "未找到 PDFium 动态库（设 DOCPARSER_PDFIUM_LIB 或安装 pypdfium2）".to_string()
            })?;
            let (tx, rx) = mpsc::channel::<(String, PdfOptions, mpsc::Sender<Resp>)>();
            std::thread::Builder::new()
                .name("docparser-pdfium".into())
                .spawn(move || {
                    let lib = file.to_str().ok_or("PDFium 路径非 UTF-8")?.to_string();
                    let bindings = Pdfium::bind_to_library(&lib).map_err(|e| format!("{e}"))?;
                    let pdfium = Pdfium::new(bindings);
                    for (path, options, resp_tx) in rx.iter() {
                        let _ = resp_tx.send(parse_one(&pdfium, &path, &options));
                    }
                    Ok::<(), String>(())
                })
                .map_err(|e| format!("{e}"))?;
            Ok(Arc::new(Mutex::new(tx)))
        })
        .as_ref()
        .map(Arc::clone)
        .map_err(|m| DocError::corrupt(m.clone()))
}

/// 主后端：PDFium worker（库可用才 available）。
#[derive(Debug, Clone, Default)]
pub struct PdfiumWorkerBackend {
    options: PdfOptions,
}

impl PdfiumWorkerBackend {
    /// 默认选项（`Auto`、不限页数）。
    pub fn new() -> Self {
        Self::default()
    }

    /// 指定解析选项（链式）。
    pub fn with_options(mut self, options: PdfOptions) -> Self {
        self.options = options;
        self
    }
}

impl ParseCapability for PdfiumWorkerBackend {
    fn id(&self) -> &str {
        "pdfium-worker"
    }
    fn formats(&self) -> &[&str] {
        &["pdf"]
    }
    fn kind(&self) -> BackendKind {
        BackendKind::Bundled
    }
    fn is_available(&self) -> bool {
        find_library().is_some()
    }
    fn parse(&self, path: &str) -> Result<RawDoc> {
        let tx = worker_sender()?
            .lock()
            .map_err(|_| DocError::corrupt("worker 锁"))?
            .clone();
        let (resp_tx, resp_rx) = mpsc::channel();
        tx.send((path.to_string(), self.options.clone(), resp_tx))
            .map_err(|_| DocError::corrupt("PDFium worker 已退出"))?;
        resp_rx
            .recv()
            .map_err(|_| DocError::corrupt("PDFium worker 无响应"))?
    }
}

/// 兜底后端 v1：pdf-extract（纯 Rust，无 dylib；CJK 无 ToUnicode 局限）。
#[derive(Debug, Clone, Default)]
pub struct PdfTextBackend {
    options: PdfOptions,
}

impl PdfTextBackend {
    /// 默认选项（不限页数）。
    pub fn new() -> Self {
        Self::default()
    }

    /// 指定解析选项（链式）；本后端只用到 `max_pages`。
    pub fn with_options(mut self, options: PdfOptions) -> Self {
        self.options = options;
        self
    }
}

impl ParseCapability for PdfTextBackend {
    fn id(&self) -> &str {
        "pdfium-text-v1"
    }
    fn formats(&self) -> &[&str] {
        &["pdf"]
    }
    fn kind(&self) -> BackendKind {
        BackendKind::Bundled
    }
    fn parse(&self, path: &str) -> Result<RawDoc> {
        let per_page = std::panic::catch_unwind(|| pdf_extract::extract_text_by_pages(path))
            .map_err(|_| {
                DocError::corrupt(
                    "pdf-extract v1 无法解析该 PDF（CJK CID/无 ToUnicode，需 pdfium-worker）",
                )
            })?
            .map_err(|e| {
                let msg = format!("{e}").to_lowercase();
                if msg.contains("password") || msg.contains("encrypt") || msg.contains("permission")
                {
                    DocError::encrypted(format!("PDF 加密或权限受限: {e}"))
                } else {
                    DocError::corrupt(format!("PDF 解析失败: {e}"))
                }
            })?;
        // max_pages（对齐 Python）：只取前 N 页
        let total = per_page.len();
        let limit = self.options.max_pages.unwrap_or(total).min(total);
        let truncated = limit < total;
        let pages: Vec<RawPage> = per_page
            .into_iter()
            .take(limit)
            .map(|page_text| RawPage {
                name: None,
                items: page_text
                    .lines()
                    .map(|l| RawTextItem {
                        text: l.to_string(),
                        ..Default::default()
                    })
                    .filter(|it| !it.text.trim().is_empty())
                    .collect(),
                ..Default::default()
            })
            .filter(|p| !p.items.is_empty())
            .collect();
        if pages.is_empty() {
            return Err(DocError::corrupt("PDF 无有效文本层"));
        }
        let mut raw = RawDoc {
            pages,
            meta: Default::default(),
            needs_ocr: false,
        };
        raw.meta
            .insert("pdf.truncated".into(), truncated.to_string());
        raw.needs_ocr = raw.pages.iter().all(|p| {
            p.items
                .iter()
                .map(|i| i.text.chars().count())
                .sum::<usize>()
                < 10
        });
        Ok(raw)
    }
}

// ---------------------------------------------------------------- layout（对照 Python process/layout.py）

/// 行级归一：把逐字/逐词 rect 合并成行级 item（对照 Python `_merge_line_fragments`）。
/// 无 bbox 的项（如 v1 兜底后端）原样保留，排在结果头部。
fn merge_lines(items: Vec<RawTextItem>) -> Vec<RawTextItem> {
    let no_bb: Vec<RawTextItem> = items
        .iter()
        .filter(|it| it.bbox.is_none())
        .cloned()
        .collect();
    let with_bb: Vec<(usize, RawTextItem)> = items
        .into_iter()
        .enumerate()
        .filter(|(_, it)| it.bbox.is_some())
        .collect();
    let mut lines: Vec<Vec<(usize, RawTextItem)>> = Vec::new();
    let mut sorted = with_bb.clone();
    sorted.sort_by(|a, b| {
        a.1.bbox
            .unwrap()
            .y0
            .total_cmp(&b.1.bbox.unwrap().y0)
            .then(a.1.bbox.unwrap().x0.total_cmp(&b.1.bbox.unwrap().x0))
    });
    for ent in &sorted {
        let bb = ent.1.bbox.unwrap();
        let mut placed = false;
        for line in lines.iter_mut() {
            // 基线对齐判同行（对齐 Python `_line_bottom_height` + `_merge_line_fragments`）：
            // 底边差 ≤ 0.3×(行代表高 + 候选高)。用纵向重叠会在密排行距≈字高时
            // 把相邻行误并（Python 侧已实测过这个坑）。
            let lb = line
                .iter()
                .map(|e| e.1.bbox.unwrap().y1)
                .fold(f32::MAX, f32::min);
            let lh = line
                .iter()
                .map(|e| e.1.bbox.unwrap().y1 - e.1.bbox.unwrap().y0)
                .fold(f32::MIN, f32::max);
            let bh = bb.y1 - bb.y0;
            if (lb - bb.y1).abs() <= 0.3 * (lh + bh) {
                line.push(ent.clone());
                placed = true;
                break;
            }
        }
        if !placed {
            lines.push(vec![ent.clone()]);
        }
    }
    let mut out: Vec<RawTextItem> = Vec::new();
    for mut line in lines {
        line.sort_by(|a, b| a.1.bbox.unwrap().x0.total_cmp(&b.1.bbox.unwrap().x0));
        let mut cur: Option<(String, Rect)> = None;
        for (_i, it) in line {
            let bb = it.bbox.unwrap();
            match &mut cur {
                None => cur = Some((it.text.clone(), bb)),
                Some((t, cb)) => {
                    let gap = bb.x0 - cb.x1;
                    let h = (cb.y1 - cb.y0).min(bb.y1 - bb.y0);
                    if gap <= (6.0_f32).max(0.6 * h) {
                        let sep = if gap > 0.2 * h { " " } else { "" };
                        *t = format!("{t}{sep}{}", it.text);
                        *cb = Rect {
                            x0: cb.x0.min(bb.x0),
                            y0: cb.y0.min(bb.y0),
                            x1: cb.x1.max(bb.x1),
                            y1: cb.y1.max(bb.y1),
                        };
                    } else {
                        out.push(RawTextItem {
                            text: std::mem::take(t),
                            bbox: Some(*cb),
                            ..Default::default()
                        });
                        cur = Some((it.text.clone(), bb));
                    }
                }
            }
        }
        if let Some((t, cb)) = cur {
            out.push(RawTextItem {
                text: t,
                bbox: Some(cb),
                ..Default::default()
            });
        }
    }
    out.splice(0..0, no_bb); // 无 bbox 项置于头部（顺序即原内容序）
    out
}

fn detect_table(lines: &[RawTextItem]) -> Option<(Vec<Vec<String>>, Vec<bool>)> {
    // y 聚行：与 Python `_group_lines` 同口径——**基线对齐**（底边差 ≤ 0.3×(行高+字高)）。
    // 用「纵向重叠 > 50%」在密排行距≈字高时会把相邻行并成一行（真实语料 05404 整栏坍缩）；
    // arxiv p8（Transformer 变体表）会因此丢掉 (A)/(B)/(D) 行（该行两个单元格被并成一格 <3 格）。
    let mut rows: Vec<Vec<RawTextItem>> = Vec::new();
    let mut sorted: Vec<&RawTextItem> = lines.iter().collect();
    sorted.sort_by(|a, b| {
        let (ab, bb) = (a.bbox.unwrap(), b.bbox.unwrap());
        ab.y0.total_cmp(&bb.y0).then(ab.x0.total_cmp(&bb.x0))
    });
    for it in sorted {
        let bb = it.bbox.unwrap();
        let bh = bb.y1 - bb.y0;
        let mut placed = false;
        for row in rows.iter_mut() {
            let lh = row
                .iter()
                .map(|r| r.bbox.unwrap().y1 - r.bbox.unwrap().y0)
                .fold(f32::MIN, f32::max);
            let lb = row
                .iter()
                .map(|r| r.bbox.unwrap().y1)
                .fold(f32::MAX, f32::min);
            if (lb - bb.y1).abs() <= 0.3 * (lh + bh) {
                row.push(it.clone());
                placed = true;
                break;
            }
        }
        if !placed {
            rows.push(vec![it.clone()]);
        }
    }
    rows.sort_by(|a, b| {
        a.iter()
            .map(|r| r.bbox.unwrap().y0)
            .fold(f32::MAX, f32::min)
            .total_cmp(
                &b.iter()
                    .map(|r| r.bbox.unwrap().y0)
                    .fold(f32::MAX, f32::min),
            )
    });
    if rows.len() < 2 {
        return None;
    }
    // x0 聚类（列锚点，容差 8pt）
    let mut xs: Vec<f32> = lines.iter().map(|it| it.bbox.unwrap().x0).collect();
    xs.sort_by(f32::total_cmp);
    let mut anchors: Vec<f32> = Vec::new();
    for x in xs {
        if anchors.is_empty() || x - *anchors.last().unwrap() > 8.0 {
            anchors.push(x);
        }
    }
    if anchors.len() < 3 {
        return None;
    }
    let col_of = |x: f32| -> usize {
        let mut best = 0usize;
        let mut bd = f32::MAX;
        for (i, a) in anchors.iter().enumerate() {
            let d = (x - a).abs();
            if d < bd {
                bd = d;
                best = i;
            }
        }
        best
    };
    let mut grid: Vec<Vec<RawTextItem>> = Vec::new();
    for mut row in rows {
        row.sort_by(|a, b| a.bbox.unwrap().x0.total_cmp(&b.bbox.unwrap().x0));
        let mut merged: Vec<RawTextItem> = Vec::new();
        for it in row {
            let bb = it.bbox.unwrap();
            match merged.last_mut() {
                Some(prev) if col_of(prev.bbox.unwrap().x0) == col_of(bb.x0) => {
                    prev.text = format!("{}{}", prev.text, it.text);
                    let pb = prev.bbox.unwrap();
                    prev.bbox = Some(Rect {
                        x0: pb.x0.min(bb.x0),
                        y0: pb.y0.min(bb.y0),
                        x1: pb.x1.max(bb.x1),
                        y1: pb.y1.max(bb.y1),
                    });
                }
                _ => merged.push(it),
            }
        }
        if merged.len() >= 3 {
            grid.push(merged);
        }
    }
    if grid.len() < 2 {
        return None;
    }
    let counts: Vec<usize> = grid.iter().map(|r| r.len()).collect();
    let modal = counts
        .iter()
        .max_by_key(|c| counts.iter().filter(|x| x == c).count())
        .copied()
        .unwrap_or(0);
    if modal < 3 {
        return None;
    }
    let consistent = counts.iter().filter(|c| **c == modal).count() as f32 / grid.len() as f32;
    if consistent < 0.6 {
        return None;
    }
    let used_keys: Vec<(f32, f32)> = grid
        .iter()
        .flat_map(|r| r.iter())
        .map(|it| {
            let b = it.bbox.unwrap();
            (b.x0, b.y0)
        })
        .collect();
    let used: Vec<bool> = lines
        .iter()
        .map(|it| {
            let b = it.bbox.unwrap();
            used_keys.contains(&(b.x0, b.y0))
        })
        .collect();
    // 表格区域自洽性：真表格的 bbox 内几乎只有表格行。若 bbox 内还散落着大量未入表的
    // 文本（正文/图注），说明这是「正文行 + 图内小字号标签」被并成多列造成的误判——
    // 典型后果是正文句子被逗号拼接的标签掰断（2026-10-26 tracemonkey p9）。
    let trect = {
        let hits: Vec<Rect> = lines
            .iter()
            .zip(&used)
            .filter(|(_, u)| **u)
            .map(|(it, _)| it.bbox.unwrap())
            .collect();
        Rect {
            x0: hits.iter().map(|r| r.x0).fold(f32::MAX, f32::min),
            y0: hits.iter().map(|r| r.y0).fold(f32::MAX, f32::min),
            x1: hits.iter().map(|r| r.x1).fold(f32::MIN, f32::max),
            y1: hits.iter().map(|r| r.y1).fold(f32::MIN, f32::max),
        }
    };
    let inside = |b: Rect| {
        b.x0 >= trect.x0 - 1.0
            && b.x1 <= trect.x1 + 1.0
            && b.y0 >= trect.y0 - 1.0
            && b.y1 <= trect.y1 + 1.0
    };
    let cells_len: Vec<usize> = grid
        .iter()
        .flat_map(|r| r.iter())
        .map(|it| it.text.chars().count())
        .collect();
    let in_table: usize = cells_len.iter().sum();
    let long_ratio = if cells_len.is_empty() {
        0.0
    } else {
        cells_len.iter().filter(|n| **n > 40).count() as f32 / cells_len.len() as f32
    };
    let stray: usize = lines
        .iter()
        .zip(&used)
        .filter(|(it, u)| !**u && inside(it.bbox.unwrap()))
        .map(|(it, _)| it.text.chars().count())
        .sum();
    if stray > in_table && long_ratio >= 0.2 {
        return None;
    }
    // 行内「长句独大」：一行里 ≥1 个 ≥40 字符的单元格，且比该行其余单元格都大 3 倍以上
    // —— 真表格（尤其数字表）不会这样；这是「正文一列 + 图内短标签」的典型形态
    //（tracemonkey p1：`inner loop header, but the outer loop he` + `Bytecodes` + `Overhead`）。
    let lopsided = grid
        .iter()
        .filter(|r| {
            let lens: Vec<usize> = r.iter().map(|it| it.text.chars().count()).collect();
            if lens.len() < 2 {
                return false;
            }
            let max = *lens.iter().max().unwrap_or(&0);
            if max < 40 {
                return false;
            }
            let rest = lens
                .iter()
                .filter(|n| **n != max)
                .max()
                .copied()
                .unwrap_or(0);
            rest > 0 && max >= 3 * rest
        })
        .count();
    if !grid.is_empty() && lopsided as f32 / grid.len() as f32 >= 0.5 {
        return None;
    }
    let rows_out: Vec<Vec<String>> = grid
        .into_iter()
        .map(|r| r.into_iter().map(|it| it.text).collect())
        .collect();
    Some((rows_out, used))
}

/// 多栏阅读顺序：只对「原序明显左右逐行交错」的页重排（与 Python `_column_order` 同口径）。
///
/// 很多 PDF（LaTeX/Word 导出）的内容流本身就是栏序，盲目重排只会把好顺序改坏
/// （实测 arxiv 论文会从 sim 0.99 掉到 0.86）。因此先用「相邻行同 y 且 x0 相差 > 半页宽」
/// 的比例做交错指纹，低于阈值一律保持原序。
///
/// 确认交错后与 Python 同序走两条路：
/// ① **沟槽法**（`order_by_gutter`）：窄项的 x 占位直方图找栏间零占位带——LaTeX/双栏论文
///    的常态，最稳；
/// ② 沟槽被跨栏元素填平/切分失败时回退**行首 x0 聚类**（`order_by_leads`）。
///
/// 只有一条路（聚类）时，表格页的多列 x0（页眉单元格 210/233/270/320/359…）会在
/// `0.25×页宽` 的阈值下链式并成一栏 → 整页放弃重排（真实语料 2610.32874v1 p7）。
fn column_order(items: Vec<RawTextItem>) -> Vec<RawTextItem> {
    if items.len() < 4 {
        return items;
    }
    let (x_min, x_max) = items.iter().fold((f32::MAX, f32::MIN), |(lo, hi), it| {
        let b = it.bbox.unwrap();
        (lo.min(b.x0), hi.max(b.x1))
    });
    let span = x_max - x_min;
    if span <= 1.0 || interleaved_ratio(&items, span) < 0.25 {
        return items;
    }
    if let Some(out) = order_by_gutter(&items, x_min, x_max, span) {
        return out;
    }
    order_by_leads(items, span)
}

/// 沟槽法（对齐 Python `_column_order` 的 `occ` 直方图分支）：窄项在 x 轴上的零占位带
/// 即栏沟；按沟槽切出的每段各成一栏，栏内自上而下。跨栏元素（宽度 > 0.6×内容宽）不参与
/// 占位统计（否则跨栏标题/图注会把栏沟填平），但仍参与按中心点归栏。
fn order_by_gutter(
    items: &[RawTextItem],
    x_min: f32,
    x_max: f32,
    span: f32,
) -> Option<Vec<RawTextItem>> {
    const MIN_GUTTER: usize = 20;
    let n = span as usize + 1;
    if n <= MIN_GUTTER * 3 {
        return None;
    }
    let wide = span * 0.6;
    let mut occ = vec![0usize; n];
    for it in items {
        let b = it.bbox.unwrap();
        if (b.x1 - b.x0) > wide {
            continue;
        }
        let lo = ((b.x0 - x_min).max(0.0) as usize).min(n - 1);
        let hi = (((b.x1 - x_min) as usize).min(n - 1)).max(lo);
        for v in occ.iter_mut().take(hi + 1).skip(lo) {
            *v += 1;
        }
    }
    let mut gutters: Vec<(usize, usize)> = Vec::new();
    let mut run: Option<usize> = None;
    for (i, v) in occ.iter().enumerate() {
        if *v == 0 {
            if run.is_none() {
                run = Some(i);
            }
        } else if let Some(s) = run.take() {
            if i - s >= MIN_GUTTER {
                gutters.push((s, i));
            }
        }
    }
    if let Some(s) = run {
        if n - s >= MIN_GUTTER {
            gutters.push((s, n));
        }
    }
    if gutters.is_empty() {
        return None;
    }

    let center = |b: Rect| (b.x0 + b.x1) / 2.0;
    let count_in = |lo: f32, hi: f32| {
        items
            .iter()
            .filter(|it| {
                let c = center(it.bbox.unwrap());
                c >= lo && c < hi
            })
            .count()
    };
    let mut bounds: Vec<(f32, f32)> = Vec::new();
    let mut prev = x_min;
    for (g0, g1) in &gutters {
        let seg = (prev, x_min + *g0 as f32);
        if count_in(seg.0, seg.1) >= 2 {
            bounds.push(seg);
            prev = x_min + *g1 as f32;
        }
    }
    let last = (prev, x_max);
    if !bounds.is_empty() && count_in(last.0, last.1) >= 2 {
        bounds.push(last);
    }
    if bounds.len() < 2 {
        return None;
    }
    let mut out: Vec<RawTextItem> = Vec::with_capacity(items.len());
    for (lo, hi) in &bounds {
        let mut col: Vec<RawTextItem> = items
            .iter()
            .filter(|it| {
                let c = center(it.bbox.unwrap());
                c >= *lo && c < *hi
            })
            .cloned()
            .collect();
        col.sort_by(|a, b| {
            let (ab, bb) = (a.bbox.unwrap(), b.bbox.unwrap());
            ab.y0.total_cmp(&bb.y0).then(ab.x0.total_cmp(&bb.x0))
        });
        out.extend(col);
    }
    // 跨栏元素（中心落在栏沟内）不在任何栏内 → 沟槽法不适用，交给聚类回退
    if out.len() != items.len() {
        return None;
    }
    Some(out)
}

/// 视觉行行首 x0 列表 `(行首 x0, 行宽)`（对齐 Python `_group_lines` + `_split_visual_lines`）：
/// 先按基线聚组成"行"，再在横向间隙处切开——CJK 逐字 rect / 单词级 fragment 的小间隙不切，
/// 左栏行尾与右栏行首、表格单元格之间的大间隙切开。切开后每段的行首 x0 才代表"栏的起点"。
fn visual_line_leads(items: &[RawTextItem]) -> Vec<(f32, f32)> {
    let mut order: Vec<&RawTextItem> = items.iter().collect();
    order.sort_by(|a, b| {
        let (ab, bb) = (a.bbox.unwrap(), b.bbox.unwrap());
        ab.y0.total_cmp(&bb.y0).then(ab.x0.total_cmp(&bb.x0))
    });
    let mut bands: Vec<Vec<Rect>> = Vec::new();
    for it in order {
        let b = it.bbox.unwrap();
        let bh = b.y1 - b.y0;
        let mut placed = false;
        for band in bands.iter_mut() {
            let lb = band.iter().map(|r| r.y1).fold(f32::MAX, f32::min);
            let lh = band.iter().map(|r| r.y1 - r.y0).fold(f32::MIN, f32::max);
            if (lb - b.y1).abs() <= 0.3 * (lh + bh) {
                band.push(b);
                placed = true;
                break;
            }
        }
        if !placed {
            bands.push(vec![b]);
        }
    }
    let frag = |seg: &[Rect]| -> (f32, f32) {
        let x0 = seg.iter().map(|r| r.x0).fold(f32::MAX, f32::min);
        let x1 = seg.iter().map(|r| r.x1).fold(f32::MIN, f32::max);
        (x0, x1 - x0)
    };
    let mut out: Vec<(f32, f32)> = Vec::new();
    for mut band in bands {
        band.sort_by(|a, b| a.x0.total_cmp(&b.x0));
        let mut cur: Vec<Rect> = vec![band[0]];
        for b in band.into_iter().skip(1) {
            let prev = *cur.last().unwrap();
            let h = ((prev.y1 - prev.y0).min(b.y1 - b.y0)).max(1.0);
            if b.x0 - prev.x1 > (2.0 * h).max(12.0) {
                out.push(frag(&cur));
                cur = vec![b];
            } else {
                cur.push(b);
            }
        }
        out.push(frag(&cur));
    }
    out
}

/// 行首 x0 单链接聚类分栏（对齐 Python `_cluster_by_x`）。
/// 不能用 `[x0, x1]` 区间合并：居中跨栏图注/窄跨栏图虽然宽度 < 60% 页宽，却横跨栏沟，
/// 区间合并会把右栏起点并进左栏（tracemonkey p11：图注 162..446 吞掉 317 的右栏）。
///
/// 聚类输入必须是**视觉行行首**（`visual_line_leads`），不是逐项 x0：表格页逐项 x0 有
/// 十几个不同值（单元格 210/233/270/320/359…），在 `0.25×页宽` 阈值下会链式并成一栏，
/// 整页放弃重排（真实语料 2610.32874v1 p7 `sim` 0.318）。成员 < 3 的孤立起点
/// （居中图注、短缩进）不作栏锚点，交给「最后一个 ≤ x0 的栏起点」归栏。
fn order_by_leads(items: Vec<RawTextItem>, span: f32) -> Vec<RawTextItem> {
    let wide = span * 0.6;
    let per_line = visual_line_leads(&items);
    if per_line.len() < 4 {
        return items;
    }
    let mut leads: Vec<f32> = per_line
        .iter()
        .filter(|(_, w)| *w <= wide)
        .map(|(x, _)| *x)
        .collect();
    if leads.len() < 4 {
        return items;
    }
    leads.sort_by(|a, b| a.total_cmp(b));
    // 阈值用**行首 x0 自己的跨度**（对齐 Python `_cluster_by_x`：`span = xs[-1] - xs[0]`），
    // 不能用整页内容跨度：表格页 bbox span（504）会把 thr 抬到 126pt，行首 118 → 244 这一步
    // 就跨过去了，十几个起点链成一簇 → 放弃重排（2610.32874 p7 `sim` 0.318）。
    let lead_span = leads.last().copied().unwrap_or(0.0) - leads.first().copied().unwrap_or(0.0);
    if lead_span <= 40.0 {
        return items;
    }
    let thr = (lead_span * 0.25).max(40.0);
    let mut groups: Vec<Vec<f32>> = Vec::new();
    for a in leads {
        match groups.last_mut() {
            Some(g) if a - *g.last().unwrap() <= thr => g.push(a),
            _ => groups.push(vec![a]),
        }
    }
    let cols: Vec<f32> = groups
        .iter()
        .filter(|g| g.len() >= 3)
        .map(|g| g[0])
        .collect();
    if cols.len() < 2 {
        return items;
    }

    // 归栏：按「最后一个 ≤ x0 的栏起点」归档（跨栏元素 x0 在首栏 → 归首栏）
    let total = items.len();
    let mut buckets: Vec<Vec<usize>> = vec![Vec::new(); cols.len()];
    for (i, it) in items.iter().enumerate() {
        let bx = it.bbox.unwrap().x0;
        let mut idx = 0;
        for (c, s) in cols.iter().enumerate() {
            if bx >= *s - 0.5 {
                idx = c;
            }
        }
        buckets[idx].push(i);
    }
    // 双栏硬校验（对齐 Python `_cluster_by_x`）：前两栏各 ≥3 行，且次栏要有足够多「与首栏
    // 同一水平带（|Δy0| < 12pt）」的行。单栏文档的缩进/居中标题也会聚出第二个簇，但它们与
    // 首栏不同行——不校验就重排，正文会被读成「先全部首栏、再全部次栏」。
    if buckets[0].len() < 3 || buckets[1].len() < 3 {
        return items;
    }
    let left_ys: Vec<f32> = buckets[0]
        .iter()
        .map(|&i| items[i].bbox.unwrap().y0)
        .collect();
    let paired = buckets[1]
        .iter()
        .filter(|&&i| {
            let y = items[i].bbox.unwrap().y0;
            left_ys.iter().any(|ly| (y - ly).abs() < 12.0)
        })
        .count();
    if (paired as f32) / (buckets[1].len() as f32) < 0.3 {
        return items;
    }
    let mut out = Vec::with_capacity(total);
    for bucket in &mut buckets {
        bucket.sort_by(|&a, &b| {
            let (ay, ax) = (items[a].bbox.unwrap().y0, items[a].bbox.unwrap().x0);
            let (by, bx) = (items[b].bbox.unwrap().y0, items[b].bbox.unwrap().x0);
            ay.total_cmp(&by).then(ax.total_cmp(&bx))
        });
        out.extend(bucket.iter().map(|&i| items[i].clone()));
    }
    debug_assert_eq!(out.len(), total);
    out
}

/// 相邻行中「同 y 但 x0 相差超过半页宽」的比例——左右逐行交错的指纹。
fn interleaved_ratio(items: &[RawTextItem], span: f32) -> f32 {
    if items.len() < 2 {
        return 0.0;
    }
    let half = (span * 0.5).max(1.0);
    let mut hits = 0usize;
    for w in items.windows(2) {
        let a = w[0].bbox.unwrap();
        let b = w[1].bbox.unwrap();
        if (b.y0 - a.y0).abs() < 3.0 && (b.x0 - a.x0).abs() >= half {
            hits += 1;
        }
    }
    hits as f32 / (items.len() - 1) as f32
}

fn assemble(raw: &RawDoc, mode: LayoutMode) -> Document {
    let pages: Vec<Page> = raw
        .pages
        .iter()
        .map(|rp| {
            // ① 行级归一（CJK 逐字 rect → 行级 item）；`raw` 模式跳过
            let (lines, all_bbox) = if mode.reflows() {
                let lines = merge_lines(rp.items.clone());
                let all_bbox = lines.iter().all(|it| it.bbox.is_some());
                (lines, all_bbox)
            } else {
                (rp.items.clone(), false)
            };
            // ② 表格检测（≥3 列 + ≥60% 行一致性）；有任一无 bbox 项 / raw 模式则跳过
            let (table_rows, used, table_rect) =
                match if all_bbox { detect_table(&lines) } else { None } {
                    Some((rows, used)) => {
                        let rect = {
                            let hits: Vec<Rect> = lines
                                .iter()
                                .zip(&used)
                                .filter(|(_, u)| **u)
                                .map(|(it, _)| it.bbox.unwrap())
                                .collect();
                            if hits.is_empty() {
                                None
                            } else {
                                Some(Rect {
                                    x0: hits.iter().map(|r| r.x0).fold(f32::MAX, f32::min),
                                    y0: hits.iter().map(|r| r.y0).fold(f32::MAX, f32::min),
                                    x1: hits.iter().map(|r| r.x1).fold(f32::MIN, f32::max),
                                    y1: hits.iter().map(|r| r.y1).fold(f32::MIN, f32::max),
                                })
                            }
                        };
                        (Some(rows), used, rect)
                    }
                    None => (None, vec![false; lines.len()], None),
                };
            // ③ 剩余段落 → 多栏阅读顺序
            let paras: Vec<RawTextItem> = lines
                .iter()
                .zip(&used)
                .filter(|(_, u)| !**u)
                .map(|(it, _)| it.clone())
                .collect();
            let ordered: Vec<RawTextItem> = if all_bbox { column_order(paras) } else { paras };
            // ④ 块与页文本：段落保持（栏序）顺序；表格按 y0 插入首个更低段落之前
            let mut blocks: Vec<docparser_core::model::Block> = Vec::new();
            if let Some(rows) = &table_rows {
                blocks.push(docparser_core::model::Block {
                    kind: BlockKind::Table,
                    table: Some(docparser_core::model::TableData {
                        rows: rows.clone(),
                        ..Default::default()
                    }),
                    bbox: table_rect,
                    ..Default::default()
                });
            }
            for it in &ordered {
                blocks.push(docparser_core::model::Block {
                    kind: BlockKind::Paragraph,
                    content: it.text.clone(),
                    bbox: it.bbox,
                    ..Default::default()
                });
            }
            let mut parts: Vec<String> = ordered.iter().map(|it| it.text.clone()).collect();
            if let Some(rows) = &table_rows {
                let ty = table_rect.map(|r| r.y0).unwrap_or(0.0);
                let table_text = rows
                    .iter()
                    .map(|r| r.join(","))
                    .collect::<Vec<_>>()
                    .join("\n");
                // 表格插入到首个 y 更低段落之前；空页/整页表格直接置首
                let mut idx = parts.len();
                for (k, it) in ordered.iter().enumerate() {
                    if it.bbox.map(|r| r.y0).unwrap_or(f32::MAX) > ty {
                        idx = k;
                        break;
                    }
                }
                parts.insert(idx, table_text);
            }
            // ④ 嵌入图 OCR 文本并入页文本（KB 语义：页文本 + "\n" + 图 OCR；有才并入）
            let imgs: Vec<docparser_core::model::Image> = rp
                .images
                .iter()
                .map(|im| docparser_core::model::Image {
                    bbox: im.bbox,
                    dedup_key: image_dedup_key(im),
                    ocr_text: im.ocr_text.clone(),
                    ..Default::default()
                })
                .collect();
            for im in &imgs {
                if let Some(t) = &im.ocr_text {
                    if !t.trim().is_empty() {
                        parts.push(t.clone());
                    }
                }
            }
            let text = parts
                .into_iter()
                .filter(|s| !s.trim().is_empty())
                .collect::<Vec<_>>()
                .join("\n");
            Page {
                blocks,
                text,
                images: imgs,
                width: rp.width,
                height: rp.height,
                rotation: rp.rotation,
                ..Default::default()
            }
        })
        .collect();

    let mut doc = Document {
        pages,
        ..Default::default()
    };
    // 逐项对齐 Python `meta.extra["pdf"]` 白名单（值是 JSON，避免改 core 的 String map）
    let mut pdf: serde_json::Map<String, serde_json::Value> = serde_json::Map::new();
    for (src, dst) in [
        ("pdf.version", "pdf_version"),
        ("pdf.title", "title"),
        ("pdf.author", "author"),
        ("pdf.producer", "producer"),
        ("pdf.creator", "creator"),
        ("headers_footers", "headers_footers"),
    ] {
        if let Some(v) = raw.meta.get(src) {
            pdf.insert(dst.to_string(), serde_json::Value::String(v.clone()));
        }
    }
    for (src, dst) in [
        ("pdf.complexity", "complexity"),
        ("pdf.page_errors", "page_errors"),
    ] {
        if let Some(v) = raw.meta.get(src) {
            if let Ok(parsed) = serde_json::from_str::<serde_json::Value>(v) {
                pdf.insert(dst.to_string(), parsed);
            }
        }
    }
    pdf.insert(
        "truncated".to_string(),
        serde_json::Value::Bool(
            raw.meta
                .get("pdf.truncated")
                .map(|s| s == "true")
                .unwrap_or(false),
        ),
    );
    pdf.insert(
        "layout_modes".to_string(),
        serde_json::json!(vec![mode.as_str(); doc.pages.len()]),
    );
    if let Ok(s) = serde_json::to_string(&pdf) {
        doc.meta.extra.insert("pdf".to_string(), s);
    }
    doc.meta
        .extra
        .insert("needs_ocr".to_string(), raw.needs_ocr.to_string());
    doc
}

/// PDF 插件：`assemble` 里做行归并 / 表格 / 分栏（版式模式可配）。
#[derive(Debug, Clone, Default)]
pub struct PdfPlugin {
    options: PdfOptions,
}

impl PdfPlugin {
    /// 默认插件（`LayoutMode::Auto`）。
    pub fn new() -> Self {
        Self::default()
    }

    /// 指定选项（链式），常用 `with_layout_mode(LayoutMode::Raw)` 关掉版式重排。
    pub fn with_options(mut self, options: PdfOptions) -> Self {
        self.options = options;
        self
    }
}

impl FormatPlugin for PdfPlugin {
    fn id(&self) -> &str {
        "pdf"
    }
    fn formats(&self) -> &[&str] {
        &["pdf"]
    }
    fn default_parse_chain(&self) -> Vec<&'static str> {
        // worker 优先；worker 缺失或解析失败时回退 v1（encrypted/unsupported 终止码由 engine 处理）
        vec!["pdfium-worker", "pdfium-text-v1"]
    }
    fn default_process_chain(&self) -> Vec<&'static str> {
        vec![]
    }
    fn assemble(&self, raw: &RawDoc) -> Document {
        assemble(raw, self.options.layout_mode)
    }
}

/// 注册 PDF 后端（worker 可用才注册；v1 恒可用）与插件（默认选项）。
pub fn register_defaults(reg: &mut Registry) {
    register_with(reg, &PdfOptions::default());
}

/// 注册 PDF 后端与插件，并注入解析选项（版式模式 / 页数上限）。
pub fn register_with(reg: &mut Registry, options: &PdfOptions) {
    reg.register_parse(
        Arc::new(PdfTextBackend::new().with_options(options.clone())),
        None,
    )
    .unwrap();
    if find_library().is_some() {
        reg.register_parse(
            Arc::new(PdfiumWorkerBackend::new().with_options(options.clone())),
            None,
        )
        .unwrap();
    }
    reg.register_plugin(Arc::new(PdfPlugin::new().with_options(options.clone())));
}

/// 便于外部核对终止码语义。
pub fn is_terminal(e: &DocError) -> bool {
    matches!(e.code, ErrorCode::Encrypted | ErrorCode::Unsupported)
}

#[cfg(test)]
mod tests {
    use super::*;

    fn item(text: &str, x0: f32, y0: f32, x1: f32, y1: f32) -> RawTextItem {
        RawTextItem {
            text: text.to_string(),
            bbox: Some(Rect { x0, y0, x1, y1 }),
            ..Default::default()
        }
    }

    fn order_stream(items: Vec<RawTextItem>) -> Vec<RawTextItem> {
        column_order(items)
    }

    fn raw_image(data: Vec<u8>, ext: &str, px: Option<(u32, u32)>) -> RawImage {
        RawImage {
            data,
            bbox: None,
            ext: ext.to_string(),
            px,
            ocr_text: None,
        }
    }

    /// 去重键：有字节 → md5 十六进制（与 Python `hashlib.md5(data).hexdigest()` 同值）
    #[test]
    fn image_dedup_key_hashes_bytes() {
        let im = raw_image(b"abc".to_vec(), "png", Some((60, 40)));
        assert_eq!(
            image_dedup_key(&im).as_deref(),
            Some("900150983cd24fb0d6963f7d28e17f72")
        );
        // 同字节 → 同键（同页重复 logo 只存一份的前提）
        let same = raw_image(b"abc".to_vec(), "jpg", Some((10, 10)));
        assert_eq!(image_dedup_key(&im), image_dedup_key(&same));
        let other = raw_image(b"abd".to_vec(), "png", Some((60, 40)));
        assert_ne!(image_dedup_key(&im), image_dedup_key(&other));
    }

    /// 无字节（lazy 路径未解码）→ `"{w}x{h}"` / `"{w}x{h}@{ext}"` 兜底，与 Python 同形；
    /// 连像素尺寸都没有时给 None（不编造键，避免把装饰图都聚成同一个键）。
    #[test]
    fn image_dedup_key_falls_back_to_size() {
        assert_eq!(
            image_dedup_key(&raw_image(Vec::new(), "png", Some((120, 80)))).as_deref(),
            Some("120x80@png")
        );
        assert_eq!(
            image_dedup_key(&raw_image(Vec::new(), "", Some((120, 80)))).as_deref(),
            Some("120x80@")
        );
        assert_eq!(image_dedup_key(&raw_image(Vec::new(), "png", None)), None);
    }

    #[test]
    fn layout_mode_parses_roundtrip() {
        for (s, m) in [
            ("auto", LayoutMode::Auto),
            ("REBUILD", LayoutMode::Rebuild),
            (" raw ", LayoutMode::Raw),
        ] {
            let parsed = LayoutMode::parse(s).expect("应可解析");
            assert_eq!(parsed, m);
            assert_eq!(parsed.as_str(), m.as_str());
        }
        assert!(LayoutMode::parse("fast").is_none());
        assert!(LayoutMode::Auto.reflows() && LayoutMode::Rebuild.reflows());
        assert!(!LayoutMode::Raw.reflows());
        assert_eq!(LayoutMode::default(), LayoutMode::Auto);
    }

    #[test]
    fn pdf_version_maps_to_dotted_string() {
        assert_eq!(pdf_version_str(PdfDocumentVersion::Pdf1_7), "1.7");
        assert_eq!(pdf_version_str(PdfDocumentVersion::Pdf2_0), "2.0");
        assert_eq!(pdf_version_str(PdfDocumentVersion::Other(21)), "2.1");
        assert_eq!(pdf_version_str(PdfDocumentVersion::Unset), "");
    }

    /// 同一条边带内多个重复文本（页眉标题 + 页码）必须全部剔除且不 panic：
    /// 旧实现按 HashMap 顺序边算边 `Vec::remove`，先删的会让后一个 key 的索引整体前移
    /// → 越界（真实语料 2610.32982v1：`removal index (is 80) should be < len (is 79)`）。
    #[test]
    fn strip_headers_footers_removes_multiple_repeated_texts() {
        let page = || RawPage {
            items: vec![
                item("Conf Title", 10.0, 5.0, 300.0, 15.0),
                item("正文第一行", 10.0, 100.0, 300.0, 112.0),
                item("正文第二行", 10.0, 120.0, 300.0, 132.0),
                item("123", 550.0, 5.0, 580.0, 15.0),
            ],
            width: Some(595.0),
            height: Some(842.0),
            ..Default::default()
        };
        let mut pages = vec![page(), page(), page()];
        let removed = strip_headers_footers(&mut pages);
        assert_eq!(removed.len(), 2, "两条重复页眉都应记录：{removed:?}");
        for p in &pages {
            let texts: Vec<&str> = p.items.iter().map(|i| i.text.as_str()).collect();
            assert_eq!(texts, vec!["正文第一行", "正文第二行"], "只应保留正文行");
        }
    }

    /// 同一行的逐字 fragment（基线一致、间隙小）合并成一个 item。
    #[test]
    fn merge_lines_joins_fragments_on_same_baseline() {
        let out = merge_lines(vec![
            item("北", 10.0, 100.0, 22.0, 112.0),
            item("京", 22.0, 100.5, 34.0, 112.5),
            item("市", 34.0, 100.0, 46.0, 112.0),
        ]);
        assert_eq!(out.len(), 1);
        assert_eq!(out[0].text, "北京市");
    }

    /// 基线对齐判同行：行距紧（≈字高）时不能把相邻两行并成一行
    /// （旧口径「纵向重叠 > 50%」会误并，Python 侧已实测）。
    #[test]
    fn merge_lines_keeps_tightly_spaced_lines_apart() {
        let out = merge_lines(vec![
            item("第一行", 10.0, 100.0, 60.0, 112.0),
            item("第二行", 10.0, 113.0, 60.0, 125.0),
        ]);
        assert_eq!(out.len(), 2, "行距 1pt 也应判为两行：{:?}", out);
    }

    /// 同一基线但水平间隙超过 max(6pt, 0.6×字高)：不并（跨栏/跨单元格场景）。
    #[test]
    fn merge_lines_splits_on_large_horizontal_gap() {
        let out = merge_lines(vec![
            item("左栏", 10.0, 100.0, 40.0, 112.0),
            item("右栏", 200.0, 100.0, 230.0, 112.0),
        ]);
        assert_eq!(out.len(), 2);
        assert_eq!(out[0].text, "左栏");
        assert_eq!(out[1].text, "右栏");
    }

    /// 左右逐行交错的双栏页：按栏重排成「左栏读完再右栏」。
    #[test]
    fn column_order_reorders_interleaved_two_columns() {
        let mut items = Vec::new();
        for i in 0..4 {
            let y = 100.0 + i as f32 * 12.0;
            items.push(item(&format!("左{i}"), 54.0, y, 293.0, y + 8.0));
            items.push(item(&format!("右{i}"), 317.0, y, 556.0, y + 8.0));
        }
        let out = order_stream(items);
        let texts: Vec<&str> = out.iter().map(|it| it.text.as_str()).collect();
        assert_eq!(
            texts,
            vec!["左0", "左1", "左2", "左3", "右0", "右1", "右2", "右3"],
            "双栏应读成栏序而非左右逐行交错"
        );
    }

    /// 居中窄图注（宽 < 60% 页宽，但横跨栏沟）不能把右栏并入左栏
    /// （tracemonkey p11 回归：旧口径按 [x0,x1] 区间合并锚点，图注 162..446 吞掉 317 的右栏）。
    #[test]
    fn column_order_keeps_right_column_with_centered_caption() {
        let mut items = Vec::new();
        for i in 0..4 {
            let y = 100.0 + i as f32 * 12.0;
            items.push(item(&format!("左{i}"), 54.0, y, 293.0, y + 8.0));
            items.push(item(&format!("右{i}"), 317.0, y, 556.0, y + 8.0));
        }
        items.push(item("居中图注", 162.0, 400.0, 446.0, 408.0));
        let out = order_stream(items);
        let texts: Vec<&str> = out.iter().map(|it| it.text.as_str()).collect();
        assert_eq!(
            texts,
            vec![
                "左0",
                "左1",
                "左2",
                "左3",
                "居中图注",
                "右0",
                "右1",
                "右2",
                "右3"
            ],
            "图注按 x0 归首栏，右栏仍须整段在后：{:?}",
            texts
        );
    }

    /// 聚类阈值必须用**行首 x0 自己的跨度**（Python `_cluster_by_x` 口径），不能用整页内容跨度：
    /// 表格页内容跨度大、行首分布窄，用内容跨度会把 54→150 这种 96pt 的间隔一起吞掉，
    /// 十几个起点链成一簇后放弃重排（2610.32874 p7 `sim` 0.318）。
    #[test]
    fn order_by_leads_threshold_uses_lead_span() {
        let mut items = Vec::new();
        for i in 0..5 {
            let y = 100.0 + i as f32 * 12.0;
            items.push(item(&format!("左{i}"), 54.0, y, 140.0, y + 8.0));
            items.push(item(&format!("右{i}"), 319.0, y, 560.0, y + 8.0));
        }
        for i in 0..3 {
            let y = 100.0 + i as f32 * 12.0;
            items.push(item(&format!("中{i}"), 160.0, y, 210.0, y + 8.0));
        }
        // 内容跨度 506（旧口径 thr=126 → 54/150 链成一栏）；行首跨度 265（新口径 thr≈66）
        let out = order_by_leads(items, 506.0);
        let texts: Vec<&str> = out.iter().map(|it| it.text.as_str()).collect();
        let last_left = texts.iter().rposition(|t| t.starts_with("左")).unwrap();
        let first_mid = texts.iter().position(|t| t.starts_with("中")).unwrap();
        assert!(
            first_mid > last_left,
            "行首 150 应自成栏、不能让 54 与 150 合并：{texts:?}"
        );
    }

    /// 单栏页 + 居中大标题：标题行首 x0 也会聚成第二簇，但没有「与首栏同一水平带」的行，
    /// 必须放弃重排（对齐 Python `_cluster_by_x` 的双栏硬校验）。
    /// 旧实现只判 `cols.len() >= 2`，会把正文读成「先全部正文行、再把标题搬到末尾」。
    #[test]
    fn order_by_leads_rejects_centered_title_single_column() {
        let mut items = Vec::new();
        // 3 行居中标题（行首 200），下方 6 行正文（行首 54）；行宽都 ≤0.6×内容跨度，
        // 才不会被 `visual_line_leads` 的「宽项不作栏锚点」过滤掉（否则函数直接早退、测不到校验）
        for i in 0..3 {
            let y = 100.0 + i as f32 * 12.0;
            items.push(item("TITLE", 200.0, y, 380.0, y + 10.0));
        }
        for i in 0..6 {
            let y = 150.0 + i as f32 * 12.0;
            items.push(item(&format!("正文{i}"), 54.0, y, 300.0, y + 8.0));
        }
        let before: Vec<String> = items.iter().map(|it| it.text.clone()).collect();
        let out = order_by_leads(items, 506.0);
        let after: Vec<String> = out.iter().map(|it| it.text.clone()).collect();
        assert_eq!(after, before, "居中标题 + 正文的单栏页不应被分栏重排");
    }

    /// 内容流本身已是栏序（LaTeX/Word 导出）的页不重排——交错指纹低于阈值即保持原序。
    #[test]
    fn column_order_keeps_sequential_flow_untouched() {
        let mut items = Vec::new();
        for i in 0..4 {
            let y = 100.0 + i as f32 * 12.0;
            items.push(item(&format!("左{i}"), 54.0, y, 293.0, y + 8.0));
        }
        for i in 0..4 {
            let y = 100.0 + i as f32 * 12.0;
            items.push(item(&format!("右{i}"), 317.0, y, 556.0, y + 8.0));
        }
        let before: Vec<String> = items.iter().map(|it| it.text.clone()).collect();
        let out = order_stream(items);
        let after: Vec<String> = out.iter().map(|it| it.text.clone()).collect();
        assert_eq!(after, before, "已是栏序的页不应被重排");
    }

    /// 行内单元格基线参差（行首标签比数字高 1.5pt）时仍按视觉行分组
    /// （arxiv p8 表 3 回归：旧的「纵向重叠 > 50%」口径把 (A)/(B)/(D) 行并没了，8 行只剩 5 行）。
    #[test]
    fn detect_table_groups_rows_with_offset_label_cells() {
        let mut lines = Vec::new();
        for i in 0..8 {
            let y = 100.0 + i as f32 * 10.0;
            lines.push(item("(A) ", 100.0, y + 0.5, 140.0, y + 9.5));
            lines.push(item("16", 200.0, y, 230.0, y + 8.0));
            lines.push(item("32", 300.0, y, 330.0, y + 8.0));
            lines.push(item("4.91", 400.0, y, 430.0, y + 8.0));
        }
        let (rows, used) = detect_table(&lines).expect("应认定为表格");
        assert_eq!(rows.len(), 8, "8 个视觉行应保持 8 行：{:?}", rows);
        assert_eq!(rows[0].len(), 4);
        assert_eq!(used.iter().filter(|u| **u).count(), 32);
    }

    /// 无 bbox 项（v1 兜底后端）原样保留在头部，且不参与合并。
    #[test]
    fn merge_lines_keeps_bboxless_items() {
        let out = merge_lines(vec![
            RawTextItem {
                text: "无坐标".into(),
                ..Default::default()
            },
            item("有坐标", 10.0, 100.0, 40.0, 112.0),
        ]);
        assert_eq!(out.len(), 2);
        assert_eq!(out[0].text, "无坐标");
        assert!(out[0].bbox.is_none());
        assert_eq!(out[1].text, "有坐标");
    }

    fn raw_doc_with_two_lines() -> RawDoc {
        RawDoc {
            pages: vec![RawPage {
                items: vec![
                    // 间隙 4pt：> 0.2×字高 → 补一个空格（西文单词分隔）
                    item("Hello", 10.0, 100.0, 50.0, 112.0),
                    item("World", 54.0, 100.0, 94.0, 112.0),
                ],
                width: Some(595.0),
                height: Some(842.0),
                ..Default::default()
            }],
            ..Default::default()
        }
    }

    /// `Auto` 走版式重排（同行 fragment 合并成一个段落）；`Raw` 保持内容流原样。
    #[test]
    fn assemble_honours_layout_mode() {
        let raw = raw_doc_with_two_lines();

        let auto = assemble(&raw, LayoutMode::Auto);
        assert_eq!(auto.pages[0].blocks.len(), 1, "同行片段应合并");
        assert_eq!(auto.pages[0].blocks[0].content, "Hello World");

        let raw_mode = assemble(&raw, LayoutMode::Raw);
        assert_eq!(raw_mode.pages[0].blocks.len(), 2, "raw 不合并");
        assert_eq!(raw_mode.pages[0].blocks[0].content, "Hello");
        assert_eq!(raw_mode.pages[0].blocks[1].content, "World");

        let pdf: serde_json::Value =
            serde_json::from_str(&raw_mode.meta.extra["pdf"]).expect("pdf 元数据应为 JSON");
        assert_eq!(pdf["layout_modes"], serde_json::json!(["raw"]));
        assert_eq!(pdf["truncated"], serde_json::json!(false));
        assert_eq!(raw_mode.meta.extra["needs_ocr"], "false");
    }

    /// 短单元格 + 稳定列锚点 → 认表（不能因为收紧判据把真表格判掉）。
    #[test]
    fn detect_table_accepts_short_cells() {
        let cols = [
            ("Region", 54.0, 100.0),
            ("Share", 200.0, 60.0),
            ("Note", 320.0, 70.0),
        ];
        let mut lines = Vec::new();
        for r in 0..3 {
            let y = 100.0 + r as f32 * 12.0;
            for (t, x, w) in cols {
                lines.push(item(&format!("{t}{r}"), x, y, x + w, y + 8.0));
            }
        }
        let hit = detect_table(&lines).expect("短单元格应认表");
        assert_eq!(hit.0.len(), 3, "应识别出 3 行");
    }

    /// 正文长句 + 右侧图内小字号标签被并成 3 列：bbox 内仍散落正文，长句占比高 → 不认表。
    /// 回归来源：tracemonkey p9（图区误判，正文被逗号拼接的标签掰断，见 REAL_CHECKLIST）。
    #[test]
    fn detect_table_rejects_prose_rows_with_figure_labels() {
        let prose = "Like most interpreters, SpiderMonkey has a foreign function interface that \
                     allows it to call C builtins and host system functions at runtime";
        let stray =
            "the interpreter API implementation functions to re-materialize the call stack \
                     on demand, which costs extra work per exit; ";
        let mut lines = Vec::new();
        for r in 0..3 {
            let y = 100.0 + r as f32 * 20.0;
            lines.push(item(prose, 54.0, y, 292.0, y + 8.0));
            lines.push(item("?>9@AJ.0A:</C./8-2", 300.0, y, 380.0, y + 6.0));
            lines.push(item("7<>;./89-@/#3'4", 400.0, y, 470.0, y + 6.0));
        }
        // 只占一列的正文行：不满足 3 列 → 不进表格，但落在表格 bbox 内
        for y in [110.0_f32, 130.0] {
            lines.push(item(&stray.repeat(4), 54.0, y, 292.0, y + 8.0));
        }
        assert!(
            detect_table(&lines).is_none(),
            "正文长句 + 图内标签不应被认成表格"
        );
    }

    /// 行内「长句独大」：正文长句 + 两个短标签凑成的行 → 不认表。
    /// 回归来源：tracemonkey p1（图 1 的代码清单标签与正文行凑成 3 列）。
    #[test]
    fn detect_table_rejects_lopsided_row() {
        let prose = "inner loop header, but the outer loop header is where the trace begins";
        let mut lines = Vec::new();
        for (r, (label_a, label_b)) in [("Bytecodes", "Overhead"), ("Record", "Enter")]
            .iter()
            .enumerate()
        {
            let y = 100.0 + r as f32 * 20.0;
            lines.push(item(prose, 54.0, y, 292.0, y + 8.0));
            lines.push(item(label_a, 300.0, y, 350.0, y + 6.0));
            lines.push(item(label_b, 400.0, y, 450.0, y + 6.0));
        }
        assert!(
            detect_table(&lines).is_none(),
            "正文长句 + 短标签列不应被认成表格"
        );
    }

    /// 选项构造：默认 Auto/不限页；`with_*` 链式覆盖。
    #[test]
    fn pdf_options_builder() {
        let d = PdfOptions::default();
        assert_eq!(d.layout_mode, LayoutMode::Auto);
        assert_eq!(d.max_pages, None);

        let o = PdfOptions::new()
            .with_layout_mode(LayoutMode::Raw)
            .with_max_pages(5);
        assert_eq!(o.layout_mode, LayoutMode::Raw);
        assert_eq!(o.max_pages, Some(5));
    }

    #[test]
    #[ignore = "需本机 PDFium 动态库"]
    fn probe_worker_cjk() {
        let p = "/Users/zerojzheng/CODE/hi-agents/documents/docparser/python/bench/corpus/text_plain.pdf";
        match worker_sender() {
            Err(e) => eprintln!("worker init: {e}"),
            Ok(tx) => {
                let tx = tx.lock().unwrap().clone();
                let (rtx, rrx) = mpsc::channel();
                tx.send((p.to_string(), PdfOptions::default(), rtx))
                    .unwrap();
                match rrx.recv() {
                    Ok(Ok(raw)) => {
                        let n: usize = raw.pages.iter().map(|pg| pg.items.len()).sum();
                        let s: usize = raw
                            .pages
                            .iter()
                            .flat_map(|pg| &pg.items)
                            .map(|i| i.text.chars().count())
                            .sum();
                        eprintln!("ok: pages={} items={} chars={}", raw.pages.len(), n, s);
                    }
                    Ok(Err(e)) => eprintln!("worker parse err: code={} msg={}", e.code, e.message),
                    Err(e) => eprintln!("channel: {e}"),
                }
            }
        }
    }
}