dsh-plugin-pdf-text

Read text out of local PDF files inside DeepSeek Harness (DSH).

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

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

功能

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

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

用法：在 DSH 会话里直接说「读一下这个 PDF」并给出路径，agent 就会调用 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