前言¶
在 DSH（DeepSeek Harness）里处理整本 PDF 技术书时，常见做法是抽纯文本丢给模型再粘回 Word 或 Markdown。这条路会丢掉原版的栏宽、字号、图片位置和矢量图，章节结构也要自己猜。扫描版还要上 OCR，成本和误差都更高。
dsh-pdf-book-translate 面向有文本层的 PDF：先按章/节拆解并生成章节纪要，再在你明确指定的页、章或节范围内并发翻译，尽量保持段落位置与版式，并支持断点续译、术语表与左右对照 PDF。下面按安装、工具链与注意点说明用法。
这是什么¶
- 名称：dsh-pdf-book-translate（DSH bundle 插件 id：
pdf-book-translate） - 维护者：MikuDayo-IoI
- 分类：工作流（社区目录归类）
- 版本：0.1.1（README 与 package.json 一致）
- 许可证：MIT
插件在 Host 侧注册三个工具：pdf_book_outline、pdf_book_translate、pdf_book_status；PDF 解析与重排由 Python PyMuPDF worker 完成。不支持 OCR，扫描版 PDF 不在支持范围内。
核心功能¶
章节扫描与纪要¶
pdf_book_outline 会检查 PDF 是否有文本层，无则直接拒绝。结构识别顺序：自带目录（TOC）→ 按标题字号/位置的启发式章/节 → 回退为单章全书。AI 为每章生成约 180–350 字摘要，结果写入输出目录的 zhan_jie.md 与 .pdf-book-state.json。
范围门禁与合并¶
pdf_book_translate 必须收到 pages、chapters、sections 之一，或用户明确要求全书时的 all=true。什么都不传时返回 status=scope_required 和可用章节列表，由 Agent 先问用户，不会默认整本翻译。
同一本书多次翻译不同范围会合并到同一份译文 PDF；状态中保留每次范围与已完成页的并集。
版式与排版（0.1.1）¶
- 段落级重排：提取时把视觉硬换行还原为连续语义段落（代码段保留换行）；翻译后按原栏宽、字号、对齐重新折行，而不是原文一行对应译文一行。
- 版式避让：重排参考同栏宽度，避开右侧图片、矢量图与相邻栏。
- 矢量图保留：仅对文本层 redact；图片、背景、表格线与矢量图仍为 PDF 原生对象，不栅格化。
翻译、缓存与术语表¶
- 按约 8 段 / 3000 字符组批，默认并发 6（可在设置中调整 1–16）。
- 每段译完即以
sha256(langPair + 原文)为键写入.translate-cache.jsonljournal，再原子合并到.translate-cache.json；进程被强杀后重跑可跳过已译段落。 - 术语表支持 JSON 数组/对象与 TXT（制表符或逗号分隔），条目可设
locked；未指定路径时会自动发现输出目录下的termbase.json、glossary.json、术语表.json等。 - API Key 留空时使用当前会话 Host 模型；填写则走 OpenAI 兼容
/chat/completions（默认https://api.deepseek.com）。
输出¶
默认输出目录为 PDF 同目录下的 <文件名>-translation，主要包括：
| 文件 | 作用 |
|---|---|
<书名>.<目标语言>.pdf |
译文 PDF |
<书名>.<目标语言>.compare.pdf |
原版/译文左右对照 |
zhan_jie.md |
章节纪要 + 内嵌断点状态 |
.pdf-book-state.json |
机器可读断点状态 |
.translate-cache.json / .translate-cache.jsonl |
段落缓存与崩溃恢复 journal |
安装与启用¶
运行依赖¶
- Python 3.10+，且能
import pymupdf：python -m pip install pymupdf - Node.js 22+，pnpm 或 npm（用于从源码构建）
从源码构建时，在仓库根目录执行：
npm install
npm run build
npm test
构建产物包括 lib/index.js（Host 入口）、lib/client.js（Web 设置卡）与 worker/*.py。
装入 DSH¶
README 说明：将包含 lib/、worker/、cordis.patch.yml 和 package.json 的包目录，通过 DSH 插件管理器以 bundle 形式安装。配置命名空间为 pdf-book-translate；设置卡挂在 bundle 配置页（plugins.bundle.config，key 为包名 dsh-pdf-book-translate）。新安装后刷新一次 Web GUI 即可看到设置项。
运行时不要把该项目的 devDependencies 一并装进 DSH 宿主；发布包仅保留 @deepseek-ai/schemastery 为 dependency。
主要设置项¶
| 设置 | 默认 | 说明 |
|---|---|---|
apiKey |
空 | 留空用 Host 模型 |
baseUrl |
https://api.deepseek.com |
OpenAI 兼容端点 |
model |
deepseek-chat |
API 模式模型名 |
langPair |
en→zh |
默认语言对 |
concurrency |
6 |
并发批次 |
termbasePath |
空 | 默认术语表路径 |
pythonBin |
python |
需能 import pymupdf |
Host 模式要求对应 provider 已在 DSH Models 页配置凭据，或环境中有如 DEEPSEEK_API_KEY 等变量；否则工具会返回可操作的错误信息。
典型用法¶
整体流程如下（与 README 一致）：
pdf_book_outline
├─ 检查文本层
├─ 识别章/节并生成摘要
└─ 写 zhan_jie.md + .pdf-book-state.json
↓
询问用户翻译范围（页 / 章 / 节 / 全书）
↓
pdf_book_translate（必须显式范围）
├─ 提取段落 → 查缓存 → 并发翻译 → 重建 PDF → 生成对照 PDF
└─ 写回 state / zhan_jie.md，返回统计
↓
pdf_book_status（中断后查看进度）
pdf_book_outline¶
| 参数 | 必填 | 说明 |
|---|---|---|
input |
✅ | PDF 路径（绝对或工作区相对） |
outputDir |
可选 | 默认 <PDF 同目录>/<文件名>-translation |
langPair |
可选 | 如 en→zh |
rescan |
可选 | true 重新识别结构 |
pdf_book_translate¶
| 参数 | 必填 | 说明 |
|---|---|---|
input |
✅ | PDF 路径 |
pages |
范围之一 | 如 1-20,35,40-45（1-based） |
chapters |
范围之一 | 如 ch-1,ch-3 |
sections |
范围之一 | 节 id 或标题 |
all |
范围之一 | 仅当用户明确要求整本时传 true |
termbase |
可选 | 术语表路径 |
pdf_book_status¶
用于中断后查看章节纪要、已翻译页并集、缓存条目数、输出文件是否存在及上次统计。
术语表示例（JSON 数组）：
[
{ "src": "transformer", "dst": "Transformer", "locked": false },
{ "src": "DeepSeek", "dst": "DeepSeek", "locked": true }
]
适用场景与注意¶
适合：有文本层的技术书、教材 PDF，需要在 Agent 工作流里分段翻译、断点续跑，并保留接近原版的版式与对照阅读。
不适合：扫描版或无文本层 PDF（插件明确无 OCR）。
已知限制（README）：
- 同一段落内混合字体样式会按首 span 样式统一写回。
- 极长译文可能触发缩字号或排版警告，记录在返回的
warnings中。 - 表格按文本行/单元格几何处理，不重建表格结构。
- 缓存键不含术语表；改术语表后若要重译，需删对应缓存或换输出目录。
安全与权限：插件以当前 DSH 进程权限读写你指定的 PDF 与输出目录，并可能调用你配置的 LLM API。安装前请阅读 GitHub 源码 与 MIT 许可证，确认环境与凭据策略符合你的要求。
DSH 社区插件目录（SkillHub 条目）由社区维护，与 DeepSeek / 幻方无官方从属关系；选型时以仓库 README 与本地构建结果为准。
结尾¶
dsh-pdf-book-translate 把「章节约束 + 术语表 + 版式保留 + 可恢复缓存」绑成一条 DSH 工作流，适合在智能体对话里先 outline、再按范围 translate、用 status 查进度。若你手头是可复制文本的 PDF 而非扫描件，这条路径比纯文本抽取再手工排版更贴近原书阅读体验。
