jiaoqsh / dsh-document

dsh-document

A DeepSeek Harness plugin bundle (@jiaoqsh/dsh-document) that gives the model a read_document tool: Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, and PDF files are converted to line-numbered Markdown the model can page through with offset/limit.

Conversion runs locally: office formats through @firecrawl/anydoc (Rust core, Node bindings) and PDFs through @firecrawl/pdf-inspector (WASM build, run in a worker thread) — no API key, no network, no external binaries; both MIT. PDFs get page selection, <!-- Page N --> markers, and page facts: total pages, text-based / scanned / mixed, and which pages have no extractable text. Files are read through the harness ctx.fs seam, so whatever filesystem provider and sandbox policy a deployment mounts applies unchanged.

Install

Into an existing profile (web, headless, or your own), from npm:

dsh plugin --profile web add @jiaoqsh/dsh-document

The npm package ships built code, so nothing runs at install time. Releases are published from this repository's release.yml through npm trusted publishing and carry provenance attestations.

From GitHub instead

dsh plugin --profile web add github:jiaoqsh/dsh-document#<commit-sha>

A git install fetches sources, so pnpm ≥ 10 refuses to run the package's prepare (a tsdown transpile of src/) until you allow it: the first add fails and prints the exact key to copy into the profile's pnpm-workspace.yaml ($DSH_HOME/profiles/<name>/pnpm-workspace.yaml). The key names the resolved tarball, so a bare package name does not match:

allowBuilds:
  '@jiaoqsh/dsh-document@https://codeload.github.com/jiaoqsh/dsh-document/tar.gz/<commit-sha>': true

Re-run the add. Allowing the build means executing this package's code on your machine at install time; pin a commit so a later push cannot change what runs.

dsh plugin prints "missing peer" warnings for the @deepseek-ai/* packages: expected. The dsh installation supplies them at runtime; profiles deliberately do not install peers.

Verify, then boot:

dsh --profile web --dump-config   # shows a "# == @jiaoqsh/dsh-document" layer
dsh --profile web

Remove with dsh plugin --profile web remove @jiaoqsh/dsh-document.

From a source checkout of the harness

pnpm dsh web --patch /absolute/path/to/dsh-document/overlay.yml

where the overlay inserts the built entry by absolute path:

- insert:
    - id: document-tools
      name: '/absolute/path/to/dsh-document/lib/index.js'

Configuration

The bundle's layer inserts one row, document-tools, with schema defaults. Override it by id in your profile's cordis.patch.yml; a patch replaces the whole config, so restate every key you need:

- id: document-tools
  config:
    maxInputBytes: 104857600   # 100 MiB
    readLimit: 2000
    maxLineLength: 2000
    maxOutputBytes: 51200
    pdfMaxPages: 100
    pdfProfile: fidelity

Key	Default	Meaning
maxInputBytes	52428800 (50 MiB)	Inclusive byte cap on the source file. Enforced by the filesystem provider before any bytes are buffered; larger files are refused.
readLimit	2000	Default and maximum number of Markdown lines returned by one call.
maxLineLength	2000	Maximum characters per returned line; overflow is cut with … [line truncated].
maxOutputBytes	51200 (50 KiB)	Maximum bytes of line text returned by one call; the window stops early and the footer says how to continue.
pdfMaxPages	100	Maximum distinct pages one pages selection may name.
pdfProfile	fidelity	PDF Markdown profile: fidelity keeps source structure, compact spends fewer tokens.

Every numeric value must be a positive integer and pdfProfile one of the two names; anything else fails the plugin load with a message naming the key.

The tool

read_document(file_path, offset?, limit?, pages?)

• file_path — resolved by the filesystem backend; relative paths resolve against the calling session's workspace.
• offset — 1-based first line of the converted Markdown (default 1).
• limit — lines to return (default and maximum readLimit).
• pages — PDF only: 1-based pages to convert, as numbers and ranges like "1-3,7" (at most pdfMaxPages). Default: every page. Naming a page beyond the last one is an error that states the page count.

Supported extensions: .pdf, .doc, .docm, .docx, .ppt, .pps, .pot, .pptx, .pptm, .ppsx, .ppsm, .xls, .xlsx, .xlsm, .xlsb, .odt, .ods, .odp, .rtf, .epub, .csv. The format comes from the extension, never from content sniffing (CSV has no signature).

Canonical value (what Code Mode receives):

{ path: string, format: 'pdf' | 'docx' | ..., offset: number,
  lines: { number: number, text: string }[], totalLines: number, truncatedByBytes: boolean,
  pdf?: { pageCount: number, kind: 'text' | 'scanned' | 'image' | 'mixed',
          pagesNeedingOcr: number[], pages?: number[], title?: string } }

Model-facing text (a PDF, pages 2 and 4 of 5):

<path>/work/report.pdf</path>
<format>pdf</format>
<pdf>5 pages, text-based; showing pages 2, 4</pdf>
<content>
1: <!-- Page 2 -->
2: 
3: Revenue grew 12% year over year.

(Showing lines 1-3 of 8. Use offset=4 to continue.)
</content>

A mixed PDF adds <warning>Pages 3, 7-8 contain no extractable text (scanned or image content); their content is missing below and would need OCR.</warning> before <content>. Non-PDF formats omit the <pdf> line.

Failures are tool errors in model terms: unsupported extension (pointing at read for plain text), pages on a non-PDF, a malformed pages value, not found, not a regular file, over maxInputBytes, encrypted, damaged or incomplete, engine resource limit, a page beyond the last page, cancellation, or no extractable text (a scanned or image-only PDF says so and that OCR is needed; this tool performs no OCR).

Model Experience

System prompt section tool:read_document

What the model sees

One fixed sentence, order 100 beside the shipped tool:read guidance:

Use the read_document tool — not read or shell commands — to inspect PDF, Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, and CSV files. It returns the document converted to line-numbered Markdown; use offset and limit to continue reading long documents. For a PDF, pass pages (for example "1-3,7") to read only those pages; page markers like <!-- Page 4 --> show where each page starts.

Token effect

Fixed: the section and the tool schema add a constant number of tokens to every request; results add up to maxOutputBytes per call.

KV Cache effect

Prefix-stable: the section text and schema never change between requests, so they do not invalidate a cached prompt prefix.

Known Limitations and Deferred Work

• No OCR — pages without a text layer are reported (pagesNeedingOcr, the <warning> line) but not read; a fully scanned or image-only PDF is an error naming the cause.
• PDF conversion runs in a fresh worker thread per call — cancellation terminates it, and the harness event loop stays free, at the cost of ~50 ms of WASM start-up per call. Office-format conversion (anydoc) runs on the libuv thread pool and cannot be cancelled once started; maxInputBytes is its bound.
• Layout-heavy PDFs may collapse paragraphs into long lines (then cut by maxLineLength); pdfProfile: compact trades structure for tokens.
• Engines are fixed — the DocumentConverter interface and routeConverters in src/converter.ts are the seam for a hosted or OCR-capable engine; none is wired today.
• The pdf-inspector native binary is not used — its npm build ships no darwin-x64 binary, so the WASM build runs everywhere for one code path.

Development

pnpm install          # also builds lib/ via prepare
pnpm run typecheck
pnpm test             # real Cordis Context + real registry + real local fs; no API key
pnpm run build

Release: bump version in package.json on main, then push the matching tag (git tag v0.2.0 && git push origin v0.2.0). release.yml checks the tag against the version, runs the checks, publishes to npm via trusted publishing, and creates the GitHub release with generated notes.

Fixtures under tests/fixtures/ were generated once with macOS textutil and cupsfilter (including a five-page PDF and an image-only PDF) and are committed so the suite runs anywhere. In source mode the PDF worker is spawned as .ts with --experimental-strip-types, so it stays free of TypeScript-only runtime syntax.

License

MIT