dsh-pdf-reader：面向视觉模型的内容感知 PDF 阅读插件

前言¶

DeepSeek Harness（DSH）的插件机制允许开发者通过 Node.js 工具扩展智能体的能力。处理 PDF 文档时，视觉模型存在 token 限制（约 384 tokens / 800×800 像素等效），直接全页渲染会导致小字号、表格结构或矢量图表细节丢失。dsh-pdf-reader 针对这一限制，利用 PyMuPDF 识别页面内容类型，将文本密集型页面转为文本提取，将图表、表格或公式密集型页面渲染为高 DPI 区域，再交由视觉模型阅读。

插件简介¶

dsh-pdf-reader 是 DeepSeek Harness 的插件，核心功能是内容感知的 PDF 阅读。它基于 PyMuPDF 构建，能够根据页面布局自动区分处理策略。当 Python 或依赖项缺失时，工具会返回清晰的警告信息（包含具体的安装命令），方便 Agent 或开发者修复环境，而不是直接报错中断流程。

安装与依赖¶

安装插件需要执行以下命令：

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

在运行插件工具前，需确保环境满足以下条件：

Node.js: 版本 >= 20
Python: 3 及以上版本
Python 依赖: pymupdf（可选 pymupdf4llm）
DSH 依赖: @deepseek-ai/cordis ^4, @deepseek-ai/dsh-tools

核心工具¶

插件提供三个主要工具，用于不同阶段的 PDF 处理。

pdf_scan¶

用于获取单页的内容概览。它返回页面的布局信息，包括列结构、矢量图形区域、光栅图像、表格、文本字符、是否有图形、公式风险以及是否有文本层等。建议在处理具体页面前先使用此工具判断页面类型。

pdf_read_page –mode mixed¶

这是核心的一站式工具。使用 --mode mixed 时，它执行以下操作：

低分辨率全页预览：返回一个低分辨率的全页渲染图（包含公式、表格网格线、插图位置和双栏布局顺序）。
文本提取：提取页面的文本内容。
高 DPI 图表/表格渲染：自动检测图表和表格区域，并将这些区域渲染为高 DPI 的 PNG 图片。

所有高分辨率图片会缓存到项目根目录下的 .dsh-pdf-reader 文件夹中，工具仅返回图片的路径。这保证了上下文窗口不会被大量图片数据填满。

pdf_render_region¶

用于精细渲染特定区域。如果通过预览发现某些区域（如未被自动裁剪的公式、拥挤的表格单元格、子图）需要更高细节，可以使用此工具。它接收 [x0, y0, x1, y1] 坐标参数，按预算填充 DPI 进行渲染，返回渲染后的图片路径。

工作流建议¶

插件设计了一套“预览 -> 内容 -> 精炼”的循环流程，以节省 token 并保证布局信息不丢失：

预览：调用 pdf_read_page --mode mixed 获取全页预览图和文本。
- 通过预览图查看页面上具体有什么内容，以此决定是否需要高分辨率渲染。
内容提取：再次调用 pdf_read_page --mode mixed。
- 工具会自动检测并渲染所有图表和表格区域，写入 .dsh-pdf-reader 缓存。将这些图片路径喂给视觉模型。
精炼：根据需要调用 pdf_render_region。
- 针对预览图中未被自动裁剪的细节区域进行放大渲染。

建议先使用 pdf_scan 对整份文档进行概览，规划哪些页面适合文本提取，哪些页面需要渲染处理。

注意事项与限制¶

表格检测误报：page.find_tables() 在绘图网格和图表上可能产生误报。因此，表格主要通过渲染路径来保证结构准确，Markdown 表格是尽力而为的补充。
公式检测：公式检测基于启发式规则（字体 + LaTeX 生产者）。PyMuPDF 解析内联数学公式效果较好，但分式等复杂结构可能需要通过 pdf_render_region 单独处理。
内存占用：大型 PDF 会被解析到内存中。
渲染策略：插件倾向于“过检测”渲染（即把网格或 Logo 当作图表渲染），因为渲染成本相对可控且安全。

结语¶

dsh-pdf-reader 通过分离文本提取与高分辨率渲染，解决了视觉模型在处理复杂 PDF 时的 token 限制问题。它提供了从概览到精细渲染的工具链，适合需要在 DeepSeek Harness 中处理包含图表、公式和复杂排版的 PDF 场景。插件源码与目录可通过 GitHub 仓库访问。