@kolmopdf/dsh-kolmopdf
为 DeepSeek Harness 提供 KolmoPDF 工具，并支持持久化 API 密钥设置和 CLI 配置。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:komoai2026/dsh-kolmopdf#9e31617e949cc03a4bec61cfaf005183b8ac8437Kolmopdf 以 @kolmopdf/dsh-kolmopdf 发布，当前版本为 1.0.4。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
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
| 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 |
KOLMOPDF_API_KEY). The value never rides settings describe responses.$DSH_HOME/kolmopdf/tasks.json (newest 200).KOLMOPDF_API_KEY in the process environment is also accepted. An env key shadows the GUI credential and makes the settings page read-only.0.1.1-rc.2 compatible (0.1.1-rc.2 client-modules format: dsh.client manifest + exports["./client"] lazy-CJS bundle)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'
One Release & Publish workflow (.github/workflows/release.yml) handles the pipeline end to end:
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.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.- in the version) publish under the next dist-tag, stable versions under latest.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.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 ... addinstalls the dependency and, because this package declaresdsh.bundle, joins the profile layer stack. A plainpnpm addwithoutdsh plugindoes not.
In the DeepSeek Harness Web GUI:
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.
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.
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).
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 |
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
status command only prints configured / not configured.outputDir. Enable this plugin only in a trusted composition.realpath so output_subdir and symlinks cannot escape outputDir.../ entries. Caps: 10,000 entries, 4 GiB uncompressed, 2 GiB download.MIT