dsh-doc-reader
Read PDF, DOCX, XLSX, PPTX and text documents as agent tools for DeepSeek Harness (dsh).
The built-in read tool returns file text, and web_fetch rejects application/pdf — so a PDF, a spreadsheet or a slide deck currently ends up as curl + pip install pypdf inside the session. This plugin closes that gap with five typed tools that return page-, sheet- and slide-aware text, including local OCR for scans and screenshots.
Tools
| Tool | What it does | Key parameters |
|---|
doc_read | Universal reader: PDF, DOCX, XLSX, PPTX, TXT/MD/CSV/HTML; auto-detects format by magic bytes | path | url, format, pages, sheet, maxRows, maxChars |
pdf_read | PDF page by page with --- page N/M --- markers, title/author metadata | path | url, pages (e.g. "1-3,7"), maxChars |
xlsx_read | One block per sheet, tab-separated rows, sheet by name or 1-based index | path | url, sheet, maxRows, maxChars |
doc_meta | Metadata only: format, size, PDF page count/title, DOCX props, XLSX sheets, PPTX slide count | path | url, format |
doc_ocr | OCR for scanned PDFs and images (PNG/JPEG/WebP/BMP/TIFF/GIF), per-page confidence | path | url, pages, langs, scale, maxChars |
Every tool accepts a local path or an http(s) URL. Prefer doc_meta first for large files, then read the pages/sheets you need — output is capped by maxChars (default 60000, hard cap 400000).
Example output
# 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 handles what pure text extraction cannot: scanned PDFs, photos and screenshots.
- Engine: tesseract.js 7 (WebAssembly, no native OCR binary) — runs fully locally, nothing is uploaded.
- PDF pages are rasterized with
pdf-to-img (pdf.js + @napi-rs/canvas) at scale 2 (~200 DPI), then recognized with one shared worker.
- Fax-style CCITT G4 and JBIG2 scans are decoded through pdf.js wasm/JS decoders (
wasmUrl is wired to the installed pdfjs-dist/wasm), so two-tone scans rasterize instead of returning blank pages.
- Default languages:
rus+eng (langs overrides, e.g. "deu", "eng"). Order matters: with eng+rus tesseract reads uppercase Cyrillic as Latin lookalikes (ПРИВЕТ → NMPUBET); Cyrillic-first keeps Latin accuracy identical (measured 94–95% on both fixture sets).
- First use downloads the language data (~4 MB per language) into
~/.dsh/cache/dsh-doc-reader/tesseract; later calls are fast (a page takes ~0.3–1 s). For offline machines set DSH_DOC_READER_OCR_LANG_PATH to a directory containing <lang>.traineddata (optionally .gz), and/or DSH_DOC_READER_OCR_CACHE for the cache location.
- At most 20 PDF pages per call; narrow with
pages. Use scale: 1 for speed, scale: 3 for small print.
- Rotation/handwriting/low-resolution scans are best-effort: tesseract has no layout magic, and confidence is reported per page so you can judge the result.
# 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
...
Limits and security
- Local files: up to 50 MB; URLs: downloaded with a 20 s timeout and the same 50 MB cap.
- Private/local hosts are refused (
localhost, 127.0.0.1, RFC1918, .local, .internal) so the tool cannot become an SSRF primitive. Download the file and pass a path instead.
- Only
http(s) URLs.
- PDF text extraction is text-based: scanned PDFs (images only) return
(no extractable text on this page) — use doc_ocr for those.
- DOCX conversion is handled by
mammoth; charts, comments and tracked changes are not materialized as text.
- XLSX returns displayed values, not formulas; rows are paged with
maxRows.
Install
Published on npm as dsh-doc-reader. Install from the built-in plugin market, or manually into a profile:
cd ~/.dsh/profiles/desktop
npx pnpm add dsh-doc-reader
Then add the bundle to the profile's package.json:
"dsh": { "profile": { "bundles": ["dsh-doc-reader", "..."] } }
Restart DSH (the plugin loads on boot; DSH composition is all-or-nothing). The five tools appear in the next session.
For local development, install the working copy instead: npx pnpm add link:~/dsh-plugins/dsh-doc-reader.
pnpm 12 may report an ignored build script for tesseract.js. That postinstall is only the OpenCollective banner — approve it with pnpm approve-builds or ignore it; OCR works either way.
Develop
npm install
npm test # node --test, runs against test/fixtures
node --check index.js
The readers live in lib/ and have no host dependency, so they can be exercised directly:
import { readDocument, documentMeta } from "./lib/read.js";
await readDocument({ path: "report.pdf", pages: "1-3" });
index.js imports @deepseek-ai/dsh-tools for defineTool; outside a DSH host the import falls back to an identity definition (the registry consumes the plain object).
Roadmap
.doc, .rtf, .odt, .epub readers.- Layout hints from OCR (word boxes, tables) and page-number citations.
- Page/sheet images for vision models (
presentResult image parts).
- Caching of parsed documents within a session.
License
MIT
