前言¶

在 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