kolmopdf
English | 中文
KolmoPDF tools for DeepSeek Harness: high-fidelity PDF→Markdown parsing, layout-preserving PDF translation, Markdown conversion, credit estimates, and balance checks.
Repository: https://github.com/komoai2026/dsh-kolmopdf
Features
| Tool | Capability |
|---|
kolmopdf_parse_pdf | PDF → Markdown, optional translation, formulas, tables, images, enrichment sidecars |
kolmopdf_translate_pdf | Layout-preserving PDF translation (translated-only or side-by-side) |
kolmopdf_convert_markdown | Markdown/ZIP → DOCX, HTML, PDF, LaTeX |
kolmopdf_estimate_cost | Local page-count + balance estimate (does not spend credits) |
kolmopdf_check_balance | Current credit balance |
kolmopdf_get_task_status | Inspect a task by id |
- The GUI stores the API key through DSH credentials (
KOLMOPDF_API_KEY). The value never rides settings describe responses.
- Settings → KolmoPDF is a dedicated settings page (configured / missing, save, clear) with a live credits card and a task overview list — balance and task statuses refresh automatically (30 s / 10 s) and manually, with a clear-log action. Task history lives in
$DSH_HOME/kolmopdf/tasks.json (newest 200).
- Tools check the key lazily. A missing key tells the user to open Settings or run the CLI.
KOLMOPDF_API_KEY in the process environment is also accepted. An env key shadows the GUI credential and makes the settings page read-only.- HTTP upload, poll, download, and ZIP extract honor the tool abort signal.
Requirements
- Node.js >= 20
- DeepSeek Harness
0.1.1-rc.2 compatible (0.1.1-rc.2 client-modules format: dsh.client manifest + exports["./client"] lazy-CJS bundle)
- KolmoPDF Plus or Pro account
- An API key from https://www.kolmopdf.com/api-keys
Install
Install the package into the DSH profile you use (example: web). GitHub is the recommended path:
# From GitHub (recommended; no npm publish required)
dsh plugin --profile web add github:komoai2026/dsh-kolmopdf
# Equivalent
dsh plugin --profile web add https://github.com/komoai2026/dsh-kolmopdf.git
This is a git dependency that ships prebuilt lib/ (no prepare script, so dsh plugin add does not hit pnpm allowBuilds). The package also declares dsh.bundle, so dsh plugin add appends @kolmopdf/dsh-kolmopdf to the profile's dsh.profile.bundles and the plugin mounts on the next start — settings page and tools appear without a hand-written composition row.
Host packages such as @deepseek-ai/dsh-tools are optional peer dependencies (same pattern as dsh-ads): they must resolve to the running Harness copy, and pnpm treats them as optional so a profile install does not warn about them. Shipping a second copy inside this plugin makes every tool call fail with Cannot read properties of undefined (reading 'prepare').
Other install sources:
# From the npm registry
dsh plugin --profile web add @kolmopdf/dsh-kolmopdf
# Local checkout
dsh plugin --profile web add D:/code/dsh-kolmopdf
dsh plugin add already activates the bundle layer. Only add a host-plane row yourself if you installed the package some other way:
- insert:
- id: kolmopdf
name: '@kolmopdf/dsh-kolmopdf'
Publishing
One Release & Publish workflow (.github/workflows/release.yml) handles the pipeline end to end:
- Change
version in package.json and push to main — the workflow compares it with the latest v* tag, creates v<version> on the bump commit and pushes it, then publishes in the same run. The tag push uses the internal token, which does not re-trigger the push event, so the same run continues straight into publishing. A push that does not change the version is a green no-op.
- Manually pushing a matching tag works too:
git tag v1.0.0 && git push origin v1.0.0 releases exactly that tag. The tag must equal package.json version exactly, or the job fails.
- Prerelease versions (
- in the version) publish under the next dist-tag, stable versions under latest.
- Publishing uses pnpm (
pnpm publish) with npm trusted publishing (OpenID Connect): the workflow holds id-token: write, npm exchanges the GitHub Actions ID token for a short-lived token bound to this workflow file, and provenance attestations are generated automatically (--provenance). No NPM_TOKEN secret is used.
pnpm publish runs pnpm check first (each publish packs a freshly built lib/), then a GitHub Release is created with generated notes.- The
Rebuild lib workflow keeps the committed lib/ in sync with src/ on every push to main (git installs never run prepare scripts).
CI workflow typechecks, tests, and builds on every PR and push to main.
One-time setup: on npmjs.com open @kolmopdf/dsh-kolmopdf → Settings → Trusted publishing and authorize GitHub Actions (.github/workflows/release.yml) for this repository (public repo; publishing requires @kolmopdf scope access). The npm trust CLI can create the publisher too. With trusted publishing in place you can revoke the package's automation token — the workflow never sends one.
See examples/cordis.patch.yml and the package-root cordis.patch.yml.
Restart the profile:
dsh web
dsh plugin ... add installs the dependency and, because this package declares dsh.bundle, joins the profile layer stack. A plain pnpm add without dsh plugin does not.
Configure the API key
Option 1: Web Settings (recommended)
In the DeepSeek Harness Web GUI:
- Open Settings.
- Open the KolmoPDF section.
- Enter the API key and save.
The page writes the key into the DSH credential store ($DSH_HOME/.credentials.yaml, reference KOLMOPDF_API_KEY). It does not go through the settings-document allowlist. If KOLMOPDF_API_KEY is already in the process environment, the page is read-only (env wins and cannot be overwritten).
A missing key does not prevent the plugin from starting. The first authenticated tool call returns an actionable prompt.
Option 2: CLI
After install, run the CLI through DeepSeek Harness so it resolves from the profile (a bare kolmopdf is not on PATH):
dsh plugin --profile web exec kolmopdf -- config set-key
This reads the key with a masked prompt and writes kolmopdf.apiKey in $DSH_HOME/settings.yaml (default ~/.dsh/settings.yaml).
# Non-interactive (lands in shell history; not recommended)
dsh plugin --profile web exec kolmopdf -- config set-key sk-xxxxxxxxxxxxxxxx
# Scripts / CI: read from stdin
printf '%s' "$KOLMOPDF_API_KEY" | dsh plugin --profile web exec kolmopdf -- config set-key
# Status (never prints the key)
dsh plugin --profile web exec kolmopdf -- config status
# Settings file path
dsh plugin --profile web exec kolmopdf -- config path
# Clear the stored key
dsh plugin --profile web exec kolmopdf -- config clear-key
# Custom settings file
dsh plugin --profile web exec kolmopdf -- config set-key --file D:/path/to/settings.yaml
The CLI preserves YAML comments, uses the same <file>.lock writer lock and atomic replace as DSH (@deepseek-ai/dsh-atomic-write), and sets owner-only permissions (0600; Windows still uses ACLs). A running DSH with file watch enabled hot-reloads the change.
Option 3: Environment variable
export KOLMOPDF_API_KEY=sk-xxxxxxxxxxxxxxxx
PowerShell:
$env:KOLMOPDF_API_KEY = 'sk-xxxxxxxxxxxxxxxx'
dsh web
Set the variable before starting DSH. You can change the name with apiKeyEnv in the composition.
Resolution order: CLI settings.apiKey → credential / environment (KOLMOPDF_API_KEY).
Optional config
Composition config is the base layer; the user settings document still overrides it:
- insert:
- id: kolmopdf
name: '@kolmopdf/dsh-kolmopdf'
config:
outputDir: ./kolmopdf-output
pollIntervalMs: 2000
maxPollMinutes: 30
httpTimeoutMs: 60000
uploadTimeoutMs: 600000
| Field | Default | Notes |
|---|
apiKey | unset | Secret. Prefer GUI credentials or CLI; do not commit this |
apiKeyEnv | KOLMOPDF_API_KEY | Environment / credential reference name |
baseUrl | https://www.kolmopdf.com | KolmoPDF API origin |
outputDir | ./kolmopdf-output | Result directory (relative to DSH cwd) |
pollIntervalMs | 2000 | Status poll interval |
maxPollMinutes | 30 | Maximum poll duration |
httpTimeoutMs | 60000 | Ordinary HTTP timeout |
uploadTimeoutMs | 600000 | Upload / download timeout |
Development
corepack enable pnpm
pnpm install
pnpm check
pnpm check runs TypeScript, Vitest, and the production build.
The optional host-composition test needs the installed Harness package directory:
DSH_ROOT=/path/to/node_modules/@deepseek-ai/dsh pnpm test:host
Security
- Do not put a real API key in the repo, README, screenshots, or issues.
- The Web credentials API reports only configured / writable state, never the secret.
- The CLI
status command only prints configured / not configured.
- Tools read local PDF/Markdown/ZIP paths from the model and write under
outputDir. Enable this plugin only in a trusted composition.
- Output directories are checked with
realpath so output_subdir and symlinks cannot escape outputDir.
- ZIP extraction rejects absolute paths and
../ entries. Caps: 10,000 entries, 4 GiB uncompressed, 2 GiB download.
- Inputs are capped at 300 MB and 800 pages (same as the KolmoPDF service) and validated locally before upload.
License
MIT
