docforge-zh 0.1.0__tar.gz

docforge_zh-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+# 统一换行符：仓库内一律 LF，避免跨平台协作的 CRLF 噪声
+* text=auto eol=lf
+*.pdf binary
+*.png binary
+*.jpg binary

docforge_zh-0.1.0/.github/ISSUE_TEMPLATE/benchmark_submission.yml

@@ -0,0 +1,65 @@
+name: "Benchmark 提交（打榜）"
+description: "提交你的解析引擎在 docforge 数据集上的评测结果"
+labels: ["benchmark"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        提交前请确认：
+        1. 结果文件由 `docforge bench --engine <你的引擎>` 或你自己的引擎按 [提交规范](https://github.com/attnstack/docforge/blob/main/docs/benchmark.md) 生成；
+        2. 已通过 `benchmark/schema.py` 的 schema 校验（校验不过的提交不会上榜）；
+        3. 请附上可复现命令与环境说明——不可复现的结果会被要求补充或关闭。
+  - type: input
+    id: engine
+    attributes:
+      label: "引擎名称与版本"
+      description: "如 docforge 0.1.0 / your-engine 1.2.0"
+      placeholder: "engine 0.1.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: dataset
+    attributes:
+      label: "数据集版本"
+      options:
+        - docforge-zh-real-v0.1-rc
+        - docforge-zh-synthetic-v0.1
+        - 两者都跑了
+        - 其他（在说明里注明）
+    validations:
+      required: true
+  - type: textarea
+    id: results
+    attributes:
+      label: "指标结果"
+      description: "文本 1−CER / 阅读顺序 / 表格 TEDS / 标题树 / 综合，以及各指标覆盖率"
+      placeholder: |
+        text=0.87 order=0.98 table=0.67 heading=0.81 overall=0.83
+        coverage: text 7/7, table 4/7 ...
+    validations:
+      required: true
+  - type: textarea
+    id: submission
+    attributes:
+      label: "提交文件"
+      description: "附上提交 JSON（或 gist / 仓库链接）。单文件超限时给下载链接"
+  - type: textarea
+    id: repro
+    attributes:
+      label: "复现命令与环境"
+      placeholder: |
+        命令：docforge bench --engine xxx --dataset ...
+        环境：Ubuntu 22.04 / Python 3.11 / CPU，OCR 引擎及版本（如涉及扫描件）
+    validations:
+      required: true
+  - type: checkboxes
+    id: declare
+    attributes:
+      label: "声明"
+      options:
+        - label: "结果由评测工具生成，未手工修改指标数字"
+          required: true
+        - label: "提交 JSON 通过 schema 校验（benchmark/schema.py）"
+          required: true
+        - label: "同一结果未同时以多个 issue 重复提交"
+          required: true

docforge_zh-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,36 @@
+name: "Bug 报告"
+description: "解析结果错误、崩溃或性能问题"
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: "问题现象"
+      description: "期望输出 vs 实际输出。表格结构错误请附原 PDF 截图与错误 HTML"
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: "复现命令"
+      placeholder: "docforge convert in.pdf -o out.md --format both"
+    validations:
+      required: true
+  - type: textarea
+    id: input_desc
+    attributes:
+      label: "输入文件特征"
+      description: "页数、数字版/扫描件、是否含表格/多栏、来源类型（公文/论文/财报）。**涉及隐私请勿上传原文件，脱敏或裁剪后附图**"
+  - type: textarea
+    id: log
+    attributes:
+      label: "日志"
+      description: "加 --json-logs 运行的输出（异常栈务必完整）"
+      render: shell
+  - type: input
+    id: env
+    attributes:
+      label: "环境"
+      placeholder: "Windows 11 / Python 3.12 / docforge 0.1.0（是否安装 [ocr]）"
+    validations:
+      required: true

docforge_zh-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: "使用问题 / 讨论"
+    url: "https://github.com/attnstack/docforge/discussions"
+    about: "解析效果调参、RAG 接入经验交流请到 Discussions"

docforge_zh-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      # OCR 依赖（paddle）不在 CI 安装：数百 MB 且非核心链路；扫描路径由本地测试覆盖
+      - name: Install
+        run: pip install -e ".[dev,bench]"
+      - name: Lint
+        run: ruff check docforge benchmark
+      - name: Seed dataset
+        run: docforge gen-seed
+      - name: Tests
+        run: pytest -q
+      - name: Benchmark smoke (deterministic gates)
+        run: |
+          docforge bench --engine docforge --engine pymupdf4llm --out results
+          python - <<'PY'
+          import json
+          for name, floor in (("docforge", 0.95), ("pymupdf4llm", 0.75)):
+              agg = json.load(open(f"results/{name}.json", encoding="utf-8"))["aggregate"]
+              overall = agg["overall"]
+              assert overall is not None and overall >= floor, f"{name} overall={overall} < {floor}"
+              print(f"{name}: overall={overall:.4f} (floor {floor})")
+          PY
+
+  leaderboard-page:
+    if: github.ref == 'refs/heads/main'
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - run: pip install -e ".[bench]"
+      - run: docforge gen-seed && docforge bench --engine docforge --engine pymupdf4llm --engine markitdown --out results
+      - run: docforge leaderboard --results results --out leaderboard/index.html
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./leaderboard

docforge_zh-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing（OIDC），无需在 CI 里存 token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

docforge_zh-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# 虚拟环境
+.venv/
+venv/
+
+# 运行产物
+badcases/
+results*/
+leaderboard/
+probe*.pdf
+.tmp/
+*.log
+examples/demo.json
+
+# 标注工作区中的临时渲染页（保留 gt/pred json）
+benchmark/data/human/*/pages/
+
+# IDE
+.idea/
+.vscode/
+技术方案.md

docforge_zh-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+欢迎 PR。工程约定先读一遍，能省一轮 review。
+
+## 开发环境
+
+```bash
+python -m venv .venv && source .venv/Scripts/activate   # Windows Git Bash
+pip install -e ".[dev,bench]"
+ruff check docforge benchmark
+pytest
+```
+
+可选：OCR 能力 `pip install "docforge[ocr]"`（PaddleOCR 较重，CI 不装，本地测试扫描链路时自行安装）。
+
+## 提交前检查
+
+1. `pytest` 全绿——核心算法（阅读顺序/表格/指标）的改动必须带新单测，覆盖正常/边界/异常三类输入；
+2. `ruff check` 无告警；
+3. 若改了指标实现或归一化：跑 `docforge bench --engine docforge`，在 PR 里贴出前后对比——种子集上任何数字变化都要能解释；
+4. 破坏性改动（schema、归一化规则、GT 格式）必须升数据集版本号。
+
+## 加一个基线引擎
+
+1. 在 `docforge/engines/` 新增引擎类，继承 `BaseEngine`，实现 `parse` 与 `missing_dependency`；
+2. 纯 markdown 输出的引擎直接继承 `_MarkdownEngineBase`，只实现 `_to_markdown`；
+3. 在 `engines/base.py::_register_defaults` 注册；
+4. 用 `docforge bench --engine your-engine` 跑一遍，确认提交能过 schema 校验。
+
+## 标注贡献
+
+见 [docs/benchmark.md](docs/benchmark.md) 第 4 节与 [benchmark/data/human/README.md](benchmark/data/human/README.md)。标注两个样本起即可提 PR，一致性报告附在 PR 描述里。
+
+## commit 风格
+
+`<area>: <what>`（如 `table: fix colspan detection on partial borders`），正文说清 why。

docforge_zh-0.1.0/Dockerfile

@@ -0,0 +1,20 @@
+# docforge 一键运行镜像：CPU 模式，含自研引擎 + OCR（PaddleOCR）+ 基线 + server
+# 构建后直接 demo：docker run --rm -v "$PWD:/data" docforge convert /data/in.pdf -o /data/out.md
+FROM python:3.11-slim
+
+# paddleocr 依赖链需要：libgomp1（paddle）、libgl1/libglib2.0-0（opencv）
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libgomp1 libgl1 libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY docforge ./docforge
+COPY benchmark ./benchmark
+
+# PaddleOCR 模型文件不入镜像（几百 MB），首次运行自动下载到 ~/.paddleocr；
+# 持久化：docker run -v docforge-models:/root/.paddleocr ...
+RUN pip install --no-cache-dir ".[ocr,bench,server]"
+
+ENTRYPOINT ["docforge"]
+CMD ["--help"]

docforge_zh-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 docforge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docforge_zh-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: docforge-zh
+Version: 0.1.0
+Summary: 中文文档解析引擎与公开 Benchmark：多栏/复杂表格 PDF -> LLM-ready Markdown 与带 bbox 的 JSON
+Author: docforge contributors
+License: MIT
+License-File: LICENSE
+Keywords: benchmark,chinese,document-parsing,ocr,pdf,rag,reading-order,table-structure
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: pymupdf>=1.24
+Provides-Extra: bench
+Requires-Dist: markitdown[pdf]>=0.1.1; extra == 'bench'
+Requires-Dist: pymupdf4llm>=0.0.17; extra == 'bench'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: ocr
+Requires-Dist: paddleocr<3.0,>=2.7; extra == 'ocr'
+Requires-Dist: paddlepaddle<3.0,>=2.6; extra == 'ocr'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Requires-Dist: python-multipart>=0.0.9; extra == 'server'
+Requires-Dist: uvicorn>=0.29; extra == 'server'
+Description-Content-Type: text/markdown
+
+# docforge
+
+**中文文档解析引擎与公开 Benchmark：把多栏、复杂表格、扫描件 PDF 转成 LLM-ready 的分层 Markdown 和带 bbox 可溯源的 JSON，并配套一个可复现的中文解析评测基准。**
+
+<p align="center">
+  <a href="#-benchmark-榜单"><img alt="benchmark" src="https://img.shields.io/badge/benchmark-中文解析评测-blue"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-green"></a>
+  <img alt="python" src="https://img.shields.io/badge/python-3.11%2B-informational">
+  <a href="https://github.com/attnstack/docforge/actions"><img alt="ci" src="https://img.shields.io/badge/CI-GitHub%20Actions-passing-brightgreen"></a>
+</p>
+
+<p align="center">
+  <img src="docs/assets/demo.png" alt="docforge：政府公文 PDF → Markdown 与跨行列表格结构还原" width="820">
+</p>
+
+## 为什么是 docforge
+
+- 文档解析是所有 RAG 的地基，但中文场景（扫描公文、财报合并单元格、双栏论文）没有公认的开源强方案；
+- markitdown / PyMuPDF4LLM 这类文字层提取器**不做版面理解**：双栏论文会被逐行交错、合并单元格直接拍平；
+- 更重要的是：**解析引擎会被追上，被引用的评测标准不会**。docforge 附带一个确定性指标、带提交校验的公开 benchmark，任何方案（包括 VLM 路线）都可以来打榜。
+
+## 30 秒 Quick Start
+
+```bash
+# 1) 安装（核心依赖极轻：PyMuPDF + jsonschema）
+pip install -e .
+# 2) 生成合成种子数据集（程序化 PDF，GT 精确已知，用于打通评测链路）
+docforge gen-seed
+# 3) 解析一个多栏+表格的 PDF
+docforge convert benchmark/data/synthetic/inputs/mixed-001.pdf -o out.md --format both
+# 4) 在种子集上跑评测（自研引擎 + 可用基线），得到 report.md 与榜单页
+docforge bench --engine docforge --engine pymupdf4llm
+docforge leaderboard --results results/ --out leaderboard/index.html
+```
+
+扫描件 OCR 为可选能力：`pip install "docforge[ocr]"`（拉起 PaddleOCR，首次运行自动下载模型）。
+
+Docker（含 OCR 全量依赖，镜像已实测可跑）：
+
+```bash
+docker build -t docforge .
+docker run --rm -v "$PWD:/data" docforge convert /data/扫描件.pdf -o /data/out.md
+```
+
+## 特性
+
+| 能力 | 状态 | 说明 |
+|---|---|---|
+| 数字版 PDF → Markdown / JSON | ✅ v0.1 | 文字层直提取，毫秒级；标题层级 + 跨页段落续接 |
+| 双栏/多栏阅读顺序还原 | ✅ v0.1 | 通栏分段 → x 投影分栏 → 行带聚类，纯几何可单测 |
+| 有框线表格结构还原 | ✅ v0.1 | 线段网格聚类 + union-find 合并，输出 rowspan/colspan HTML |
+| 扫描件 OCR | 🔌 可选 | `docforge[ocr]`（PaddleOCR 2.x/3.x 双代适配），Windows 原生实测：扫描公文页文本 0.9931；扫描页表格结构 v0.2 |
+| 公式 → LaTeX | ⏳ v0.2 | 指标已实现并入库，转换链路未启用（诚实声明，见「不足」） |
+| Benchmark（4 指标 + schema 校验 + 榜单） | ✅ v0.1 | CER / TEDS / 阅读顺序 / 标题树，全部确定性指标，无 LLM judge |
+| 人工标注工作流 | 🚧 进行中 | 预标注 + 双人一致性工具（`docforge annotate` / `docforge bench-agree`） |
+| CLI / Docker / FastAPI | ✅ / ✅ / ✅ | 同步 `/convert`；异步任务队列 v0.2 |
+
+## 架构
+
+```mermaid
+flowchart LR
+    A[PDF/图片] --> B{文字层?}
+    B -- 有 --> C[提取: 文字块/词/矢量线段]
+    B -- 无 --> O[OCR 可选依赖<br/>PaddleOCR]
+    O --> C2[OCR 行 -> 阅读排序 -> 段落合并]
+    C --> D[表格结构还原<br/>线段网格 + union-find]
+    C --> E[页眉页脚剔除<br/>跨页重复证据]
+    C --> F[标题层级<br/>字号加权中位数]
+    D --> G[阅读顺序还原<br/>通栏分段/投影分栏/行带聚类]
+    E --> G
+    F --> G
+    C2 --> G
+    G --> H[导出]
+    H --> I[分层 Markdown]
+    H --> J[带 bbox JSON<br/>page/bbox/reading_order/confidence]
+    I --> K[Benchmark Runner<br/>CER / TEDS / 顺序对 / 标题树]
+    J --> K
+    K --> L[结果 JSON -> 榜单页]
+```
+
+核心算法（值得读源码的部分）：
+
+- **阅读顺序**：[docforge/stages/reading_order.py](docforge/stages/reading_order.py) —— 通栏块先剥离再分栏；行带容差取 0.5×块高中位数；
+- **表格结构**：[docforge/stages/table.py](docforge/stages/table.py) —— 局部边界缺失经 union-find 汇成跨行列区域；L 形合并的降级策略；
+- **指标**：[benchmark/metrics/teds.py](benchmark/metrics/teds.py) 与 [benchmark/metrics/tree_edit.py](benchmark/metrics/tree_edit.py) —— Zhang-Shasha 树编辑距离自研实现 + 单测。
+
+## Benchmark 榜单
+
+两个数据集，口径均为确定性四指标（详见 [docs/benchmark.md](docs/benchmark.md)）：
+
+### ① 真实公文集 `docforge-zh-real-v0.1-rc`（7 样本：5 数字页 + 2 仿真扫描页）
+
+来源：政府公开公文（依《著作权法》第五条可再分发，来源 URL 见 manifest）。GT 文本取自 PDF 文字层并逐块与原文程序化核对，结构（标题层级/表格跨行列）由标注员读渲染图核定；**已完成第二轮独立复核（仅依据渲染图重标），文本一致率 1.0000、结构零分歧（[AGREEMENT.md](benchmark/data/real-v0.1-rc/AGREEMENT.md)）；单标注员两轮，升 v0.1 需第二位标注员**。
+
+| 引擎 | 文本 1−CER ↑ | 阅读顺序 ↑ | 表格 TEDS ↑ | 标题树 ↑ | 综合 ↑ |
+|---|---|---|---|---|---|
+| docforge 0.1.0（含 OCR） | 0.8760 | 0.9762 | 0.6667 | 0.8095 | **0.8321** |
+| PyMuPDF4LLM | 0.5331 | 1.0000 | 0.2044 | 0.5952 | 0.5832 |
+| markitdown | 0.3576 | 0.9667 | 0.0000 | 0.3333 | 0.4144 |
+
+> 复现：`docforge bench --engine docforge --engine pymupdf4llm --engine markitdown --dataset benchmark/data/real-v0.1-rc --out results-real`（docforge 需 `pip install "docforge[ocr]"`）
+> 诚实解读（重要）：
+> - 数字页（5 样本）docforge 全指标 1.0：文本指标对"文字层提取类"引擎区分度低（GT 与引擎同源于文字层，1.0 是预期而非奇迹），区分度在结构——真实公文的跨行合并表格（rowspan=4×3 组、colspan 备注行）与"黑体/楷体同字号标题"，两个基线均无法还原；
+> - 扫描页（2 样本）：扫描公文页 OCR 文本 0.9931、阅读顺序 1.0（真实识别质量，非文字层同源）；扫描表格页 text 0.139 / table 0.0 是**已声明的 v0.1 边界**——扫描页无矢量线，表格结构不可还原，退化文本混入正文也被 GT 判罚，两项负分如实计入总分；
+> - docforge 真实集数字基于 7 个样本，样本量小，不外推为整体性能主张；标题判定依赖公文格式先验（黑体/楷体/编号模式），对非公文版式的泛化未验证。
+
+### ② 合成种子集 `docforge-zh-synthetic-v0.1`（10 样本，评测链路自证与回归）
+
+| 引擎 | 文本 1−CER ↑ | 阅读顺序 ↑ | 表格 TEDS ↑ | 标题树 ↑ | 综合 ↑ |
+|---|---|---|---|---|---|
+| docforge 0.1.0 | 1.0000 | 1.0000 | 1.0000 | 1.0000 | **1.0000** |
+| PyMuPDF4LLM | 0.9773 | 1.0000 | 1.0000 | 0.6296 | 0.9017 |
+| markitdown | 0.8389 | 0.9524 | 0.9726 | 0.4445 | 0.8021 |
+
+> 复现：`docforge gen-seed && docforge bench --engine docforge --engine pymupdf4llm --engine markitdown && docforge leaderboard --results results --out leaderboard/index.html`（每样本耗时与逐项分数见 `results/report.md`；测试环境：Windows 11 / Python 3.12 / CPU）
+> ⚠️ 合成集数字只证明"评测链路工作正常 + 引擎在构造样例上正确"，**不构成对真实文档的性能主张**。
+>
+> 对对比结果的两点说明：
+> - **PyMuPDF4LLM 在合成集表格 TEDS 上与我们打平**（1.0000）：它能从 PDF 单元格拓扑恢复结构，只是不输出 rowspan/colspan 属性——在真实集的复杂表格上它掉到 0.2044，差距来自跨行列合并的真实复杂度；
+> - markitdown 在双栏样本上文本分 0.32（逐行左右交错），这正是方案定位所针对的痛点，实测坐实。
+
+## Benchmark 设计要点（为什么可信）
+
+1. **确定性指标**：CER、TEDS（树编辑距离）、有序对准确率、标题树相似度——无 LLM judge，同输入必得同分；
+2. **归一化先约定**：NFKC → 小写 → 去空白，规则最小化并开源（[benchmark/normalize.py](benchmark/normalize.py)），防止全半角/空白差异污染数字；
+3. **提交格式即契约**：JSON Schema 公布，CI 校验（[benchmark/schema.py](benchmark/schema.py)），块粒度与对齐规则显式化；
+4. **标注质量自证**：双人独立标注 + `docforge bench-agree` 一致性报告；标注协议见 [docs/benchmark.md](docs/benchmark.md)。
+
+## 快速上手（开发者）
+
+```bash
+git clone https://github.com/attnstack/docforge && cd docforge
+python -m venv .venv && source .venv/Scripts/activate   # Windows Git Bash
+pip install -e ".[dev,bench]"
+pytest            # 全部单测 + 集成测试
+ruff check docforge benchmark
+```
+
+## 已知不足（诚实清单）
+
+- **无框线表格不支持**：v0.1 只承诺有框线表格；无框线需要检测模型（PP-Structure/SLANet），在 v0.2 路线图上；
+- **公式只检测不转换**：LaTeX 识别（pix2tex 类）对中文混排准确率未实测，v0.1 不启用，避免给不可信数字；
+- **OCR：Windows 原生已验证；WSL2/Docker + AMD 组合 `import paddleocr` 即崩溃**：实测 paddlepaddle 3.x 有 onednn 推理上游 bug（PIR 属性转换未实现）；pin 的 2.6 稳定组合在 Windows 原生（含 AMD CPU）完整跑通扫描链路（真实扫描公文页文本 0.9931），但在 WSL2/Docker 的 Linux wheel 上**导入 paddleocr 即 SIGILL**（其原生库初始化在 AMD Zen 上的问题，已用 import 追踪定位到导入层）。`docforge[ocr]` 因此 pin 2.x；docforge 的懒加载设计保证数字版解析完全不触碰 paddle（数字路径在容器内正常），扫描需求在 WSL2+AMD 下请用 Windows 原生或 Intel 环境；
+- **扫描页表格结构与标题不支持**：扫描页无矢量线（表格）无字号元数据（标题），v0.1 如实降级并在评测中计入负分，v0.2 用 PP-Structure 解决；
+- **真实集规模小、单标注**：7 样本（5 数字 + 2 扫描仿真），单标注流程，双人标注与 Kappa/一致率报告在补；扩展到 50–100 页的标注协议见 docs/benchmark.md；
+- **标题判定依赖公文格式先验**：黑体/楷体字体名 + 编号模式（一、/（一）/——）在公文上实测有效，对非公文中文版式的泛化未验证；
+- **段落回流是启发式**：依赖首行缩进/字体连续信号，对无缩进的西文行级拆分场景可能欠合并；
+- **PaddleOCR 模型文件不进镜像/仓库**：首次运行需联网下载（约几百 MB）。
+
+## Contributing
+
+见 [CONTRIBUTING.md](CONTRIBUTING.md)。benchmark 提交与榜单规则见 [docs/benchmark.md](docs/benchmark.md)。
+
+## License
+
+[MIT](LICENSE)