前言¶
在 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 仓库。
