前言¶

在 DeepSeek Harness（DSH）里接入外部 PDF 服务时，常见问题不只是“能不能调”，而是 API key 放在哪里、余额能不能看、任务状态怎么查。komoai2026/dsh-kolmopdf 是一个面向 DSH 的 KolmoPDF 工具插件，把 PDF 解析、翻译、转换、成本估算、余额查询和任务状态查询放到 DSH 的工具层，并提供 GUI、CLI 和环境变量三种 API key 配置方式。

这是什么¶

komoai2026/dsh-kolmopdf 由 komoai2026 维护，采用 MIT 许可。它面向与 DeepSeek Harness 0.1.1-rc.2 compatible 的环境，要求 Node.js >= 20，并需要 KolmoPDF Plus 或 Pro 账号。API key 需要从 https://www.kolmopdf.com/api-keys 获取。

它主要解决 DSH 用户调用 KolmoPDF 时的工具入口和配置问题：调用 PDF 工具、保存 API key、查看余额、查看任务状态。

核心功能¶

它提供以下工具：

• kolmopdf_parse_pdf：PDF → Markdown，可选翻译、公式、表格、图片、enrichment sidecars。
• kolmopdf_translate_pdf：保留版式的 PDF 翻译，支持 translated-only 或 side-by-side。
• kolmopdf_convert_markdown：Markdown/ZIP → DOCX、HTML、PDF、LaTeX。
• kolmopdf_estimate_cost：本地页数 + balance 估算，不消耗额度。
• kolmopdf_check_balance：查看当前 credit 余额。
• kolmopdf_get_task_status：按 id 检查任务状态。

配置和状态查看方面还提供：

• GUI Settings → KolmoPDF 页面保存 API key，并显示 live credits 与 task overview。
• CLI config set-key/status/clear-key/path。
• 环境变量 KOLMOPDF_API_KEY。

安装与启用¶

先确认环境满足要求：

• Node.js >= 20
• DeepSeek Harness 0.1.1-rc.2 compatible
• KolmoPDF Plus 或 Pro 账号
• 已从 https://www.kolmopdf.com/api-keys 获取 API key

然后在目标 DSH profile 中安装。示例使用 web profile：

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

安装后启动 Web profile：

dsh web

注意宿主包是 optional peer dependencies，它们必须解析到当前运行的 Harness 副本。如果携带第二份副本，可能导致工具调用失败。

配置 API key¶

有三种方式。选择其中一种即可。

GUI 配置¶

1、打开 DeepSeek Harness Web GUI。
2、进入 Settings → KolmoPDF。
3、输入 API key 并保存。

GUI 会把 key 写入 DSH credential store，引用名为 KOLMOPDF_API_KEY。

CLI 配置¶

CLI 通过 DSH profile 执行：

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

这条命令会把 kolmopdf.apiKey 写入 $DSH_HOME/settings.yaml。

其他常用命令：

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

CLI 写入时使用 DSH 原子写锁，并设置 owner-only permissions 0600。

环境变量¶

也可以在启动 DSH 前设置：

export KOLMOPDF_API_KEY=sk-xxxxxxxxxxxxxxxx

环境变量 KOLMOPDF_API_KEY 会被接受。如果存在 env key，它会覆盖 GUI credential，并让设置页只读。

解析顺序与缺 key 行为¶

解析顺序为：

CLI settings.apiKey → credential / environment (KOLMOPDF_API_KEY)

缺少 API key 不会阻止插件启动。首次需要认证的工具调用会返回可操作提示，引导你打开设置或执行 CLI。

任务历史¶

任务历史保存在：

$DSH_HOME/kolmopdf/tasks.json

最多保留 newest 200 条。GUI 的 KolmoPDF 设置页会显示 task overview，也可以调用 kolmopdf_get_task_status 按 id 检查任务状态。

适用场景与注意¶

适合需要在 DSH 里调用 KolmoPDF 的场景：PDF 解析成 Markdown、保留版式翻译、把 Markdown/ZIP 转成 DOCX/HTML/PDF/LaTeX、估算调用成本、查看 credit 余额、查询任务状态。

使用前注意：

• 插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。
• 需要 KolmoPDF Plus 或 Pro 账号，API key 来自 KolmoPDF 的 api-keys 页面。
• env key 会覆盖 GUI credential，并让设置页只读。
• CLI 会把 kolmopdf.apiKey 写入 $DSH_HOME/settings.yaml，注意该文件的权限和存放位置。
• 宿主包必须解析到运行中的 Harness 副本；第二份副本可能导致工具调用失败。

结尾¶

dsh-kolmopdf 把 KolmoPDF 的 PDF 处理工具接进 DSH，并把 API key 配置、余额查看和任务状态查询放到同一套插件配置里。仓库地址：https://github.com/komoai2026/dsh-kolmopdf。