dsh-converter

English | 中文

A file conversion plugin for DSH (DeepSeek Harness). It provides a conversion engine that covers 20 tool chains / 1000+ format pairs (images / audio-video / documents / e-books / 3D / spreadsheets ...) and runs entirely through external CLIs (ffmpeg, pandoc, libreoffice, imagemagick, vips, calibre, ...) or pure JS (vcf), exposed to the model as tools.

DSH framework docs: https://deepseek-harness.github.io/deepseek-harness/develop/basic/

1. Tools

Tool	Purpose
convert_file	Convert a local file: { inputPath, to, from?, outputPath?, converter? }. Output defaults to the input directory (same name, new extension). Unsupported pairs return the list of available targets; missing converter returns the install command
list_conversions	Query the format matrix: pass from to get that format's convertible targets (grouped by converter); omit it for a full category overview
check_converters	Detect which converter CLIs are available on this machine (with version numbers)

2. Installation

From npm / GitHub

dsh plugin --profile web add dsh-converter                        # install from npm
dsh plugin --profile web add github:ai-tool-labs/dsh-converter    # or from GitHub
# Desktop: open the "Plugins" panel in the sidebar → click "Add Plugin" → type "dsh-converter" → Install
# Restart harness after installing to take effect (Desktop: restart the App; Web: restart dsh web)

From source (developer)

# 1) Build
pnpm install && pnpm --filter dsh-converter build

# 2) Install into a profile (example: web profile)
dsh plugin --profile web add /path/to/dsh-plugins/packages/dsh-converter

Enable in the profile

Append the following to <profile>/cordis.patch.yml (the shipped cordis.patch.yml shows all options, commented out):

- insert:
    - id: file-converter
      name: dsh-converter
      config:
        enableTools: true
        enableSkill: true
        maxFileSizeMb: 500      # per-file size limit (default 500MB, matches the Web version)
        timeoutMs: 300000       # external CLI timeout (default 5 minutes)

3. Converter dependencies

check_converters tells you which converters are missing; install commands per platform:

Converter	Purpose	macOS	Ubuntu	Windows
ffmpeg	Audio / video / GIF	brew install ffmpeg	apt install ffmpeg	choco install ffmpeg
pandoc	Universal doc conversion	brew install pandoc	apt install pandoc	choco install pandoc
libreoffice	Office / PDF	brew install --cask libreoffice	apt install libreoffice	choco install libreoffice
imagemagick	Images	brew install imagemagick	apt install imagemagick	choco install imagemagick
vips	Images (high-perf)	brew install vips	apt install libvips-tools	choco install vips
calibre	E-books	brew install --cask calibre	apt install calibre	choco install calibre
inkscape	Vector graphics	brew install --cask inkscape	apt install inkscape	choco install inkscape
xelatex	LaTeX → PDF	brew install --cask mactex	apt install texlive-xetex	install MiKTeX
vcf	Contacts vcf → csv	✅ pure JS, no install	✅	✅

See src/engine/installCommands.ts for the full list (all 20 tool chains, per-platform commands).

4. Architecture

src/index.ts          —— entry: Config / inject / apply
src/tools.ts          —— convert_file / list_conversions / check_converters
src/skills.ts         —— file-conversion skill (teaches the model how to use it)
src/engine/           —— ported conversion engine (logic identical to the original project)
  ├── registry.ts           —— format-matrix pure data + query functions (no Node deps)
  ├── fileTypeCategories.ts —— extension → category (pure data)
  ├── normalizeFiletype.ts  —— format alias normalization (jfif→jpeg, md→markdown, ...)
  ├── main.ts               —— mainConverter: auto-select converter + path/Buffer I/O
  └── <converter>.ts        —— 20 converters (ffmpeg/pandoc/vips/vcf/...)

Key differences from the Web version

1. File I/O: input and output are local paths (the Web version uses HTTP upload + OSS storage);
2. Timeout & cancellation: injected through the engine's execFileOverride extension point — external CLI timeouts (timeoutMs config) auto-kill, and cancellation of the tool call (exec.signal) terminates the child process immediately without leaving zombies;
3. Self-healing errors: unsupported pairs return availableTargets, missing converters return install commands — the model can self-correct instead of failing repeatedly;
4. Diagnosable: check_converters exposes CLI availability to the model.

Engine notes

• The engine is written in TypeScript with zero third-party dependencies (Node built-ins only):
  • imports use relative paths;
  • main.ts is the main converter and exposes an execFileOverride extension point (used for timeout / cancellation);
  • detectOS() is implemented for a Node environment (rather than browser UA detection).
• Because the engine has no runtime dependencies, it is self-contained and easy to maintain.

5. Development

pnpm --filter dsh-converter typecheck   # type check
pnpm --filter dsh-converter build       # tsc → build/
pnpm --filter dsh-converter smoke       # smoke test:
                                                   #   vcf→csv (pure JS) real conversion,
                                                   #   unsupported-format error hints,
                                                   #   format-matrix query, unload cleanup