BiRead 面向技术教材、论文集和专著的中英阅读：把“一本英文书等机器翻译”和“已经有官方中译本的两本书”明确分成两条路径，再在同一个双栏阅读器中阅读、跳转和校对。
它不是在线网盘，也不是通用 OCR 平台。PDF、OCR 结果、书库数据库、翻译缓存与 API key 都留在本机项目目录；只有用户主动发起翻译时，选定范围的文字才会交给 DeepSeek。
技术教材的中英文对照常有两个不同问题：
- 已有英文原版和正式中文译本时，重点是让两本页数不同的书按章节、节和阅读位置对齐，方便校对与对照阅读；它们不是“英文书 + 待生成译文”。
- 只有英文书时，机器译文可以作为快速辅助，但必须先处理扫描页、先验证少量样例，并且能在中断后续跑，避免整书重新计费。
BiRead 因此把导入语义、后台任务和阅读映射分开：官方配套书走“对比阅读路径”；英文孤本走“OCR / 翻译路径”。两条路径最终使用同一套双栏阅读控制，但不会互相伪装成翻译对象。
| 使用场景 | 导入内容 | 结果 |
|---|---|---|
| 单本阅读 | 任意一份 PDF | 单栏 PDF 阅读 |
| 官方中英配套 | 英文原版 + 中文译本 | 一个 paired 书目、双栏对照、目录锚点 |
| 仅有英文版 | 英文 PDF | 扫描检测 → 可选 OCR → 五页样例 → 可选整书机器翻译 |
- 两栏各自保留真实页码、页数、目录和阅读进度；页码不必相同。
- 有目录的官方双版本按章节/节编号生成严格单调锚点；从任一侧目录跳转时，另一侧跳到对应位置，区间内按锚点插值同步。
- 没有可靠目录匹配时，只使用首尾粗略锚点并显示“等待校对”，不会假装已经精确对齐。
- 每栏可直接输入页码、前后跳 10 页、打开目录并点击跳转；页码字号独立于页面缩放。
- 同步滚动只由用户滚动或跳页触发，可用快捷键开关；没有“无人操作时页面自己向下滚”的自动滚动。
- 本地 PDF.js 虚拟化渲染与 HTTP Range 响应，避免一次性加载整本 PDF。
- 导入时对最多 12 个页面抽样，区分
text、mixed与scanned；文字很少的封底或元数据页不会掩盖扫描书。 - 可在本机用 RapidOCR + ONNX CPU 为扫描英文 PDF 添加隐藏文字层，原页面图像和公式画面不变；也可上传同版式的可搜索 OCR PDF。
- 先从正文约 10% / 30% / 50% / 70% / 90% 自动选取 5 页翻译样例，再决定是否支付整书成本。
- 使用 PDFMathTranslate-next / BabelDOC 与 DeepSeek V4 Flash；先调用余额接口验证 key，不产生生成 token，也不展示或保存余额。
- 整书翻译需在样例确认后再次确认。任务按 16 页分块，源文件、翻译配置和输出哈希都一致的块才可复用；中断后重新验证 key 即可从未完成块继续。
- 发布完整译本前检查文件可打开性、完整页数、页面几何与基本空页结构；发布步骤带回滚保护，不会直接破坏已经可读的样例。
在 Windows 中双击 启动双语PDF阅读器.cmd。首次启动会在项目内的 .venv/ 与 .cache/ 准备运行环境，然后打开：http://127.0.0.1:8765/。
结束时双击 停止双语PDF阅读器.cmd。服务只绑定 127.0.0.1，不会对局域网公开。
已有英文和中文两本书：选择“中英配对”，一次上传英文原版和官方中文译本。它们将始终作为一个书目存在；进入书目后可选择只看英文、只看中文或对比阅读。若 PDF 自带目录，系统会用目录编号生成可跳转大纲和同步锚点。
只有英文版：选择“翻译”。如果检测为扫描版，先双击 安装OCR引擎.cmd，再在页面执行“准备 OCR → 开始本机 OCR”。OCR 不调用付费 API。随后双击 安装翻译引擎.cmd 安装本地翻译器，再输入 DeepSeek API key 并点击“验证”。
- 点击“制作五页样例”。key 仅保留在这次后台任务的内存里，不写浏览器存储、SQLite、命令行或日志。
- 在双栏中检查正文、公式、图表和版式；样例不满意时不要开始整书翻译。
- 确认样例后，选择“翻译全书”，再次验证 key 并确认页数。服务会发放仅限该书、该 key 和 15 分钟内使用一次的授权。
- 长任务不自动刷新页面。点击“手动刷新”查看分块完成情况；阅读器操作或关闭浏览器不会打断后台翻译。停止本地服务、系统休眠或重启后，重新启动服务并验证 key 即可继续。
- 钱德勒《现代统计力学导论》：英文 286 页、中文 271 页，合并为一个双语书目；生成 88 个严格单调锚点和可跳转大纲。
- Shankar《量子力学原理（第 2 版）》：英文 679 页、中文 644 页，生成 105 个锚点；第 12 章的跳转稳定落在英文第 319 页、中文第 309 页。
《An Introduction to Tensors and Group Theory for Physicists》共 257 页。原始 PDF 被正确识别为扫描版；本机 OCR 后，先完成五页视觉核验，再完成 17 个翻译分块（每块 16 页，最后一块 1 页）。合并后通过 257/257 页、页面几何和结构 QA，成为同页双栏的机器译本。
这次整书翻译的 DeepSeek 实际费用为 ¥4.88。运行中账户页曾显示 858 次 API 请求、2,311,858 tokens 与 ¥3.67，但该面板有延迟且汇总全部 API key；请求数是版面中标题、正文、图注、表格及公式邻近文本的分段数，不能等同于页数或重译次数。
- 进度看起来不动不等于挂起。 进度只在一个 16 页块完成并通过 QA 后更新；正文和公式密集的块可能持续数分钟。应手动刷新，勿重复提交任务。
- 浏览器不是翻译执行器。 翻译由本地 FastAPI 服务与
pdf2zh_next子进程完成；浏览、关闭浏览器或刷新任务页面不会影响后台任务。 - 结构 QA 不是人工视觉 QA。 它证明 PDF 可打开、页数和几何合理；公式、图像遮盖和少量复杂页仍应在阅读器中抽样检查。
- OCR 不承诺公式语义。 RapidOCR 的隐藏文字层服务于翻译输入和检索，公式、图和原始版面仍以 PDF 页面为准；MinerU 的重排 Markdown/JSON 不能直接替代同版式 OCR PDF。
- 目录不足时不能凭空精确对齐。 当前可提取或匹配 PDF 大纲并生成粗略回退锚点，但尚没有图形化的人工锚点修订器。
- 已修复测试对真实任务的影响。 测试服务现在被固定到独立临时数据目录，不会再把正在运行的真实翻译任务误标为中断。
$env:UV_CACHE_DIR = "$PWD\.cache\uv"
uv sync --extra dev
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check src tests翻译生命周期与断点续作细节见 docs/translation-pipeline.md，HTTP 接口见 docs/api-contract.md。
*.pdf、storage/、数据库、API key、模型、缓存、日志和本地环境都由.gitignore排除；请勿提交受版权保护的教材或个人凭据。- API key 仅用于用户主动开始的样例或整书翻译，不属于项目配置，也不应写入 issue、截图或提交记录。
- 本仓库包含 PDF.js 解码资源及其许可证；使用 RapidOCR、PDFMathTranslate-next、BabelDOC、DeepSeek 等上游组件时，请分别遵守其许可证与服务条款。
主要上游：PDF.js、RapidOCR、PDFMathTranslate-next、BabelDOC。DeepSeek key 预检使用官方 GET /user/balance 接口。