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 倉庫訪問。