kolmopdf

KolmoPDF Tool 插件，为 DeepSeek Harness 提供高保真 PDF→Markdown 解析、保留版式的 PDF 翻译、Markdown 文档转换、费用预估和余额查询。

仓库：<https://github.com/komoai2026/dsh-kolmopdf>

功能

Tool	功能
`kolmopdf_parse_pdf`	PDF → Markdown，可选同步翻译，支持公式、表格、图片与 enrichment sidecar
`kolmopdf_translate_pdf`	保留原版式翻译 PDF，可输出纯译文或双栏对照
`kolmopdf_convert_markdown`	Markdown/ZIP → DOCX、HTML、PDF、LaTeX
`kolmopdf_estimate_cost`	本地读取页数并结合账户余额估算 credits（不扣费）
`kolmopdf_check_balance`	查询当前 credits 余额
`kolmopdf_get_task_status`	按 task id 排查超时或卡住的任务

GUI 通过 DSH 凭据库保存 API Key（KOLMOPDF_API_KEY），不会出现在设置 describe 响应里。
Web GUI 的 Settings → KolmoPDF 是单独设置页，显示“已配置/未配置”并提供保存和清除，附带实时积分卡片与任务总览列表——积分与任务状态自动刷新（30 秒 / 10 秒），支持手动刷新与清除记录。任务历史保存在 $DSH_HOME/kolmopdf/tasks.json（最多 200 条）。
Tool 调用时才检查 Key；没有配置时会提示打开设置页或使用 CLI。
也支持进程环境变量 KOLMOPDF_API_KEY。环境变量优先，存在时设置页为只读。
上传、轮询、下载与 ZIP 解压都会响应 Tool 取消信号。

要求

Node.js >= 20
DeepSeek Harness 0.1.1-rc.2 兼容版本（0.1.1-rc.2 client-modules 格式：dsh.client 清单 + exports["./client"] 惰性 CJS bundle）
KolmoPDF Plus 或 Pro 账户
在 <https://www.kolmopdf.com/api-keys> 创建 API Key

安装

先把包安装到需要使用的 DSH profile（以 web 为例）。推荐直接从 GitHub 安装：

# 从 GitHub 仓库安装（推荐，无需等 npm 发布）
dsh plugin --profile web add github:komoai2026/dsh-kolmopdf

# 等价写法
dsh plugin --profile web add https://github.com/komoai2026/dsh-kolmopdf.git

这是普通的 Git 依赖：仓库里带编好的 lib/，没有 prepare，因此不会触发 pnpm allowBuilds。同时声明了 dsh.bundle，所以 dsh plugin add 会把 @kolmopdf/dsh-kolmopdf 写进该 profile 的 dsh.profile.bundles，下次启动就会挂载——设置页和 Tool 会自动出现，不必手写 composition 行。

@deepseek-ai/dsh-tools 等宿主包是 可选 peer 依赖（和 dsh-ads 一样），必须解析到当前 Harness 自带的那一份；pnpm 将其视为 optional，profile 安装时不会告警。如果插件再自带一份，任意 Tool 调用都会报 Cannot read properties of undefined (reading 'prepare')。

也可以从 npm 或本地目录安装：

# 从 npm registry 安装
dsh plugin --profile web add @kolmopdf/dsh-kolmopdf

# 在本仓库直接进行本地测试
dsh plugin --profile web add D:/code/dsh-zhiyipdf

dsh plugin add 已经会激活 bundle 层。只有用别的方式装包时，才需要自己在 profile 的 cordis.patch.yml 里加一行：

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

参见 [examples/cordis.patch.yml](examples/cordis.patch.yml) 和仓库根目录的 [cordis.patch.yml](cordis.patch.yml)。

发版

一个 Release & Publish workflow（.github/workflows/release.yml）全自动完成发版与发布：

修改 package.json 的 version 并推送 main——workflow 会与最新 v* tag 比对，在版本号变更提交上创建并推送 v<版本号> tag，然后在同一次运行中完成发布。tag 推送用的是工作流内部 token，不会重新触发 push 事件，所以本次运行直接继续发布。版本号未变化的推送为绿色空操作。
也可以手动推送与版本一致的 tag：git tag v1.0.0 && git push origin v1.0.0 直接触发发布——tag 必须与 package.json 版本完全一致，否则任务失败。
预发布版本（版本号含 -）发布到 next dist-tag，正式版本发布到 latest。
发布使用 pnpm（pnpm publish），并采用 npm Trusted Publishing（OpenID Connect）：workflow 声明 id-token: write，npm 用 GitHub Actions 的 ID token 换取绑定到该 workflow 文件的短期发布令牌，provenance 证明自动生成（--provenance）——无需 NPM_TOKEN secret。
pnpm publish 会先跑 pnpm check（发布时打包的是刚构建的 lib/），然后发布到 npmjs 并创建带自动生成说明的 GitHub Release。
Rebuild lib workflow 会在每次推送到 main 时把提交的 lib/ 与 src/ 保持同步（Git 安装方式不执行 prepare 脚本）。
CI workflow 在每次 PR 与 main 推送时执行类型检查、测试与构建。

一次性配置：在 npmjs.com 打开 @kolmopdf/dsh-kolmopdf → Settings → Trusted publishing，授权本仓库的 GitHub Actions（.github/workflows/release.yml）（公开仓库；发布需持有 @kolmopdf scope 权限）。也可以用 npm trust CLI 创建该 publisher。配置完成后可以吊销包的自动化 token——workflow 不会再发送任何 token。

重启 profile：

dsh web

> dsh plugin ... add 会安装依赖，并且因为本包声明了 dsh.bundle，会加入 profile 的 layer 栈。单独 pnpm add、不走 dsh plugin 则不会。

配置 API Key

方法一：Web 设置页（推荐）

打开 DeepSeek Harness Web GUI：

1. 点击左下角 Settings / 设置； 2. 进入独立的 KolmoPDF 设置项； 3. 输入 API Key 并保存。

设置页把 Key 写入 DSH 凭据库（$DSH_HOME/.credentials.yaml 的 KOLMOPDF_API_KEY 引用），不经过设置文档 allowlist。若进程环境里已经有 KOLMOPDF_API_KEY，设置页会显示为只读（环境变量优先，不能覆盖）。

如果尚未设置 Key，插件仍可启动；第一次需要鉴权的 Tool 调用会返回可操作提示。

方法二：CLI

安装包后，请通过 DeepSeek Harness 调用 CLI（直接打 kolmopdf 会提示找不到命令，因为它不在全局 PATH 上）：

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

命令会用遮罩输入读取 Key，并写入 $DSH_HOME/settings.yaml（默认 ~/.dsh/settings.yaml）中的 kolmopdf.apiKey。

# 非交互传参（会进入 shell history，不推荐）
dsh plugin --profile web exec kolmopdf -- config set-key sk-xxxxxxxxxxxxxxxx

# 脚本/CI：从 stdin 读取
printf '%s' "$KOLMOPDF_API_KEY" | dsh plugin --profile web exec kolmopdf -- config set-key

# 查看状态（不会输出 Key）
dsh plugin --profile web exec kolmopdf -- config status

# 查看实际设置文件路径
dsh plugin --profile web exec kolmopdf -- config path

# 清除已保存 Key
dsh plugin --profile web exec kolmopdf -- config clear-key

# 使用自定义 settings 文件
dsh plugin --profile web exec kolmopdf -- config set-key --file D:/path/to/settings.yaml

CLI 会尽量保留 YAML 注释；写入使用与 DSH 自身 settings 提供者相同的 <file>.lock 写锁与原子替换（@deepseek-ai/dsh-atomic-write），并把设置文件权限设为 owner-only（0600；Windows 上仍受 ACL 控制）。正在运行且启用了文件监听的 DSH 会热加载该修改。

方法三：环境变量

export KOLMOPDF_API_KEY=sk-xxxxxxxxxxxxxxxx

PowerShell：

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

环境变量需要在启动 DSH 前设置。可在 composition 中把 apiKeyEnv 改成其他变量名。

解析顺序：CLI 写入的 settings.apiKey → 凭据库 / 环境变量（KOLMOPDF_API_KEY）。

可选配置

可直接在 composition 的插件行提供 base 配置；用户 settings 层仍会覆盖它：

- insert:
    - id: kolmopdf
      name: '@kolmopdf/dsh-kolmopdf'
      config:
        outputDir: ./kolmopdf-output
        pollIntervalMs: 2000
        maxPollMinutes: 30
        httpTimeoutMs: 60000
        uploadTimeoutMs: 600000

字段	默认值	说明
`apiKey`	未设置	Secret；推荐由 GUI/CLI 写入，不要提交到 composition
`apiKeyEnv`	`KOLMOPDF_API_KEY`	环境变量 / 凭据引用名
`baseUrl`	`https://www.kolmopdf.com`	KolmoPDF 服务地址
`outputDir`	`./kolmopdf-output`	结果输出目录（相对 DSH 启动目录）
`pollIntervalMs`	`2000`	轮询任务状态间隔
`maxPollMinutes`	`30`	最长轮询分钟数
`httpTimeoutMs`	`60000`	普通 HTTP 请求超时
`uploadTimeoutMs`	`600000`	上传/下载超时

开发

corepack enable pnpm
pnpm install
pnpm check

pnpm check 依次运行 TypeScript 类型检查、Vitest 测试和生产构建。

安全说明

不要把真实 API Key 写入仓库、README、截图或 issue。
Web 凭据 API 只返回是否已配置 / 是否可写，不返回 secret 内容。
CLI 状态命令只显示 configured/not configured。
插件会读取 Tool 参数指定的本地 PDF/Markdown/ZIP，并把结果写入 outputDir；只在可信的 DSH composition 中启用它。
输出目录先按 realpath 校验：output_subdir 及其中的符号链接都不能逃出 outputDir。
ZIP 下载使用路径穿越检查，拒绝绝对路径和 ../ 条目；解压上限为 10,000 个条目与 4 GiB 总解压大小，单次结果下载上限 2 GiB。
输入文件上限 300 MB、最多 800 页（与 KolmoPDF 服务端限制一致），并在本地先校验后再上传；上传、轮询、下载与解压都会响应取消信号。

License

MIT

来源信息

安装

检查来源文件

kolmopdf

功能

要求

安装

发版

配置 API Key

方法一：Web 设置页（推荐）

方法二：CLI

方法三：环境变量

可选配置

开发

安全说明

License

更多相关插件

dsh-hooks-claude-code

dsh-hooks-codex

WeKnora#dsh-weknora