dsh-zpdf 怎么安装？

在已安装 dsh CLI 引擎的环境中，进入插件页复制安装命令一键执行即可；自动检查通过：npm 包已发布且 engines 声明满足基线（声明 Node >=20）；该结论来自程序自动检查，未经人工实机验证。

dsh-zpdf 兼容性怎么样？

自动检查通过：npm 包已发布且 engines 声明满足基线（声明 Node >=20）；该结论来自程序自动检查，未经人工实机验证。

dsh-zpdf 有中文文档吗？

已提供中文翻译 README（由 DeepSeek 最新模型翻译生成），本站可切换中英文对照阅读。

dsh-zpdf 还在维护吗？

GitHub 1 星。最近一次上游提交在 2026/10/29。

PDF 智转 nguyenvanhoang1/dsh-zpdf

DeepSeek Harnessv1.0.5

nguyenvanhoang12 天前有提交已提供中文文档扫描：含敏感能力

在 GitHub 查看 ↗

ZPDF Tool 插件，为 DeepSeek Harness 提供高保真 PDF→Markdown 解析、保留版式的…

30.8/100

综合分

GitHub 星标

npm 周下载

—/5

用户评分

数据截至 2026/10/30 · 周下载取自 npm 全网（含 CI / 镜像），非本站安装数；综合分由星标、活跃度与兼容性检查合成。

安装命令 · 需先装 dsh CLI 引擎

dsh plugin --profile web add @kolmopdf/dsh-zpdf

npm 源 · @kolmopdf/dsh-zpdf 的发布者账号已校验与本仓库一致

状态速览

判定依据：实装验证 · 静态安装检查 · 自动扫描 · 仓库维护状态

信任档位：已验证

是什么

dsh 原生插件 · model

装得上吗

本站已在 dsh 0.2.1-rc.2 下真实安装成功

非静态推断

L4 · 真实安装等级说明 →

安全吗

本站尚未对该插件做风险分级

暂未覆盖，不等同于无风险

还在维护吗

活跃：最近一次提交在 2 天前

档位由哪些信号合成

本站实装验证（真实安装 L4 覆盖全站；L5 为运行时冒烟或实机截图，覆盖范围小于 L4） · 验证所用 dsh 版本 · 静态安装检查 · 风险分级 · 仓库维护状态。下方各区块是它的证据明细。

验证判据与等级说明 →

社区实装还没有人打卡 · 装过的第一个就是你

安装兼容性检查✓ 自动检查通过

展开查看检查明细 ↓

以下结论由程序自动检查 npm 包、engines 声明与入口文件得出，未做人工实机验证——能装不等于用着没问题。

✓npm 包@kolmopdf/dsh-zpdf @ 1.0.5

✓Node 引擎要求 >=20 · 基线 Node 22.19 满足

✓dsh CLI 依赖未声明 dsh 版本约束

✓入口文件main/exports/bin 已声明

验证方式：npm registry 存在性 + package.json 静态校验 · 最后检查 2026/10/12 22:45:02

安全扫描自动 · 静态分析源码

v2.7.0

🔵 扫描：含敏感能力尚无人工评估

展开查看扫描说明与证据 ↓

静态扫描发现插件具备触达本地系统的能力：执行外部命令、读写/删除本地文件、读取剪贴板或密钥类环境变量（至少其一）。这是能力清单，不是危险判定——具体能力项与证据见下方，安装前请自行判断是否需要。

读写/删除本地文件发起外部网络请求

查看扫描证据（共 24 处，展示前 17 条）

发起网络请求
lib/index.js:169
response = await fetch(url, init);
读取本地文件
lib/index.js:187
const bytes = await readFile(filePath);
发起网络请求
lib/index.js:293
const response = await fetch(`${this.options.baseUrl}/api/pdf-to-markdown-proxy/download/${encodeURIComponent(taskId)}`, {
写入本地文件
lib/index.js:306
const output = createWriteStream(destination);
读取本地文件
lib/index.js:350
text = await readFile(path, "utf8");
写入本地文件
lib/index.js:362
await mkdir(dirname(path), { recursive: true });
写入本地文件
lib/index.js:366
await mkdir(dirname(path), { recursive: true });
写入本地文件
lib/index.js:394
await mkdir(dirname(path), { recursive: true });
读取本地文件
lib/index.js:404
return (await stat(filePath)).size;
写入本地文件
lib/index.js:505
await mkdir(outputRoot2, { recursive: true });
写入本地文件
lib/index.js:523
await mkdir(target, { recursive: true });
读取本地文件
lib/index.js:600
const [realBase, realTarget] = await Promise.all([realpath(base), realpath(target)]);
读取本地文件
lib/index.js:670
const data = await readFile(filePath);
读取本地文件
lib/index.js:693
const preview = (await readFile(markdownPath, "utf8")).slice(0, 500);
发起网络请求
lib/client.js:140
const response = await fetch(url, { cache: "no-store" });
发起网络请求
lib/client.js:240
const response = await fetch("/plugins/zpdf/tasks", { method: "DELETE", cache: "no-store" });
读取本地文件
lib/cli.js:54
text = await readFile(path, "utf8");

扫描于 2026/11/1（0 天前） · 范围入口闭包 + 全包扫描 · 来源 npm 发布包

静态扫描只反映源码中出现的调用，不构成安全背书；人工评估与自动扫描相互独立、互不覆盖。

依赖的 DSH / Cordis 模块

@deepseek-ai/cordis@deepseek-ai/dsh-api-remotes@deepseek-ai/dsh-atomic-write@deepseek-ai/dsh-client-connection@deepseek-ai/dsh-client-locale@deepseek-ai/dsh-client-ui-primitives@deepseek-ai/dsh-client-ui-settings@deepseek-ai/dsh-client-ui-slots@deepseek-ai/dsh-credentials@deepseek-ai/dsh-home-paths@deepseek-ai/dsh-settings@deepseek-ai/dsh-system-prompt

给这个插件打分还没有人投票↓

用户评分

还没有人投票，来当第一个

广告精选好物

飞利浦 TAH6519 主动降噪耳机 ¥299

头戴式无线 anc 主动降噪，蓝牙连接，久戴舒适向。

·anc 主动降噪 · 头戴式无线
·价格与库存以商品页实时为准

去淘宝看看→

广告MCP 兼容手册

装完插件，给 AI 接上 MCP

Cursor、Claude Code、VS Code 逐个核对：能不能装、配置怎么写、装不上是什么原因。

·按客户端逐格核对
·结论标注依据与风险等级

查 MCP 兼容性→

功能亮点

PDF转Markdown
保留版式
持久化API密钥设置

DeepSeek Harness 官方 ZPDF 工具，集成持久化的 API 密钥与设置。

README

由 DeepSeek 最新模型翻译生成

展开完整文档（README 剩余 1 节）

zpdf

ZPDF Tool 插件，为 DeepSeek Harness 提供高保真 PDF→Markdown 解析、保留版式的 PDF 翻译、Markdown 文档转换、费用预估和余额查询。

仓库：<https://github.com/nguyenvanhoang1/dsh-zpdf>

功能

| Tool | 功能 |
| zpdf_parse_pdf | PDF → Markdown，可选同步翻译，支持公式、表格、图片与 enrichment sidecar |
| zpdf_translate_pdf | 保留原版式翻译 PDF，可输出纯译文或双栏对照 |
| zpdf_convert_markdown | Markdown/ZIP → DOCX、HTML、PDF、LaTeX |
| zpdf_estimate_cost | 本地读取页数并结合账户余额估算 credits（不扣费） |
| zpdf_check_balance | 查询当前 credits 余额 |
| zpdf_get_task_status | 按 task id 排查超时或卡住的任务 |

- GUI 通过 DSH 凭据库保存 API Key（ZPDF_API_KEY），不会出现在设置 describe 响应里。
- Web GUI 的 Settings → ZPDF 是单独设置页，显示“已配置/未配置”并提供保存和清除，附带实时积分卡片与任务总览列表——积分与任务状态自动刷新（30 秒 / 10 秒），支持手动刷新与清除记录。任务历史保存在 $DSH_HOME/zpdf/tasks.json（最多 200 条）。
- Tool 调用时才检查 Key；没有配置时会提示打开设置页或使用 CLI。
- 也支持进程环境变量 ZPDF_API_KEY。环境变量优先，存在时设置页为只读。
- 上传、轮询、下载与 ZIP 解压都会响应 Tool 取消信号。

要求

- Node.js >= 20
- DeepSeek Harness 0.1.1-rc.2 兼容版本（0.1.1-rc.2 client-modules 格式：dsh.client 清单 + exports["./client"] 惰性 CJS bundle）
- ZPDF Plus 或 Pro 账户
- 在 <https://www.zhiyipdf.com/api-keys> 创建 API Key

安装

先把包安装到需要使用的 DSH profile（以 web 为例）。推荐直接从 GitHub 安装：

从 GitHub 仓库安装（推荐，无需等 npm 发布）
dsh plugin --profile web add github:nguyenvanhoang1/dsh-zpdf

等价写法
dsh plugin --profile web add https://github.com/nguyenvanhoang1/dsh-zpdf.git

这是普通的 Git 依赖：仓库里带编好的 lib/，没有 prepare，因此不会触发 pnpm allowBuilds。同时声明了 dsh.bundle，所以 dsh plugin add 会把 @nguyenvanhoang1/dsh-zpdf 写进该 profile 的 dsh.profile.bundles，下次启动就会挂载——设置页和 Tool 会自动出现，不必手写 composition 行。

@deepseek-ai/dsh-tools 等宿主包是 可选 peer 依赖（和 dsh-ads 同款模式）：所有宿主 peer 都在 peerDependenciesMeta 中标记为 optional，安装时 pnpm 不再报 "missing peer"；运行时契约不变——必须解析到当前 Harness 自带的那一份（模块回退栈）。如果插件再自带一份，任意 Tool 调用都会报 Cannot read properties of undefined (reading 'prepare')。

也可以从本地目录安装：

在本仓库直接进行本地测试
dsh plugin --profile web add D:/code/work-relate/dsh-zpdf

dsh plugin add 已经会激活 bundle 层。只有用别的方式装包时，才需要自己在 profile 的 cordis.patch.yml 里加一行：

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

参见 examples/cordis.patch.yml 和仓库根目录的 cordis.patch.yml。

发版

npm 发布暂未启用，请使用上面的 GitHub 安装命令。新包名为 @nguyenvanhoang1/dsh-zpdf，对应 npm scope 尚未配置发布授权。

启用 Release & Publish（.github/workflows/release.yml）前，需取得该 npm scope 的发布权限，并将 npm Trusted Publisher 配置为 owner nguyenvanhoang1、仓库 dsh-zpdf、workflow release.yml。工作流使用 OIDC，不使用 NPM_TOKEN secret。本次仓库迁移不修改此前已发布的 npm 包。

CI 执行类型检查、测试和构建；Rebuild lib 同步已提交的 lib/，确保不执行 prepare 脚本的 Git 安装可以直接使用成品。

重启 profile：

dsh web

dsh plugin ... add 会安装依赖，并且因为本包声明了 dsh.bundle，会加入 profile 的 layer 栈。单独 pnpm add、不走 dsh plugin 则不会。

配置 API Key

方法一：Web 设置页（推荐）

打开 DeepSeek Harness Web GUI：

1. 点击左下角 Settings / 设置；
2. 进入独立的 ZPDF 设置项；
3. 输入 API Key 并保存。

设置页把 Key 写入 DSH 凭据库（$DSH_HOME/.credentials.yaml 的 ZPDF_API_KEY 引用），不经过设置文档 allowlist。若进程环境里已经有 ZPDF_API_KEY，设置页会显示为只读（环境变量优先，不能覆盖）。

如果尚未设置 Key，插件仍可启动；第一次需要鉴权的 Tool 调用会返回可操作提示。

方法二：CLI

安装包后，请通过 DeepSeek Harness 调用 CLI（直接打 zpdf 会提示找不到命令，因为它不在全局 PATH 上）：

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

命令会用遮罩输入读取 Key，并写入 $DSH_HOME/settings.yaml（默认 ~/.dsh/settings.yaml）中的 zpdf.apiKey。

非交互传参（会进入 shell history，不推荐）
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

查看状态（不会输出 Key）
dsh plugin --profile web exec zpdf -- config status

查看实际设置文件路径
dsh plugin --profile web exec zpdf -- config path

清除已保存 Key
dsh plugin --profile web exec zpdf -- config clear-key

使用自定义 settings 文件
dsh plugin --profile web exec zpdf -- config set-key --file D:/path/to/settings.yaml

CLI 会尽量保留 YAML 注释；写入使用与 DSH 自身 settings 提供者相同的 <file>.lock 写锁与原子替换（@deepseek-ai/dsh-atomic-write），并把设置文件权限设为 owner-only（0600；Windows 上仍受 ACL 控制）。正在运行且启用了文件监听的 DSH 会热加载该修改。

方法三：环境变量

export ZPDF_API_KEY=sk-xxxxxxxxxxxxxxxx

PowerShell：

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

环境变量需要在启动 DSH 前设置。可在 composition 中把 apiKeyEnv 改成其他变量名。

解析顺序：CLI 写入的 settings.apiKey → 凭据库 / 环境变量（ZPDF_API_KEY）。

可选配置

可直接在 composition 的插件行提供 base 配置；用户 settings 层仍会覆盖它：

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

| 字段 | 默认值 | 说明 |
| apiKey | 未设置 | Secret；推荐由 GUI/CLI 写入，不要提交到 composition |
| apiKeyEnv | ZPDF_API_KEY | 环境变量 / 凭据引用名 |
| baseUrl | https://www.zhiyipdf.com | ZPDF 服务地址 |
| outputDir | ./zpdf-output | 结果输出目录（相对 DSH 启动目录） |
| pollIntervalMs | 2000 | 轮询任务状态间隔 |
| maxPollMinutes | 30 | 最长轮询分钟数 |
| httpTimeoutMs | 60000 | 普通 HTTP 请求超时 |
| uploadTimeoutMs | 600000 | 上传/下载超时 |

开发

corepack enable pnpm
pnpm install
pnpm check

pnpm check 依次运行 TypeScript 类型检查、Vitest 测试和生产构建。

可选的宿主组合测试需要指定已安装的 Harness 包目录：

DSH_ROOT=/path/to/node_modules/@deepseek-ai/dsh pnpm test:host

安全说明

- 不要把真实 API Key 写入仓库、README、截图或 issue。
- Web 凭据 API 只返回是否已配置 / 是否可写，不返回 secret 内容。
- CLI 状态命令只显示 configured/not configured。
- 插件会读取 Tool 参数指定的本地 PDF/Markdown/ZIP，并把结果写入 outputDir；只在可信的 DSH composition 中启用它。
- 输出目录先按 realpath 校验：output_subdir 及其中的符号链接都不能逃出 outputDir。
- ZIP 下载使用路径穿越检查，拒绝绝对路径和 ../ 条目；解压上限为 10,000 个条目与 4 GiB 总解压大小，单次结果下载上限 2 GiB。
- 输入文件上限 300 MB、最多 800 页（与 ZPDF 服务端限制一致），并在本地先校验后再上传；上传、轮询、下载与解压都会响应取消信号。

License

MIT