CODEX KNOWLEDGE

PaddleOCR-MarkItDown 最小集成设计

2026/04/24 9 min read CODEX KNOWLEDGE 目录 CODEX KNOWLEDGE 类 能力设计 项目 ATRAMENTI CONSOLE 形态 方案 PADDLEOCR MARKITDOWN 最小集成设计

PaddleOCR-MarkItDown 最小集成设计

结论

本轮建议的高质量 PDF 转 Markdown 最小方案是：

  • PaddleOCR 负责扫描件 / 模糊件 / 拍照件 / 重布局理解
  • MarkItDown 负责文本型 PDF、Office、HTML、URL 与 fallback
  • 在两者之上增加一个 repo-managed router，统一做输入判断、命令编排和输出契约

本轮不建议把两者串成“所有文件都先 OCR 再 Markdown”的重链路，也不建议把 MarkItDown 当作 PaddleOCR 输出 Markdown 的二次转换器。

为什么主方案先选 PaddleOCR + MarkItDown

1. 许可证更稳

  • PaddleOCR 官方仓库是 Apache-2.0
  • MarkItDown 官方仓库是 MIT
  • 相比之下，MinerU 当前使用的是自定义 MinerU Open Source License

因此在长期整合、二次分发、公司内落地、后续开源边界审查上，PaddleOCR + MarkItDown 的风险更低。

2. 中文与脏扫描场景证据更直接

PaddleOCR 官方 README 当前直接强调：

  • 处理中英日拼音等多语言混排
  • 面向 Warping / Scanning / Screen Photography / Illumination / Skewed 真实脏输入
  • 输出 Markdown / JSON

对“比较模糊的 PDF”这个目标，证据链比只强调通用 OCR 更对题。

3. 与仓内现有能力更互补

仓内当前已经有：

  • codex/mcps/integrations/documents/markitdown
  • codex/mcps/markitdown-mcp
  • codex/skills/markitdown

因此本轮真正缺的不是另一个 Markdown 转换器，而是一个：

  • 决定何时走 MarkItDown
  • 决定何时走 PaddleOCR
  • 统一输出与 fallback

的决策层。

最小架构

输入层

  • 输入文件路径
  • 输出 Markdown 路径
  • 可选 engine 偏好
  • 可选运行配置

路由层

当前阶段已经加入轻量 probe + 规则：

  • 图片输入：优先 PaddleOCR
  • doc/docx/ppt/pptx/xls/xlsx/html/htm/csv/xml/json/txt/md/epub：走 MarkItDown
  • pdf：
    • 先跑 PDF text-layer probe
    • 判定 text 时走 MarkItDown
    • 判定 scan 时走 PaddleOCR
    • 判定 unknown 时回退到默认引擎
    • 用户显式 prefer-ocr 时走 PaddleOCR

下一阶段再补：

  • 页数 / 图片占比 / 可复制文本量探测
  • 失败后自动 fallback

PDF text-layer probe

当前 router 已实现一个轻量启发式 probe：

  • 读取 PDF 原始 bytes
  • 尝试解压 FlateDecode streams
  • 统计 BT / Tf / Tj / TJ 等文本操作符
  • 统计图片标记
  • 抽取 literal text 片段

probe 只输出三类：

  • text
  • scan
  • unknown

这不是严格 PDF 解析器，但已经足以承担当前“自动区分文本 PDF 与扫描 PDF”的最小决策层角色。

adapter 层

MarkItDown adapter

负责：

  • 文本型 PDF
  • Office / HTML / 文本类输入
  • fallback

当前默认使用官方 CLI 模板：

uvx --from git+https://github.com/microsoft/markitdown.git@604bba13da2f43b756b49122cb65bdedb85b1dff#subdirectory=packages/markitdown markitdown {input} -o {output}

PaddleOCR adapter

负责：

  • 扫描 PDF
  • 模糊 PDF
  • 拍照件
  • 图片输入

本轮只固定 adapter 接口，不在仓内写死运行命令。原因是 PaddleOCR 当前有多种落地形态：

  • pipeline
  • VLM
  • CPU / GPU / NPU
  • 本地 Python 环境
  • 独立服务

如果在没有现场验证的情况下把某条命令写死进仓，会把 router 变成脆弱的 host-bound 脚本。

输出层

统一输出：

  • Markdown
  • 可选 JSON 决策结果

当前最小 evidence 包括：

  • selected engine
  • fallback engine
  • planned command
  • route reasons

Canonical 落点

设计文档

  • E:\My Project\Atramenti-Console\codex\plugins\obsidian\data\docs\agent\PaddleOCR-MarkItDown 最小集成设计.md

capability 原型

  • E:\My Project\Atramenti-Console\codex\mcps\integrations\documents\pdf-markdown-router

现有依赖能力

  • E:\My Project\Atramenti-Console\codex\mcps\integrations\documents\markitdown
  • E:\My Project\Atramenti-Console\codex\mcps\markitdown-mcp

当前 router 原型包含什么

tools/router.mjs

支持：

  • --input
  • --output
  • --engine auto|markitdown|paddleocr
  • --config
  • --prefer-ocr
  • --probe-only
  • --json
  • --execute

默认推荐使用：

  • 先 plan
  • 再在配置补齐后 execute

tools/router.config.example.json

作用：

  • 固定 MarkItDown 的命令模板
  • 给 PaddleOCR 预留本机绑定位
  • 不把未经验证的 Paddle 命令写死进仓

本轮边界

本轮明确不做：

  • 真正把 router 注册成新的全局 MCP
  • 安装 / 绑定 PaddleOCR 的完整本机运行时
  • 做 PDF 内容级 text-layer 探测
  • 做跨页表格质量对比基准

下一阶段建议

阶段 1：把 Paddle 本机命令绑定跑通

目标：

  • 选定你机器上的 Paddle backend
  • 用你自己的 3 到 5 份样本跑通
  • 把经过验证的命令写入非示例配置

阶段 2：补更强自动探测与 fallback

补：

  • 更强的 PDF text-layer / image density / page probe
  • 简单扫描件判定
  • execute 失败后的 fallback

阶段 3：再决定是否 MCP 化

当前判断：先不要升级成真正 MCP。

理由：

  • PaddleOCR 的本机执行命令还没有完成现场绑定
  • 当前 capability 的稳定部分是“路由与决策”，不是“完整执行链”
  • 如果现在就 MCP 化，会把一个尚未固定 backend 的原型接口过早承诺成稳定外部能力

只有当下面三件事都稳定后，再把它升级成真正的 MCP：

  • route rule 稳定
  • PDF probe 稳定
  • Paddle command 稳定
  • 输出契约稳定

否则先把它留在 repo-managed local router 层，成本更低，也更容易迭代。