Foreword¶

When collaborating with agents in DSH (DeepSeek Harness), it’s often necessary to pass local files to the model: PDF reports, spreadsheets, screenshots, and code directories. Common approaches involve manually copying and pasting content or relying on external scripts to convert documents to text first. The former is impractical for large files and complex formats, while the latter requires maintaining a separate conversion pipeline.

dsh-file-upload is a DSH file-message plugin maintained by HongMing-Huang. It provides a web-based upload experience similar to Claude / Codex, converting documents to Markdown on demand for agents to read. This article introduces its positioning, capabilities, installation, and usage.

What Is This¶

dsh-file-upload is a file-message plugin for DeepSeek Harness, designed for web-based workflows. Maintained by HongMing-Huang, it is currently at npm version 0.5.2 under the MIT license, with approximately 14 stars on GitHub.

The core problem this plugin solves is creating a zero-configuration pipeline that connects “dragging a file into a conversation” with “the agent reading the document.” After uploading, an @relative/path reference appears in the message (similar to OpenAI Codex). The agent reads the document on demand via the read_document tool, converting it to Markdown at read time, rather than inserting the entire file content directly into the input field.

Upload and Attachment Display¶

The plugin adds a paperclip button to the composer toolbar and supports global drag-and-drop overlay (drop to attach), paste-to-attach, and multi-file uploads.

After uploading, small text files (default ≤8 KB) are inlined directly into the composer. Larger documents are displayed as attachment cards, with color-coded type indicators (red for PDF, blue for DOC, green for XLS, gray for TXT, purple for ZIP, gold for JSON), showing the filename and size, and can be individually removed.

Typing @ in the composer brings up a list of uploaded files. Selecting a file by relative path inserts a mention, consistent with the @ referencing习惯 in Codex.

Document to Markdown (Built-in MarkItDown)¶

Document reading does not rely on the user’s local Python installation or additional downloads. The plugin includes a TypeScript port of Microsoft MarkItDown (markitdown-node), covering 20+ formats: PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, RSS, Atom, ZIP, Jupyter notebooks; images use OCR by default (Tesseract, supporting 110+ languages); audio transcription requires model credentials. Parsing is performed locally with no network calls.

If the official MarkItDown CLI is installed locally or specified via configuration, the plugin prioritizes using the CLI (which may additionally support formats like EPUB); otherwise, it falls back to the built-in engine. Example startup log:

[dsh-file-upload] Document → Markdown ready: bundled MarkItDown engine (20+ formats, image OCR) — fully packaged, no downloads, no Python.

The optional configuration item markitdownBin points to the CLI path; if left empty, only the built-in engine is used.

Image Processing¶

When uploading, the plugin detects the current session’s model capabilities and follows three paths:

1. Multimodal models (declaring image input, such as GPT-4o, Qwen-VL, Claude, Gemini): Uses the official read_image tool, with images directly entering the model context.
2. Installed vision bridge (e.g., dsh-vision-proxy, with automatic detection of its routed image input declaration): Same as above.
3. Text-only models (DeepSeek official API is text-only): The plugin automatically generates image descriptions (“explain the image”) via the vision discovery chain, inserting them with the message to enable text-based models to reason based on the description.

The vision discovery chain’s default order: Explicitly configured visionEndpoint / visionModel → Local Ollama (http://localhost:11434, automatically selecting VL models like DeepSeek-VL2, keeping images local) → Using OpenAI-compatible endpoint keys from dsh credentials seam.

read_document Tool¶

Agents read uploaded files via read_document <path>. The converted Markdown supports pagination (offset / limit, up to 2000 lines per call) with line numbers; it includes an LRU parsing cache based on byte budget (invalidated on file changes), reads via ctx.fs, and inherits sandbox and fs-observation policies.

Typical usage:

1. Click the composer paperclip or drag files anywhere into the window.
2. Small text appears directly in the input field, documents are shown as attachment cards, and messages carry path references.
3. The agent executes read_document <path> to read Markdown content on demand with pagination.

Security and Storage¶

The upload route only accepts loopback connections; filenames are sanitized; files are stored in session-isolated directories .dsh-uploads/<sessionId>; content is deduplicated by sha256; concurrent uploads are limited (default 4); unreference uploads have a default TTL of 7 days, with periodic sweeps configurable.

Installation and Enabling¶

Install under the DSH Web profile:

dsh plugin --profile web add dsh-file-upload
# restart dsh web

Restart the dsh web process after installation. The plugin is designed to work out-of-the-box with zero configuration, requiring no separate Python installation or backend selection.

Configuration Options (Optional)¶

Default values cover common scenarios; adjustments are only needed when necessary. Key fields are:

Complete configuration table available in the GitHub README.

Use Cases and Notes¶

Suitable for workflows in DSH Web where local documents, spreadsheets, and screenshots frequently need to be passed to agents for analysis: code reviews with attached PDFs, data analysis with XLSX files, and understanding screenshot content with text-only models.

Before use, note that the plugin runs with the permissions of the current dsh process. Before installation, review the source code and MIT license to ensure upload and file access ranges meet your security requirements. Node engine requirement is >=22.6.0.

This plugin is listed in the SkillHub community directory (an independent site, not affiliated with DeepSeek / High-Flyer), categorized under workflows. Repository and documentation:

• Directory page: https://www.skillhub.cn/plugins/HongMing-Huang/dsh-file-upload
• GitHub: https://github.com/HongMing-Huang/dsh-file-upload