前言¶
在 DeepSeek Harness（DSH）里让智能体读 PDF，常见做法是整本走 OCR 或单一提取库。数字版论文往往自带文本层，盲目 OCR 既慢又容易打乱阅读顺序；扫描件、手机拍照则必须有视觉识别；表格和公式若只得到「一串字符」，下游模型很难当结构化数据用。dsh-pdf-router 面向这类问题：提供一个工具 pdf_read，按每一页的情况选引擎，并在需要时走版面感知流程，把表格落成 HTML、公式落成 LaTeX。
这是什么¶
dsh-pdf-router 是维护者 yuanfuda 发布的 DSH 插件，在 SkillHub 目录中归类为模型推理。它不是一个简单的「PDF 转文本」插件——README 明确说明同类能力已有不少；重点是让含表格、公式的页面返回机器可用的结构，而不只是人类可读的文字。
插件当前版本为 0.2.0，许可证 MIT。仓库：https://github.com/yuanfuda/dsh-pdf-router 。
核心功能：一页一策¶
工具 pdf_read 对每一页做路由，而不是全书统一 OCR。README 给出的对照如下：
| 页面情况 | 引擎 | 成本（README 表述） |
|---|---|---|
| 有文本层 | PyMuPDF 直接提取 | 约 0.01 s/页，无识别误差 |
| 无文本层（扫描/照片） | 视觉 OCR 端点（推荐 MiniCPM-OCR） | 约 20–130 s/页 |
| 表格或公式重要 | MiniCPM-OCR 版面管线 | 约 130–200 s/页 |
下面分述各路径在做什么。
文本层优先¶
有文本层的页用 PyMuPDF 提取。依赖运行在 router.py 所用 Python 环境中的 PyMuPDF；未安装时工具会返回可操作的错误，而不是堆栈跟踪。
扫描与图片¶
无文本层时走可插拔的 OCR 端点。默认指向本地 OpenAI 兼容服务（见配置项 ocrEndpoint）。任意支持 POST {base}/chat/completions 且能在 content 里带 image_url 的后端均可接入，例如 Ollama、vLLM、LM Studio 或托管 API。
未部署 OCR 端点时，数字 PDF 仍可用；扫描页会返回警告，说明缺少什么。
版面与结构（structure）¶
当 want 为 structure（或在 auto 下需要结构时），插件依赖 MiniCPM-OCR 的 SDK 与 PP-DocLayoutV3。表格以 HTML <table> 形式返回；公式以 LaTeX 呈现；多栏页面的阅读顺序由推荐模型管线处理。README 称 structure 模式与 MiniCPM-OCR 专用；ocrProfile: generic 仅请求 Markdown 里带 HTML 表与 LaTeX 的说明，效果取决于模型是否具备文档训练。
插件推荐的后端是 OpenBMB 的 MiniCPM-OCR（Apache-2.0）。README 列出其在 Real5-OmniDocBench、OCRBench v2 等公开指标，以及 Q8_0 权重约 775 MB、视觉投影约 859 MB、文档所述约 16 GB 系统内存下限等部署信息；本地部署示例见仓库 README（含 ModelScope 权重与 llama.cpp Vulkan 起服务命令）。
安装与启用¶
在 DSH 中安装插件使用 README 原文命令（注意 --profile web）：
dsh plugin --profile web add github:yuanfuda/dsh-pdf-router
安装后需要重启 harness：加载器对插件模块只做一次 import()，新装的 bundle 要在下次启动时才被加载；之后在该 profile 的会话里会出现工具 pdf_read。
安装前应自行查看仓库源码与 MIT 许可证；插件以当前 dsh 进程权限运行，PDF 路径与 OCR 端点访问范围与此一致。
可选依赖：OCR 端点与（structure 模式下的）minicpm-ocr SDK、PP-DocLayoutV3 需自行部署；插件不会替你下载约 1.6 GB 级别的权重。
配置¶
在 bundle patch 或 profile patch 里插件行的 config 中设置。README 配置表摘要如下：
| Key | 默认值 | 含义 |
|---|---|---|
pythonPath |
自动检测，否则 python |
能 import pymupdf 的 Python |
ocrEndpoint |
http://127.0.0.1:18499/v1 |
OpenAI 兼容 base URL |
ocrModel |
minicpm-ocr |
发给端点的模型名 |
ocrApiKey |
空 | 托管端点的 bearer token |
ocrProfile |
auto |
提示族：auto / minicpm / generic |
ocrPrompt |
空 | 覆盖指令文本 |
sdkExe |
自动检测 | minicpmvocr 可执行文件，仅 structure |
layoutModelDir |
自动检测 | PP-DocLayoutV3 推理目录，仅 structure |
defaultWant |
auto |
auto / text / structure |
timeoutMs |
1800000 |
整文档时间预算 |
换用其他视觉模型时，可指向自有端点，例如：
{ "ocrEndpoint": "http://127.0.0.1:11434/v1", "ocrModel": "qwen2.5vl:7b", "ocrProfile": "generic" }
典型用法¶
调用 pdf_read 时传入 JSON 参数。README 示例：
{ "path": "C:\\docs\\paper.pdf" } // per-page routing
{ "path": "C:\\docs\\paper.pdf", "pages": "7", "want": "structure" } // HTML tables + LaTeX
{ "path": "C:\\docs\\scan.pdf", "want": "text" } // never call OCR
{ "path": "C:\\docs\\photo.jpg" } // images are OCRed directly
返回内容包括路由统计、每页耗时、警告、Markdown，以及 out 路径。超过 14000 字符的文档会写入 out，内联结果会被截断。
适用场景与注意¶
适合谁： 需要在 DSH 智能体流程里读 PDF 或图片、且希望数字 PDF 快读、扫描件走 OCR、个别页要表格 HTML 与公式 LaTeX 的开发者。
性能： README 写明纯 CPU 上较慢——例如 30 页双栏论文走 SDK 约一小时； born-digital PDF 在 auto 下可为秒级。大批量宜离线或夜间跑。
质量： 表格已结构化但非完美；复杂多级表头仍可能列错位。
开发侧： 修改插件代码后需重启 harness（Node 按 URL 缓存模块，HMR 不覆盖链入 profile 的工作区目录）。离线可运行 node selftest.mjs 检查注册与渲染路径，无需启动完整 harness。
DSH 生态理念是「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek、幻方无官方从属关系。本插件在目录页：https://www.skillhub.cn/plugins/yuanfuda/dsh-pdf-router 。
结尾¶
dsh-pdf-router 用 pdf_read 把「有文本层 / 要 OCR / 要结构」拆成按页路由，在成本与可用性之间做显式权衡。数字论文优先 PyMuPDF；扫描与图片走可配置 OCR；结构模式面向表格 HTML 与公式 LaTeX。安装命令以 README 为准，OCR 与 SDK 需自备运行时。
- 目录页：https://www.skillhub.cn/plugins/yuanfuda/dsh-pdf-router
- GitHub：https://github.com/yuanfuda/dsh-pdf-router
