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 模式自动挑可翻译内容，不误翻公式与代码：先做结构化切片，只把自然语言送去翻译； 公式（$…$、$$…$$、\(…\)、\[…\]）、代码（``` 围栏、行内、缩进块）、URL、邮箱原样保留。
• 自选目标语言：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，agent 可以直接调用。

目录结构

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 -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 -ExecutionPolicy Bypass -File .\install.ps1
   # macOS / Linux：
   # node install.mjs
   

3. 让 DSH 装上这个 bundle（任选其一）：

   • 让 DSH 里的 agent 执行：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」。

模型工具：

// 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 }

自测

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 模式可复用当前 profile 的登录凭据。