前言¶

做智能體開發繞不開 PDF：論文、報告、合同，直接丟給模型，公式、表格、多欄版式很容易丟信息；要翻譯一份 PDF 還得自己拼解析、排版、回寫的管線。DeepSeek Harness（DSH）的思路是「一切皆插件」，這類高頻能力不必自己造。下面介紹 dsh-zpdf，一個把 PDF 解析、版式翻譯、格式轉換和積分管理封裝成 DSH 工具的社區插件。

這是什麼¶

dsh-zpdf 由 komoai2026 維護，npm 包名爲 @kolmopdf/dsh-zpdf，採用 MIT 許可證。一句話定位：ZPDF tools for DeepSeek Harness with durable API-key settings and CLI configuration——爲 DSH 提供一組 ZPDF 工具，並解決 API key 的持久化配置問題。

底層依賴 ZPDF 服務，需要 Plus 或 Pro 賬戶，API key 從 https://www.zhiyipdf.com/api-keys 獲取。

核心功能¶

插件提供六個工具：

• zpdf_parse_pdf：PDF → Markdown，可選翻譯，支持公式、表格、圖片及 enrichment sidecar 文件
• zpdf_translate_pdf：保持版式的 PDF 翻譯，可輸出僅譯文或雙語對照
• zpdf_convert_markdown：Markdown/ZIP → DOCX、HTML、PDF、LaTeX
• zpdf_estimate_cost：本地頁數 + 餘額估算，不消耗積分
• zpdf_check_balance：查詢當前積分餘額
• zpdf_get_task_status：按 id 查詢任務狀態

除工具外，還有 Web 設置頁：Settings → ZPDF 是一個專屬設置頁，顯示密鑰已配置/缺失，支持保存與清除，帶即時積分卡片和任務總覽列表——餘額與任務狀態分別按 30 秒/10 秒自動刷新，也支持手動刷新與清空日誌。任務歷史保存在 $DSH_HOME/zpdf/tasks.json，保留最近 200 條。HTTP 上傳、輪詢、下載與 ZIP 解壓均遵循工具的 abort 信號，取消調用不會留下殘留請求。

環境要求¶

• Node.js >= 20
• 兼容 DeepSeek Harness 0.1.1-rc.2（dsh.client manifest + exports["./client"] lazy-CJS bundle）
• ZPDF Plus 或 Pro 賬戶，以及對應的 API key

安裝與啓用¶

推薦從 GitHub 安裝到常用 profile（示例用 web）：

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

等價寫法：

dsh plugin --profile web add https://github.com/komoai2026/dsh-zpdf.git

這個包聲明瞭 dsh.bundle，dsh plugin add 會自動把 @kolmopdf/dsh-zpdf 追加到 profile 的 dsh.profile.bundles，下次啓動即完成掛載，設置頁和工具會自動出現，不需要手寫組合行。注意：純 pnpm add 不會做這一步。

安裝後重啓 profile：

dsh web

其他安裝來源：

# 從 npm registry
dsh plugin --profile web add @kolmopdf/dsh-zpdf

# 從本地路徑
dsh plugin --profile web add D:/code/work-relate/dsh-zpdf

如果通過 dsh plugin add 之外的裝法安裝，需要手動在組合中補一行：

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

另外，主機包（如 @deepseek-ai/dsh-tools）是該插件的 optional peer 依賴，peerDependenciesMeta 全部標記爲 optional，安裝時 pnpm 不會報 missing peer；但運行時要求它們解析到正在運行的 Harness 副本，如果包內被塞進第二份拷貝，工具調用會直接失敗。

配置 API key¶

有三種方式，推薦 GUI。

方式一：Web 設置頁。打開 DeepSeek Harness Web GUI，進入 Settings → ZPDF，輸入 API key 並保存。頁面把 key 寫入 DSH credentials 存儲（$DSH_HOME/.credentials.yaml，引用 ZPDF_API_KEY），不經過設置文檔 allowlist，值不會出現在 settings describe 響應中。

方式二：CLI。安裝後通過 DSH 執行 CLI（裸的 zpdf 不在 PATH 上）：

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

這條命令以掩碼提示輸入，把 zpdf.apiKey 寫入 $DSH_HOME/settings.yaml（默認 ~/.dsh/settings.yaml）。寫入過程保留 YAML 註釋，使用與 DSH 相同的原子替換與 <file>.lock 寫鎖，並設置 owner-only 0600 權限（Windows 使用 ACL）。

其餘子命令：

# 非交互傳入（會留在 shell 歷史，不推薦）
dsh plugin --profile web exec zpdf -- config set-key sk-xxxxxxxxxxxxxxxx

# 腳本/CI：從 stdin 讀取
printf '%s' "$ZPDF_API_KEY" | dsh plugin --profile web exec zpdf -- config set-key

# 查看狀態（不打印密鑰）
dsh plugin --profile web exec zpdf -- config status

# 查看設置文件路徑
dsh plugin --profile web exec zpdf -- config path

# 清除密鑰
dsh plugin --profile web exec zpdf -- config clear-key

# 指定自定義設置文件
dsh plugin --profile web exec zpdf -- config set-key --file D:/path/to/settings.yaml

方式三：環境變量。需在啓動 DSH 前設置：

export ZPDF_API_KEY=sk-xxxxxxxxxxxxxxxx

PowerShell：

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

密鑰解析順序爲：CLI settings.apiKey → 憑據/環境變量（ZPDF_API_KEY）。進程環境中的 ZPDF_API_KEY 優先於 GUI 憑據，並會使設置頁變爲只讀；可用組合中的 apiKeyEnv 更改變量名。

缺 key 不會阻止插件啓動。首次需要鑑權的工具調用會返回可操作提示，引導打開 Settings 或運行 CLI。

適用場景與注意¶

適合這些場景：

• 需要把 PDF 轉成模型友好的 Markdown，同時保留公式、表格、圖片
• 要翻譯 PDF 又不想丟版式，或需要雙語對照輸出
• 需要把 Markdown 批量導出爲 DOCX、HTML、PDF、LaTeX
• 調用前想估算成本、查餘額、按 id 跟蹤任務狀態

使用前注意：

1. 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。本項目爲 MIT，源碼公開在 GitHub。
2. 環境變量裏的 ZPDF_API_KEY 會覆蓋 GUI 憑據並讓設置頁只讀，遇到「設置頁無法編輯」先查環境變量。
3. 非交互方式傳 key 會留在 shell 歷史，腳本場景改用 stdin 或環境變量。

結尾¶

dsh-zpdf 把 PDF 解析、版式翻譯、格式轉換這些高頻但瑣碎的能力裝進了 DSH 的插件體系，配合持久化的密鑰配置和本地任務歷史，裝完重啓就能用。社區目錄頁（獨立站點，與 DeepSeek、幻方無官方從屬關係）：https://www.skillhub.cn/plugins/komoai2026/dsh-zpdf；源碼倉庫：https://github.com/komoai2026/dsh-zpdf。