LiteParse 源码架构解析面向 AI Agent 与开发者的代码库导航与扩展指南【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparseLiteParse 是一个用Rust编写的开源、轻量级文档解析库专注于空间文本提取带精确包围盒的文本定位默认完全本地运行、零云端依赖。本指南以仓库根目录的 AGENTS.md 为骨架结合核心源码config.rs、parser.rs、projection.rs 等展开帮助你在几十分钟内建立对该代码库的整体认知理解数据处理流水线、六大核心设计决策、各语言绑定的入口位置以及如何安全地扩展新输出格式、新 OCR 引擎和新的 CLI 选项。一、项目概览定位与核心能力LiteParse是一个开源 PDF 解析库核心用Rust编写强调快速、轻量的文档处理与空间文本提取。它完全本地运行默认没有任何云依赖。同时为以下语言提供绑定Node.js / TypeScript通过 napi-rsPython通过 PyO3WebAssembly通过 wasm-bindgen可运行于浏览器关于性能定位项目 README.md 宣称空间文本解析基于 PDFium、约每页 2–5ms但具体数值会随文档复杂度与硬件环境变化应以实测为准。关键能力一览能力说明空间文本提取带精确包围盒bounding box的文本定位灵活 OCR内置 Tesseract或可插拔的 HTTP OCR 服务器多格式支持PDF、DOCX、XLSX、PPTX、图片经转换多语言绑定Rust、Node.js/TypeScript、Python、浏览器WASMCLI所有安装方式cargo、npm、pip均提供命令行工具从 conversion.rs 的源码看非 PDF 格式覆盖范围相当广办公文档doc/docx/docm/dot/dotm/dotx/odt/ott/rtf/pages、演示文稿ppt/pptx/pptm/pot/potm/potx/odp/otp/key、电子表格xls/xlsx/xlsm/xlsb/ods/ots/csv/tsv/numbers、图片jpg/jpeg/png/gif/bmp/tiff/tif/webp/svg以及纯文本txt/md/markdown/log。二、代码地图从 Workspace 到各 crate 的目录结构仓库是一个 Cargo workspace根清单在 Cargo.toml。下面是整体目录结构继承自 AGENTS.md 并标注了各模块职责liteparse/ ├── crates/ │ ├── liteparse/ # 核心 Rust 库 CLI 二进制 │ │ └── src/ │ │ ├── main.rs # CLI 入口点clap │ │ ├── lib.rs # 库根统一 re-export 公共 API │ │ ├── parser.rs # LiteParse 编排器LiteParse 结构体 │ │ ├── config.rs # 配置类型与默认值 │ │ ├── types.rs # 核心数据类型ParseResult、TextItem 等 │ │ ├── projection.rs # 空间网格投影版面重建最复杂模块 │ │ ├── extract.rs # 从 PDFium 提取原始文本 │ │ ├── render.rs # 页面渲染 / 截图 │ │ ├── conversion.rs # 非 PDF 格式转换LibreOffice、image/resvg/usvg 等 Rust crate │ │ ├── ocr_merge.rs # 将 OCR 结果与原生文本合并 │ │ ├── error.rs # 错误类型 │ │ ├── ocr/ # OCR 引擎实现 │ │ │ ├── mod.rs # OcrEngine trait │ │ │ ├── tesseract.rs # 内置 Tesseract OCR │ │ │ └── http_simple.rs # HTTP OCR 服务器客户端 │ │ └── output/ # 输出格式化器 │ │ ├── mod.rs │ │ ├── json.rs │ │ └── text.rs │ ├── liteparse-napi/ # Node.js 绑定napi-rs │ ├── liteparse-python/ # Python 绑定PyO3 / maturin │ ├── liteparse-wasm/ # WASM 绑定wasm-bindgen │ ├── pdfium/ # PDFium C API 的 Rust 封装 │ └── pdfium-sys/ # PDFium FFIC → Rust绑定 ├── packages/ │ ├── node/ # npm 包原生二进制的 TS 包装 CLI │ │ └── src/ │ │ ├── lib.ts # Node.js 公共 LiteParse 类 │ │ ├── cli.ts # CLI 入口commander │ │ └── native.ts # 原生二进制加载器 │ ├── python/ # PyPI 包原生二进制的 Python 包装 │ │ └── liteparse/ │ │ ├── __init__.py │ │ ├── parser.py # Python 公共 LiteParse 类 │ │ ├── types.py # Python dataclass 类型 │ │ └── cli.py # CLI 入口 │ └── wasm/ # WASM npm 包 ├── ocr/ # 示例 OCR 服务器实现 │ ├── easyocr/ # EasyOCR 包装服务器 │ ├── paddleocr/ # PaddleOCR 包装服务器 │ └── suryaocr/ # Surya OCR 2多语言包装服务器 └── Cargo.toml # Workspace 根补充说明两点源码细节输出格式化器不止两个AGENTS.md 目录树中只写了json.rs与text.rs而实际还有 markdown.rs结构化 Markdown 输出供 LLM / RAG 管线使用三者对应OutputFormat枚举的三个变体见 config.rs。OCR 引擎不止两个除tesseract.rs与http_simple.rs外在启用oar-ocr特性且非 WASM 目标时还会编译 oar.rs见 ocr/mod.rs。三、数据处理流程一次文档解析的生命周期AGENTS.md 给出了端到端的 7 步数据流。结合源码逐条展开1. 输入Input接收文件路径或原始字节。在 main.rs 中parse子命令甚至支持-作为输入路径——从标准输入读取文档字节例如curl -sL … | lit parse -未读到数据时会给出明确的错误提示。2. 格式转换Conversion如需要非 PDF 格式通过 LibreOffice 与 image/resvg/usvg 等 Rust crate 转为 PDF。支持扩展名清单见 conversion.rs。转换工具的选择LibreOffice 或 ImageMagick由系统环境决定。3. PDF 加载PDF LoadingPDFium 提取文本项text items、图片、元数据。底层是 pdfium 与 pdfium-sys 两层 FFI 封装。4. OCR如启用对文本稀疏的页面区域渲染后进行 OCR。这是选择性的——并非整篇文档都跑 OCR详见下文设计决策 4。5. 网格投影Grid Projection使用锚点系统anchor system对文本布局进行空间重建是 projection.rs 的核心职责详见设计决策 3。6. 后处理Post-processing包围盒计算、文本清理。7. 输出Output格式化为JSON或纯文本以及 Markdown见上文说明由 output/json.rs 与 output/text.rs 分别负责。在 CLI 层面main.rs 定义了 6 个子命令其中 4 个面向用户、2 个是隐藏的开发工具子命令用途parse解析单个文档PDF、DOCX、XLSX、PPTX、图片等screenshot生成文档页面截图PNGbatch-parse批量解析目录下多个文档is-complex判断文档是否“复杂”到需要 OCR 或更重的解析结果输出 JSON可用作 shell 谓词extract隐藏提取 PDF 原始文本项不做网格投影开发用image-bounds隐藏提取页面内嵌图片包围盒开发用四、六大核心设计决策深度解读AGENTS.md 明确了该代码库的六大关键设计决策以下是结合源码的深入解读。4.1 Rust 核心 多语言薄绑定核心解析逻辑用 Rust 编写以保证性能与内存安全。各语言绑定 crate 只是薄封装——包装核心liteparsecrate 的类型与异步 API不重复实现解析逻辑liteparse-napi→ 经 napi-rs 提供 Node.js 绑定crates/liteparse-napi/src/lib.rsliteparse-python→ 经 PyO3/maturin 提供 Python 绑定crates/liteparse-python/src/lib.rsliteparse-wasm→ 经 wasm-bindgen 提供浏览器 WASM 绑定crates/liteparse-wasm/src/lib.rs核心库的公共 API 统一从 lib.rs 再导出LiteParse编排器结构体定义在 parser.rs。4.2 OcrEngine 特性抽象OCR 引擎的可插拔设计OCR 功能采用 trait 抽象OcrEngine定义在 ocr/mod.rs。该 trait 的核心是异步recognize方法接收像素数据RGB 或灰度字节、宽高与OcrOptions语言 DPI返回带包围盒与置信度的词级结果VecOcrResult。OcrResult的四个字段值得注意ocr/mod.rstext识别出的文本bbox像素坐标系中的[x1, y1, x2, y2]左、上、右、下confidence0.0–1.0 的置信度polygon可选的四点多边形按字形正立阅读方向 TL → TR → BR → BL 排列允许投影器恢复旋转文本的方向该抽象支持三种引擎内置 Tesseract默认通过tesseract-rs编译进来零额外配置。tesseract是默认特性见 crates/liteparse/Cargo.toml 中default [tesseract]。HTTP OCR 服务器客户端即 http_simple.rs 中的HttpOcrEngine符合 OCR_API_SPEC.md 定义的标准协议POST /ocrmultipart 表单携带file与language字段返回{ results: [{ text, bbox, confidence, polygon? }] }。客户端还兼容生产 worker 的“位置元组”响应格式[polygon, text, confidence]并内置了重试/退避策略默认最多 10 次尝试、1s 基数退避翻倍至 10s 上限加抖动。WASM 构建中的 JS 侧 OCR通过回调接口实现让浏览器端可以注入自定义 JS OCR。4.3 空间网格投影最复杂的部分AGENTS.md 明确指出 projection.rs 是整个代码库**最复杂也最重要**的模块。它实现了版面重建核心机制包括锚点式布局Anchor-based layout跟踪文本对齐方式左对齐、右对齐、居中、浮动用常量FLOATING_SPACES、COLUMN_SPACES区分浮动文本与多栏间距。前向锚点Forward anchors在行与行之间携带对齐信息保证阅读顺序连续。列检测Column detection识别多栏布局FLOWING_COLUMN_GAP_MULTIPLIER等常量参与判定。旋转处理Rotation handlingcanonical_rotation函数把任意旋转归一到 0°/90°/180°/270° 最近直角容差 2°将 90°/180°/270° 旋转文本变换回正确阅读顺序。OCR 合并将原生 PDF 文本与 OCR 结果合并在输出中保留置信度分数与来源标记该逻辑在 ocr_merge.rs从LayoutComplexityReason等类型可看出它还承担复杂度信号计算。4.4 选择性 OCR平衡精度与性能OCR 只在嵌入图片中文本提取失败的区域运行而不是整篇文档都跑 OCR。这背后还有一个更细的分级is-complex子命令会先判断页面是否需要 OCRneeds_ocr字段并输出布局复杂度原因多栏MultiColumn、疑似表格TableLikely、图形密集DenseGraphics只有被判为文本稀疏的页面才会进入 OCR 路径。由此可以用“先is-complex、再按需parse”的方式路由文档避免无谓的 OCR 开销。值得注意的是 main.rs 中is-complex在存在需要 OCR 的页面时会以非零退出码退出因此它可以直接作为 shell 谓词exit 0简单→ parse --no-ocr是安全的。4.5 配置default-first 设计配置采用“默认优先”策略用户只需覆盖需要的字段。完整默认值定义在 config.rs 的Default实现中关键项如下配置项默认值说明ocr_languageengTesseract 语言码eng/fra/deu…ocr_enabled随构建特性变化编译了tesseract特性时为true无内置引擎的构建WASM默认为关闭需显式配合ocr_server_url或 WASM 回调启用ocr_server_urlNone未提供时使用内置 Tesseractmax_pages1000最大解析页数target_pagesNone指定页如1-5,10,15-20解析上限MAX_TARGET_PAGES 100_000防止超大范围参数导致内存耗尽dpi150.0渲染分辨率OCR 与截图共用output_formatJsonjson/text/markdownimage_modePlaceholderoff剥离图片引用/placeholder默认输出占位/embed同时提取像素字节extract_linkstrue将链接注解渲染为 Markdown 的textnum_workersCPU 核数 − 1最少 1并发 OCR worker 数ocr_failure_fataltrue系统性 OCR 失败每个 OCR 任务都失败且至少有一个文本稀疏页时中止整个解析其他默认关闭但值得一提的开关extract_screenshots渲染 PNG 截图、continue_on_page_error页面级失败继续解析并收集到page_errors、extract_images/image_output_dir提取内嵌图片字节并落盘、extract_form_fieldsAcroForm 表单字段、extract_structure_tree标签 PDF 逻辑结构树、extract_blocks输出与 Markdown 渲染同源的分类布局块、emit_word_boxes词级子包围盒会显著增大载荷等。CLI 层面对这些配置的映射很直接例如parse子命令的--ocr-server-header Name: Value可重复传递对应ocr_server_headers--image-mode接受off|placeholder|embed--no-ocr会关闭 OCR 等完整参数见 main.rs。4.6 外部工具格式转换LiteParse没有实现各办公格式的解析器而是用系统工具LibreOffice把办公格式转换为 PDF再统一走 PDFium 提取。这种“转换优先”策略用极少的代码获得了极广的格式支持。图片与 SVG 走的是纯 Rust 的 image/resvg/usvg crate 链见 conversion.rs不依赖外部程序。五、常见开发任务如何安全地扩展 LiteParseAGENTS.md 给出了四类典型扩展任务的路径这里补充源码层面的落点新增一种输出格式在 crates/liteparse/src/output/ 下新建文件在 config.rs 的OutputFormat枚举中新增变体注意#[serde(rename_all lowercase)]序列化后是小写字符串在 main.rs 与各绑定 crate 中接线parse_output_format函数、绑定 crate 的类型导出。新增一种 OCR 引擎在 crates/liteparse/src/ocr/ 下实现OcrEnginetrait实现name与recognize在 parser.rs 中增加初始化逻辑在 config.rs 中增加配置项。OcrEnginetrait 内部含prefers_grayscale默认方法返回false内部做二值化的引擎如 Tesseract偏好灰度输入而颜色训练的引擎偏好 RGB——新引擎应根据自身特性覆写它。修改文本提取逻辑关键文件都集中在 crates/liteparse/src/projection.rs — 版面重建最复杂extract.rs — 从 PDFium 提取原始文本项ocr_merge.rs — 合并 OCR 与原生文本。添加 CLI 选项在 config.rs 的LiteParseConfig中增加字段在 main.rs 中增加 clap 参数在 parser.rs 中贯通在绑定 crateliteparse-napi、liteparse-python、liteparse-wasm中暴露。Node.js 侧还需同步 packages/node/src/lib.ts 的LiteParseConfig接口类型。修改 Node.js / Python 包装库 API 改动编辑 packages/node/src/lib.tsCLI 改动编辑 packages/node/src/cli.ts原生二进制接口定义在 packages/node/src/native.tsPython 侧库 API 在 packages/python/liteparse/parser.py类型在 packages/python/liteparse/types.pyCLI 入口在 packages/python/liteparse/cli.py。六、关键依赖一览下表继承自 AGENTS.md 的依赖表依赖用途pdfiumC 库PDF 文本提取与渲染tesseract-rs内置 OCR 引擎可选tesseract特性clapCLI 框架serde/serde_json序列化tokio异步运行时reqwestHTTP 客户端用于 OCR 服务器image图像处理PNG 编码napi-rsNode.js 原生绑定pyo3/maturinPython 原生绑定wasm-bindgenWASM 绑定七、入口点速查语言入口Rust CLIcrates/liteparse/src/main.rsRust 库crates/liteparse/src/lib.rs →parser.rs中的LiteParse结构体Node.jspackages/node/src/lib.ts 导出LiteParse类Pythonpackages/python/liteparse/parser.py 导出LiteParse类WASMcrates/liteparse-wasm/ 经 wasm-bindgen 暴露LiteParseCLI 的典型用法示例对应 OCR_API_SPEC.md 中的集成演示# 基础解析默认输出纯文本 lit parse document.pdf # 指定 JSON 输出并写入文件 lit parse document.pdf --format json -o output.json # 接入自建 OCR 服务器 lit parse document.pdf --ocr-server-url http://localhost:8080/ocr # 只解析指定页 lit parse document.pdf --target-pages 1-5,10,15-20 # 批量解析 lit batch-parse ./input ./output --format markdown --recursive --extension .pdf八、相关文档导航仓库内配套文档均与本文内容强相关可继续深入用户向文档README.md另有中文版 README.zh-CN.mdOCR 服务器标准协议OCR_API_SPEC.mdWASM 包说明packages/wasm/README.mdPython 包说明packages/python/README.mdOCR 服务器参考实现ocr/README.mdEasyOCR / PaddleOCR / SuryaOCR 三个示例服务器均按 OCR_API_SPEC.md 实现可直接用python server.py启动后接入【免费下载链接】liteparseA fast, helpful, and open-source document parser项目地址: https://gitcode.com/GitHub_Trending/li/liteparse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考