前言¶
在智能體開發與文檔處理場景中，處理 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 文檔的開發者。
