dsh-bilingual-reader

Readme

# dsh-bilingual-reader

中文 | [English](./README.en.md)

在 **DeepSeek Harness (DSH)** 的 `dsh-better-sidebar` 里阅读论文 PDF，用大模型做**划词翻译**的插件。

> 在侧边栏打开 PDF → 选中一句话复制 → 插件**结合上下文**用大模型译成中文。翻译走 DSH 现有模型，**完全隔离主对话上下文**，只作阅读辅助。

## 使用场景

- 你在 DSH 侧边栏（better-sidebar）打开一篇论文 PDF 阅读。
- 想快速弄懂某个句子 / 术语：**选中 + 复制**，插件自动翻译。
- 不想把内容丢进主对话去问 —— 翻译只发生在插件里，**不污染主对话上下文**。

## 特性

- **PDF 原生渲染**：用浏览器 / Electron 的 PDF 引擎显示原文 —— **排版完美**、可翻页、可复制，与内置阅读器一致。
- **划词翻译**：复制选中文本 → 桌面版（Electron）**自动翻译**；无法自动时点「**翻译选中**」按钮。
- **多语种互译**：源语言 / 目标语言各一个下拉框。内置**中文 / 英语 / 日语 / 韩语**，也可点「＋语言…」**手动添加任意语言**。默认目标语言跟随界面语言。
- **语种自动识别**：源语言选「**自动识别**」时，先用零成本字符集启发式判断（中 / 日 / 韩稳定）；当有**多个同文种语言**（如同时含英 / 法 / 德）或启发式读不准时，再交给大模型识别一次，结果**预填**源语言、可随时改。
- **上下文感知**：在全文里查找复制内容的**唯一位置**，取周边文字作上下文。唯一命中最准；多处出现 / 未命中则**无上下文直译**（避免错误上下文误导）。
- **上下文长度可调**：滑块控制取周围多少字作上下文。
- **设置持久化**：源语言、目标语言、上下文长度、自定义语言都会记住，下次打开直接用。
- **原文 + 译文对照**：下方同时显示复制的原文与译文，便于核对，并支持一键**复制译文**。
- **隔离主对话**：翻译走 `ctx.llm` 的一次性独立调用，**不写回主会话**，复用 DSH 已配置的模型与 API key。

> **小语种说明**：翻译质量的下限由所用大模型决定。插件通过明确源 / 目标语言名（并允许自定义语言名）来尽可能引导模型，但小语种（训练数据少）的质量上限仍在模型本身。

## 安装

```sh
dsh plugin add github:Johnblur/dsh-bilingual-reader
```

装完**彻底退出托盘里的 DSH Desktop** 再重新打开。

## 使用

1. better-sidebar 侧栏 `+` → 打开「**双语阅读**」标签（标签栏名为 `translator`，菜单内按界面语言显示 `翻译` / `translator`）。
2. 点「**浏览…**」从工作区选一个 PDF，或输入 / 粘贴路径点「**加载**」。
3. 在上方 PDF 里**选中一段文字并复制**：
   - 桌面版（Electron）：检测到剪贴板变化，**自动翻译**。
   - web 端或自动不可用时：点「**翻译选中**」按钮。
4. 下方显示 **原文 + 译文**；用「**源** / **目标**」下拉选择互译语言（源选「自动识别」可让插件判断），用「**上下文**」滑块调整取上下文的长度。

## 依赖与说明

- 依赖 DSH 运行时注入的服务（`dsh-better-sidebar`、`@deepseek-ai/dsh-llm`）与 `pdfjs-dist`（主机端取文）。
- **适配的 DSH 版本**：`@deepseek-ai/dsh-llm` **≥ 0.1.2-rc.1**（`deepFreeze` 已从 `dsh-llm` 的公开导出中移除，v1.0.2 起不再依赖它）。`dsh-better-sidebar` **≥ 0.17.1**。DSH 更新后若插件报 `does not provide an export named 'deepFreeze'`，需升级插件到 v1.0.2+。
- **复用 DSH 现有模型与 API key**（无需额外 key），可用环境变量覆盖：
  - `DSH_BILINGUAL_PROVIDER`（默认 `deepseek-official`）
  - `DSH_BILINGUAL_MODEL`（默认 `deepseek-v4-flash-vision-exp`）
- 「自动翻译」依赖主机读取系统剪贴板（Electron 桌面版）；纯 web 端没有该能力，走按钮。

## 本地构建（给开发者）

```sh
pnpm i
pnpm build      # tsdown -> lib/ + tsc -> lib/types
pnpm test       # vitest：纯逻辑 + 隔离测试
```

## 常见问题

- **复制后不自动翻译**：确认用的是桌面版（Electron）；或直接点「翻译选中」按钮。
- **译文没用上下文**：选中的词在文中出现多次 / 没匹配到唯一位置 → 插件主动用无上下文直译，避免错误上下文。
- **想更准**：选中**一整句**而不是单个词，通常能唯一匹配、上下文更准。
- **重新打开后标签还是旧标题**：旧标签是开标签时固化的标题；关掉该标签重新通过 `+` 打开即可显示 `translator`。

## License

MIT