dsh-tool-pdf
English | 中文
A DeepSeek Harness (dsh) plugin that adds a read_pdf tool for PDF text extraction — lets an AI agent (LLM) read, extract, and summarize PDF files, page by page.
Built on unpdf (a serverless build of Mozilla PDF.js). It reads PDF bytes through the harness filesystem seam (ctx.fs), so it obeys the same workspace and sandbox policy as the built-in read tool.
Keywords: DeepSeek Harness · dsh · dsh plugin · read_pdf · PDF reader · PDF text extraction · extract text from PDF · AI agent tool · LLM tool · PDF.js · unpdf
> read_pdf is a model-facing tool, not a UI button. It does not appear as a menu item or a settings entry. It shows up in the conversation when the model actually reads a PDF — you trigger it by asking the model to read one.
Quick start
1. Install into the web profile
dsh web boots the web profile, so install the plugin there (not into a new profile):
dsh plugin --profile web add github:Jeffine322/dsh-tool-pdf
2. Start the Web UI
dsh web
3. Configure a model and a workspace
In the browser: Settings → Models (enter your DeepSeek API key, then save), then Choose workspace and select the directory that contains your PDFs.
4. Ask the model to read a PDF
Start a session and say:
> Read /path/to/report.pdf and summarize it.
The model calls read_pdf({ file_path: "/path/to/report.pdf" }), and you see the extracted text in the conversation.
Verify it is installed
dsh web --dump-config
If the output contains a tool-pdf row (- id: tool-pdf, name: dsh-tool-pdf), the plugin is mounted.
Install details
Requires a dsh installation with the dsh CLI on your PATH.
# From this repo's git URL
dsh plugin --profile add github:Jeffine322/dsh-tool-pdf
# Or from a local checkout
dsh plugin --profile add ./dsh-tool-pdf
The package declares dsh.bundle, so dsh plugin appends it to the profile's bundle layers automatically. The built dist/index.mjs is committed to this repo, so a git install needs no build step and no allowBuilds approval.
How it works
PDF is a binary format, not plain text: a page's visible characters are stored as glyph codes in a content stream, mapped back to Unicode through each font's encoding table. The built-in read tool therefore refuses PDFs as binary — read_pdf decodes them.
Parsing is delegated to unpdf, which bundles Mozilla's PDF.js (the engine Firefox uses), so this plugin never touches PDF's binary internals. The pipeline is:
read_pdf({ file_path })
→ extension gate (must be .pdf)
→ ctx.fs.resolve + stat # regular file; missing/dir → typed error
→ ctx.fs.readBytes(…, maxFileBytes) # obeys workspace/sandbox policy
→ re-view as plain Uint8Array # pdf.js rejects a Node Buffer
→ getDocumentProxy(bytes) # load the document
→ extractText(pdf, { mergePages: false }) # text per page
→ capPages(…, maxOutputChars) # bound the total output
→ formatPdfReadOutput(…) # // envelope
→ return text to the model + emit fs/observed
Two bounds keep a large PDF from blowing up the model context: maxFileBytes (the file read) and maxOutputChars (the extracted text). It extracts plain text only — no layout, tables, or images (see Limitations).
Config
| Field | Default | Meaning |
|---|---|---|
maxFileBytes |
52428800 (50 MiB) |
Maximum PDF file bytes read per call; larger files fail with FS_TOO_LARGE. |
maxOutputChars |
100000 |
Maximum extracted-text characters returned per call; overflow truncates the last page. |
To change them, override the row in your profile's cordis.patch.yml (a patch replaces the whole config, so restate every key you change):
- id: tool-pdf
name: dsh-tool-pdf
config:
maxFileBytes: 10485760
maxOutputChars: 50000
Development
pnpm install
pnpm build # tsdown bundles src/*.ts → dist/index.mjs (committed)
Structure:
src/index.ts # the plugin: name/inject/Config/apply, registers read_pdf
src/extract.ts # unpdf extraction + output capping + envelope formatting
cordis.patch.yml # bundle layer: inserts the plugin row
The plugin keeps @deepseek-ai/dsh-tools, @deepseek-ai/dsh-fs, and @deepseek-ai/cordis as external imports (via tsdown's deps.neverBundle) rather than bundled copies, so at runtime it shares the running harness's single service instances. They are therefore not declared as npm dependencies: Node resolves them against the dsh installation's node_modules when the plugin loads. unpdf and @deepseek-ai/schemastery are ordinary dependencies.
Limitations
- No layout or table structure — extraction returns plain text in reading order; tables, columns, and images are not reconstructed.
- Scanned PDFs have no text layer — raster-only pages extract to empty text; OCR is out of scope.
- Encrypted PDFs — password-protected documents are reported as not readable.
License
MIT
