前言¶

在 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.jsonl journal，再原子合併到 .translate-cache.json；進程被強殺後重跑可跳過已譯段落。
• 術語表支持 JSON 數組/對象與 TXT（製表符或逗號分隔），條目可設 locked；未指定路徑時會自動發現輸出目錄下的 termbase.json、glossary.json、術語表.json 等。
• API Key 留空時使用當前會話 Host 模型；填寫則走 OpenAI 兼容 /chat/completions（默認 https://api.deepseek.com）。

輸出¶

默認輸出目錄爲 PDF 同目錄下的 <文件名>-translation，主要包括：

安裝與啓用¶

運行依賴¶

• 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。

主要設置項¶

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¶

pdf_book_translate¶

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 而非掃描件，這條路徑比純文本抽取再手工排版更貼近原書閱讀體驗。

• 社區目錄：https://www.skillhub.cn/plugins/MikuDayo-IoI/dsh-pdf-book-translate
• 源碼與文檔：https://github.com/MikuDayo-IoI/dsh-pdf-book-translate