Preface

Models in DeepSeek Harness can usually only read text directly. When non-text files such as PDF, Excel, or PPT need to be processed, scripts are often required to perform preprocessing first. markitdown is an excellent document-to-Markdown tool provided by Microsoft, but its traditional usage requires a Python environment. As a DeepSeek Harness plugin, dsh-markitdown allows the model to invoke MarkItDown directly in the DSH environment without assuming a specific Python environment or installation layout.

Plugin Introduction

dsh-markitdown is a wrapper that exposes Microsoft MarkItDown as a DeepSeek Harness tool. It converts documents in various formats, including PDF, Word, Excel, PowerPoint, HTML, CSV, EPUB, or URL, into Markdown readable by the model.

  • Owner: jiekesu967
  • Category: model inference
  • License: MIT

Core Features

The plugin supports converting the following formats to Markdown:

  • Documents: PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), HTML, EPUB
  • Data: CSV, TSV, XML
  • Code and notebooks: JSON, Jupyter (.ipynb)
  • Web: URL

When external tools are missing, the plugin falls back to built-in converters. In addition, it supports recognizing images, audio, and YouTube content via OCR.

Installation and Activation

Before use, ensure the environment meets the following requirements:

  • DeepSeek Harness: 0.1.5-rc.1 or later (both 0.1.x and 0.2.x are supported)
  • Node.js: ^22.19.0 or >=24.0.0

Installation Steps

  1. Run the following command to install the plugin:
    dsh plugin --profile web add github:jiekesu967/dsh-markitdown
  1. After installation, restart dsh web; the tool will take effect in the next session.
  2. To use PDF, OCR, or full Office conversion features, it is recommended to install MarkItDown locally:
    pip install "markitdown[all]"
    # 或安装 uv 后使用 uvx
    winget install astral-sh.uv

Typical Usage

In the Harness workflow, the model can directly invoke the markitdown tool.

Convert a local file to Markdown:

markitdown({ input: "reports/q3.pdf" })

Convert and save to a specified path:

markitdown({ input: "data/forecast.xlsx", output: "notes/forecast.md" })

Convert web page content:

markitdown({ input: "https://example.com/spec.html" })

Configuration

All configuration items are optional. The default values are as follows:

- id: markitdown
  name: dsh-markitdown
  config:
    engine: auto              # 自动检测可用引擎
    uvxPackage: "markitdown[all]"   # 指定 uvx 安装时的包名
    command: ""               # 显式指定可执行文件
    timeoutMs: 120000         # 单次转换超时时间
    maxChars: 120000          # 内联结果的最大字符数
    maxBytes: 67108864        # 内置引擎读取文件的最大字节数
    allowUrls: true           # 是否接受 URL 输入
    extraArgs: []             # 传递给外部引擎的额外参数

Engine detection order (when engine: auto):

  1. markitdown CLI (requires pip install "markitdown[all]")
  2. uvx markitdown (no package installation required, but uv must be installed)
  3. python -m markitdown (requires Python 3.10+ to be installed)
  4. Built-in converters (no extra dependencies, but with limited functionality)

Usage Notes

  • Path resolution: Relative paths (e.g., input: "reports/q3.pdf") are resolved relative to the session workspace, not the current working directory of the process.
  • File writing: When writing files via the output parameter, the operation goes through the filesystem interface and is subject to sandbox policies and read/write rules.
  • Input validation: If the input file is missing, the plugin reports an error before starting the subprocess, rather than failing during execution.
  • Output truncation: If the Markdown result exceeds maxChars and no output path is specified, the result is truncated and a clear truncation notice is provided.
  • Security limits:
    • Local files exceeding maxBytes are rejected for reading.
    • URL responses are subject to content length limits; if the limit is exceeded, they are not downloaded.
    • Archive extraction is limited by the size of each entry (default 256MiB).
    • Excel column references beyond XFD are discarded.
  • Permissions: MarkItDown performs I/O operations under the current process permissions. Handle untrusted input sources with care.

Summary

dsh-markitdown addresses the pain point that DeepSeek Harness models cannot directly process non-text documents. It provides cross-environment compatibility through automatic detection and fallback mechanisms. For scenarios requiring extraction of structured data from documents, this plugin is a direct and efficient tool.