DeepSeek Harness Plugin

alotherss/DeepSeekHarness-plugin#dsh-pdf-tools

Stars ★ 0 Downloads (30d) 325 Category Tools & Capabilities Added 2026-11-16 npm dsh-pdf-tools

Page-scoped PDF tools for the model: pdf_info reads the page count and whether a text layer exists, pdf_outline and pdf_search locate pages, pdf_text extracts only those pages, and pdf_render rasterises one page. Per-call caps and CJK radical normalisation are built in.

Install

# from npm (prebuilt)

dsh plugin --profile web add dsh-pdf-tools

# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)

dsh plugin --profile web add github:alotherss/DeepSeekHarness-plugin#path:/packages/dsh-pdf-tools

Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).

README

Page-scoped PDF tools for the model. Never converts a whole document: a 900-page manual extracted end to end is hundreds of thousands of tokens, while one page is a few hundred.

Five tools: pdf_info (page count, metadata, whether a text layer exists), pdf_outline (bookmark tree with page numbers), pdf_text (the text of specific pages), pdf_search (full-text search that reports only the pages that matched), and pdf_render (one page to PNG).

Why page-scoped

Context is the scarcest resource in an agent, and PDF is the easiest format to swallow whole. Dumping a document has two costs: the tokens explode, and the two or three pages that actually matter end up buried under a hundred thousand words.

So every entry point here demands page numbers. pdf_info tells you the size and whether the document has a usable text layer; pdf_search or pdf_outline locates the pages; pdf_text returns just those. Search returns page numbers and snippets, never body text.

Tools

Tool What it does
pdf_info Page count, title, author, size, and whether a text layer exists (which decides between pdf_text and pdf_render)
pdf_outline Bookmark (table of contents) tree, one line per entry with the page it starts on
pdf_text Text of specific pages: 5, 10-12, 3,7,9, all; at most 40 pages per call
pdf_search Literal, case-insensitive search returning matching pages, snippets, and a page list
pdf_render Rasterise one page to PNG and attach it to the result: schematics, scope captures, scans, tables that extract scrambled

pdf_text caps at 40 pages and 120k characters per call and refuses anything larger with a message telling the model to narrow the range — deliberately, so one call cannot flood the context.

Typical flow

  1. pdf_info -> 852 pages, text layer present
  2. pdf_outline -> chapter 7 (DMA) starts on page 240
  3. pdf_text 240-244 -> read those five pages
  4. The timing diagram on page 243 extracts as gibberish -> pdf_render 243, and the image lands in context

Two CJK pitfalls, already handled

Chinese PDFs routinely map Han glyphs onto Unicode compatibility characters, and an unnormalised search then misses text that is plainly there:

  1. Kangxi radicals (U+2F00-U+2FDF, e.g. U+2F42) - folded back by NFKC.
  2. CJK Radicals Supplement (U+2E80-U+2EFF, e.g. U+2EDA for the "page" character) - NFKC leaves this block alone, so a 58-entry table folds it.

Install

Inside DSH: Plugins -> Plugin market, search for dsh-pdf-tools.

Command line:

dsh plugin --profile web add dsh-pdf-tools

Refresh the page afterwards; no restart needed.

Dependencies

  • pdfjs-dist (pure JavaScript: extraction, outline, page indices)
  • @napi-rs/canvas (native, used only by pdf_render; prebuilt binaries, nothing is compiled)
  • @deepseek-ai/dsh-tools: declared as a peerDependency. That declaration is the mechanism DSH uses to route the import to the host's own copy, so it must not become a dependency.

Privacy

Everything runs locally: no network, no uploads, no registry writes. Parsed documents are cached by path plus modification time, four at most, and re-parsed when the file changes. Rendered PNGs default to the dsh-pdf-tools folder inside the system temporary directory.

Known limits

  • Password-protected PDFs are refused with a clear error rather than failing silently.
  • A page with no text layer can only be viewed through pdf_render; OCR is out of scope.
  • pdf_text caps at 40 pages and 120k characters. Reading a whole book is not a supported workflow, and not a good one.

License

MIT

Content from the project README on GitHub ↗

Links

More in this category

View the whole category →

Community comments

Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.