翻译面板 jcy0chenyuan0/dsh-plugin-translate

dsh-plugin-translate

给 DeepSeek Harness（DSH） 加上翻译能力：聊天区顶部右侧只有一个「🌐 翻译」按钮，鼠标放上去翻译面板自动展开，移开自动收起（点一下＝翻译最新回复并钉住面板）。

- 两种模式任选：
1. 任意 AI 的 API —— OpenAI 兼容的 baseUrl + apiKey + model（也可切 anthropic 风格 /v1/messages），可接 OpenAI / Kimi / Qwen / GLM / OpenRouter / 本地 Ollama / LM Studio 等；
2. 直接接入 DeepSeek —— 有 API Key 走 OpenAI 兼容端点；没有 Key 时自动复用当前 profile 已登录的 DeepSeek 账号凭据（和 harness 自带的 dsh-llm-deepseek-account 同一套取凭据方式）。
- AI 模式自动挑可翻译内容，不误翻公式与代码：先做结构化切片，只把自然语言送去翻译；
公式（$…$、$$…$$、\(…\)、\[…\]）、代码（- 自选目标语言：13 种（zh-Hans / zh-Hant / en / ja / ko / fr / de / es / it / pt / ru / ar / hi）。
- 论文 PDF 翻译：识别 PDF 文字块与精确位置，逐块翻译后写回原位置，另存为 <文件名>_t.pdf （页数不变；公式、代码、图、未翻译内容保持原样）。扫描版（无文字层）不做 OCR，会明确报告。
- 同一个能力也暴露成模型工具：translate_text、translate_pdf，智能体可以直接调用。

目录结构

dsh-plugin-translate/
├─ package.json # bundle + dsh.client 声明 ├─ cordis.patch.yml.tpl # profile 补丁层模板（install 脚本生成 cordis.patch.yml） ├─ lib/ │ ├─ translate-host.js # Host 实现：两种 provider、切片器、PDF 流水线、/api 路由 │ ├─ index.js # 只为 main/exports 转发，内容等价于 export * from "./translate-host.js" │ ├─ client.js # Client 半边（预打包好的浏览器 bundle） │ └─ pdfhelper.py # PyMuPDF 助手：extract（抽块）/ render（涂白写译文） ├─ locale/zh.json, locale/en.json ├─ icon.svg ├─ test/ │ ├─ smoke.mjs # Host 纯函数 + provider 请求成形 + 工具 schema（34 项） │ ├─ client-bundle.mjs # 无浏览器跑 client bundle（14 项） │ ├─ e2e.mjs # 真跑 Python + 真写 PDF（9 项） │ ├─ pdf-helper.test.py # PDF 助手（127 项） │ └─ fixtures/ # 测试用 PDF ├─ install.ps1 # Windows：按当前目录生成 cordis.patch.yml └─ install.mjs # macOS/Linux：同上

安装

首次安装：先在本目录运行 install.ps1（Windows）或 node install.mjs（macOS/Linux）。
脚本按当前目录自动生成 cordis.patch.yml（已 .gitignore），不写死任何盘符。

缺少环境怎么办（默认自动安装）

安装时 install.ps1 默认静默安装缺失环境；只想检查时加 -CheckOnly： powershell powershell -ExecutionPolicy Bypass -File .\install.ps1 只检查、不安装： powershell -ExecutionPolicy Bypass -File .\install.ps1 -CheckOnly

插件加载时也会在后台运行 bootstrap.ps1 -AutoInstall -Quiet（6 小时内不重复），不阻塞 DSH 启动；首次装完可能需要重试工具。

- Python：优先用 DSH 自带运行时；没有则 winget install Python.Python.3.12 --scope user。
- PyMuPDF：& "<python>" -m pip install pymupdf（外部 Python 可加 --user）；只做纯文本翻译时不需要。
- 也可用 DSH_PYTHON 或 config.pythonPath 指定带 PyMuPDF 的解释器。
- 关闭自动安装：patch 的 config 里设 autoInstall: false，或设置环境变量 DSH_BOOTSTRAP=0。

1. 把整个目录放到任意位置（例如 %USERPROFILE%\.dsh\plugins\dsh-plugin-translate）。
2. 在该目录里运行一次安装脚本，它会按当前目录自动生成 cordis.patch.yml（不写死盘符）：

powershell
powershell -ExecutionPolicy Bypass -File .\install.ps1
macOS / Linux：
node install.mjs

3. 让 DSH 装上这个 bundle（任选其一）：
- 让 DSH 里的智能体执行：plugin_manager install_bundle file:<该目录的绝对路径>；
- 或按 cordis.patch.yml 里 insert 的内容，手工把这一行加到 <profile>/cordis.patch.yml（例如 %USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml）。

装完后在 GUI 的「设置 → 插件」里能看到 dsh-plugin-translate，可整体启用/停用。
改完 lib/translate-host.js 想立刻生效：换一个没被加载过的实现文件名（例如 translate-host2.js）并同步改 cordis.patch.yml 的 name，再重新 install_bundle —— loader 按模块路径缓存 ES 模块，换路径即可免重启换新代码。

配置

cordis.patch.yml 的 config（全部可选，省略即默认值）：

| 键 | 默认 | 说明 |
| mode | auto | auto / deepseek / custom / microsoft；auto 依次尝试 DeepSeek 直连 → 任意 AI → 微软 |
| target | zh-Hans | 默认目标语言 |
| aiBaseUrl aiApiKey aiModel | 空 | 任意 AI 的 API：OpenAI 兼容地址（如 https://api.openai.com/v1）、Key、模型名 |
| aiStyle | openai | openai / anthropic（后者走 /v1/messages） |
| deepseekApiKey deepseekModel | 空 | DeepSeek 直连：留空则用当前 profile 登录的 DeepSeek 账号 |
| deepseekBaseUrl deepseekAccountBaseUrl | https://api.deepseek.com / .../anthropic | 端点 |
| useAccountCredential | true | 是否允许复用 DeepSeek 账号凭据 |
| microsoftKey microsoftRegion | 空 | 可选附加：微软翻译；配了 Key 才会在面板里出现该模式 |
| batchChars batchItems | 1800 / 12 | 单次请求的字符数与条数上限 |
| maxOutputTokens | 16384 | AI 输出上限（推理模型把额度花在思考上时会自动拆批重试） |
| timeoutMs | 60000 | 单次请求超时 |
| maxChars maxPdfPages maxPdfBlocks | 20000 / 300 / 4000 | 文本与 PDF 规模上限 |
| pythonPath | 空 | 指定带 PyMuPDF 的 Python；留空则自动搜索 DSH 自带 runtime → PATH 上的 python / python3，也支持环境变量 DSH_PYTHON |

也可以用环境变量：AI_BASE_URL / AI_API_KEY / AI_MODEL / AI_STYLE、DEEPSEEK_API_KEY、 MS_TRANSLATOR_KEY / MS_TRANSLATOR_REGION。

用法

GUI：聊天区顶部右侧的「🌐 翻译」→ 悬停展开面板 → 选模式与目标语言 → 点按钮翻译最新回复；选中聊天里的文字后点面板里的「翻译选中」；面板底部填 PDF 路径 → 「翻译 PDF 并另存为 _t.pdf」。

模型工具： jsonc // translate_text { "text": "……", "target": "en", "mode": "deepseek" }

// translate_pdf —— 另存为 <原文件名>_t.pdf（可用 out 指定路径 / dryRun 只体检） { "path": "<PDF 路径>", "target": "zh-Hans" } { "path": "<PDF 路径>", "target": "zh-Hans", "dryRun": true }

自测

powershell
node test/smoke.mjs # Host：34/34
node test/client-bundle.mjs # Client bundle：14/14（无浏览器）
node test/e2e.mjs # PDF 端到端：真跑 Python、真写 _t.pdf（需 PyMuPDF）
DSH_PYTHON=<带 PyMuPDF 的 Python> node test/e2e.mjs
<带 PyMuPDF 的 Python> test/pdf-helper.test.py # PDF 助手：127/127

已知限制

- 扫描版 PDF 不做 OCR：没有文字层就没有可翻译内容，会明确列出 pagesWithoutText。
- 版面溢出：原文是中文、译文是英文时，英文更长，个别标题/表头放不进原矩形；助手会尽量缩小字号，仍放不下的块会出现在 overflow 警告里（其余正文照常）。
- 第一次请求可能偏慢：推理型模型偶发「200 但空响应体」，插件会自动退避重试并逐级拆批。
- 只翻译正文块；图片里的文字、矢量图标注不处理。

可移植性 / 换机器安装

这个仓库不包含本机绝对路径或 API Key：cordis.patch.yml 由安装脚本按当前目录生成（已 .gitignore），Key 通过 config 或环境变量传入。

换一台机器：

1. git clone 本仓库到任意目录；
2. 运行 powershell -ExecutionPolicy Bypass -File .\install.ps1（Windows）或 node install.mjs（macOS/Linux）；
3. 在 DSH 里执行 plugin_manager install_bundle file:<本目录的绝对路径>；
4. 需要 PDF 翻译时，确保有带 PyMuPDF 的 Python，或在 patch 的 config.pythonPath 指定解释器。

运行环境

- Windows / macOS / Linux 均可：Host 与 Client 都是 Node/浏览器代码。
- PDF 翻译需要 PyMuPDF（pip install pymupdf）；纯文本翻译不需要。
- 不落盘保存 API Key；DeepSeek 模式可复用当前配置档的登录凭据。