dsh-file-convert
Local-first file conversion for DeepSeek Harness.
Convert images, PDFs and data files directly inside your DSH agent sessions — no API keys, no uploads, no servers, no token cost for the conversion itself. Files never leave your machine.
Unofficial community plugin. Not affiliated with or endorsed by DeepSeek.
Stable baseline: v1.0.x supports DeepSeek Harness Desktop 0.2.1-rc.5, with exact DSH integration dependencies. Keep this host version to keep using the plugin; newer DSH releases do not require an update to this baseline. Compatibility with other hosts requires separate verification. Node.js ^22.19.0 || >=24.0.0 is required. See installation, upgrades and rollback.
Why
Agents constantly need file conversions: "turn this PDF into images", "give me that JSON as YAML", "convert all JPGs in this folder to WebP". Instead of shelling out or pasting data around, dsh-file-convert gives your agent eight purpose-built tools backed by battle-tested local libraries.
- ✅ Local execution — files never leave the machine
- ✅ No API key, no server, no conversion tokens
- ✅ Natural language friendly — the agent calls the tools, you just ask
- ✅ Batch conversions with a compact summary
- ✅ Honest failures — missing dependency, unsupported pair, existing output: every error says exactly why
- ✅ Images, PDF and data need zero external binaries — prebuilt npm packages only. Media needs one tool (ffmpeg), clearly reported when missing
Supported conversions
| Source | Targets |
|---|
| PNG, JPG, WEBP | PNG, JPG, WEBP (any-to-any) |
| SVG | PNG, JPG, WEBP |
| PDF | PNG, JPG, TXT |
| JSON | YAML, CSV |
| YAML | JSON, CSV |
| DOCX, PPTX, XLSX | PDF |
| PDF | PNG, JPG, TXT, DOCX (experimental); TXT supports OCR for scanned PDFs |
| MP4 | GIF, MP3 |
| MOV | MP4 |
| WAV | MP3 |
| CSV | JSON, YAML |
26 conversions. Images, PDF and data work out of the box via npm install. Optional tools unlock the rest, each clearly reported by list_conversions when missing:
- FFmpeg -> media rows. Install it system-wide (preferred for untrusted media), or ask the agent to run
install_media_dependencies — it downloads pinned current builds (FFmpeg 6.1.1, ~56 MB total, one time) into the plugin cache, sha256-verified, from the npmmirror binary CDN with the GitHub release as fallback.
- LibreOffice -> DOCX/PPTX/XLSX to PDF.
winget install TheDocumentFoundation.LibreOffice / brew install --cask libreoffice / apt install libreoffice.
- Ghostscript -> PDF compression in
optimize_file.
- Python + pdf2docx -> the experimental PDF to DOCX row (
pip install pdf2docx).
- Tesseract (optional) -> faster OCR for scanned PDFs; without it the bundled tesseract.js is used and its language data is fetched explicitly via
install_ocr_dependencies (winget install UB-Mannheim.TesseractOCR).
Install
Inside a DSH profile — three ways, easiest first:
# 1. from npm (once published)
dsh plugin --profile desktop add dsh-file-convert@1.0.0 --save-exact
# 2. straight from GitHub (a `prepare` build runs; allow it once)
dsh plugin --profile default add github:zzy-12345678/dsh-file-convert
Git installs may ask you to allow the build step in the profile's pnpm-workspace.yaml:
allowBuilds:
dsh-file-convert: true
First-install note: pnpm may also ask you to decide on a build script for tesseract.js (it only shows a donation notice — skipping is safe). Set it in the same file and re-run the install:
allowBuilds:
tesseract.js: false
From a local checkout (e.g. while hacking on it):
git clone https://github.com/zzy-12345678/dsh-file-convert
cd dsh-file-convert && npx --yes npm@11.6.2 ci && npm run build
dsh plugin --profile default add /absolute/path/to/dsh-file-convert
Then restart DSH (dsh web or your usual entry point). All eight tools appear automatically.
The eight tools
convert_file
Convert one file.
{ "input": "/tmp/report.pdf", "output_format": "png", "dpi": 200 }
Converted: /tmp/report.pdf (pdf) -> /tmp/report.png (png)
1.2 MB -> 431.0 KB in 1.4s
- Default output: next to the input file, same base name, new extension.
- Multi-page PDFs produce
<name>-<page>.<ext> for every page; pages: "1-3,5" selects pages (outputs keep their real page numbers, text joins only the selection).
- Scanned PDFs → TXT:
ocr: true (optionally ocr_lang, default chi_sim+eng) recognizes the rendered pages instead of the text layer. Engine priority: a local Tesseract CLI, then the bundled tesseract.js (whose language data is never downloaded implicitly — run install_ocr_dependencies first, about 10-30 MB per language).
- Existing outputs are refused unless
overwrite: true.
- Options:
output, overwrite, quality (1–100), dpi (PDF/SVG rasterization), pages, ocr, ocr_lang.
batch_convert
Convert every matching file in a directory (top level).
{ "input_dir": "/home/me/Pictures", "output_format": "webp" }
Batch convert in /home/me/Pictures -> WEBP
Converted: 18, skipped: 2, failed: 0
Output dir: /home/me/Pictures/output
input_format filters by source format; omit it to auto-detect every convertible file.output_dir defaults to <input_dir>/output.- Existing outputs are skipped (not overwritten) unless
overwrite: true.
inspect_file
Facts before action, detected from file content — not just the extension:
{ "input": "/tmp/scan.pdf" }
{ "kind": "pdf", "pages": 24, "encrypted": false, "likelyScanned": true, "bytes": 13000000 }
optimize_file
Shrink a file toward a target size instead of converting it:
{ "input": "video.mp4", "target_size_mb": 20 }
Optimized: video.mp4 (mp4) -> video-min.mp4
18.3 MB -> 19.7 MB (target 20 MB) in 41.2s
Applied: two-pass x264: video 512k + audio 128k over 185.0s
- MP4/MOV: two-pass x264, the video bitrate is computed from the target (audio 128k, dropping to 64k for tight targets); output is always MP4. Requires ffmpeg + ffprobe.
- JPG/WEBP: binary-searches the highest encoder quality that fits; PNG uses palette reduction. No external tools needed.
- PDF: Ghostscript quality presets (printer/ebook/screen), first preset that fits the target wins; requires Ghostscript.
- Targets below what the codec can physically reach are refused with the achievable minimum.
- GIF optimization is not supported yet.
install_media_dependencies
One-call media setup: downloads pinned FFmpeg 6.1.1 static builds (ffmpeg + ffprobe) into the plugin cache (~/.dsh-file-convert/bin), verifies the pinned sha256, and proves the binaries run before reporting success. Served from the npmmirror binary CDN with the GitHub release as a byte-identical fallback. System installs keep priority over the cache. Ask the user for consent first — it is a sizable download.
install_ocr_dependencies
Downloads the tesseract.js language data (about 10-30 MB per language, chi_sim+eng by default) into the plugin cache, so ocr: true works without a local Tesseract. Skips when a local Tesseract CLI is installed or the data is already cached. Ask the user for consent first — conversions never download language data implicitly.
list_conversions
All 26 conversions with their live availability on this machine — unavailable rows name the missing tool and how to install it. Images, PDF and data rows are usable out of the box; media, office and PDF-compression rows depend on the optional tools (media can even be set up by the agent via install_media_dependencies).
open_ui
Open the local drag-and-drop web UI from inside a DSH session. The first call starts the server inside the plugin process and opens the browser; later calls return the running URL without starting anything twice. In DSH Desktop the converter is also always available as a native "文件转换" tab in the conversation view — open_ui is only needed when you want it in a separate browser window.
{}
dsh-file-convert UI is running at http://127.0.0.1:5757/ (opened in your browser; ...)
Local web UI (drag & drop)
The engine ships with a zero-dependency web app: drag files into the browser, pick a target format, download the result. Everything runs on your machine. It is available two ways:
- Native in DSH Desktop (default): the plugin mounts the app at
/dsh-file-convert on the DSH web server and injects a client bundle that adds a "文件转换" tab to the conversation view — click the tab and the converter appears in place, no extra server. The iframe talks to the same origin, and the DSH host's own gate protects it.
- Standalone (
npm run ui, or ask the agent to call open_ui): its own server on http://127.0.0.1:5757 (walks up to the next free port if taken), gated by a random per-session token. Useful outside DSH or when you want the converter in a normal browser window.
Feature parity in both modes:
- Drag & drop files (or click to browse); jobs queue one by one with upload progress, warnings and per-file download links. Multi-page PDFs produce one download per page.
- The target-format picker is driven by the live capability matrix (the same data as
list_conversions), so unavailable pairs are hidden and the real detected input format corrects a wrong guess after the first attempt.
- Closing the tab mid-conversion aborts the underlying work (the same true-cancellation semantics as the tools).
- Standalone security: binds to
127.0.0.1 only and refuses any other interface; every API call requires a random per-session token.
- Standalone flags:
--port (default 5757), --no-open, --timeout-min (default 30 per conversion), --max-upload-mb (default 2048).
Plugin config
| Key | Default | Meaning |
|---|
quality | 85 | Default JPEG/WebP quality (1–100) |
dpi | 150 | Default rasterization DPI for PDF inputs |
timeoutMs | 120000 | Cooperative timeout for one conversion |
maxInputMb | 2048 | Refuse inputs above this size (MB) |
maxPdfPages | 200 | Full-document PDF rasterization refuses more pages; use pages for larger documents |
maxOutputPixels | 16000000 | Clamp rasterized pixels per page (width × height) to this budget |
uiAutoStart | false | Start the web UI as soon as the plugin loads (otherwise the agent starts it on demand via open_ui) |
uiTimeoutMin | 30 | Per-conversion deadline inside the web UI (longer than timeoutMs because UI users convert long videos) |
batchMaxFiles | 500 | Max files examined per batch_convert run; beyond it the summary reports what was skipped instead of silently capping |
outputRoots | [] | When non-empty, explicit output paths must resolve inside one of these directories (recommended for shared deployments; the default next-to-input output is always exempt) |
ffmpegPath / ffprobePath | - | Explicit binary paths when ffmpeg is not on PATH (common on Windows) |
sofficePath / ghostscriptPath / pythonPath / tesseractPath | - | Explicit paths for the optional tools, overriding auto-detection |
Limit coverage: maxInputMb applies to convert, batch, inspect and optimize alike; maxPdfPages applies to PDF rasterization and text extraction (both implicit full-document runs and explicit pages selections); maxOutputPixels applies to PDF rasterization, OCR rendering and SVG rasterization.
What timeoutMs cancellation stops: external binaries are killed mid-run (ffmpeg, LibreOffice, Ghostscript, Tesseract CLI); an in-flight PDF page render is cancelled through pdf.js's render task; tesseract.js recognition is stopped by terminating its worker; pure-JS pipelines (sharp encoding, JSON/YAML/CSV parsing) are interrupted at every step boundary and never write output after an abort. One large synchronous step (a single sharp encode or JSON.parse) cannot be interrupted mid-flight — its result is discarded instead of written. Every final-path write is atomic (sibling temp file + rename), so an aborted conversion never leaves a half-written file behind.
Architecture
DSH
│
dsh-file-convert
┌──────────────┴──────────────┐
src/index.ts src/core/ ← the whole engine,
(thin DSH glue: (no DSH imports) testable standalone
name/inject/apply, │
Config schema, ConversionRouter
8 tool registrations) │
┌─────────────────┼─────────────────┐
↓ ↓ ↓
ImageConverter PdfConverter DataConverter
sharp pdfjs-dist js-yaml
(libvips npm) @napi-rs/canvas csv-parse / stringify
MediaConverter OfficeConverter
ffmpeg (detected) LibreOffice (detected)
PdfToDocxConverter optimize_file/pdf
python + pdf2docx Ghostscript (detected)
- Declarative matrix: every conversion is a data row (
{ from, to }) on its converter. Routing, list_conversions and dependency checks are all derived from it.
- Detection: content first - binary magic (file-type), SVG sniffing, and JSON parsing (plus a YAML document-marker guess for extension-less files) - with the extension as fallback. Conflicts resolve in favor of the content, with a warning.
- Core is DSH-agnostic:
src/core never imports Cordis/DSH, so the engine can be unit-tested, wrapped in a CLI, or served over MCP later. If the DSH developer-preview API shifts, only the glue layer changes.
- Dependencies: external binaries (FFmpeg, LibreOffice, Poppler) are detected, never auto-installed —
list_conversions reports them and prints per-platform install hints. The interface is already in place (BinaryDependency).
Development
Use npm 11.6.2 for dependency resolution (also pinned in CI). With an older npm, run npx --yes npm@11.6.2 ci. Keep the committed lockfile; do not use --legacy-peer-deps to generate a different dependency graph.
npm ci # npm 11.6.2; installs the locked dependency graph
npm run build # tsc -> lib/
npm test # release-metadata checks + Vitest (optional tools gate some suites)
npm run smoke # end-to-end against lib/
npm run check:release
On Windows, scripts\prepare-release.cmd installs, validates, tests and packs the current version. It stops at the first failure and does not push tags or publish. The release workflow checks that v<version> matches both manifests before publishing through OIDC.
To recover a partially completed release, run the Release workflow manually on main with the existing tag (for example v0.5.2). It checks out that tag, reruns validation, skips npm publishing only when the published package belongs to the exact tagged commit, and creates the GitHub release only if it is missing. Temporary API failures are retried.
Local development pulls the dsh-tools peer closure into devDependencies so typecheck and vitest can load the 0.2.1 tool registry. End users of the published plugin do not install these — the host profile provides them.
Add a conversion = add one capability row + implement it in a converter. Add a backend = implement the Converter interface and register it in createRouter().
Fidelity & safety expectations
- Lossy by nature: PDF→DOCX (experimental), OCR and office→PDF are reconstructions — expect layout and recognition differences.
inspect_file's likelyScanned flag tells you when OCR is the right tool, and results carry warnings.
- Cached ffmpeg builds: the download convenience installs pinned sha256-verified FFmpeg 6.1.1 static builds. For untrusted media, a current system FFmpeg takes priority — prefer it in security-sensitive setups.
- Not a sandbox:
outputRoots resolves symlinks and resource limits (maxInputMb, maxPdfPages, maxOutputPixels, batchMaxFiles) cap runaway jobs, but the default next-to-input output is intentionally exempt from roots, and an agent that may write files can always write somewhere. For hostile multi-tenant use, add OS-level isolation on top.
Compatibility
| Component | Verified version |
|---|
| DeepSeek Harness Desktop | 0.2.1-rc.5 |
| @deepseek-ai/dsh-tools | 0.2.1-rc.5 |
| @deepseek-ai/cordis | 4.0.5 |
| @deepseek-ai/schemastery | 3.18.5 |
| Node.js | ^22.19.0 || >=24.0.0 (CI covers 22 and Windows 24) |
The 1.0.x line keeps this host baseline. Patches may fix defects without moving the supported DSH runtime. Supporting a different host is a separate release decision, not a reason to repin 1.0.x. The plugin retains defineTool argument validation and the host's compatibility checks. Stable refers to this plugin's support contract; the supported DSH release remains an official release candidate. See STABILITY.md for the operating limits and recovery steps.
Roadmap
V0.2 — Media (FFmpeg) shipped: MP4→GIF/MP3, WAV→MP3, MOV→MP4, plus optimize_file with target-size two-pass encoding.V0.3 — Office + PDF tooling shipped: DOCX/PPTX/XLSX→PDF via LibreOffice, experimental PDF→DOCX via python pdf2docx, PDF compression via Ghostscript; on-demand dependency downloads with an automatic CN mirror.V0.4 — OCR (Tesseract) shipped: PDF→TXT supports ocr: true (optional ocr_lang), local Tesseract CLI first with the bundled tesseract.js as fallback, language data fetched explicitly via install_ocr_dependencies.V0.5 — Local web UI shipped: drag & drop app with a live capability matrix, hosted natively in DSH Desktop as a "文件转换" conversation tab (webServer mount + client bundle) with a standalone open_ui fallback; Chinese-first user-facing text; true cancellation and atomic writes extended to every path.- Later: OCR → DOCX for scanned PDFs, conversion chains (PPTX→PDF→PNG), video downscaling in
optimize_file, resize/rotate image options.
License
MIT. dsh-file-convert distributes no external binaries; runtime libraries (sharp, pdfjs-dist, @napi-rs/canvas, js-yaml, csv) are installed from npm under their own licenses.
