前言¶

做智能体开发绕不开 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。