前言¶
在 DeepSeek Harness（DSH）裏讀英文論文，常見路徑是：自己裝 BabelDOC、配 ~/.config/babeldoc/config.toml，再讓智能體或腳本去調命令行。BabelDOC 本身能把 PDF 翻成雙語對照版，但直接用時往往會遇到三類問題：配置文件寫了卻不被自動加載、翻譯 API 默認帶上隱藏的 reasoning token、術語表每篇論文重新抽一遍。dsh-paper-translate 把 BabelDOC 包成 DSH 工具 paper_translate，在宿主裏統一做環境自檢、成本預估和術語表複用，翻譯前先讓你看到 token 和費用，不滿意可以不跑。
這是什麼¶
維護者 RyanZhangK 在 GitHub 開源的 dsh-paper-translate（MIT，當前 package 版本 0.1.0），分類屬於 DSH 社區目錄裏的「聯網工具」。它不重新實現翻譯引擎，而是在調用 BabelDOC 時補上：顯式傳 config、固定關閉 OpenAI 兼容接口上的 thinking、按 domain 持久化術語表到本地 CSV。輸出爲 .dual.pdf（原文與譯文逐頁交替）和 .mono.pdf（純譯文）。
社區插件目錄頁：https://www.skillhub.cn/plugins/RyanZhangK/dsh-paper-translate（獨立站點，與 DeepSeek / 幻方無官方從屬關係）。
核心功能¶
下面介紹 README 中已寫明、且與實現對應的能力。
先報成本再動手。 傳 dryRun: true 時只做環境檢查與成本預估，不啓動翻譯；滿意再正式跑。命中 BabelDOC 本地翻譯緩存時結果會說明 0 token；要強制重翻傳 ignoreCache: true。
壓低隱藏推理開銷。 插件固定向 BabelDOC 傳 --openai-thinking disabled。README 中以同一段正文對比：默認 thinking 下 completion 裏大量是 reasoning token，關閉後 completion 明顯下降，譯文長度幾乎不變；整篇 PDF 上原生 BabelDOC 與關閉 thinking 的差異同樣顯著。術語提取走 BabelDOC 內另一路 translator，不受該開關約束，省這部分主要靠複用詞表。
術語表跨文檔複用。 按 domain（如 slam、rl、cv，默認 general）存於 ~/.local/share/dsh-paper-translate/glossary/<domain>.csv。同領域第二篇論文直接複用已有表，跑完會把新增術語回填；格式與 BabelDOC 原生三列 CSV（source,target,tgt_lng）一致，可導入已有 .glossary.csv。
環境自檢。 缺 babeldoc、config 缺 key、bitstring 版本與 BabelDOC 0.6.4 不兼容等情況，返回可執行的修復提示而非一長串 traceback；dryRun 時還會探活 API。
BabelDOC 側三個已知坑的對應處理。 一是 CLI 默認不讀 ~/.config/babeldoc/config.toml，插件始終顯式傳 -c；二是服務端默認 thinking；三是每次翻譯重抽術語——由上述 domain 詞表機制緩解。
README 還給出一篇 8 頁論文、模型 deepseek-v4-flash 下的對比表：原生 BabelDOC 約 238,099 token（~¥0.33），本插件首次含抽術語約 99,385 token（~¥0.14），複用詞表實測約 43,553 token（~¥0.035）。實際受文字量與公式密度影響。
安裝與啓用¶
插件以當前 DSH 進程權限運行；安裝前建議瀏覽倉庫源碼與 LICENSE。不要只在 profile 的 package.json 里加 dependency 而不寫入 dsh.profile.bundles，否則 DSH 啓動不會加載該包。
推薦從 GitHub 一條命令安裝（會同時寫 dependencies 和 dsh.profile.bundles）：
dsh plugin --profile web add github:RyanZhangK/dsh-paper-translate
安裝後重啓 dsh web 即可；README 寫明不需要在插件目錄裏自行 npm install，@deepseek-ai/cordis 與 @deepseek-ai/dsh-tools 爲 optional peer，由 DSH 宿主解析。
若要改併發等參數，在 profile 的 cordis.patch.yml 裏給 paper-translate 對應項加 config（見倉庫內 cordis.patch.yml 註釋）。引擎要求：node >= 20，dsh 爲 ^0.2.0-rc.1 || ^0.2.1-rc.1。
BabelDOC 與 Python 依賴需自行準備；插件不代裝。例如 BabelDOC 0.6.4 需要 bitstring>=4.3,<5 時，README 給出：
uv pip install --python ~/.local/share/uv/tools/babeldoc/bin/python "bitstring>=4.3,<5"
典型用法¶
工具名爲 paper_translate。pdf 必填且必須是絕對路徑（工具進程 cwd 不是 shell 當前目錄，相對路徑會被拒絕）。
| 參數 | 說明 |
|---|---|
pdf |
PDF 絕對路徑 |
domain |
術語庫領域，默認 general |
pages |
部分頁，如 1-6 或 1,3,7-9 |
extractGlossary |
默認 true；僅當該領域尚無可用詞表時才真正抽術語；傳 false 只複用、不抽新詞 |
langOut |
目標語言，默認沿用 config 的 lang-out |
outputDir |
輸出目錄，默認沿用 config 的 output |
dryRun |
僅檢查與預估，不翻譯 |
ignoreCache |
忽略 BabelDOC 緩存 |
在 DSH 對話裏可以自然描述，例如：先用 paper_translate 對某 PDF 設 dryRun 估 token；確認後再翻成中文並設 domain 爲 slam。
產物名爲 <論文名>.no_watermark.zh-CN.dual.pdf 與 .mono.pdf；跑完會報告實際用量與預估差異。
適用場景與注意¶
適合：需要在 DSH 智能體流程裏整篇翻譯有文本層的 PDF、希望翻譯前看到費用、同領域多篇論文希望共用術語表的用戶。
務必知曉的限制（來自 README）：
- 只處理帶文本層的 PDF，掃描件不會自動 OCR。
- 非 PDF 不支持。
- 術語去重規則爲
source+tgt_lng，舊值優先，新詞只增不覆蓋。 - 默認併發 2；過高易撞 API 429。
- 成本預估按頁均攤，只翻前幾頁試讀時可能低於整篇預估。
- 不做 zathura 劃詞、批量隊列、Web UI。
插件安裝與調用均在你本機 DSH profile 與進程權限下進行；聯網翻譯會使用你在 BabelDOC config 中配置的 API key。
結尾¶
dsh-paper-translate 的價值可以概括爲：在 DSH 裏把 BabelDOC 變成可對話調用的 paper_translate，用 dryRun 和緩存說明控制花費，用 domain 術語表和關閉 thinking 減少重複開銷。進一步瞭解可打開 SkillHub 目錄頁 與 GitHub 倉庫。
