文档读取器 reg4916/dsh-doc-reader

dsh-doc-reader

把 PDF、DOCX、XLSX、PPTX 和文本文档读成智能体工具，供 DeepSeek Harness (dsh) 使用。

内置的 read 工具只返回文件文本，web_fetch 又拒绝 application/pdf —— 所以现在碰到 PDF、表格或幻灯片，只能在会话里 curl + pip install pypdf。这个插件补上了这块空白：五个带类型的工具，返回能区分页、工作表和幻灯片的文本，还支持对扫描件和截图做本地 OCR。

截图

doc_read —— 能区分页的 PDF 文本和表格行：

doc_read output

doc_ocr —— 对扫描件和图片做本地 OCR，带每页置信度：

doc_ocr output

工具

| 工具 | 作用 | 关键参数 |
| doc_read | 通用读取器：PDF、DOCX、XLSX、PPTX、TXT/MD/CSV/HTML；按 magic bytes 自动识别格式 | path \| url、format、pages、sheet、maxRows、maxChars |
| pdf_read | 逐页读 PDF，带 --- page N/M --- 标记，返回标题/作者元数据 | path \| url、pages（如 "1-3,7"）、maxChars |
| xlsx_read | 每个工作表一个块，行用制表符分隔，按名称或从 1 开始的索引选工作表 | path \| url、sheet、maxRows、maxChars |
| doc_meta | 只返回元数据：格式、大小、PDF 页数/标题、DOCX 属性、XLSX 工作表、PPTX 幻灯片数 | path \| url、format |
| doc_ocr | 对扫描版 PDF 和图片（PNG/JPEG/WebP/BMP/TIFF/GIF）做 OCR，带每页置信度 | path \| url、pages、langs、scale、maxChars |

每个工具都接受本地路径或 http(s) URL。大文件建议先用 doc_meta，再读你需要的页/工作表 —— 输出受 maxChars 限制（默认 60000，上限 400000）。

输出示例

invoice.pdf — PDF · 184.2 KB source: /work/invoice.pdf pages 1, 2 of 7 · title: Invoice 2026-10

--- page 1/7 ---
ACME Ltd — Invoice 0042 ...

budget.xlsx — XLSX · 12.4 KB source: https://example.com/budget.xlsx sheets: Data, Second

sheet "Data" — 3 rows × 3 cols 1 | Year | Revenue | Note 2 | 2024 | 1000 | ok 3 | 2025 | 2000 | Привет

OCR

纯文本提取搞不定的，交给 doc_ocr：扫描版 PDF、照片、截图。

- 引擎：tesseract.js 7（WebAssembly，不需要原生 OCR 二进制）—— 完全在本地跑，不上传任何东西。
- PDF 页面用 pdf-to-img（pdf.js + @napi-rs/canvas）按 scale 2（约 200 DPI）栅格化，再用一个共享 worker 识别。
- 传真式的 CCITT G4 和 JBIG2 扫描件走 pdf.js 的 wasm/JS 解码器（wasmUrl 指向已安装的 pdfjs-dist/wasm），所以双色扫描件能正常栅格化，不会返回空白页。
- 默认语言：rus+eng（可用 langs 覆盖，例如 "deu"、"eng"）。顺序很重要：用 eng+rus 时，tesseract 会把大写西里尔字母读成外形相似的拉丁字母（ПРИВЕТ → NMPUBET）；西里尔字母在前时，拉丁字母的准确率保持不变（在两套测试样本上实测均为 94–95%）。
- 首次使用会下载语言数据（每种语言约 4 MB），存到 ~/.dsh/cache/dsh-doc-reader/tesseract；之后的调用很快（一页约 0.3–1 s）。离线机器请把 DSH_DOC_READER_OCR_LANG_PATH 设为存放 <lang>.traineddata（可选 .gz）的目录，并可用 DSH_DOC_READER_OCR_CACHE 指定缓存位置。
- 每次调用最多处理 20 页 PDF；用 pages 缩小范围。要速度用 scale: 1，要看清小字用 scale: 3。
- 旋转、手写、低分辨率扫描只能尽力而为：tesseract 没有版面识别的魔法，每页都会报告置信度，方便你判断结果。

scan.pdf — PDF (OCR) · 1.8 MB source: /work/scan.pdf OCR: tesseract rus+eng · pages 1, 2 of 12

--- page 1/12 (ocr, 91.4%) ---
INVOICE 2026-042
...

限制与安全

- 本地文件：最大 50 MB；URL：下载超时 20 s，同样上限 50 MB。
- 拒绝私有/本地主机（localhost、127.0.0.1、RFC1918、.local、.internal），这样工具就不会变成 SSRF 的入口。请先下载文件，再传 path。
- 只接受 http(s) URL。
- PDF 文本提取基于文本层：扫描版 PDF（只有图片）会返回 (no extractable text on this page)，这类文件请用 doc_ocr。
- DOCX 转换由 mammoth 处理；图表、批注和修订不会转成文本。
- XLSX 返回显示值，不返回公式；行用 maxRows 分页。

安装

已发布到 npm：dsh-doc-reader。可以从内置插件市场安装，也可以手动装进配置档：

cd ~/.dsh/profiles/desktop
npx pnpm add dsh-doc-reader

然后把 bundle 加进配置档的 package.json：

"dsh": { "profile": { "bundles": ["dsh-doc-reader", "..."] } }

重启 DSH（插件在启动时加载；DSH 的组装是全有或全无）。五个工具会在下一个会话中出现。

本地开发时，改为安装工作副本：npx pnpm add link:~/dsh-plugins/dsh-doc-reader。

pnpm 12 可能会提示 tesseract.js 的构建脚本被忽略。那个 postinstall 只是 OpenCollective 横幅——用 pnpm approve-builds 批准，或者直接忽略；两种情况下 OCR 都能正常工作。

开发

npm install
npm test # node --test, runs against test/fixtures
node --check index.js

读取器都在 lib/ 里，不依赖宿主，可以直接调用：

import { readDocument, documentMeta } from "./lib/read.js";
await readDocument({ path: "report.pdf", pages: "1-3" });

index.js 从 @deepseek-ai/dsh-tools 导入 defineTool；在 DSH 宿主之外，这个导入会回退到一个恒等定义（注册表消费的是普通对象）。

路线图

- .doc、.rtf、.odt、.epub 读取器。
- 来自 OCR 的版面提示（文字框、表格）和页码引用。
- 供视觉模型使用的页面/表格图片（presentResult 图片部分）。
- 在会话内缓存已解析的文档。

许可证

MIT