zhtx2024/dsh-pdf: DeepSeek Harness PDF 解析工具集

前言¶

DeepSeek Harness (DSH) 通過插件機制擴展功能。在開發使用 DSH 的智能體時，處理 PDF 文檔是常見需求。然而，標準的 PDF 渲染引擎（如 pdfjs）在處理未內嵌 CJK 字體的 PDF 時往往失效，常見於嘉立創或 EasyEDA 導出的原理圖，導致文字缺失或亂碼。

zhtx2024/dsh-pdf 針對這一問題，爲 DSH 提供了一套 PDF 解析工具集，通過混合引擎設計，解決了非內嵌中文字體的渲染與提取難題。

該插件爲 DSH 代理提供了三個原生工具，並內置了雙引擎渲染邏輯：

pdf_info
獲取 PDF 文檔的元數據，包括總頁數、單頁尺寸（pt）、文檔生成信息以及字體列表。字體列表中會標記每個字體的內嵌狀態（embedded）。
pdf_extract_text
提取 PDF 中的文本內容。支持通過參數指定頁碼或提取位置座標（每行的 x/y 座標及字號）。
pdf_render_page
將指定頁面渲染爲 PNG 圖片。支持自定義縮放比例（scale）和輸出目錄（outDir）。

通過 DSH 的命令行工具安裝該插件。安裝後需重啓 DSH 或打開新的會話，工具纔會生效。

dsh plugin --profile web add @zhtx2026/dsh-pdf

安裝完成後，可以在 DSH 會話中直接調用上述工具。

    pdf_info("D:/Downloads/SCH_SA-V11A.pdf")

    pdf_extract_text("D:/Downloads/SCH_SA-V11A.pdf", { page: 1 })

    pdf_render_page("D:/Downloads/SCH_SA-V11A.pdf", { page: 1, scale: 2 })

該插件採用混合引擎架構，根據 PDF 字體情況自動切換渲染方式：

pdfjs 引擎：當 PDF 中的所有字體都已內嵌時，使用標準的 pdfjs 進行文本提取和渲染。這是處理大多數標準 PDF 的默認方式。
sysfont 引擎：針對未內嵌 CJK 字體的 PDF（如嘉立創導出的原理圖），插件會自動啓用內置解碼器。該解碼器解析 PDF 的內容流（如 BT/ET、Tf、Tm 等操作符），將 UniGB-UCS2-H 或 UTF-16BE 編碼映射爲 Unicode，並調用系統字體（如 SimSun、SimHei）進行繪製。這避免了 pdfjs 在遇到非內嵌字體時拋出 translateFont failed 錯誤。

使用時需注意以下限制：

掃描件限制：如果是純圖片或掃描件 PDF（沒有文本層），pdf_extract_text 將返回空結果，但 pdf_render_page 仍可用。
字體假設：sysfont 渲染器假定 Type0 CID 代碼等於 Unicode 代碼點（針對 UniGB-UCS2-H 字體）。其他特殊 CID 字體會回退到 pdfjs 引擎。
內存佔用：大文件會完全解析到內存中。
會話重啓：安裝後必須重啓 DSH 或打開新會話，插件的熱插拔掛載纔會生效。

zhtx2024/dsh-pdf 通過雙引擎策略，填補了 DeepSeek Harness 在處理國產 EDA 工具導出 PDF 時的文本渲染空白。若需查看源碼或目錄信息，可訪問 GitHub 或社區目錄。