dsh-pdf-reader
面向视觉模型的内容感知 PDF 读取插件：逐页分析图（矢量与栅格）、表格、公式风险与双栏排版，基于内容识别进行混合提取，图表/公式页渲染成高 DPI 区域裁切。提供低清预览以理解页面概况并支持指定选区获取高清渲染。功能包装为多个工具供Agent使用。
READMEdsh-pdf-reader
DeepSeek Harness 插件：面向视觉模型的内容感知 PDF 读取。
插件会按 PDF 的内容来决定读取方式：文本密集的页面直接提取成文本；而含图、表格、公式或双栏排版的页面，则渲染成高 DPI 的区域裁切喂给视觉模型——这样论文里的矢量图和结构化表格就不会因为单张图片的 token 上限而丢失。
底层基于 PyMuPDF。当缺少 Python 或依赖时，工具会返回一条清晰的、可执行的警告（含确切安装命令），交给 Agent 去处理，而不是直接硬失败。
安装
▼sh复制代码dsh plugin --profile web add dsh-pdf-reader
需要一个装有 pymupdf 的 Python 解释器。
在安装好 Python 之后，可以在 DeepSeek Harness 中安装
dsh-python-env 插件，让 Agent
自动处理依赖——它会自己创建项目 venv 并安装 pymupdf，无需任何手动步骤：
▼sh复制代码dsh plugin --profile web add dsh-python-env
如需手动搭建：
▼sh复制代码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 读取更省成本、且不因排版拍平而丢内容：
- 预览（整页、低清）。 对某页调用
pdf_read_page --mode mixed。它返回一张低清fullPage渲染（整页布局——公式、表格格线、图的位置、双栏顺序）+ 该页文本。先看预览，了解页面上有什么，再决定是否花高清预算。 - 取内容（自动、进缓存）。 同一次
mixed调用会自动检测每个图/表区域并渲染成高清 PNG。所有 PNG 都写入<cwd>/.dsh-pdf-reader，只返回路径——重/长的内容存在缓存里，永不内联进上下文。把路径交给read_image即可。 - 按需精修。 若某块仍太小、或没被自动裁切（未裁到的公式、拥挤的表格单元格、子图），用
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
