前言¶
DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”。在本地化 PDF 处理这一场景中，通常需要人工介入或依赖昂贵的 SaaS 服务。dsh-pdf-translate 插件利用 DeepSeek 或任意 OpenAI 兼容 API，直接在本地对文本型 PDF 进行全文翻译，输出保留版式、字体样式、图片与链接的可编辑 PDF。
核心能力¶
该插件解决了“翻译”与“版式保留”之间的矛盾，主要能力包括：
- 输入输出：支持文本型 PDF（有文本层）；输出文本可选中、可复制的可编辑 PDF。
- 版式保留：保留段落区域、字体样式、图片与链接。
- 原文处理：原文经 redaction 真正删除，而非简单的白块遮盖。
- 翻译控制：代码块原样保留；段落级翻译，支持样式（字号/颜色/对齐）。
- 单任务限制：单次任务最多翻译 50 页，超出需分页段多次处理。
- 术语表与缓存：支持导入 JSON/TXT 术语表锁定专有名词；按段落哈希实现断点续传。
安装与启用¶
安装插件：
dsh plugin --profile desktop add dsh-pdf-translate
安装后，重启 DSH Desktop。在设置页的“插件区”找到「PDF 翻译」卡片，填入 API Key 并保存。API Key 会被 role('secret') 保护，绝不写入会话日志。
使用方式¶
插件提供工具调用与命令行两种方式。
Agent 工具调用¶
Agent 可调用 translate_pdf 工具：
* input：输入 PDF 绝对路径。
* outputDir：输出目录。
* pageStart / pageEnd：页面范围（1-based），默认全文，单次任务 ≤ 50 页。
* langPair：语言对，如 en→zh。
* termbase：术语表文件路径（JSON/TXT）。
命令行使用¶
node scripts/translate-cli.mjs <input.pdf> <outputDir> 1 20 en→zh
输出目录将生成 <书名>.<langPair>.pdf 及 .translate-cache.json（用于断点续传）。
术语表格式¶
JSON 格式支持 locked 字段（锁定不翻译）：
[
{ "src": "API", "dst": "应用程序接口", "locked": false },
{ "src": "GPT", "dst": "GPT", "locked": true }
]
TXT 格式每行 原文,译文。
技术实现¶
插件由 TypeScript (Cordis) 和 Python (PyMuPDF) 组成。
- 架构：TS 层负责编排与 API 调用，Python Worker 负责底层 PDF 操作。
- Worker 启动：必须使用
python -m worker.main启动，并确保工作目录为仓库根目录。 - 工作流：
- 检测：检测 PDF 文本层，无文本层报错。
- 提取：识别段落（列检测 + 行合并 + 列表项规则），生成带 ID 的文本块。
- 重建：两阶段重建。先 redaction 删除所有原文，再根据几何锚点插入译文文本框。
已知限制¶
- 仅文本型 PDF：扫描版（需 OCR）不在 v1 范围。
- 版式细节丢失：下划线样式丢失；密集表格行可能被合并。
- 交互干扰：与 redaction 区域相交的链接注释会被删除；超长单行译文可能溢出页面。
- 复杂版式：文本框重叠或旋转文字的版式处理能力有限。
资源¶
- 插件目录：DSH Catalog
- 源码仓库：GitHub
