@ggboy123/dsh-paper-reader 1.4.1 → 1.5.1

package/README.md

@@ -7,7 +7,7 @@
 
 **English**: [README_EN.md](README_EN.md)
 
-[DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件：**论文伴读工作台** —— 文献库 + PDF 阅读器 + AI 伴读，回答自带页码、点页码跳回原文。当前版本 **v1.4.1**。
+[DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件：**论文伴读工作台** —— 文献库 + PDF 阅读器 + AI 伴读，回答自带页码、点页码跳回原文。当前版本 **v1.5.1**。
 
 > 💬 **QQ 交流群：1127244508** —— 安装/使用问题、功能建议、bug 反馈都欢迎来聊。
 
@@ -19,14 +19,16 @@
 
 ## 核心能力
 
-- 📚 **三栏工作台**：专题 → 论文文献库、居中 PDF 阅读器（缩放 / 适宽 / 滚动 ↔ 单页翻页 / 键盘翻页）、右侧原生对话
-- 💬 **带页码的伴读**：回答必带页码，点页码平滑跳回 PDF 对应位置并高亮；选中文字即问；🕐 回看历史对话、＋ 新开对话
-- 🤖 **教练式带读**：paper 会话自动用专用 preset——定分步阅读计划、逐节指导、出题批改，学习进度跨会话累积
-- 🀄 **中文版**：原文 ↔ 纯中文原地切换（babeldoc 零预装，自动安装），译文 PDF 一键导出（纯中文 / 中英对照）
-- 🗂️ **文献管理**：专题/论文改名、删除（删除前列文件清单、进回收站**可恢复**、非空专题批量清空一次确认）
-- ➕ **两个可选增强**（默认关，见「进阶」）：MinerU 解析——扫描件可读、公式可点引用可检索；语义检索端点——大白话命中术语段落
+- 📚 **三栏工作台**：专题文献库 + PDF 阅读器 + 右侧原生对话；安装后不改动官方界面，侧栏只多一行开关
+- 💬 **带页码的伴读**：回答必带页码，点页码跳回原文并高亮；选中文字即问；支持历史对话
+- 🤖 **教练式带读**：专用 preset 定分步阅读计划、逐节指导、出题批改，学习进度跨会话累积
+- 🀄 **一键中文版**：原文 ↔ 纯中文原地切换，译文 PDF 一键导出（纯中文 / 中英对照），翻译引擎零预装自动安装
+- 🈯 **划词翻译（公式保留）**（v1.5.1）：选中点「译」出纯译文气泡；选区含公式时用 MinerU 识别的 LaTeX 替换文本层乱码、要求模型原样保留
+- 🖥️ **中英对照 / 分屏**（v1.5.1）：并排对照页或左右分屏同步滚动，随时切换、按文献记忆
+- 🗂️ **文献管理**：专题/论文改名、删除进回收站可恢复
+- ➕ **可选增强**（默认关）：MinerU 解析——扫描件可读、公式可点引用可检索；嵌入端点——大白话命中术语段落
 
-安装后**不改动官方界面**：侧栏底部多一行「📚 论文伴读」开关，点击才进入伴读模式，再点即还原。
+各功能的前提与配置细节见 [docs/features.md](docs/features.md)。
 
 ## 安装
 
@@ -39,86 +41,36 @@
 
 完成。侧栏底部点「📚 论文伴读」进入文献库，上传 PDF 开始用。
 
-完整流程演示（添加插件 → 启用 → 重启 → 打开论文直接提问）：
-
 ![官方桌面端安装并使用论文伴读插件](https://raw.githubusercontent.com/GGboya/dsh-paper-reader/main/docs/desktop-official-use.gif)
 
-> 已在官方桌面端 V0.2.0-rc.2（内置 dsh 0.2.0-rc.2，macOS arm64）实测通过。
-> 需要 ≥1.2.0：更早版本会被 0.2.x 运行时的 peer 兼容校验拒载（插件列表里显示异常）。
-
-> 想直接在客户端里逛插件市场（4000+ 插件、分类、评论、一键安装），可另装社区插件 [`dshmarket`](https://github.com/dsh-market/dsh-market)，本插件已在其目录中。
+> 已在官方桌面端 V0.2.0-rc.2（内置 dsh 0.2.0-rc.2，macOS arm64）实测通过；插件需 ≥1.2.0。
+> 想逛插件市场可另装社区插件 [`dshmarket`](https://github.com/dsh-market/dsh-market)，本插件已在其目录中。
 
-**排坑（都是实测踩过的）**：
+**排坑**（都是实测踩过的）：
 
-- **升级后插件开关会回到停用**：侧栏 → 插件 → 打开「启用」→ 重启。症状有迷惑性——文献树还在但点论文没反应，其实是没启用
-- **添加时务必带 `@latest`**：不带版本号对已装过的插件是 no-op（dsh 的插件管理器按首次记录的版本处理，不会追新）
-- pnpm 若开了供应链策略 `minimumReleaseAge`（发布 N 小时内的新包拒装，桌面端默认开）：等过窗口期，或在 `~/.dsh/profiles/web/.npmrc` 加 `minimum-release-age-exclude[]=@ggboy123/dsh-paper-reader`；桌面端的豁免清单在 `~/.dsh/profiles/desktop/pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude`
-- 旧版 PaperReader 桌面版（社区 DSH Desktop 预装打包）**已停止维护**，请迁移到本方式
+- **升级后插件开关会回到停用**：重新打开「启用」并重启。症状有迷惑性——文献树还在但点论文没反应
+- **添加务必带 `@latest`**：不带版本号对已装过的插件是 no-op，不会追新
+- pnpm 供应链策略 `minimumReleaseAge` 拦新包时：等过窗口期，或把本包加进豁免清单（`~/.dsh/profiles/web/.npmrc` 的 `minimum-release-age-exclude[]`；桌面端在 `~/.dsh/profiles/desktop/pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude`）
 
 ### 开发者：命令行 dsh
 
 ```bash
-dsh plugin --profile web add @ggboy123/dsh-paper-reader@latest
+dsh plugin --profile web add @ggboy123/dsh-paper-reader@latest   # 升级也是这条；不带版本号是 no-op
 ```
 
-> npm 包名走 `@ggboy123` 作用域：裸名 `dsh-paper-reader` 已被另一个插件占用。
 > 不要用 `github:GGboya/dsh-paper-reader` 安装 —— dist 不入库，git 安装会导致 profile 起不来。
 
-**升级**也用 `@latest`（或显式版本号）——不带任何版本的 `add` 对已装依赖是 no-op：
-
-```bash
-dsh plugin --profile web add @ggboy123/dsh-paper-reader@latest   # 永远装最新
-grep '"version"' ~/.dsh/profiles/web/node_modules/@ggboy123/dsh-paper-reader/package.json   # 查当前版本
-# 重启 dsh web 生效；浏览器 Cmd+Shift+R 强刷，避免旧阅读器页面缓存
-```
-
 ## 怎么用
 
-1. **进入**：侧栏底部点「📚 论文伴读」——左侧变为文献库树（再点还原官方工作区列表）
-2. **入库**：＋ 新建专题 → ⬆ 上传 PDF（空库直接点「上传 PDF」会自动建「默认专题」）
-3. **读 + 问**：点论文打开——中间阅读器、右侧对话。直接在输入框提问（无需点名论文，回答自带页码），或**选中论文里的文字**直接弹框提问；点回答里的「第 N 页」跳回原文
-4. **中文版**：顶栏「中」——没译文时一键生成（首次自动装翻译引擎，需在弹出的表单里配一次 OpenAI 兼容端点，DeepSeek/GLM/Kimi 的 key 都行）；⤓ 下载当前版本 PDF；▣ 单页翻页 ↔ 滚动
-5. **管理**：行悬停出 ✎ 改名 / 🗑 删除。删除会先列出将处理的文件清单，确认后**移入回收站**（`data/.trash/`，可手工恢复）；非空专题删除 = 批量清空清单一次确认
-6. **对话**：对话头部 🕐 看该论文的历史对话、＋ 新开一个
-
-## 进阶（可选，默认关闭）
-
-### MinerU 解析：扫描件可读、公式可点引用
-
-默认用本地 pdf.js 提取文本——**普通文本型 PDF 完全够用，什么都不用配**。两类场景需要 MinerU：
-
-- **扫描版 PDF**（老论文、书章、扫描讲义）：没有文本层，pdf.js 读不了，MinerU（OCR）能读
-- **公式**：PDF 里公式是图形乱码，选不中也搜不到。**公式引用**——MinerU 把公式识别成 LaTeX 后，点 PDF 上的公式即引用进对话提问；`QK^T` 这类公式检索也能命中；顶栏「∑ 公式」面板按页浏览全文公式
-
-**需要自己准备（二选一）**，在 **设置 → 论文伴读 → 「MinerU 解析后端」** 里配置：
-
-| 方式 | 准备 | 适合 |
-| --- | --- | --- |
-| 云端（最简单） | 到 [mineru.net](https://mineru.net) 注册 → 站内「API 管理」创建 token → 设置里模式选「云端」、粘 token、「测试连接」→ 保存。约 1 分钟，免费额度 | 大多数人 |
-| 本地自建（免注册） | `pip install -U "mineru[core]"` → `mineru-api --host 127.0.0.1 --port 8000` → 设置里模式选「本地」 | 重度/隐私敏感；免费无限、论文不出本机 |
+1. **进入**：侧栏底部点「📚 论文伴读」（再点还原）
+2. **入库**：＋ 新建专题 → ⬆ 上传 PDF
+3. **读 + 问**：直接提问（回答自带页码），或选中文字弹框提问；点「第 N 页」跳回原文
+4. **中文版**：顶栏「中」一键生成（首次需在弹出表单里配一次 OpenAI 兼容端点，DeepSeek/GLM/Kimi 的 key 都行）
+5. **管理**：行悬停出 ✎ 改名 / 🗑 删除；对话头部 🕐 历史、＋ 新开
 
-配置好后：新上传的扫描件自动走 MinerU；已入库的论文在「∑ 公式」面板里点「用 MinerU 重新转录」即可（**旧缓存不会自动重录**，想要公式可搜需对那篇显式重录一次）。
+## 文献管理（安全说明）
 
-> 说明：云端 `pipeline` 通道已用真实 token 端到端实测（19 页论文，18/18 公式与本地一致）；`vlm` 系列模型未验证。token 落盘 0600，界面只回掩码。常见报错排查见 [docs/reader-ux-requirements.md](docs/reader-ux-requirements.md)。
-
-### 嵌入语义检索
-
-给 `search_paper` 接一个 OpenAI 兼容 `/embeddings` 端点（设置 → 论文伴读 →「嵌入模型检索（可选）」卡片，填 URL/模型/Key，保存前会真打一发预检）：关键词一个没命中的**语义相近**片段也能进候选——大白话提问（「训练时怎么调学习率」）命中术语段落，与关键词结果融合、不替代。不配（或只配一半）= 默认关闭，一条请求都不发，检索行为与原来完全一致。
-
-> ⚠️ **隐私提示**：启用后，两类文本都会发送到你配置的那个端点——① 论文的分块文本（正文片段，算分块向量）；② 检索时的查询文本（每次检索的提问，算查询向量）。端点必须是你要信任的服务；不配则一条请求都不发。
-
-配置三选一（优先级同翻译端点）：设置面板（推荐）> profile YAML `config.embed` > 环境变量 `DSH_EMBED_API_KEY`（只补 key）。向量缓存在 `<专题>/<论文名>.embeddings.json`（只存向量：不含明文 key、不含查询文本），按端点/模型/内容哈希失效——换端点、换模型、重新转录后自动重算；分块按 `batchSize`（默认 32）提交，任一批失败整体降级、不落盘。端点本次不可达时照常返回关键词结果并标注降级原因，不静默失败。
-
-> **非目标**（留后续）：本地 ONNX / transformers.js 嵌入模型、全库预计算、向量数据库——本轮只做 API 端点。
-
-## 文献管理细则
-
-- 删除 = **移入回收站** `data/.trash/<时间戳>/`（带 manifest 清单），把文件移回专题目录即恢复；本版不自动清理、无一键恢复 UI
-- 会被移入回收站的文件 = 该文献的全部同名产物：`<文献>.pdf`、`.txt`、`.pages.json`、`.transcript.json`、`.mineru.md`、`.mineru.json`、`.embeddings.json`、`.study.json`，以及译文变体 `<文献>-en.pdf` / `-zh.pdf` / `-dual.pdf`（含中断残留的 `.tmp-*`）；伴读会话历史**不删**（存在 dsh 会话库里）
-- **前置拒绝**：该文献有运行中的会话、正在生成译文、或同篇已有删除/改名在进行中时，操作会被拦（防止删掉正在用的东西）
-- **安全边界**：删除/改名只作用于文献库目录内；路径穿越（`..`、绝对路径、符号链接逃逸）一律拒绝；中途失败自动回滚已移动的文件
-- 改名后：转录缓存/译文/学习档案全部跟随搬家；历史伴读会话**本体保留**但不再挂在新名字下（会话 id 编码旧名）；纯大小写改名在 macOS/Windows 可用
-- 手工放进 `data/` 的怪名字文件（如 `.hidden.pdf`）也能正常删除/改名，不会成为孤儿
+- 删除 = **移入回收站** `data/.trash/`（带 manifest，移回即恢复）；会处理该文献的全部产物：`<文献>.pdf`、`.txt`、`.pages.json`、`.transcript.json`、`.mineru.md`、`.mineru.json`、`.embeddings.json`、`.study.json` 与译文变体 `<文献>-en.pdf` / `-zh.pdf` / `-dual.pdf`（含 `.tmp-*` 残留）；伴读会话历史不删。运行中会话/翻译中的文献会被前置拒绝；路径穿越一律拒绝、失败自动回滚——细则见 [docs/features.md](docs/features.md)
 
 ## 参与开发
 
@@ -129,37 +81,19 @@ dsh plugin --profile web add ./dsh-paper-reader   # 从父目录执行，或用
 dsh --profile web                                  # 侧栏变为文献库树
 ```
 
-![参与开发：clone → pnpm install → build → 本地安装](https://raw.githubusercontent.com/GGboya/dsh-paper-reader/main/docs/dev-workflow.gif)
+改完 `pnpm run build` 重启 profile 即生效；`npm test` 跑全量测试（354 用例，CI 三平台）。架构、测试守卫与开发约定见 [AGENTS.md](AGENTS.md)。
 
-- 改完 `pnpm run build` 重启 profile 即生效；`npm test` 跑全量测试（354 用例，CI 在 ubuntu/macos/windows 三平台跑）
-- 文献库目录默认 `~/.dsh-paper-reader/data`，在 profile 的 `cordis.patch.yml` 里可改（可直指 pdfqa 的 `data/` 复用旧缓存）；翻译/MinerU/嵌入端点优先在设置 UI 里填（存 `$DSH_HOME/.dsh-paper-reader/` 下，0600），YAML 里的 `config.translate` / `config.mineru` / `config.embed` 退为部署方默认值
-- 翻译引擎冒烟（Windows 依赖完整性，无需本地 Windows）：`pnpm smoke:engine clean|managed-uv|pip-fallback|repair|translate`，CI 全新干净机器每周一定时跑
+## 贡献者
 
-## 架构
+感谢每一位贡献者：
 
-```
-src/
-  index.ts      Cordis 壳：inject tools；webServer 等服务就绪后挂路由
-  tools.ts      5 个 agent 工具：list_papers / transcribe_pdf / search_paper / study_progress / study_update
-  host.ts       webServer 路由（/paper-reader/*），connection.requestRejection 鉴权；
-                sessionController.create/prompt（agentPreset=paper-reader）+ follow SSE 桥
-  library.ts    纯函数：文献库目录约定与解析（.txt/.pages.json/.transcript.json/.mineru.* 产物路径）
-  library-manage.ts 纯函数：删除/重命名（回收站、精确 stem、路径穿越防护、批量清空）
-  transcribe.ts 纯函数：pdf.js 提取 + 页码偏移表 + MinerU 后端选择与缓存来源语义
-  mineru.ts     纯函数：MinerU 客户端（本地 /tasks 轮询；mineru.net v4 云端 + 最小 ZIP 读取器）
-  mineru-config.ts / embed-config.ts / translate-config.ts / typesafe-config.ts 纯函数：各端点配置读写（0600）+ 预检
-  search.ts     纯函数：分段 + 关键词打分 + 公式查询归一化 + 嵌入混合召回
-  embed.ts      纯函数：/embeddings 客户端 + 分块向量缓存
-  formulas.ts   纯函数：MinerU 公式索引（LaTeX + bbox → 阅读器热区/面板）
-  study.ts      纯函数：学习档案（计划 + 检验成绩）读写
-  translate.ts  纯函数：babeldoc 调用（中文/中英对照 PDF 生成）
-  babeldoc-install.ts 纯函数：无 Python 环境时自动安装 babeldoc（uv → 托管 Python → venv）
-  rerank.ts     纯函数：search_paper 语义重排（TypeSafe/Jev，无凭据时退回关键词排序）
-  preset.ts     纯函数：自带 agent preset 安装到 $DSH_HOME/.agent-presets/
-presets/paper-reader/  「论文伴读」agent preset（persona 完整提示词 + compaction）
-reader/index.html      阅读器页面（pdf.js，独立于 React 宿主，iframe 承载）
-lib/client.js          浏览器半边：文献库树(sidebar.workspaces 接管) + PDF 页签 + 主面板
-```
+<a href="https://github.com/GGboya/dsh-paper-reader/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=GGboya/dsh-paper-reader" alt="贡献者头像墙" />
+</a>
+
+## Star 趋势
+
+[![Star 趋势图](https://api.star-history.com/svg?repos=GGboya/dsh-paper-reader&type=Date)](https://star-history.com/#GGboya/dsh-paper-reader&Date)
 
 ## License
 

package/dist/babeldoc-install.js

@@ -217,13 +217,17 @@ const CN_MIRRORS = [
     'https://mirrors.aliyun.com/pypi/simple/',
     'https://mirrors.cloud.tencent.com/pypi/simple',
 ];
+// babeldoc 依赖 bitstring>=4.3.0 无上界，而 bitstring 5.0（2026-10 发布）删除了 BitStream，
+// babeldoc 的 pdf_creater.py 仍在 `from bitstring import BitStream` —— 裸装必装出残缺 venv。
+// 上游修掉该 import 或锁上界后可移除此 pin。
+const BITSTRING_PIN = 'bitstring<5';
 async function pipInstallBabeldoc(py) {
     await run(py, ['-m', 'ensurepip', '--upgrade'], { timeout: 5 * 60_000 });
     let lastErr = null;
     for (const m of CN_MIRRORS) {
         try {
             await run(py, [
-                '-m', 'pip', 'install', '--no-cache-dir', '--timeout', '120', '--retries', '3', '-i', m, 'babeldoc',
+                '-m', 'pip', 'install', '--no-cache-dir', '--timeout', '120', '--retries', '3', '-i', m, 'babeldoc', BITSTRING_PIN,
             ], { timeout: 30 * 60_000 });
             return;
         }
@@ -260,7 +264,7 @@ async function installBabeldoc(uv, venvDir, onPhase) {
         await viaPipFallback(null);
     else {
         try {
-            await run(uv, ['pip', 'install', '--python', py, 'babeldoc'], { timeout: 20 * 60_000 });
+            await run(uv, ['pip', 'install', '--python', py, 'babeldoc', BITSTRING_PIN], { timeout: 20 * 60_000 });
         }
         catch (uvErr) {
             await viaPipFallback(uvErr);

package/dist/formulas.js

@@ -19,6 +19,51 @@
 //   `\text{}`/`\textrm`/`\mbox` 一族按既有规则整组原样保留（组内空格是排版语义）。
 import { readFile, stat } from 'node:fs/promises';
 import { compressMathSpaces, normalizeMathBraces } from "./mineru.js";
+/** 从 `.mineru.json` 的原始文本建 text 块索引（只收含 `$` 的块）。 */
+export function buildTextBlockIndex(raw) {
+    if (raw === null)
+        return { source: 'none', blocks: [], reason: 'no-mineru-artifact' };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { source: 'none', blocks: [], reason: 'bad-artifact' };
+    }
+    if (!isRecord(parsed))
+        return { source: 'none', blocks: [], reason: 'bad-artifact' };
+    const list = parsed['contentList'];
+    if (!Array.isArray(list))
+        return { source: 'none', blocks: [], reason: 'bad-artifact' };
+    // page_idx 缺失的块沿用上一个有页码的块（与 buildFormulaIndex / transcribe 的投影口径一致）
+    const blocks = [];
+    const perPage = new Map();
+    let lastPageIdx = 0;
+    for (const b of list) {
+        if (!isRecord(b))
+            continue;
+        if (b['type'] !== 'text')
+            continue;
+        const pi = b['page_idx'];
+        if (typeof pi === 'number' && Number.isFinite(pi) && pi >= 0)
+            lastPageIdx = Math.trunc(pi);
+        const text = b['text'];
+        if (typeof text !== 'string' || !text.includes('$'))
+            continue;
+        const index = (perPage.get(lastPageIdx) ?? 0) + 1;
+        perPage.set(lastPageIdx, index);
+        blocks.push({
+            page: lastPageIdx + 1,
+            pageIdx: lastPageIdx,
+            index,
+            bbox: toBbox(b['bbox']),
+            text: compactLatex(text),
+        });
+    }
+    // 注意：blocks 为空**不是**错误——产物可能根本没有含 `$` 的 text 块（行内还原直接
+    // 走 unavailable）。reason 只在「读不到 contentList」时给，语义与 FormulaReason 一致。
+    return { source: 'mineru', blocks };
+}
 /** 供测试与调用方复用的紧凑化：既有投影两步 + 算子名统一（见下）。 */
 export function compactLatex(rawLatex) {
     return unifyOperatorNames(normalizeMathBraces(compressMathSpaces(rawLatex)));
@@ -240,33 +285,61 @@ export function buildFormulaIndex(raw, opts = {}) {
     };
 }
 let cache = null;
-/** 读 `<ref.mineruJsonPath>` 并建索引。文件缺失/损坏一律返回可用的空索引，**不抛异常**。 */
-export async function readFormulaIndex(ref) {
+let rawCache = null;
+let textCache = null;
+/**
+ * 读 `.mineru.json` 原始文本（缺失 → null）。**不抛异常**：权限等异常也降级成 null，
+ * 由调用方决定 reason（读取失败按 bad-artifact 记）。
+ */
+async function readMineruRaw(ref) {
     let key = `${ref.mineruJsonPath}:absent`;
     try {
         const st = await stat(ref.mineruJsonPath);
         key = `${ref.mineruJsonPath}:${st.mtimeMs}:${st.size}`;
-        if (cache && cache.key === key)
-            return cache.value;
+        if (rawCache && rawCache.key === key)
+            return { key, raw: rawCache.raw };
         const raw = await readFile(ref.mineruJsonPath, 'utf8');
-        const value = buildFormulaIndex(raw);
-        cache = { key, value };
-        return value;
+        rawCache = { key, raw };
+        return { key, raw };
     }
     catch (err) {
         const code = err.code;
         if (code === 'ENOENT' || code === 'EISDIR') {
-            const value = buildFormulaIndex(null);
-            if (cache?.key === key)
-                return cache.value;
-            cache = { key, value };
-            return value;
+            if (!(rawCache && rawCache.key === key))
+                rawCache = { key, raw: null };
+            return { key, raw: null };
         }
-        // 权限等异常也不许把阅读器打崩：降级成 bad-artifact
-        return EMPTY('bad-artifact', `读取 mineru.json 失败：${code ?? 'unknown'}`);
+        return { key, raw: null, failed: code ?? 'unknown' };
     }
 }
+/** 读 `<ref.mineruJsonPath>` 并建索引。文件缺失/损坏一律返回可用的空索引，**不抛异常**。 */
+export async function readFormulaIndex(ref) {
+    const { key, raw, failed } = await readMineruRaw(ref);
+    if (failed !== undefined)
+        return EMPTY('bad-artifact', `读取 mineru.json 失败：${failed}`);
+    if (cache && cache.key === key)
+        return cache.value;
+    const value = buildFormulaIndex(raw);
+    cache = { key, value };
+    return value;
+}
+/**
+ * 读同一份产物并建 **text 块索引**（行内公式还原用，服务端内部；不经 `/api/formulas`
+ * 下发——§7 R14/R15 明确要求响应面不变）。与 `readFormulaIndex` 共用原始文本缓存。
+ */
+export async function readTextBlockIndex(ref) {
+    const { key, raw, failed } = await readMineruRaw(ref);
+    if (failed !== undefined)
+        return { source: 'none', blocks: [], reason: 'bad-artifact' };
+    if (textCache && textCache.key === key)
+        return textCache.value;
+    const value = buildTextBlockIndex(raw);
+    textCache = { key, value };
+    return value;
+}
 /** 仅供测试：清空记忆化。 */
 export function resetFormulaCache() {
     cache = null;
+    rawCache = null;
+    textCache = null;
 }

package/dist/host.js

@@ -6,7 +6,8 @@ import { randomUUID } from 'node:crypto';
 import { basename, join, resolve } from 'node:path';
 import { listPapers, listTopics, resolveDataDir, resolvePaper, resolveUploadTopic, validateEntryBoundary, validateEntryName, } from "./library.js";
 import { ManageError, assertInside, clearTopic, planTopicClear, deletePaper, deleteTopic, isManageError, planPaperDelete, planTopicDelete, realDataDir, renamePaper, renameTopic, resolveTopicDir, validateName, } from "./library-manage.js";
-import { readFormulaIndex } from "./formulas.js";
+import { readFormulaIndex, readTextBlockIndex } from "./formulas.js";
+import { MAX_CHUNKS, MAX_LATEX_CHARS, MAX_TEXT_CHARS, MAX_TOTAL_CHARS, SelectionTranslateError, assembleSource, formulaStatusOf, translateSelection, } from "./translate-selection.js";
 import { MineruError, sanitizeDetail } from "./mineru.js";
 import { readTranscript, transcribePaper, ScannedPdfError, ShortTextError } from "./transcribe.js";
 import { pdfVariantPath, restartTranslation, startTranslation, zhStatus } from "./translate.js";
@@ -347,10 +348,17 @@ export function registerRoutes(ctx, config) {
                 json(res, 400, { error: 'bad asset name' });
                 return;
             }
-            const mime = { '.mjs': 'text/javascript', '.js': 'text/javascript', '.css': 'text/css', '.map': 'application/json' };
+            const mime = { '.mjs': 'text/javascript', '.js': 'text/javascript', '.css': 'text/css', '.map': 'application/json',
+                // 字体（vendored KaTeX 的 woff2 就靠这条；不给对 MIME 时某些浏览器会拒绝 @font-face）
+                '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf' };
             try {
                 const body = await readFile(new URL(name, readerVendorDir));
-                res.writeHead(200, { 'content-type': (mime[name.slice(name.lastIndexOf('.'))] ?? 'application/octet-stream') + '; charset=utf-8', 'content-length': body.length, 'cache-control': 'no-cache' });
+                const ext = name.slice(name.lastIndexOf('.'));
+                const type = mime[ext] ?? 'application/octet-stream';
+                // 只有文本类才追加 charset：给 font/woff2 这类二进制资源加 `; charset=utf-8` 是错的
+                // （实测 font/woff2 被浏览器按未知类型处理的风险；见 test/reader-vendor-http.test.mjs）
+                const texty = type.startsWith('text/') || type === 'application/json';
+                res.writeHead(200, { 'content-type': texty ? type + '; charset=utf-8' : type, 'content-length': body.length, 'cache-control': 'no-cache' });
                 res.end(body);
             }
             catch {
@@ -777,6 +785,102 @@ export function registerRoutes(ctx, config) {
             json(res, 200, await readFormulaIndex(ref));
             return;
         }
+        /* ── 划词翻译（公式保留，契约 docs/selection-translate-requirements.md §3.9）─────
+           客户端只送「按页 + 按 display 归属切好的 chunk」；行内公式的还原（选区文本 ↔ MinerU
+           text 块对齐）在服务端做，所以请求体里**没有任何矩形/bbox/pageSize**。
+           本接口只读（不写盘）⇒ 定位沿用 /api/formulas 的读路径语义，不做写路径边界。
+           API key 只存在于本进程：请求体只有 model（客户端从 /api/zh 拿到的 apiKeyHint 仅用于展示），
+           响应体与错误文案一律不带 key。 */
+        if (sub === '/api/translate-selection' && req.method === 'POST') {
+            const body = (await readBody(req));
+            const bad = (msg, code = 'bad-request') => json(res, 400, { error: msg, code });
+            if (!Array.isArray(body.chunks))
+                return bad('chunks 必须是数组');
+            if (body.chunks.length < 1 || body.chunks.length > MAX_CHUNKS) {
+                return bad(`chunks 数量必须在 1~${MAX_CHUNKS} 之间（收到 ${body.chunks.length}）`, 'too-large');
+            }
+            const chunks = [];
+            let total = 0;
+            for (const raw of body.chunks) {
+                if (typeof raw !== 'object' || raw === null)
+                    return bad('chunks 的每一项必须是对象');
+                const c = raw;
+                const page = c.page;
+                if (typeof page !== 'number' || !Number.isInteger(page) || page < 1)
+                    return bad('chunk.page 必须是 ≥1 的整数');
+                const text = typeof c.text === 'string' ? c.text : '';
+                const latex = typeof c.latex === 'string' ? c.latex : '';
+                if (c.kind === 'formula') {
+                    if (!latex)
+                        return bad('formula chunk 的 latex 不能为空');
+                    if (latex.length > MAX_LATEX_CHARS)
+                        return bad(`latex 超过 ${MAX_LATEX_CHARS} 字符`, 'too-large');
+                    total += latex.length;
+                    chunks.push({ page, kind: 'formula', latex });
+                    continue;
+                }
+                if (c.kind !== 'text')
+                    return bad("chunk.kind 必须为 'text' 或 'formula'");
+                if (text.length > MAX_TEXT_CHARS)
+                    return bad(`text 超过 ${MAX_TEXT_CHARS} 字符`, 'too-large');
+                total += text.length;
+                chunks.push({ page, kind: 'text', text });
+            }
+            if (total === 0)
+                return bad('选区为空');
+            if (total > MAX_TOTAL_CHARS)
+                return bad(`选区总长超过 ${MAX_TOTAL_CHARS} 字符`, 'too-large');
+            let ref;
+            try {
+                const args = {};
+                if (typeof body.path === 'string' && body.path)
+                    args.path = body.path;
+                else {
+                    if (typeof body.topic !== 'string' || typeof body.name !== 'string' || !body.topic || !body.name) {
+                        return bad('必须提供 topic + name（或 path）');
+                    }
+                    args.topic = body.topic;
+                    args.name = body.name;
+                }
+                ref = resolvePaper(dataDir, args);
+            }
+            catch {
+                throw notFound('文献不存在（划词翻译需要先能定位到该文献）');
+            }
+            const { endpoint, source } = await resolveTranslateEndpoint(config.translate);
+            if (source === 'none') {
+                json(res, 503, { error: '未配置翻译端点：在阅读器里点 ⚙ 填写（OpenAI 兼容端点即可）', code: 'no-endpoint' });
+                return;
+            }
+            const index = await readTextBlockIndex(ref);
+            const asm = assembleSource(chunks, index);
+            try {
+                const r = await translateSelection(endpoint, asm.source);
+                json(res, 200, {
+                    translation: r.translation,
+                    model: r.model,
+                    cached: r.cached,
+                    formulaTotal: r.formulaTotal,
+                    formulaKept: r.formulaKept,
+                    formulaLost: r.formulaLost,
+                    formulaApplied: asm.applied,
+                    formulaSkipped: asm.skipped,
+                    formulaStatus: formulaStatusOf(asm),
+                    hasBlockIndex: asm.hasBlockIndex,
+                    ms: r.ms,
+                });
+            }
+            catch (err) {
+                if (!(err instanceof SelectionTranslateError))
+                    throw err;
+                json(res, err.status, {
+                    error: err.message,
+                    code: err.code,
+                    ...(err.upstreamStatus !== null ? { upstreamStatus: err.upstreamStatus } : {}),
+                });
+            }
+            return;
+        }
         // 新建伴读会话（会话N+1）。最新可见会话还是空白草稿时直接复用它——
         // 连点「新建」不再堆积空会话（毫无意义的点击什么都不存）。
         // n 用全量扫描分配（含归档/空白），绝不与磁盘上已有目录撞号。

package/dist/mineru.js

@@ -64,8 +64,7 @@ function redactSecret(msg, secret) {
  * 导出供 `mineru-config.ts` 的预检复用（预检也会把响应体片段拼进错误，见 F-R2-1）。
  */
 export function sanitizeDetail(msg, secret = '') {
-    const out = redactSecret(msg, secret);
-    return out
+    const out = redactSecret(msg, secret)
         // Bearer 之后只吃到「不可能属于令牌」的字符为止：不要把紧跟的 ) ] } , ; 引号 一起吃掉（验证报告 O4）
         .replace(/Bearer\s+[^\s)\]}>"',;]+/gi, 'Bearer [redacted]')
         .replace(/\bsk-[A-Za-z0-9_-]{4,}\b/g, '[redacted]')
@@ -73,6 +72,10 @@ export function sanitizeDetail(msg, secret = '') {
         .replace(/\s+/g, ' ')
         .trim()
         .slice(0, 240);
+    // 截断同样不能落在代理对中间：错误详情会进 tool result / 模型上下文，孤立代理项会让
+    // 宿主的请求整轮 400（issue #9 同类）。宁可短 1 个码元。
+    const last = out.charCodeAt(out.length - 1);
+    return last >= 0xd800 && last <= 0xdbff ? out.slice(0, -1) : out;
 }
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);

package/dist/search.js

@@ -30,9 +30,17 @@ export function chunkText(text, size = 1500) {
         while (rest.length > size) {
             if (cur.length > 0)
                 flush(restStart);
-            chunks.push({ index: chunks.length + 1, start: restStart, end: restStart + size, text: rest.slice(0, size) });
-            rest = rest.slice(size);
-            restStart += size;
+            // 硬切回退到码点边界：slice 按 UTF-16 码元计数，切点若落在代理对中间（数学论文的
+            // LaTeX 斜体全在 U+1D400 区段，如 𝑋 = D835 DC4B），前后片段就各带一个孤立代理项。
+            // 片段文本经 search_paper 原样返回 → 留在会话历史 → 宿主之后每一轮模型请求都
+            // 400 INVALID_REQUEST，整条会话报废（issue #9）。宁可片段短 1 个码元，绝不切开代理对。
+            let cut = size;
+            const beforeCut = rest.charCodeAt(cut - 1);
+            if (beforeCut >= 0xd800 && beforeCut <= 0xdbff && cut > 1)
+                cut -= 1;
+            chunks.push({ index: chunks.length + 1, start: restStart, end: restStart + cut, text: rest.slice(0, cut) });
+            rest = rest.slice(cut);
+            restStart += cut;
         }
         if (rest !== '') {
             if (cur.length > 0)

package/dist/translate-config.js

@@ -117,6 +117,9 @@ export async function testTranslateEndpoint(ep) {
         // Node 的 fetch 把真实原因（ECONNREFUSED / 证书错误 / 超时）塞在 cause 里，
         // 只报 "fetch failed" 对用户毫无帮助
         const cause = err instanceof Error && err.cause instanceof Error ? `: ${err.cause.message}` : '';
-        return { ok: false, detail: (err instanceof Error ? err.message : String(err)) + cause };
+        // ⚠️ t7（t4 评审 R-04 的同类项）：这条 detail 会进响应体、再上屏（设置浮层）。
+        // fetch 抛出的原因串可能带上 baseUrl（含凭据/查询参数）或回显 Authorization ——
+        // 与同函数上面两条分支一样先过 sanitizeDetail；可读原因（ECONNREFUSED 等）不受影响。
+        return { ok: false, detail: sanitizeDetail((err instanceof Error ? err.message : String(err)) + cause, apiKey) };
     }
 }