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 或社区目录。