AngelosZou/dsh-pdf-reader

dsh-pdf-reader

DeepSeek Harness 插件：面向视觉模型的内容感知 PDF 读取。

插件会按 PDF 的内容来决定读取方式：文本密集的页面直接提取成文本；而含图、表格、公式或双栏排版的页面，则渲染成高 DPI 的区域裁切喂给视觉模型——这样论文里的矢量图和结构化表格就不会因为单张图片的 token 上限而丢失。

底层基于 PyMuPDF。当缺少 Python 或依赖时，工具会返回一条清晰的、可执行的警告（含确切安装命令），交给 Agent 去处理，而不是直接硬失败。

安装

dsh plugin --profile web add dsh-pdf-reader

需要一个装有 pymupdf 的 Python 解释器。

在安装好 Python 之后，可以在 DeepSeek Harness 中安装
dsh-python-env 插件，让 Agent
自动处理依赖——它会自己创建项目 venv 并安装 pymupdf，无需任何手动步骤：

dsh plugin --profile web add dsh-python-env

如需手动搭建：

python -m venv .venv
.venv\Scripts\python.exe -m pip install pymupdf

工具

| 工具 | 作用 |
| --- | --- |
| pdf_scan | 逐页内容画像——栏数、图（矢量区域）、栅格图、表格、文本字符数、hasGraphics、formulaRisk、hasTextLayer。先用它决定每一页该怎么读。 |
| pdf_read_page | 读一页。mode=mixed 是一步到位：低清 fullPage 预览 + 该页文本 + 每个自动检测到的图/表区域的高清 PNG（路径，缓存于 .dsh-pdf-reader）。mode=auto/text/render 强制单一路径。 |
| pdf_render_region | 对某区域 [x0,y0,x1,y1] 以填满预算的 DPI（或显式 dpi）做定向高清渲染，返回路径供 read_image。 |

推荐工作流

工具围绕 预览 → 取内容 → 按需精修 的循环设计，让大 PDF 读取更省成本、且不因排版拍平而丢内容：

1. 预览（整页、低清）。 对某页调用 pdf_read_page --mode mixed。它返回一张低清 fullPage 渲染（整页布局——公式、表格格线、图的位置、双栏顺序）+ 该页文本。先看预览，了解页面上有什么，再决定是否花高清预算。
2. 取内容（自动、进缓存）。 同一次 mixed 调用会自动检测每个图/表区域并渲染成高清 PNG。所有 PNG 都写入 /.dsh-pdf-reader，只返回路径——重/长的内容存在缓存里，永不内联进上下文。把路径交给 read_image 即可。
3. 按需精修。 若某块仍太小、或没被自动裁切（未裁到的公式、拥挤的表格单元格、子图），用 pdf_render_region 按你在 fullPage 预览上读到的确切 [x0,y0,x1,y1] 放大它。

每份文档先用 pdf_scan 做整体概览，判断哪些页是纯文本、哪些是图/表/公式密集，再逐页套用上面的循环。

为什么这样设计

双栏论文的图往往是矢量（只有整页光栅化才能看见），表格在文本提取下会丢失结构，公式在部分文本层会乱码。而 DeepSeek 将每张图片限制在约 800×800 等价 / 384 token——用这个预算去读整页双栏，会让每栏只有 ~350px，正文小字、上下标和图的细节都会丢失。解决方案：

- 文本页 → 提取（便宜、精确，保留正文以及 PyMuPDF 能良好解码的行内公式）。
- 图/表/公式页 → 渲染区域，并缩放到填满约 640k 像素预算：dpi = 72 × sqrt(640000 / 区域面积(pt²))。内容完整（预算内不丢失任何可读内容）、token 最优（正好渲染到预算，不超出）。

区域检测是启发式的（不是完美分类器），并且刻意偏向渲染——矢量簇来自 get_drawings()、栅格来自 get_image_rects()、表格用同一套聚类、数学来自字体 + LaTeX Producer。它宁可过度标记（可能把带格线的表或 logo 当图）也不漏标，因为渲染便宜且安全。

缺少依赖时

每个工具按优先级解析 Python 解释器——先 $VIRTUAL_ENV 指向的已激活 venv，再 PATH 上的 python/python3/py，最后项目下的 .venv/venv/env——并探测其能否 import pymupdf（顺带可选 pymupdf4llm），选第一个能导入的。若都不行，则返回一条说明缺什么、如何修复的警告，让 Agent 去安装依赖、切换解释器或回退。

限制

- page.find_tables() 在绘图网格/图表上会误判，所以表格主要靠渲染来读（可靠路径）；pymupdf4llm 输出的 Markdown 表格只是尽力补充。
- 公式检测是启发式的（字体 + LaTeX Producer）。PyMuPDF 对行内公式解码良好，但分式/上下标结构仍可能不完美——需要精确结构时对公式用 pdf_render_region。
- 整页在预算下只有约 83 DPI 等价；工具对双栏页从不这么做——它们改为裁切区域，正文用提取。
- 大 PDF 会被整体读入内存。

要求

- Node ≥ 20、@deepseek-ai/cordis ^4、@deepseek-ai/dsh-tools（peer 依赖，由 harness 提供）。
- Python 3 + pymupdf（可选 pymupdf4llm）。

许可证

MIT