PDF 阅读器 SkanderBog/dsh-pdf-reader

DSH PDF Reader

一个独立的 DeepSeek Harness 插件，用来在 DSH Desktop 里读 PDF。不改桌面外壳，不依赖 npm 运行时依赖，不做后台索引，也不下载模型。

它能做什么

| 工具 | 用途 |
| pdf_status | 检查 Poppler、Tesseract 和已安装的 OCR 语言。 |
| pdf_inspect | 统计页数、逐页文本是否可用、扫描件警告和覆盖率。 |
| pdf_read | 读取页码范围，保留表格间距，按需对扫描页做 OCR，并报告截断情况。 |
| pdf_search | 对内嵌文本做字面搜索，给出页码引用，并明确标出扫描件覆盖缺口。 |
| pdf_render | 把整页或放大后的裁剪区域作为真正的 Harness 图片附件发送。 |

正常附上一个 PDF，然后提问：

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.

插件会往智能体的系统提示词里加一段简短的阅读工作流。当前智能体预设必须允许使用这些工具。如果受限预设把它们藏起来了，换一个允许插件工具的预设。

兼容性

这是一个 Harness 宿主插件，不依赖 Tauri、Electron 内部实现，也不需要定制的桌面分支。它用的是官方工具注册表、文件系统、系统提示词和附件服务。

| 宿主 | 状态 |
| 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。只要所需服务和原生依赖齐备，预期兼容；打包好的官方桌面版尚未在此测试。 |
| Linux 上的 Harness 0.2.1-alpha.1 / 0.2.1-alpha.2 / 0.2.1-rc.2 | 打包插件测试在 CI 中通过。 |
| 其他 Harness 版本或 Windows | 尚未验证。 |

官方桌面版的说明见 DeepSeek 的桌面文档。它的运行时跟随桌面版发布，所以请检查已安装的版本，不要假定每个桌面版都带最新运行时。面向消费者的 DeepSeek 聊天网站/应用是另一个产品，不会加载这个 Harness 插件。
Poppler 和 Tesseract 是外部原生程序，本包不捆绑它们。安装时请选择与宿主操作系统和架构匹配的版本。GUI 应用的 PATH 可能和终端不同；如果 pdf_status 报告工具缺失，请配置绝对路径。在 Apple Silicon 上，Homebrew 通常把二进制文件装在 /opt/homebrew/bin；在 Intel Mac 上装在 /usr/local/bin。Windows 需要自己的原生可执行文件和 OCR 语言数据；Linux 的 OCR 封装不可移植。

安装

需要 Node 22.19+ 或 24+，以及 DeepSeek Harness 0.2.0-rc.2 或更新版本，并且要带工具输出、文件系统和附件接口。本包声明了这个 Harness 版本下限，插件管理器可以在安装前检查。已在 Linux 上针对 Harness 0.2.0-rc.2 测试。打包的官方桌面 GUI 和 Windows 执行尚未测试。

从 GitHub release 下载 dsh-pdf-reader-0.1.4.tgz。用桌面的 Plugins 页面安装归档并启用 dsh-pdf-reader。本项目通过 GitHub releases 分发。npm 上无作用域的 dsh-pdf-reader 名称属于另一位作者；请用本仓库的归档或 GitHub 源码安装本插件。

官方桌面请优先用它的 Plugins 页面。如果使用官方桌面安装的命令行，先启动一次桌面以初始化其配置档，完全退出，然后运行：

dsh plugin --profile desktop add /absolute/path/dsh-pdf-reader-0.1.4.tgz

命令结束后重新打开桌面。不要把 desktop 用作社区 shell 的配置档，除非该 shell 确实拥有那个配置档。如果 Harness 核心的配置档不使用热重载，请重启它。

对于具名命令行配置档：

dsh plugin --profile YOUR_PROFILE add /absolute/path/dsh-pdf-reader-0.1.4.tgz

使用桌面实际运行的配置档；它的名字不一定是 web 或 desktop。包安装和 bundle 激活由 Harness 管理。不要把工具代码复制到模型服务商，也不要编辑桌面生成的前端。

要禁用或卸载，请使用同一个插件管理器。禁用会移除工具和工作流；内存中的覆盖范围和临时工作 PDF 会被丢弃。会话中已生成的图片附件仍由 Harness 管理。

商店兼容性与权限

engines.dsh 是宿主的版本门槛。DSH STORE 单独读取 dsh.compatibility.dsh、dshReleases 和 dshOperations；清单声明了这两种格式。打包的 API 测试在 DSH 0.2.0-rc.2、0.2.1-alpha.1、0.2.1-alpha.2 和 0.2.1-rc.2 上通过。兼容性矩阵描述的是已测试的宿主 API，不是每个桌面 GUI 或操作系统。安装/启动/卸载在 0.2.0-rc.2 上有各自独立的可丢弃命令行配置档证据；更新回滚仍未知。

| 能力 | 范围与边界 |
| 源文件 | 通过挂载的 Harness 文件系统服务读取；每次调用都会检查访问权限。源 PDF 永远不会被修改。 |
| 本地写入 | 私有 OS 临时文档/OCR 文件；渲染出的图像通过宿主附件服务存储。卸载会删除工作副本；硬崩溃可能留下 OS 临时文件。 |
| 命令 | 仅使用 Poppler 和 Tesseract，采用固定参数数组，shell: false，支持取消、截止时间和输出限制。管理员可以配置可执行文件的绝对路径；这些二进制文件必须可信。 |
| 网络 | 插件不直接发起网络请求。Harness 可能把返回的 PDF 文本/图像发送给会话选定的模型服务商。 |
| 环境 / 凭据 | 原生子进程只收到显式的运行时路径/字体/OCR 允许列表，而不是完整宿主环境。API 密钥、token、代理认证、NODE_OPTIONS、LD_PRELOAD 以及动态库搜索覆盖项（LD_LIBRARY_PATH、DYLD_LIBRARY_PATH、DYLD_FALLBACK_LIBRARY_PATH）都不会转发。插件不请求凭据服务，也不读取凭据文件。这不是 OS 沙箱：配置的可执行文件仍以用户文件权限运行。 |
| 外部依赖 | OS 安装的 Poppler；可选的 Tesseract，需带有所需语言数据。没有运行时 npm 依赖，没有生命周期安装脚本，不自动下载，也不捆绑原生可执行文件。 |

扫描器的确切发现、复现命令和剩余准入边界见商店审核证据。文件/命令访问对本地 PDF 处理器不可或缺；商店 10 月 15 日的审核仍阻止安装，等待对原生依赖的独立验证。这些声明不构成商店批准或独立安全认证。

原生依赖

Poppler 提供 pdfinfo、pdftotext、pdfimages 和 pdftoppm。本地 OCR 需要 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

每个二进制文件都可以在插件的 Cordis config 中配置绝对可执行路径，例如 tesseract: /absolute/path/tesseract。默认名称通过桌面进程的 PATH 解析。位于 ~/.local/share/dsh-pdf-reader/tesseract 的用户本地 Tesseract 包装器会被自动检测。该可选运行时需单独安装，不捆绑进 npm 包。
可执行文件、它的共享库，以及字体/OCR 配置，都必须来自你信任的来源。绝对路径只能标识程序，不能验证它的身份。插件保留 PATH、主目录和字体/OCR 设置，是为了保持原生兼容性；它不校验这些内容的所有者，也不阻止受信任的包装脚本设置自己的环境。需要私有库的自定义安装，应在经过审查的包装脚本里设置固定的库路径，不要依赖继承来的 LD_LIBRARY_PATH 或 DYLD_* 值。

要得到可复现的本地依赖清单，请在源码检出目录下运行 node scripts/native-evidence.mjs > ../native-evidence.json。传入与你的 Cordis 配置匹配的显式路径，例如 --tesseract /absolute/path/tesseract。脚本会计算插件运行时和解析到的原生可执行文件的哈希，用插件过滤后的环境探测它们的版本，并且只记录环境变量名。运行这条命令前先审查这些程序：版本探测会执行它们。这份清单是作者提供的证据，不是 Store 审批，也不是签名校验；包装脚本、共享库、配置和 OCR 数据都需要单独核验来源。参见 Store 审查证据。

OCR 语言默认是 eng。需要英文和简体中文时，让智能体传入 language: "eng+chi_sim"。pdf_status 会列出实际安装的语言。其他语言需要对应的 Tesseract 数据。

设计与限制

- 源文件字节通过挂载的 Harness 文件系统服务商读取，使用调用会话的工作目录。每次工具调用都会重新检查访问权限，即使文档已缓存。源文件永远不会被修改。
- 解析和 OCR 在本地临时工作副本中运行，使用固定的可执行文件参数，不做 shell 插值。插件本身不发起网络调用。提取的文本和渲染的图像随后由 Harness 作为普通工具结果，发送给会话配置的模型服务商。
- 子进程包装脚本强制执行截止时间、输出限制、取消，并限制为一个 OCR 线程。子进程环境只保留运行时路径、字体和 OCR 设置（见 src/process.mjs 中的 nativeEnvironment）。依赖其他环境变量的自定义包装脚本，必须在受信任的包装脚本里自行设置这些值。工具处理串行执行，以限制内存占用。最多缓存四份文档；卸载插件会清理它的临时副本。页面渲染失败或被取消时，返回前会删除任何写了一半的 PNG。进程硬崩溃可能留下操作系统临时文件。
- 限制：每个 PDF 64 MiB，2,000 页，每次调用 100 条检查记录和 10 个读取页，每次读取返回 60,000 个文本字符。长文本和检查范围有明确的续读字段。超大文档应拆分。
- 渲染出的区域长边为 600–2,400 像素。裁剪区域用 [left, top, right, bottom] 表示，取的是显示页面的比例，页面已按旋转校正，从左上角量起。需要过度栅格化的极小裁剪会被拒绝。
- pdf_render 检查当前路由模型的图像能力。纯文本或未知路由会被明确拒绝。OCR 文本在纯文本模型和视觉模型下都能用。本插件不会自动把文档发给第二个模型，也不会另选服务商。
- 页面内嵌文本很少，或 Poppler 检测到内嵌图像时，会自动触发 OCR，混合了文本与扫描内容的页面也算。可选中文本会保留，另附一段单独标注的整页 OCR 读取结果；重复或冲突的读取结果不算独立证据。带文字层的 logo 和扫描件也可能触发额外处理。图像检测不覆盖矢量轮廓；可疑页面请用 ocr: "force"。缺少依赖会明确报错；OCR 输出为空时绝不会抹掉可选中文本。ocr: "off" 会跳过图像检测和 OCR。
- 搜索每批提取最多处理 100 页，字面查询只编译一次。它仍会扫描整个请求范围，即使返回的片段已达上限，也会报告完整匹配数。要取更多匹配，把 next_offset 作为 offset 传回，文件、查询和页码范围保持不变；next_offset: null 表示没有更多匹配。两次请求之间要检查 sha256 是否变化；文档变了就从 offset 0 重新开始。每批仍受原生输出上限约束；页面异常密集时可能仍需缩小范围。搜索只覆盖内嵌文本，稀疏页面会明确警告；扫描区域和 OCR 输出不参与搜索。搜索命中不能证明覆盖了整份文档。
- 覆盖率描述的是当前缓存生命周期内这些工具返回的完整文本和页面图像，不代表模型已理解，也不证明做过视觉检查。裁剪只覆盖所选区域。重启和缓存淘汰会重置覆盖率。
- PDF 物理页码从 1 开始，可能与印刷页码不同。返回的引用包含文件名、物理页码和原始来源路径。
- 版面提取和 OCR 都可能出错。表格仍是文本，间距只是近似，不保证单元格数据准确。数学识别、手写内容、歧义阅读顺序和图表解读仍需人工核对。受密码保护的文档需要先提供解锁副本。

验证

2026-10-08 的兼容性审计在隔离的 Harness 0.2.0-rc.2 宿主中，把本次检出的代码与 Context Manager、Rewind 0.15.0、Better Sidebar 0.24.1 和 DSH Market 1.66.6 一起跑了一遍。文本提取和图片附件通过共享工具注册表正常工作；禁用这两个受审计插件后，其他插件的注册项仍然保留。Market 的覆盖范围仅限于路由注册和它的只读能力端点。配套的 Context Manager 仓库里有可复现的 test:installed 测试装置。桌面版 0.22.4 锁定同一批宿主 API；本次测试没有跑它的打包 GUI，也没有跑桌面端自带的任何功能。

搜索回归测试用一份真实的 201 页 PDF，经 Poppler 处理，转换器带保护，会拒绝过大的提取批次。测试验证跨批次边界的匹配和稀疏页、续读偏移、非首页范围，以及片段上限之后的精确总数。测试还会检查缓存页数上限附近的转换器计数，以捕捉因淘汰而反复提取的问题。

源码里包含合成的正文/表格、扫描件、图文混排和旋转 PDF 测试样本，并针对真实的 Cordis 工具注册表、文件系统和附件存储运行测试。这些集成测试中，模型能力查询是受控的；不会产生付费模型调用。

先安装上面的原生依赖，再安装锁定版本的测试专用 npm 依赖：

npm ci --ignore-scripts
npm run check
npm run test:package

页面读取会在重叠范围和布局切换之间复用缓存的文本和图片计数。只有缺失的页面才会启动转换器，每批最多 100 页。每份文档在两种模式下合计最多保留 200 个文本页和 4,194,304 个文本字符（最多 8 MiB 的 UTF-16 字符存储，不含对象开销），淘汰最久未使用的页面。图片计数按物理页各保留一个数字，受 2,000 页文档上限约束。每次工具调用都会做源指纹校验和文件系统权限校验。

包检查会创建 tarball，核对它的精确文件列表，并对解包后的包运行集成测试套件。npm test 针对源码运行。如果想测试已有的 Harness 安装，把 DSH_RUNTIME 设为该安装的包根目录。GitHub Actions 在 Linux 上用 Node 22 和 24 跑包测试套件，在 macOS 上用 Node 24 跑。额外的 Linux Node 24 流水线测试 Harness 0.2.1-alpha.1、0.2.1-alpha.2 和 0.2.1-rc.2；默认依赖集仍是 0.2.0-rc.2。操作系统测试跑的是插件和原生工具，不是打包的桌面 GUI。

测试使用全新的临时 Harness 主目录，绝不改动用户的会话或凭据。测试遵循插件正常的 Tesseract 查找顺序（先 ~/.local/share/dsh-pdf-reader/tesseract，再 PATH），除非用 DSH_PDF_TEST_TESSERACT 指定绝对可执行文件路径。英文和简体中文数据都必须安装。
要做真实的命令行生命周期检查，请使用单独安装的精确 Harness 版本（不是桌面外壳的中间层）：

DSH_CLI=/absolute/path/node_modules/@deepseek-ai/dsh/lib/bin.js npm run test:profile

它会打包当前检出，新建临时 DSH_HOME，调用官方插件 add/remove 命令，用真实宿主服务启动最小配置档，检查工具可见性与文本提取，然后验证卸载并删除测试 home。它从不写入正常的 DSH 配置档，也不需要模型凭据。必须已正确安装 pnpm 和 Poppler。DSH_PROFILE_EVIDENCE=/absolute/path/report.json 会保存限定范围内的结果。

这验证的是文档处理行为，不是端到端模型准确率基准。要衡量模型收益，请固定模型、提示词和解码设置，在同一批 PDF 上对比现有附件处理、这些工具，以及人工核验的证据。以源目录中的 evaluation.json 作为评分标准的起点。