Introduction

PDFs are unavoidable in agent development: papers, reports, contracts. Feeding them directly to the model easily loses information such as formulas, tables, and multi-column layouts. Translating a PDF also requires piecing together a pipeline for parsing, layout translation, and rewriting. The philosophy behind DeepSeek Harness (DSH) is “everything is a plugin,” so there’s no need to build these high-frequency capabilities yourself. Below is an introduction to dsh-zpdf, a community plugin that encapsulates PDF parsing, layout translation, format conversion, and point management into DSH tools.

What is it

Maintained by komoai2026, the npm package name is @kolmopdf/dsh-zpdf and it uses the MIT license. One-line positioning: ZPDF tools for DeepSeek Harness with durable API-key settings and CLI configuration—provides a set of ZPDF tools for DSH and solves the problem of persistent API key configuration.

It relies on the ZPDF service at the bottom, requiring a Plus or Pro account, with API keys obtained from https://www.zhiyipdf.com/api-keys.

Core Features

The plugin provides six tools:

  • zpdf_parse_pdf: PDF → Markdown, optional translation, supports formulas, tables, images, and enrichment sidecar files
  • zpdf_translate_pdf: Layout-preserving PDF translation, can output translation-only or bilingual parallel
  • zpdf_convert_markdown: Markdown/ZIP → DOCX, HTML, PDF, LaTeX
  • zpdf_estimate_cost: Local page count + balance estimation, does not consume points
  • zpdf_check_balance: Query current points balance
  • zpdf_get_task_status: Query task status by ID

In addition to tools, there is a Web settings page: Settings → ZPDF is a dedicated settings page that displays whether the key is configured or missing, supports saving and clearing, and includes a real-time points card and task overview list—balance and task status refresh automatically every 30 seconds/10 seconds respectively, and support manual refresh and clearing logs. Task history is saved in $DSH_HOME/zpdf/tasks.json, retaining the last 200 entries. HTTP upload, polling, download, and ZIP decompression all respect the tool’s abort signal; canceling a call does not leave behind residual requests.

Environment Requirements

  • Node.js >= 20
  • Compatible with DeepSeek Harness 0.1.1-rc.2 (dsh.client manifest + exports["./client"] lazy-CJS bundle)
  • ZPDF Plus or Pro account, and corresponding API key

Installation and Enablement

It is recommended to install into a common profile from GitHub (example uses web):

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

Equivalent syntax:

dsh plugin --profile web add https://github.com/komoai2026/dsh-zpdf.git

This package declares dsh.bundle. dsh plugin add automatically appends @kolmopdf/dsh-zpdf to the profile’s dsh.profile.bundles. Mounting is complete on the next startup, and the settings page and tools appear automatically; no need to manually write the combination line. Note: Pure pnpm add does not perform this step.

Restart the profile after installation:

dsh web

Other installation sources:

# From npm registry
dsh plugin --profile web add @kolmopdf/dsh-zpdf

# From local path
dsh plugin --profile web add D:/code/work-relate/dsh-zpdf

If installed via a method other than dsh plugin add, you need to manually add a line to the combination:

- insert:
    - id: zpdf
      name: '@kolmopdf/dsh-zpdf'

Additionally, the host package (e.g., @deepseek-ai/dsh-tools) is an optional peer dependency of this plugin. All peerDependenciesMeta are marked as optional, so pnpm will not report missing peers during installation. However, runtime requires them to resolve to the running instance of Harness; if a second copy is bundled inside the package, tool calls will fail directly.

Configuring API Key

There are three ways, with the GUI recommended.

Method 1: Web settings page. Open the DeepSeek Harness Web GUI, go to Settings → ZPDF, enter the API key and save. The page writes the key to the DSH credentials store ($DSH_HOME/.credentials.yaml, referencing ZPDF_API_KEY), does not go through the settings document allowlist, and the value will not appear in the settings describe response.

Method 2: CLI. After installation, execute the CLI via DSH (the bare zpdf is not on PATH):

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

This command prompts for input with masking and writes zpdf.apiKey to $DSH_HOME/settings.yaml (default ~/.dsh/settings.yaml). The write process preserves YAML comments, uses the same atomic replacement and <file>.lock write lock as DSH, and sets owner-only 0600 permissions (ACLs are used on Windows).

Other subcommands:

# Non-interactive input (will remain in shell history, not recommended)
dsh plugin --profile web exec zpdf -- config set-key sk-xxxxxxxxxxxxxxxx

# Script/CI: read from stdin
printf '%s' "$ZPDF_API_KEY" | dsh plugin --profile web exec zpdf -- config set-key

# Check status (does not print the key)
dsh plugin --profile web exec zpdf -- config status

# View settings file path
dsh plugin --profile web exec zpdf -- config path

# Clear key
dsh plugin --profile web exec zpdf -- config clear-key

# Specify custom settings file
dsh plugin --profile web exec zpdf -- config set-key --file D:/path/to/settings.yaml

Method 3: Environment variables. Must be set before starting DSH:

export ZPDF_API_KEY=sk-xxxxxxxxxxxxxxxx

PowerShell:

$env:ZPDF_API_KEY = 'sk-xxxxxxxxxxxxxxxx'
dsh web

The key resolution order is: CLI settings.apiKey → Credentials/Environment Variable (ZPDF_API_KEY). The ZPDF_API_KEY in the process environment takes precedence over GUI credentials and will make the settings page read-only; the apiKeyEnv in the available combination can change the variable name.

Missing the key will not prevent the plugin from starting. The first tool call requiring authentication will return an actionable prompt guiding you to open Settings or run the CLI.

Use Cases and Notes

Suitable for these scenarios:

  • Need to convert PDF to model-friendly Markdown while retaining formulas, tables, and images
  • Need to translate PDF without losing layout, or require bilingual parallel output
  • Need to batch export Markdown to DOCX, HTML, PDF, LaTeX
  • Want to estimate cost, check balance, or track task status by ID before calling

Notes before use:

  1. The plugin runs with the permissions of the current dsh process; check the source code and license before installing. This project is MIT licensed, and the source code is public on GitHub.
  2. The ZPDF_API_KEY in the environment variables overrides GUI credentials and makes the settings page read-only. If you encounter “Settings page cannot be edited,” check the environment variables first.
  3. Passing the key in a non-interactive way will remain in shell history; use stdin or environment variables in script scenarios.

Conclusion

dsh-zpdf packs high-frequency but trivial capabilities like PDF parsing, layout translation, and format conversion into the DSH plugin ecosystem. Combined with persistent key configuration and local task history, you can use it immediately after installation and restart. The community directory page (independent site, no official affiliation with DeepSeek or High-Flyer): https://www.skillhub.cn/plugins/komoai2026/dsh-zpdf; Source code repository: https://github.com/komoai2026/dsh-zpdf.