前言¶
在智能体开发与文档处理场景中，处理 PDF 文档常常需要人工拆页、OCR、翻译、公式重排与排版重建。这些环节重复度高、容错率低，且容易引入格式错乱。
DeepSeek Harness（DSH）采用插件化架构，允许在对话界面直接调用各类工具。PDF 翻译插件 csukingzq/dsh-pdf-translator 利用视觉模型对 PDF 进行逐页渲染，自动识别正文、图注、表格和公式，输出中文 PDF 与可编辑 LaTeX 源码压缩包，并支持 AI 核验与断点续跑。
插件定位与解决的问题¶
插件名称为 dsh-pdf-translator，由维护者 csukingzq 开发。它将 PDF 翻译任务封装为 DSH 工具链的一部分，通过视觉模型理解文档结构，而非依赖本地 OCR，从而在保证精度的同时减少依赖。
核心价值在于：
- 用视觉模型代替本地 OCR，降低对环境与字体的依赖；
- 自动重建表格结构与 LaTeX 排版；
- 输出可直接编译的 LaTeX 工程，方便后续编辑与复用；
- 在 DSH 桌面版中通过面板完成环境准备与配置，无需终端操作。
核心能力¶
插件支持以下能力：
-
逐页渲染与定位
- 将 PDF 逐页渲染为图片，由视觉模型识别正文、图注、表格和公式。
- 不使用本地 OCR，依赖支持图片输入的 OpenAI 兼容 API。 -
图形与表格重建
- 图形按原边界裁取，保留原始曲线与数据；图下附中文对照说明。
- 表格重建为 Markdown / HTML，支持合并单元格。 -
输出结构
- 每次翻译在输出目录下新建一个以文档名和时间命名的子文件夹。
- 文件夹内仅包含两个文件：中文 PDF 和 LaTeX 源码 zip 压缩包。 -
环境与配置
- 首次运行通过面板「一键准备环境」自动创建 Python 环境、安装依赖并下载 Pandoc / Tectonic（约 300 MB）。
- 面板支持填写模型配置（接口地址、模型名称、API 密钥），密钥仅写入本机配置文件。
- 支持后台任务、任务取消、断点续跑和缓存复用。 -
AI 核验
- 可选逐页检查译文，最多两轮修订与重新编译。
- 缓存由用户手动清理，不自动删除。
安装与启用¶
桌面版：
- 打开 DSH，点击 插件 → 添加插件。
- 输入
dsh-pdf-translator，点击 安装，然后 立即启用。
CLI：
npx.cmd @deepseek-ai/dsh plugin --profile web add dsh-pdf-translator
GitHub Release 方式：下载 dsh-pdf-translator.tgz，在 插件 → 添加插件 中选择该文件。
首次运行：面板一键完成¶
安装并启用插件，重启 Harness 后打开左下角或标题栏的 PDF 翻译 面板：
- 首次会显示「首次使用需要准备运行环境」，点 一键准备环境。插件会自动创建 Python 环境、安装依赖并下载 Pandoc / Tectonic（约 300 MB，需要联网），面板显示进度，可取消或重试。默认优先走国内镜像（
ghproxy.net/gh-proxy.com/ghfast.top，pip 用清华 / 阿里源），失败会自动回退官方 GitHub / PyPI。 - 就绪后点 填写模型配置，填写接口地址、模型名称和 API 密钥并保存。密钥只写入本机
config.json，不会上传。 - 直接 选择 PDF 开始翻译，不需要重启。
已配置过的用户不会看到向导；之后可随时用面板里的 模型配置 修改。
手动安装环境（离线/网络受限时）¶
如果自动安装失败（例如无法访问 GitHub 或 pip 源），可以在 PowerShell 中手动执行：
& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -ExecutionPolicy Bypass -File "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-pdf-translator\scripts\setup.ps1" -OfficialOnly
自定义镜像或单独覆盖安装包地址：
setup.ps1 -PipIndexUrls "https://pypi.tuna.tsinghua.edu.cn/simple" -TectonicUrl "https://..." -PandocUrl "https://..."
安装长时间停在某个镜像时，脚本会自动尝试下一个镜像和官方源；全部失败可手动下载后放进 %USERPROFILE%\.dsh\dsh-pdf-translator\runtime。
& "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-pdf-translator\scripts\setup.ps1"
Web / CLI profile 把 desktop 换成 web。然后编辑模型配置：
%USERPROFILE%\.dsh\dsh-pdf-translator\config.json
{
"base_url": "https://api.deepseek.com/v1",
"model": "REPLACE_WITH_A_VISION_MODEL",
"api_key": "REPLACE_WITH_YOUR_KEY",
"thinking": "auto",
"auto_repair_rounds": 3
}
手动改完后无需重启，直接翻译即可。也可以在聊天中发送「调用 pdf_translator_doctor 检查 PDF 翻译插件环境」。
典型用法¶
页面左下角和聊天标题栏都有 PDF 翻译 入口：
- 点击 选择 PDF。
- 确认输出目录和翻译页码，支持
all、1-5、1,3,5-8。 - 点击 开始翻译。
- 在 Harness 任务列表查看进度和结果。
也可以直接在聊天中说明：
使用 pdf_translate，把 D:\资料\paper.pdf 的第 1–3 页翻译为中文，先用 pdf_inspect 检查页数。
常用工具：
| 工具 | 用途 |
|---|---|
pdf_translate |
翻译并生成中文 PDF 和 LaTeX 源码压缩包 |
pdf_inspect |
查看页数、文件大小，校验页码范围 |
pdf_review |
开启 AI 核验后逐页检查、预览和修订 |
pdf_translator_doctor |
检查 Python、排版运行时和模型配置 |
pdf_cache_list |
只读查看缓存 |
pdf_panel |
显示或隐藏翻译面板 |
pdf_translate 主要参数：pdf、pages、workers（1–8，默认 4）、imageQuality、thinking、renderOnly、outputDir、background。默认后台执行，也可以通过 background: false 等待结果。
输出结构¶
每次翻译在所选输出目录下新建一个以文档名和时间命名的子文件夹，里面只有两个文件：
输出目录\论文名_20261024-120019_ab12cd\
├── 论文名_0cb8b7_zh.pdf 中文 PDF
└── 论文名_0cb8b7_zh-latex.zip LaTeX 源码压缩包
zip 内是可直接用 XeLaTeX 或 Tectonic 编译的完整工程（main.tex、layout.tex、images/、README.txt 等），不包含编译日志和中间文件。译文、结构数据和核查报告保存在插件数据目录的 work 下，不会出现在输出目录。
main.tex 的字体是条件选择的：本机有宋体 / Times New Roman 时保持原样，缺少时（如 Overleaf）自动改用 Fandol 和 TeX Gyre Termes。因此整个 zip 可以直接上传 Overleaf，编译器选 XeLaTeX 即可，不需要改字体；记得连同 images/ 一起上传。
数据与更新¶
用户数据默认保存在：
%USERPROFILE%\.dsh\dsh-pdf-translator
包含 config.json、.venv、runtime、outputs 和 work。更新或重装插件不会删除这些数据；卸载后如需彻底清理，可手动删除该目录。
可用环境变量覆盖：
| 变量 | 用途 |
|---|---|
DSH_PDF_DATA_DIR |
数据、缓存和输出目录 |
DSH_PDF_CONFIG |
模型配置文件 |
DSH_PDF_PYTHON |
Python 可执行文件 |
DSH_PDF_RUNTIME_DIR |
Pandoc / Tectonic 目录 |
翻译时选中的页面图片会发送到配置的模型接口，可能产生 API 费用。API 密钥只保存在本机配置或进程环境中。
适用场景与注意¶
适合需要批量翻译 PDF 文档、保留排版结构、并输出可编辑 LaTeX 源码的场景，如学术论文翻译、技术文档本地化等。
插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。插件使用 MIT 许可证。
小结¶
dsh-pdf-translator 将 PDF 翻译、结构识别与 LaTeX 重建整合为 DSH 中的一个工具链，支持面板一键环境准备与配置，并提供后台任务与 AI 核验能力。它不依赖本地 OCR，通过视觉模型理解文档内容，适合需要在智能体工作流中处理 PDF 文档的开发者。
