PDF 文字提取 peanutcd2005/dsh-plugin-pdf-text

dsh-plugin-pdf-text

在 DeepSeek Harness（DSH）里读取本地 PDF 文件的文字。

给 DeepSeek Harness（DSH）用的 PDF 文字读取插件：注册一个 pdf_extract 工具，让智能体自己读 PDF 报告，不必让用户截图或转格式。

纯 Node、无 Python、不联网、文件不离开本机。

功能

注册一个工具 pdf_extract，它可以：

- 逐页返回 PDF 文字，每页带页眉标记，例如 ===== 第 3 页 =====；
- 回答开头给出统计：总页数、已读取页数、其中有文字的页数；
- 整份 PDF 一页文字都没有时，明确说明「这很可能是纯图片扫描件，需要 OCR」，绝不编造内容；
- 返回给模型的内容上限 32000 字符，超长时按页边界截断并提示改用 maxPages 或 saveTo；
- 可选把全文另存为文本文件（saveTo），便于之后反复检索；
- 明确报错：文件不存在、目录不存在、无权限、PDF 加密等都会给出可读提示，而不是静默失败。

用法：在 DSH 会话里直接说「读一下这个 PDF」并给出路径，智能体就会调用 pdf_extract。

安装

前置：已安装 DSH，profile 名称已知（本机为 desktop）。

从 GitHub 安装（推荐，也是插件市场用的方式）

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

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

从本地 tarball 安装（离线）

本插件用本地 tarball 安装时，除 unpdf 首次下载外不联网；若 profile 里已有 unpdf 则完全离线。

1) 打包（在插件项目目录里）
pnpm pack --pack-destination .pack

2) 安装到 profile（用绝对路径，且路径保持纯英文，避免中文路径乱码）
dsh plugin --profile desktop add "C:\Users\csh\dsh-tools\dsh-plugin-pdf-text\.pack\dsh-plugin-pdf-text-0.1.0.tgz"

3) 重启 profile 才生效（插件不热加载）

安装后可用下面三条命令对账：

a) profile 的 bundles 里应出现 dsh-plugin-pdf-text Get-Content "$env:USERPROFILE\.dsh\profiles\desktop\package.json"

b) 组合配置应出现 id: pdf-text 的行，且无重复、无告警注意：桌面版（Electron 托管）会拒绝 dump-config 并返回 'profile "desktop" is managed exclusively by the Electron application'，这种情况改用界面「插件」页 /「设置 → 内置插件」确认；在 dsh web 等非桌面 profile 上该命令正常可用。
dsh --profile desktop --dump-config

c) 重启后在会话中调用 pdf_extract 读一份 PDF

卸载：

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

参数

| 参数 | 必填 | 类型 | 含义 |
| path | 是 | string | PDF 文件的绝对路径。 |
| maxPages | 否 | integer ≥ 1 | 只读取前 N 页；省略则读取全部页面。超过总页数时按总页数处理。 |
| saveTo | 否 | string | 把提取到的全文另存为该绝对路径的文本文件（带统计行与页眉）。所在目录必须已存在。 |

返回内容示例：

文件：C:\...\沙文一号加气站可行性研究报告9.9(3)(1).pdf（14.1 MB）
总页数：198；已读取：3 页；其中有文字的页数：2

===== 第 1 页 ===== 贵阳市矿能集团石化发展有限公司沙文一号加气站 可行性研究报告 ...

纯图片扫描件：

文件：C:\Users\csh\Desktop\2026年度学习证明.pdf（1.9 MB）总页数：1；已读取：1 页；其中有文字的页数：0

该 PDF 共 1 页，但这一批页面没有提取到任何文字层。
它很可能是纯图片扫描件（整页是照片或截图），需要 OCR 才能识别内容。本工具不会编造内容。
如果只想先看一部分，可用 maxPages 指定页数；如果确认是扫描件，请改用 OCR 工具。

使用限制

- 只处理带文字层的 PDF。 纯图片扫描件（整页是照片或截图）返回「无文字层 / 需要 OCR」提示，不返回空内容、也不编造内容。本插件不含 OCR。
- 返回给模型的内容上限 32000 字符。 超长时按页边界截断，并提示改用 maxPages 分批读取，或用 saveTo 保存全文后再定位段落。saveTo 写出的文件是全文，不受该上限影响。
- 判定「这一页有文字」的标准：去掉空白后不少于 20 个字符；页眉页脚等零星字符的页可能被算作无文字页。
- 只读取，不改动 PDF。 唯一的写操作是 saveTo 指定的文本文件（UTF-8）。
- 纯本地运行。 不联网、不依赖 Python、不调用外部服务，文件内容不离开本机。
- saveTo 不会自动建目录。 目标目录不存在时会明确报错。
- 扫描件、加密 PDF、损坏 PDF 都会明确报错或提示，不会返回空内容。

实现说明

- 解析依赖 unpdf（零运行时依赖、服务端取向的 pdf.js 封装），加载参数为 { verbosity: 0, useSystemFonts: true, isEvalSupported: false }，用于压掉 pdf.js 的字体告警；
按页提取文本（extractText(proxy, { mergePages: false })）。
- 插件不 import 任何 @deepseek-ai/ 包：profile 的插件目录里解析不到这些包，导入会导致插件加载失败。
工具定义直接按 ctx.tools.register() 的契约手写（{ name, description, parameters, output: { schema, render }, execute }）。
- 项目文件：lib/index.js 全部实现、cordis.patch.yml bundle 补丁、scripts/verify.mjs 验收脚本。

自检

在插件项目目录，把 profile 的 unpdf 借来当依赖即可运行（脚本只读 PDF）
node scripts/verify.mjs "C:\path\to\report.pdf"
node scripts/verify.mjs "C:\path\to\scanned.pdf" --expect-scan

脚本会打印总页数、已读取页数、有文字的页数、耗时，并对扫描件断言「无文字层」提示。

发布到 DSH 插件市场

市场（dsh-plugin-marketplace）没有申请入口：给 GitHub 仓库打上 topic dsh-plugin，CI 最迟 2 小时扫描收录。

1. 建仓库并推代码（仓库名建议与包名一致：dsh-plugin-pdf-text）：

cd dsh-plugin-pdf-text
git init
git add -A
git commit -m "feat: pdf_extract tool for DSH (0.1.0)"
git remote add origin https://github.com/peanutcd2005/dsh-plugin-pdf-text.git
git push -u origin main

2. 打 topic：仓库页 → ⚙ Settings → Topics → 添加 dsh-plugin。
建议再加：dsh、deepseek-harness、cordis-plugin、pdf。

3. 等 CI 收录：最迟 2 小时出现在市场列表（设置 →「DSH 插件市场」）。

4. 改名提醒：如果你的 GitHub 用户名以后变了，记得同步更新 package.json 的 repository / homepage / bugs 与本文档里的仓库地址。

收录自检（对照市场 STANDARD.md）：

| 检查项 | 本仓库状态 |
| 根目录 package.json 有 dsh 声明 | ✅ dsh.plugin + dsh.bundle.patch → 判为 cordis 插件（bundle 型） |
| main 指向仓库里真实存在的文件（产物型，无需构建） | ✅ lib/index.js 已提交，无 scripts.build |
| 根目录无 install.ps1 / install.sh | ✅ 不会误判成脚本型 |
| 宿主接口包只进 peerDependencies | ✅ 更彻底：不依赖任何 @deepseek-ai/ 包（见「实现说明」） |
| version 每次发版必须 bump | ✅ 当前 0.1.0；改代码务必改版本，否则「更新」按钮不会出现 |
| 包名唯一 | ✅ 已核对市场索引：无 dsh-plugin-pdf-text 占用 |
| 分类敏感词自查 | ✅ 简介未含微信/通知/商店/榜单等词 |
| 披露字段（disclosure） | ✅ cloud:false、network:[]、apiKeys:[]、retention:none |

两个容易踩的坑（本仓库已避开）：

- 不要在运行时或安装脚本里自己写 cordis.patch.yml 注册条目 —— 市场安装时会自动注册，双注册会导致 Web 服务路由重复、启动崩溃（市场 issue #39）。
- 不要把 @deepseek-ai/dsh-tools 等宿主包写进普通 dependencies —— 旧版副本会遮蔽宿主（STANDARD §6.6）。本插件干脆不 import 任何 @deepseek-ai/*。同时市场在注册 bundle 时会校验 dependencies+peerDependencies 全部可解析，声明解析不到的宿主 peer 会直接让安装失败。

验收记录（本机实测）

验收对象：沙文一号加气站可行性研究报告9.9(3)(1).pdf（14.1 MB）。

| 检查项 | 期望 | 实测 |
| 总页数 | 198 | 198 |
| 有文字的页数 | 169–170 | 169 |
| 第 123 页财务指标 | 含「财务内部收益率」「1107.25 万元」「19.06」 | 全部命中（财务内部收益率、1107.25、19.06） |
| 纯图片扫描件 | 返回「无文字层 / 需要 OCR」，不编造内容 | 2026年度学习证明.pdf（1 页）、关于贵阳矿能集团风电投资项目之投资合作协议.pdf（62 页）均正确返回 OCR 提示 |
| 超长截断 | 32000 字符上限 + 按页截断提示 | 130 页调用返回 32079 字符，末页为第 49 页并附提示 |
| 耗时 | — | 整份 198 页约 0.8–1.4 s |
| 进程退出码 | 0 | 0（无 pdf.js 字体告警） |

安装验证三连：

1. profile dsh.profile.bundles 含 dsh-plugin-pdf-text，且无重复项；
2. dsh --profile desktop --dump-config 在本机被 Electron 拒绝（profile "desktop" is managed exclusively by the Electron application），因此改用「已安装文件与源码逐字节一致 + 工具在活动会话中真实可用」作为等价证据；
3. 重启后 agent 在本会话直接调用 pdf_extract 读通了上述报告。

License

MIT