Preface

When integrating an external PDF service into DeepSeek Harness (DSH), the common issues aren’t just “can it be called,” but where the API key is stored, whether the balance can be viewed, and how to check task status. komoai2026/dsh-kolmopdf is a KolmoPDF tool plugin for DSH that brings PDF parsing, translation, conversion, cost estimation, balance checking, and task status querying into DSH’s tool layer, offering three ways to configure the API key: GUI, CLI, and environment variables.

What This Is

komoai2026/dsh-kolmopdf is maintained by komoai2026 and licensed under MIT. It targets environments compatible with DeepSeek Harness 0.1.1-rc.2, requires Node.js >= 20, and needs a KolmoPDF Plus or Pro account. The API key must be obtained from https://www.kolmopdf.com/api-keys.

It primarily addresses the tool entry point and configuration issues for DSH users invoking KolmoPDF: calling PDF tools, saving API keys, checking balance, and viewing task status.

Core Features

It provides the following tools:

  • kolmopdf_parse_pdf: PDF → Markdown, with optional translation, formulas, tables, images, and enrichment sidecars.
  • kolmopdf_translate_pdf: Layout-preserving PDF translation, supporting translated-only or side-by-side formats.
  • kolmopdf_convert_markdown: Markdown/ZIP → DOCX, HTML, PDF, LaTeX.
  • kolmopdf_estimate_cost: Local page count + balance estimation, without consuming credits.
  • kolmopdf_check_balance: Check current credit balance.
  • kolmopdf_get_task_status: Check task status by ID.

It also offers the following for configuration and status viewing:

  • GUI Settings → KolmoPDF page to save the API key, displaying live credits and a task overview.
  • CLI config set-key/status/clear-key/path.
  • Environment variable KOLMOPDF_API_KEY.

Installation and Enablement

First, confirm the environment meets the requirements:

  • Node.js >= 20
  • DeepSeek Harness 0.1.1-rc.2 compatible
  • KolmoPDF Plus or Pro account
  • API key obtained from https://www.kolmopdf.com/api-keys

Then install it in the target DSH profile. The example uses the web profile:

dsh plugin --profile web add github:komoai2026/dsh-kolmopdf

After installation, start the Web profile:

dsh web

Note that the host packages are optional peer dependencies and must resolve to the currently running Harness instance. Bundling a second copy may cause tool invocation failures.

Configuring the API Key

There are three ways. Choose one.

GUI Configuration

  1. Open the DeepSeek Harness Web GUI.
  2. Navigate to Settings → KolmoPDF.
  3. Enter the API key and save.

The GUI writes the key to the DSH credential store with the reference name KOLMOPDF_API_KEY.

CLI Configuration

The CLI runs through the DSH profile:

dsh plugin --profile web exec kolmopdf -- config set-key

This command writes kolmopdf.apiKey to $DSH_HOME/settings.yaml.

Other common commands:

dsh plugin --profile web exec kolmopdf -- config status
dsh plugin --profile web exec kolmopdf -- config clear-key
dsh plugin --profile web exec kolmopdf -- config path

The CLI uses DSH’s atomic write lock and sets owner-only permissions 0600.

Environment Variable

You can also set it before starting DSH:

export KOLMOPDF_API_KEY=sk-xxxxxxxxxxxxxxxx

The KOLMOPDF_API_KEY environment variable is accepted. If an env key exists, it overrides the GUI credential and makes the settings page read-only.

Resolution Order and Missing Key Behavior

The resolution order is:

CLI settings.apiKey → credential / environment (KOLMOPDF_API_KEY)

A missing API key does not prevent the plugin from starting. The first authenticated tool call will return an actionable prompt, guiding you to open settings or run the CLI.

Task History

Task history is stored in:

$DSH_HOME/kolmopdf/tasks.json

A maximum of the newest 200 entries is retained. The GUI’s KolmoPDF settings page displays a task overview, and you can also call kolmopdf_get_task_status to check task status by ID.

Use Cases and Considerations

It is suitable for scenarios where KolmoPDF needs to be invoked from within DSH: parsing PDFs to Markdown, layout-preserving translation, converting Markdown/ZIP to DOCX/HTML/PDF/LaTeX, estimating invocation costs, checking credit balances, and querying task status.

Before using it, note:

  • The plugin runs with the current dsh process permissions; inspect the source code and license before installation.
  • A KolmoPDF Plus or Pro account is required, and the API key comes from KolmoPDF’s api-keys page.
  • The env key overrides the GUI credential and makes the settings page read-only.
  • The CLI writes kolmopdf.apiKey to $DSH_HOME/settings.yaml; pay attention to that file’s permissions and storage location.
  • The host packages must resolve to the running Harness instance; a second copy may cause tool invocation failures.

Conclusion

dsh-kolmopdf integrates KolmoPDF’s PDF processing tools into DSH and consolidates API key configuration, balance checking, and task status querying within the same plugin settings. Repository address: https://github.com/komoai2026/dsh-kolmopdf.