前言¶

在 DeepSeek Harness（DSH）裏做文檔類任務時，常見需求是把 PDF 轉成可編輯的 Markdown、在保留版式的前提下做翻譯，或把 Markdown 再導出成 DOCX、HTML 等格式。若只在對話裏粘貼全文，版式、公式、表格和圖片往往丟失；若自己對接第三方 API，還要處理上傳、輪詢、下載和密鑰存放。社區插件 @nguyenvanhoang1/dsh-zpdf 把 ZPDF（智譯 PDF） 的能力封裝成 DSH 工具，並與 Harness 的憑證、設置頁和 CLI 打通。下面介紹它是什麼、提供哪些工具，以及如何安裝與配置 API Key。

這是什麼¶

@nguyenvanhoang1/dsh-zpdf（倉庫 nguyenvanhoang1/dsh-zpdf）由維護者 nguyenvanhoang1 發佈，在 SkillHub 目錄中歸類爲 admin-security。插件自述爲：面向 DeepSeek Harness 的官方 ZPDF 工具集，支持持久化的 API Key 與設置集成（English README 中表述爲 Official ZPDF tools for DeepSeek Harness with durable API-key and settings integration）。

它需要 Node.js >= 20、與 DeepSeek Harness 0.1.1-rc.2 兼容的 client-modules 格式，以及 ZPDF Plus 或 Pro 賬號；API Key 在 智譯 PDF API Keys 頁面 申請。當前 package 版本爲 1.0.5，許可證 MIT。npm 發佈已暫停，安裝以 GitHub 爲準。

核心功能¶

插件向 Harness 註冊一組以 zpdf_ 爲前綴的工具，能力如下（與倉庫 README 工具表一致）：

Web 端會在 Settings → ZPDF 提供獨立設置頁（已配置/缺失、保存、清除），以及實時積分卡片和任務概覽列表；餘額約每 30 秒、任務狀態約每 10 秒自動刷新，也可手動刷新並清空日誌。任務歷史保存在 $DSH_HOME/zpdf/tasks.json（保留最新 200 條）。API Key 通過 DSH 憑證寫入 ZPDF_API_KEY，不會出現在 settings describe 響應中；工具在首次需要時再檢查密鑰，缺失時會提示打開設置或使用 CLI。進程環境變量 ZPDF_API_KEY 同樣有效，且會覆蓋 GUI 憑證並使設置頁只讀。HTTP 上傳、輪詢、下載與 ZIP 解壓會響應工具的 abort 信號。

安裝與啓用¶

在你要使用的 DSH profile（示例爲 web）中安裝。README 推薦從 GitHub 安裝（倉庫已預構建 lib/，無需 prepare 腳本）：

# From GitHub (recommended; no npm publish required)
dsh plugin --profile web add github:nguyenvanhoang1/dsh-zpdf

# Equivalent
dsh plugin --profile web add https://github.com/nguyenvanhoang1/dsh-zpdf.git

包聲明瞭 dsh.bundle，因此 dsh plugin add 會把 @nguyenvanhoang1/dsh-zpdf 加入 profile 的 dsh.profile.bundles，下次啓動即可掛載設置頁與工具，一般無需手寫 composition 行。若用其他方式只安裝了包而未走 dsh plugin，可按 README 在 composition 中插入：

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

安裝後重啓 profile：

dsh web

說明：dsh plugin ... add 會同時安裝依賴並加入 profile 層棧；單獨 pnpm add 而不經 dsh plugin 不會完成 bundle 掛載。運行時需能解析 Harness 自帶的 @deepseek-ai/dsh-tools 等 host peer（均爲 optional peer，安裝時不報缺 peer，但運行時必須指向當前 Harness 副本）。

配置 API Key¶

任選一種方式即可；解析順序爲 CLI settings.apiKey → 憑證 / 環境變量（ZPDF_API_KEY）。

方式一：Web 設置（推薦）

1. 打開 Harness Web 的 Settings。
2. 進入 ZPDF 分區。
3. 填寫 API Key 並保存。

密鑰寫入 $DSH_HOME/.credentials.yaml（引用 ZPDF_API_KEY）。若環境裏已有 ZPDF_API_KEY，頁面爲只讀。

方式二：CLI

通過 profile 執行插件自帶的 zpdf 命令（裸 zpdf 不在 PATH 上）：

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

非交互示例（會進入 shell 歷史，README 不推薦）：

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

腳本可從 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

CLI 寫入 $DSH_HOME/settings.yaml 中的 zpdf.apiKey，與 DSH 使用相同的鎖與原子替換；啓用文件監視時可熱加載。

方式三：環境變量

export ZPDF_API_KEY=sk-xxxxxxxxxxxxxxxx

在啓動 DSH 前設置；composition 中可用 apiKeyEnv 改名。

可選 composition 配置¶

用戶 settings 仍可覆蓋 composition 中的 config：

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

典型用法¶

在 Harness 對話或 agent 流程中，由模型按需調用上述工具即可，無需單獨再寫 HTTP 客戶端。常見路徑包括：

1. 上傳 PDF 後調用 zpdf_parse_pdf 得到 Markdown 及可選 sidecar。
2. 需要整份 PDF 譯文時調用 zpdf_translate_pdf（譯文-only 或並排）。
3. 已有 Markdown 或 ZIP 時調用 zpdf_convert_markdown 導出 DOCX、HTML、PDF 或 LaTeX。
4. 扣費前先調用 zpdf_estimate_cost 做頁數與餘額預估；需要時用 zpdf_check_balance 與 zpdf_get_task_status 覈對積分與異步任務。

結果默認落在 ./zpdf-output（可通過 outputDir 修改）。

適用場景與注意¶

適合已在 DSH 中編排智能體、且持有 ZPDF Plus/Pro 與 API Key 的開發者：論文/報告 PDF 結構化、多語言 PDF 翻譯、Markdown 多格式導出等，都可以在 Harness 工具層完成，並與 Web 設置頁統一管理密鑰和任務列表。

安裝前建議自行閱讀倉庫源碼與 MIT 許可證。插件以當前 DSH 進程權限運行，會讀寫 $DSH_HOME 下的憑證、設置與 zpdf/tasks.json，並向 baseUrl 發起上傳與下載；請勿在倉庫、截圖或 issue 中泄露真實 API Key。社區目錄 SkillHub 插件頁 與 GitHub 無 DeepSeek / 幻方官方從屬關係，DSH 生態本身是「一切皆插件」的擴展模型。

結尾¶

dsh-zpdf 把 ZPDF 的解析、翻譯、格式轉換與積分查詢收成一組 DSH 工具，並把 API Key 接到憑證、設置頁和 CLI 三條路徑上。若你要在 Harness 裏處理 PDF 與 Markdown 流水線，可按 README 從 GitHub 安裝、配置 Key 後重啓 dsh web 使用。

• 目錄頁：https://www.skillhub.cn/plugins/nguyenvanhoang1/dsh-zpdf
• 源碼與文檔：https://github.com/nguyenvanhoang1/dsh-zpdf