前言¶
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
