前言¶
在 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
