DeepSeek Harness (DSH) focuses on extending functionality through plugins. In model inference scenarios, having the model read local documents directly is a common requirement. This usually requires relying on external APIs or shell commands. The @jiaoqsh/dsh-document plugin adds a read_document tool to DSH for the model, converting local documents into Markdown for the model to parse.

Core Features

The plugin provides file reading capabilities through the read_document tool, supporting multiple format conversions and local processing.

  • Format Support: Supports Word (.doc, .docm, .docx), PowerPoint (.ppt, .pps, .pot, .pptx, .pptm, .ppsx, .ppsm), Excel (.xls, .xlsx, .xlsm, .xlsb), OpenDocument (.odt, .ods, .odp), RTF, EPUB, CSV, and PDF.
  • Local Conversion: The conversion process runs entirely locally, using @firecrawl/anydoc for Office formats and @firecrawl/pdf-inspector (WASM) for PDFs. No API keys or network connection are required.
  • Pagination and Metadata: Provides offset and limit pagination parameters. For PDFs, supports page selection (e.g., “1-3,7”) and returns metadata (total page count, document type, pages requiring OCR).
  • Filesystem Integration: File reading is performed through DSH’s ctx.fs seam, compatible with any mounted filesystem provider and sandbox policy.

Installation and Enablement

Installing the plugin requires specifying an existing profile (for example, web, headless, or a custom profile).

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

After installation, you can verify that the plugin loaded successfully with the following command:

dsh --profile web --dump-config

To remove the plugin:

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

Configuration

The plugin is configured via cordis.patch.yml. The default configuration inserts a document-tools layer. Parameters can be adjusted through configuration overrides.

Configuration Item Default Value Description
maxInputBytes 52428800 (50 MiB) The maximum input file size (in bytes). Checked by the filesystem provider before any bytes are buffered; files exceeding this limit are rejected.
readLimit 2000 The default and maximum number of Markdown lines returned in a single call.
maxLineLength 2000 The maximum number of characters in returned line text. Any excess is truncated.
maxOutputBytes 51200 (50 KiB) The maximum byte size of returned line text in a single call.
pdfMaxPages 100 The maximum number of distinct pages that can be specified in a single pages selection.
pdfProfile fidelity PDF Markdown profile: fidelity preserves source structure, while compact generates fewer tokens.

Usage Example

The interface for the model to call the read_document tool is as follows:

read_document(file_path: string, offset?: number, limit?: number, pages?: string)
  • file_path: Resolved by the filesystem backend. Relative paths are resolved relative to the calling session’s workspace.
  • offset: The starting line number of the returned Markdown (defaults to 1).
  • limit: The number of lines to return (default and maximum is readLimit).
  • pages: PDF only. 1-based page numbers or ranges, such as "1-3,7" (up to pdfMaxPages pages). Defaults to all pages.

Return Format

The format returned by the tool includes the document path, format, content, and PDF-specific metadata.

<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>

Error Handling

The tool treats errors as tool errors in the model’s terminology. Common errors include:
* Unsupported file extension.
* Using the pages parameter on a non-PDF file.
* The file is not found, is not a regular file, exceeds maxInputBytes, is encrypted, is corrupted, or its content cannot be extracted (such as scanned PDFs).

Limitations and Notes

  • No OCR Support: The plugin does not perform OCR. If a PDF lacks a text layer, it returns a warning but does not read the content. Fully scanned or image-only PDFs result in an error.
  • Performance: PDF conversion runs in a separate worker thread for each call, with approximately 50ms of startup overhead. Office format conversion runs in the libuv thread pool and cannot be canceled once started.
  • Layout Issues: Layout-intensive PDFs may merge paragraphs into long lines, which are then truncated by maxLineLength.
  • Tech Stack: Uses pdf-inspector built with WASM rather than a native binary. Requires Node.js version >= 22.19.
  • Dependency Management: peerDependencies are not automatically installed with a profile; ensure the environment is properly configured.

Summary

The plugin provides DSH with local, secure, and network-free document reading capabilities. Through Markdown conversion and pagination, the model can efficiently process long documents. Developers can adjust configuration parameters according to actual needs to balance performance and the quality of returned content.