前言¶

在 DeepSeek Harness（DSH）里处理 PDF 时，常见做法是让用户截图、复制粘贴，或先转成 Word / 文本再喂给 agent。这些步骤打断对话，也容易丢页码和结构。若 PDF 就在本机、且带可提取的文字层，更合理的做法是让 agent 直接按路径读文件。

下面介绍社区插件 dsh-plugin-pdf-text（维护者 peanutcd2005，分类：客户端）：在 DSH 中注册工具 pdf_extract，逐页返回文字与页级统计，并识别「纯图片扫描件」；纯 Node 实现，不依赖 Python，默认不联网，文件不离开本机。

这是什么¶

dsh-plugin-pdf-text 是 DSH 的 Cordis bundle 型插件（dsh.kind: server），入口为 lib/index.js，当前版本 0.1.0，许可证 MIT。它在 profile 里向 agent 暴露一个工具 pdf_extract，用于读取用户指定的本地 PDF 绝对路径，把带文字层的内容按页组织后返回给模型。

插件披露字段标明：cloud: false、offlineMode: true、无外部 API Key；权限仅为读取用户指定的 PDF，以及可选写入 saveTo 指定的文本文件。

核心功能¶

pdf_extract 的能力（均来自仓库 README 与实现说明）：

1. 逐页文本：每页带页眉标记，例如 ===== 第 3 页 =====。
2. 开头统计：总页数、已读取页数、其中有文字的页数。
3. 扫描件提示：整份 PDF 一页都提不到文字层时，明确说明「很可能是纯图片扫描件，需要 OCR」，不编造内容。
4. 返回长度上限：给模型的内容最多 32000 字符；超长时按页边界截断，并提示改用 maxPages 或 saveTo。
5. 可选落盘：saveTo 可将全文（含统计行与页眉）另存为 UTF-8 文本；落盘文件不受 32000 字符上限约束。
6. 可读错误：文件不存在、目录不存在、无权限、PDF 加密等会给出明确提示，而非静默失败。

解析依赖 npm 包 unpdf（^1.8.1），按页提取文本；插件不 import 任何 @deepseek-ai/* 包，工具定义按 ctx.tools.register() 契约手写，避免 profile 插件目录解析宿主包失败。

安装与启用¶

前置：本机已安装 DSH，且已知 profile 名称（文档示例为 desktop）。

从 GitHub / 插件市场安装（推荐）¶

dsh plugin --profile desktop add peanutcd2005/dsh-plugin-pdf-text

DSH 兼容 install 与 add 两种写法；也可在「设置 → DSH 插件市场」搜索 dsh-plugin-pdf-text 安装。

安装后需重启 profile 才生效（插件不热加载）。卸载示例：

dsh plugin --profile desktop remove dsh-plugin-pdf-text

离线 tarball（可选）¶

除 unpdf 首次下载外可不联网；profile 里已有 unpdf 时可完全离线。打包与安装路径见仓库 README；路径建议纯英文，避免中文路径乱码。

安装后对账¶

• 查看 profile 的 package.json，bundles 中应出现 dsh-plugin-pdf-text。
• 桌面 Electron 托管的 desktop profile 可能拒绝 dsh --profile desktop --dump-config，此时改在界面「插件」页确认。
• 重启会话后，让 agent 调用 pdf_extract 读一份本地 PDF 做冒烟验证。

Node 引擎要求：^22.19.0 || >=24.0.0（见 package.json）。

典型用法¶

会话里怎么说¶

在 DSH 会话中说明要读的 PDF，并给出绝对路径，agent 会调用 pdf_extract。例如：「读一下这个 PDF」并附上路径。

工具参数¶

返回示例（节选）：

文件：C:\...\report.pdf（14.1 MB）
总页数：198；已读取：3 页；其中有文字的页数：2

===== 第 1 页 =====
...

纯图片扫描件时，统计中「其中有文字的页数」为 0，并附带需要 OCR 的说明，不会返回臆造正文。

大文件与分批读¶

超过 32000 字符时，模型侧结果会在页边界截断并提示：用 maxPages 分批读，或用 saveTo 保存全文后再在本地检索段落。

适用场景与注意¶

适合：可行性报告、合同、论文等带文字层的本地 PDF；希望 agent 直接引用页码与段落、且数据不出本机的场景。

不适合：整页扫描图、照片型 PDF——插件不含 OCR，只会提示需要 OCR 工具。

其他限制（README 原文要点）：

• 判定「该页有文字」：去掉空白后不少于 20 个字符；页眉页脚极少时可能计为无文字页。
• 只读 PDF 本体；除 saveTo 外不写文件。
• 加密、损坏 PDF 会报错或提示，不返回空内容冒充成功。

安全与信任：插件以当前 DSH 进程权限读盘；安装前请查看 GitHub 仓库 源码与 MIT 许可证。社区目录 SkillHub 插件页 与 DeepSeek / 幻方无官方从属关系，属 DSH「一切皆插件」生态中的第三方条目。

维护者在本机验收记录中，对约 198 页、14.1 MB 的报告测得整份提取约 0.8–1.4 s；扫描件样例均正确返回 OCR 提示。以上为仓库自述，读者环境可能不同。

链接¶

• 社区目录：https://www.skillhub.cn/plugins/peanutcd2005/dsh-plugin-pdf-text
• 源码与完整说明：https://github.com/peanutcd2005/dsh-plugin-pdf-text