前言¶

在 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。