前言¶
在 DeepSeek Harness（DSH）里处理 PDF，常见做法是整份丢给模型或自己写脚本调 Poppler。前者难以精确到页码和扫描页，后者又要维护工具链和对话里的引用格式。dsh-pdf-reader 是面向 DSH Desktop 的独立 Harness 插件：不改桌面壳、不拉 npm 运行时依赖、不做后台索引或自动下载模型，通过官方工具注册表把「按页阅读、检索、局部 OCR、整页或裁剪图附件」接到智能体工作流里。下面介绍它的定位、能力与安装用法。
这是什么¶
dsh-pdf-reader（GitHub：SkanderBog/dsh-pdf-reader，维护者 SkanderBog）是 Harness 宿主插件（pluginType: feature），当前发布版本 0.1.4（MIT）。它利用 Harness 的文件系统、系统提示与附件服务，在本地调用 Poppler 与可选的 Tesseract，实现页级 PDF 阅读、字面量搜索、扫描页选择性 OCR，以及把整页或放大裁剪区域作为真实 Harness 图像附件交给对话。
DeepSeek 官网聊天应用/网站是另一套产品，不会加载此类 Harness 插件；需在带插件机制的 DSH Desktop 或对应 CLI profile 上使用。
核心工具¶
插件向智能体暴露五类工具（名称以 README 为准）：
| 工具 | 作用 |
|---|---|
pdf_status |
检查 Poppler、Tesseract 及已安装的 OCR 语言包是否可用。 |
pdf_inspect |
页数、各页是否有可选中文本、扫描页警告与覆盖率。 |
pdf_read |
按页范围读取，保留表格间距，对扫描页选择性 OCR，并报告截断情况。 |
pdf_search |
在嵌入文本中做字面量搜索，返回页引用，并标明扫描覆盖缺口。 |
pdf_render |
将整页或放大裁剪区域作为 Harness 图像附件输出。 |
插件还会在 system prompt 里加入一段简短的 PDF 阅读工作流说明。当前 Agent 预设必须允许这些工具；若受限预设隐藏了插件工具，需换用允许 plugin tools 的预设。
环境与兼容¶
运行时要求（来自 package.json / README）：
- Node 22.19+ 或 24+
- DeepSeek Harness ≥ 0.2.0-rc.2，或在 manifest 中声明的
0.2.1-alpha.1/0.2.1-alpha.2/0.2.1-rc.2
已文档化的验证情况（非穷尽）：
- Linux 上 DSH Tauri Desktop + Harness
0.2.0-rc.2：维护者称已安装启用并通过集成与 OCR 测试。 - macOS 原生插件执行：0.1.1 打包插件在 GitHub Actions（Node 24、Poppler、Tesseract）中通过 22 项集成测试。
- 官方 DeepSeek Harness Desktop 使用相同插件机制；官方源码在 2026-10-02 审阅时为
0.2.0-rc.2，在具备所需服务与原生依赖时期望兼容，但 打包版官方桌面 GUI 与 Windows 执行尚未在此项目内完整验证。
Poppler 与 Tesseract 为 系统级原生程序，插件不捆绑。GUI 应用的 PATH 可能与终端不同；若 pdf_status 报缺失，可在插件 Cordis config 中为各二进制配置绝对路径（README 以 Tesseract 为例）。Apple Silicon 上 Homebrew 常见路径为 /opt/homebrew/bin，Intel Mac 为 /usr/local/bin。
安装与启用¶
分发方式为 GitHub Release v0.1.4 中的 dsh-pdf-reader-0.1.4.tgz。npm 上未 scoped 的 dsh-pdf-reader 属于其他作者，应使用本仓库的归档包或 GitHub 源码安装。
官方桌面（优先）： 在桌面的 Plugins 页面安装该 .tgz 并启用 dsh-pdf-reader。
若使用官方桌面自带的 dsh 命令：先启动桌面一次以初始化 profile，完全退出后执行（路径改为本机绝对路径）：
dsh plugin --profile desktop add /absolute/path/dsh-pdf-reader-0.1.4.tgz
命令结束后重新打开桌面。社区 shell 除非实际拥有 desktop profile，否则不要用 desktop 作 profile 名。若 profile 不支持热重载，需重启 Harness core。
命名 CLI profile：
dsh plugin --profile YOUR_PROFILE add /absolute/path/dsh-pdf-reader-0.1.4.tgz
请使用桌面实际运行的 profile 名称（不一定是 web 或 desktop）。禁用或卸载通过同一插件管理器完成；禁用会移除工具与工作流，内存中的覆盖信息与临时工作 PDF 会被丢弃，已生成并进入对话的图像附件仍由 Harness 管理。
原生依赖安装¶
Poppler 提供 pdfinfo、pdftotext、pdfimages、pdftoppm；本地 OCR 需要 Tesseract 及对应语言数据，纯渲染与可选中文本不强制 Tesseract。
Ubuntu/Debian：
sudo apt install poppler-utils tesseract-ocr tesseract-ocr-eng tesseract-ocr-chi-sim
macOS（CI 中测过原生工具；打包桌面 GUI 未在此验证）：
brew install poppler tesseract tesseract-lang
Windows 需自备对应架构的可执行文件与 OCR 语言数据；Linux 侧的 OCR 封装不可直接移植。
典型用法¶
正常附件挂上 PDF 后，可按 README 示例向智能体说明意图（英文提示词，行为等价于「先用工具再总结」）：
Use the PDF tools to read this document. Inspect its pages first, OCR scanned pages in English and Chinese, and inspect relevant figures. Explain the findings with PDF page references. Tell me which pages or regions you could not read.
针对表格页：
Read PDF page 6 with layout preserved, then render a crop of the table and check the numbers against the text. Cite the page.
建议流程：先用 pdf_inspect 了解页结构与扫描情况，再用 pdf_read / pdf_search 取文本并引用页码，对图或表格用 pdf_render 做视觉核对；无法读取的页或区域应在回复中明确说明。
权限与安全边界（安装前须知）¶
插件以 当前 DSH 进程的用户权限 运行，并非 OS 级沙箱。README 与 Store 兼容性说明中的要点：
- 源 PDF：经 Harness 文件系统服务只读访问，每次调用校验，不修改源文件。
- 本地写入：私有 OS 临时目录中的文档/OCR 中间文件；渲染图经宿主附件服务存储；卸载会清理工作副本，硬崩溃可能遗留 OS 临时文件。
- 子进程：仅调用 Poppler 与 Tesseract，固定参数、
shell: false，带取消、超时与输出上限；管理员配置的绝对路径二进制需视为可信。 - 网络：插件本身不发起直接网络请求；Harness 可能把返回的文本/图像发给当前对话所选模型提供商。
- 环境：子进程使用显式 allowlist 的运行时路径/字体/OCR 配置，不转发 API 密钥、
NODE_OPTIONS、LD_PRELOAD及动态库搜索路径覆盖等。
DSH STORE 在 2026-10-15 的审阅中因原生依赖的独立验证等原因，安装仍可能被拦截；manifest 中的声明不等于商店批准或独立安全认证。安装前应自行审阅源码与 MIT 许可证，并确认 Poppler/Tesseract 来源可信。
适用场景¶
- 在 DSH Desktop 或 CLI 会话里分析技术 PDF、合同、扫描件，需要 页码引用 与 扫描页本地 OCR（如英/中）。
- 需要把 表格布局 与 裁剪图 一并交给多模态模型核对，而不是只粘贴纯文本。
- 希望 无 npm 运行时依赖、无后台索引，依赖本机已安装的 Poppler/Tesseract。
不太适合：仅使用 DeepSeek 网页/ App、无法安装 Harness 插件的环境；尚未验证的 Windows 或任意 Harness 版本；期望插件自带 OCR 引擎、无需系统安装 Tesseract 的场景。
链接¶
- 社区目录页：https://www.skillhub.cn/plugins/SkanderBog/dsh-pdf-reader
- 源码与 README：https://github.com/SkanderBog/dsh-pdf-reader
- 当前安装包：https://github.com/SkanderBog/dsh-pdf-reader/releases/tag/v0.1.4
dsh-pdf-reader 把页级 PDF 阅读、搜索、本地 OCR 与可视化裁剪收敛为一组 Harness 工具，适合在已部署 DSH 且本机具备 Poppler/Tesseract 的开发者与智能体工作流中使用。
