前言¶
DeepSeek Harness（DSH）通过插件扩展能力，已支持 Python 3.12 虚拟环境。把 BabelDOC 的 PDF 翻译能力注册成 Agent 工具后，可以在对话里直接说「把这个 PDF 翻译成中文」。BabelDOC 会保留原 PDF 的排版：字体、公式、图表位置，以及水印等元信息。
插件定位¶
这是一个 DeepSeek Harness 插件，由维护者 Alex-yuanli 发布。它将 BabelDOC 的 PDF 翻译能力接入 DSH，让 Agent 能调用 babeldoc_translate 工具。插件本身不含任何密钥或 Python 运行时，也不参与逐句翻译——只负责拼参数、起进程、收产物、报错。译文的每个字都由 BabelDOC 拿着使用者的密钥直接请求 api.deepseek.com 得到，消耗的是 API 额度。
核心功能¶
插件提供两个输出格式：
*.dual.pdf：原文与译文对照的双语版*.mono.pdf：纯译文版
同一篇论文（如 Attention Is All You Need）翻译后，公式、图表和页边水印都会留在原位。
插件在 DSH 里注册了 babeldoc_translate 工具与 /babeldoc 命令。工具参数包括：
files：必填，一个或多个 PDF 的绝对路径lang_in/lang_out：源 / 目标语言，默认取配置 en → zhpages：只翻部分页，BabelDOC 语法，如1-3,5output_dir：输出目录，默认取配置，再退回输入文件所在目录dual/mono：是否输出双语版 / 纯译文版，默认都输出watermark：是否保留 BabelDOC 水印，默认 falseenhance_compatibility：某些 PDF 渲染异常时打开兼容性增强translate_tables：是否翻译表格内文字，默认 falseglossary_files：术语表 CSV 的绝对路径（列：source、target、可选 tgt_lng）qps：每秒请求数上限，默认取配置 4
返回值为每个输入文件对应的 dual / mono 绝对路径，以及本次运行的日志文件路径。API Key 通过临时 TOML 传给 BabelDOC 并在结束后删除，不出现在进程命令行里。
安装与启用¶
插件已发布到 npm，也可以从 GitHub 获取。
会话中安装（最简，当前进程立即生效）：
plugin_manager { action: "install_bundle", target: "babeldoc-on-dsh" }
终端中安装（改 profile 文件，重启 DSH 后生效）：
dsh plugin --profile <profile 名> add babeldoc-on-dsh
<profile 名> 是正在用的 profile，桌面版常见为 desktop 或 web。注意写错名字时 dsh 不会报错，而是静默新建一个空 profile 把插件装进去，GUI 里看不到——装完没反应先回头看这个。
不走 npm 的装法（用仓库里的最新提交，或 npm 不可达时）：
plugin_manager { action: "install_bundle", target: "git+https://github.com/Alex-yuanli/babeldoc-on-dsh.git" }
这种方式需要本机有 git，没有时 pnpm 会报 [ERR_PNPM_GIT_RESOLVE_FAILED] git ls-remote failed。也可以先 clone 再按本地目录装：
git clone https://github.com/Alex-yuanli/babeldoc-on-dsh.git
plugin_manager { action: "install_bundle", target: "D:\\path\\to\\babeldoc-on-dsh" }
安装后该插件在该 profile 下的所有会话中生效，并随 DSH 重启保留。装完还需要准备 BabelDOC 运行时，再执行一次 /babeldoc key <你的 key>。
配置 API Key¶
第一次使用时直接在 deepseek harness 的会话框里执行：
/babeldoc key sk-xxxxxxxxxxxxxxxx
- 密钥写入
%USERPROFILE%\.dsh\babeldoc\settings.json，不进入会话记录（该命令声明了recordInput: false） - 命令回显只显示
sk-x...xxxx这样的掩码 - 发布插件时包里不含任何 api key，每个使用者填自己的
其它子命令：
| 命令 | 作用 |
|---|---|
/babeldoc 或 /babeldoc status |
查看运行时、接口地址、模型、密钥是否已配置 |
/babeldoc key <sk-...> |
保存 API Key |
/babeldoc model <名称> |
切换模型，如 deepseek-chat、deepseek-reasoner |
/babeldoc base <URL> |
切换 OpenAI 兼容接口地址 |
/babeldoc clear |
清除已保存的 Key |
也可以不用命令，把值写进 profile 的 cordis.patch.yml（适合统一部署）：
- id: babeldoc-on-dsh
name: babeldoc-on-dsh
config:
babeldocPath: 'C:\Users\name\.dsh\babeldoc\venv\Scripts\babeldoc.exe'
baseUrl: 'https://api.deepseek.com/v1'
model: 'deepseek-chat'
apiKey: ''
langIn: 'en'
langOut: 'zh'
outputDir: ''
qps: 4
hfEndpoint: 'https://hf-mirror.com'
extraArgs: []
读取顺序：/babeldoc 存的设置 → 插件配置 → 环境变量 BABELDOC_API_KEY / DEEPSEEK_API_KEY / OPENAI_API_KEY。
运行环境¶
插件依赖一份独立的 BabelDOC 运行时。装完插件先跑一次一键脚本，它会自动找 Python、建好 venv、装 BabelDOC，并把模型字体一起下好：
node babeldoc-on-dsh\scripts\setup-runtime.mjs
脚本是幂等的，中断或失败后重跑会从断点继续（已完成的文件校验后跳过）。它做的四步：
- 找 Python：优先 DSH 自带的 3.12，其次
py -3.12/python3.12/python3，都要求3.10 ≤ 版本 < 3.14 - 建 venv：
%USERPROFILE%\.dsh\babeldoc\venv，已存在且可用则直接复用 - 装 BabelDOC：按 USTC → 阿里云 → 腾讯云 → 华为云 → 官方 PyPI 依次尝试，命中即停；同时把
bitstring锁在<5（5.x 删掉了 BabelDOC 用到的BitStream）、把pymupdf锁在<2（2.0 的_mupdf扩展在部分 Windows 上加载失败，babeldoc一启动就崩） - 下模型字体：约 370MB，走魔搭（ModelScope）镜像，逐文件校验 sha3-256
| 参数 | 作用 |
|---|---|
--python <exe> |
指定解释器 |
--mirror <url> |
指定 PyPI 镜像 |
--no-assets |
只装运行时，不下载模型字体 |
装好后的目录形态：
C:\Users\name\.dsh\babeldoc\
venv\ 用 DSH 自带的 Python 3.12 建的虚拟环境
venv\Scripts\babeldoc.exe
模型与字体单独缓存在 %USERPROFILE%\.cache\babeldoc，不属于 venv，可以单独清理。
也可以只补下模型（例如运行时已装好、只缺资源）：
C:\Users\name\.dsh\babeldoc\venv\Scripts\python.exe babeldoc-on-dsh\scripts\seed-assets.py
适用场景与注意¶
插件适合需要批量翻译 PDF 文档（如论文、报告）并保留排版的高校师生、研究者。使用前应检查插件源码与许可证（MIT）。
插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。安装后需要执行运行环境准备脚本，并配置 API Key。
排查¶
- 报「runtime not found」：报错会列出尝试过的每个路径。插件会把配置里继承来的
C:\Users\<别人>\.dsh\...自动换成本机用户主目录再找，所以通常跑一次node babeldoc-on-dsh\scripts\setup-runtime.mjs即可；也可以让babeldocPath直接指向存在的babeldoc.exe。 - 报「needs an OpenAI-compatible API key」：先执行
/babeldoc key <你的 key>。 babeldoc.exe一启动就崩，报ImportError: DLL load failed while importing _mupdf：PyMuPDF 2.0 在部分 Windows 上加载不了这个扩展。一键脚本已固定pymupdf<2，若手动升级过，用 venv 里的解释器降回 1.26.x：
%USERPROFILE%\.dsh\babeldoc\venv\Scripts\python.exe -m pip install "pymupdf<2"- 不确定缺什么：执行
/babeldoc status，它会分别报告运行时、模型字体、Key 的状态并给出下一步。 - 翻译中途报错：结果里的
Log:指向完整日志，常见原因是余额不足、模型名不对或 PDF 损坏。 - 部分 PDF 排版错乱：调用时传
enhance_compatibility: true。
卸载¶
plugin_manager { action: "remove_bundle", target: "babeldoc-on-dsh" }
运行时目录 %USERPROFILE%\.dsh\babeldoc 与缓存 %USERPROFILE%\.cache\babeldoc 可手动删除。
