@ggboy123/dsh-paper-reader 1.2.0 → 1.3.0

package/README.md

@@ -9,7 +9,7 @@
 
 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件：论文伴读工作台 —— PDF 转录 / 检索 + 原生对话伴读 + 内置阅读器。
 
-> **👉 普通用户不用看这一页。** 如果你只是想装一个能用的 App，请直接去 [**PaperReader 论文伴读桌面版**](https://github.com/GGboya/PaperReader) —— 那是把本插件预装好的桌面应用，下载 DMG 拖进「应用程序」就能用，不需要任何环境。本仓库面向的是想自己装插件、或想改代码的用户。
+> **👉 普通用户直接看「安装 → 方式一」**：装 DeepSeek 官方桌面端，添加插件即可，不需要任何开发环境。本仓库面向的是想自己装插件、或想改代码的用户。
 
 功能迁移自本地独立产品 pdfqa（Go 实现的论文伴读工具）。原则：agent 循环 / 模型层 / 会话持久化全部交给 dsh 框架，插件只做「转录 + 检索 + 阅读器 UI」的薄壳组合。
 
@@ -23,50 +23,39 @@
 
 ## 功能
 
-- 📚 **侧栏文献库树**：「论文伴读」模式开启时接管工作区侧栏，专题 → 论文两级；支持新建专题、上传 PDF（默认关闭，不覆盖官方界面）
+- 📚 **侧栏文献库树**：「论文伴读」模式开启时接管工作区侧栏，专题 → 论文两级；支持新建专题、上传 PDF、**专题/论文改名与删除**（行悬停出 ✎ 🗑；删除两击确认；改名连带转录缓存 / 译文 / 学习档案一起搬家）（默认关闭，不覆盖官方界面）
 - 💬 **原生对话伴读**：点击论文即在右侧打开它的 dsh 原生会话（流式 / 工具卡 / 用量条全是官方 UI）；默认只呈现当前对话，对话列头部的 🕐 下拉回看**历史对话**（真实标题+日期，点哪条进哪条），＋ 新建对话
 - 🔗 **会话绑定论文**：会话 id 编码文献身份，工具调用自动定位当前论文——直接在输入框提问无需点名论文，回答必带页码
 - 🤖 **专用 agent preset「论文伴读」**：paper 会话自动使用专用 preset —— 像老师一样带读：制定分步阅读计划（每步带页码和思考题）→ 逐节指导、点评 → 出题检验、逐题批改 → 成绩与薄弱点记入 `<文献>.study.json` 学习档案，跨会话累积；快速问答（选中即问）则直接回答，不上课
-- 📖 **PDF 阅读器居中**：中间是论文（PDF.js 缩放 / Retina 高清 / 文本层选择 / 适宽模式），最右是该论文的原生对话 —— 视觉换位实现，列宽拖拽/折叠仍是 dsh 原生行为，关掉 PDF 页签即还原官方布局
+- 📖 **PDF 阅读器居中**：中间是论文（PDF.js 缩放 / Retina 高清 / 文本层选择 / 适宽模式 / **滚动 ↔ 单页翻页双模式**——‹ › 翻页、页码输入跳转、← → / PageUp / PageDown / Space / Home / End 键盘翻页），最右是该论文的原生对话 —— 视觉换位实现，列宽拖拽/折叠仍是 dsh 原生行为，关掉 PDF 页签即还原官方布局；状态栏显示 PDF 完整路径，点击复制
 - 💬 **选中即问**：阅读器里选中文字 → 弹出提问框 → 注入当前会话，原生对话区实时回答
 - 📍 **引用定位**：回答里的「第 N 页」可点击，平滑跳回 PDF 对应页并闪烁
-- 🀄 **中英切换**：顶栏「中」按钮原文 ↔ 纯中文切换；无译文时一键后台生成（babeldoc），生成需配置 `translate` 端点；**无需预装 Python**——首次生成时自动下载 uv + 托管 Python + babeldoc（macOS / Linux / Windows，约几分钟），全程落在用户目录
+- 🀄 **中英切换 + 导出**：顶栏「中」按钮原文 ↔ 纯中文切换；无译文时一键后台生成（babeldoc），生成需配置 `translate` 端点；**无需预装 Python**——首次生成时自动下载 uv + 托管 Python + babeldoc（macOS / Linux / Windows，约几分钟），全程落在用户目录；顶栏 ⤓ 一键**下载当前版本**（原文 / 纯中文 / 中英对照 PDF）
 - 🔍 **PDF 转录 + 检索**：本地提取（pdf.js，纯 Node 无需 Python），页眉页脚剔除 / 连字 / 断词愈合 / 段落重排，产出页码偏移表；可选接入 TypeSafe/Jev 语义重排（设置面板填端点即启用，不配置时退回纯关键词排序）；兼容 pdfqa 的 `data/` 缓存布局（旧缓存读取时自动补建页码索引）
 
-## 安装
-
-### 方式一：PaperReader 桌面版（一键安装，推荐普通用户）
-
-[PaperReader](https://github.com/GGboya/PaperReader) 是把本插件**预装好**的桌面应用（基于社区桌面客户端 [DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) 打包）：
+> **库管理须知**：改名/删除直接作用于磁盘文件（论文的转录缓存、译文、学习档案随之改名/删除）；论文/专题改名后，历史伴读会话不再挂在树上（会话本体仍在 dsh 全局会话列表里），学习进度跟着文件走不丢；翻译进行中的论文禁止改名/删除。
 
-1. 从 [Releases](https://github.com/GGboya/PaperReader/releases/latest) 下载 DMG（macOS Universal,Intel / M 系列芯片都行；Windows 版打包中）
-2. 打开 DMG，把 PaperReader 拖进「应用程序」
-3. 首次打开用 右键 → 打开（免签名发布，只弹这一次）；首次启动有几分钟一次性初始化
-
-打开就是文献库 + 阅读器 + 伴读对话，不用再执行任何命令。
+## 安装
 
-### 方式二：已有桌面客户端，自己装插件
+### 方式一：官方桌面端装插件（推荐）
 
 **DeepSeek 官方桌面端**（[deepseek.com/download](https://www.deepseek.com/download/) 下载，即 DeepSeek Harness 桌面版）：
 
 1. 安装并启动，登录 DeepSeek 账号
-2. 侧栏 → **插件** → **添加插件**，输入 `@ggboy123/dsh-paper-reader` 安装
-3. 重启桌面端生效
+2. 侧栏 → **插件** → **添加插件**，输入 `@ggboy123/dsh-paper-reader@1.3.0` 安装
+3. 装完默认**停用**：点进插件详情，打开「启用」开关
+4. **重启桌面端**（热启用状态下打开论文的链路会静默失效，重启进开机组合才正常，实测）
 
-> 已在官方桌面端 V0.2.0-rc.2（内置 dsh 0.2.0-rc.2，macOS arm64）实测通过：侧栏文献库、新建专题、上传 PDF、PDF 阅读器、原生对话伴读、历史/新建对话按钮全部可用。
-> 需要 ≥1.2.0：更早版本会被 0.2.x 运行时的 peer 兼容校验拒载（插件列表里显示异常）。
+完整流程演示（添加插件 → 启用 → 重启 → 打开论文直接提问）：
 
-**社区 DSH Desktop**（[anywhere-labs/dsh-desktop](https://github.com/anywhere-labs/dsh-desktop)，社区的 DeepSeek Harness 桌面客户端，macOS / Windows，开箱即用，不需要装 Node.js）：
+![官方桌面端安装并使用论文伴读插件](https://raw.githubusercontent.com/GGboya/dsh-paper-reader/main/docs/desktop-official-use.gif)
 
-1. 下载安装 DSH Desktop 并启动
-2. 托盘菜单 → **Open DSH Terminal**（终端里自带 `dsh`/`pnpm`，只对那个终端生效）
-3. 执行 `dsh plugin add @ggboy123/dsh-paper-reader@1.2.0`
-4. 退出并重开 DSH Desktop（插件变更要重启才进 Loader 组合）
+> 已在官方桌面端 V0.2.0-rc.2（内置 dsh 0.2.0-rc.2，macOS arm64）实测通过：侧栏文献库、新建专题、上传 PDF、PDF 阅读器、原生对话伴读、历史/新建对话按钮全部可用。
+> 需要 ≥1.2.0：更早版本会被 0.2.x 运行时的 peer 兼容校验拒载（插件列表里显示异常）。
 
-> 已在 DSH Desktop 2.0.13（内置 dsh 0.1.5-rc.2）上实测通过：侧栏文献库、PDF 阅读器、选中即问、页码跳转、原生对话伴读、翻译引擎自动安装（uv + Python + babeldoc 全程落在用户目录）全部可用。
-> 注意：Desktop 的 `desktop` profile 被 Electron 独占管理，外部 CLI 直接 `dsh plugin --profile desktop add` 会被拒（`managed exclusively by the Electron application`）——必须从 Desktop 自己的终端进。
+> 曾经的 PaperReader 桌面版（基于社区 DSH Desktop 的预装打包）**已不再维护**——统一收敛到官方桌面端 + 插件的形式，老用户请迁移到本方式。
 
-### 方式三：命令行 dsh（开发者）
+### 方式二：命令行 dsh（开发者）
 
 ```bash
 dsh plugin --profile web add @ggboy123/dsh-paper-reader
@@ -80,7 +69,7 @@ dsh plugin --profile web add @ggboy123/dsh-paper-reader
 **已装过的用户升级必须带显式版本号**——不带版本的 `add` 对已存在的依赖是 no-op（pnpm 按首次安装时记录的版本范围解析，不会追新）：
 
 ```bash
-dsh plugin --profile web add @ggboy123/dsh-paper-reader@1.2.0
+dsh plugin --profile web add @ggboy123/dsh-paper-reader@1.3.0
 # 重启 dsh web 生效；浏览器 Cmd+Shift+R 强刷，避免旧阅读器页面缓存
 ```
 
@@ -92,7 +81,11 @@ grep '"version"' ~/.dsh/profiles/web/node_modules/@ggboy123/dsh-paper-reader/pac
 
 > pnpm 若开了供应链策略 `minimumReleaseAge`（发布 N 小时内的新包拒装）：要么等过窗口期，要么在 `~/.dsh/profiles/web/.npmrc` 加一行 `minimum-release-age-exclude[]=@ggboy123/dsh-paper-reader`（只豁免本插件，不动全局策略）。
 
-本地开发：
+### 参与开发（本地调试）
+
+欢迎改代码。流程：clone → 构建 → 以本地目录装进 profile，之后改完 `pnpm run build` 重启对应 profile 即可验证：
+
+![参与开发：clone → pnpm install → build → 本地安装](https://raw.githubusercontent.com/GGboya/dsh-paper-reader/main/docs/dev-workflow.gif)
 
 ```bash
 git clone https://github.com/GGboya/dsh-paper-reader
@@ -123,6 +116,21 @@ dsh --profile web                                  # 侧栏变为文献库树
 
 > 伴读模式是**按需开启**的：默认不注册 `sidebar.workspaces`（官方工作区/会话列表原样），侧栏底部「📚 论文伴读」开关点击才接管，再点还原；模式选择记在 localStorage。退出模式时已打开的 PDF 页签和伴读会话不受影响。
 
+### 翻译引擎冒烟测试（Windows 依赖完整性）
+
+Windows 用户最常见的翻车点是翻译引擎装不上（杀软拦 uv、网络截断、venv 残缺）。安装逻辑 `src/babeldoc-install.ts` 是纯 Node 模块（不依赖 Cordis/Electron），配了 GitHub Actions 在**全新干净机器**上跑冒烟，无需本地 Windows：
+
+```bash
+pnpm build
+pnpm smoke:engine clean          # 全新安装全链路
+pnpm smoke:engine managed-uv     # 强制走插件托管 uv 下载（sha256 校验路径）
+pnpm smoke:engine pip-fallback   # 强制走 pip + 国内镜像备用通道
+pnpm smoke:engine repair         # 破坏 venv（删 pymupdf）后验证自检→自动修复
+pnpm smoke:engine translate      # 再起本地 mock OpenAI 端点,真跑一遍 babeldoc 翻译管线
+```
+
+CI（`.github/workflows/engine-smoke.yml`）：`windows-latest` 跑全部四个场景 + translate-e2e，`macos-latest`/`ubuntu-latest` 跑 clean 防回归；改安装/翻译代码的 push 触发，外加每周一定时（uv/PyPI 在变，代码不动也可能突然坏）。两个测试钩子环境变量：`DSH_PR_MANAGED_UV_ONLY=1`（跳过系统 uv 查找）、`DSH_PR_FORCE_PIP_CHANNEL=1`（跳过 uv 装包通道）。
+
 ## 架构
 
 ```

package/dist/babeldoc-install.js

@@ -65,6 +65,10 @@ async function findUv(home) {
     const own = uvPath(home);
     if (existsSync(own))
         return own;
+    // 测试钩子：CI runner 常在 PATH 预装 uv，会静默绕过 downloadUv；
+    // DSH_PR_MANAGED_UV_ONLY=1 时跳过系统查找，强制走插件托管下载链路（含 sha256 校验）。
+    if (process.env.DSH_PR_MANAGED_UV_ONLY === '1')
+        return null;
     if (await whichOk('uv'))
         return 'uv';
     const candidates = isWin
@@ -76,6 +80,36 @@ async function findUv(home) {
     }
     return null;
 }
+/** GitHub API 请求头：有 GITHUB_TOKEN/GH_TOKEN 就带上——匿名限流 60/h 按出口 IP 算，
+ * CI runner 和企业 NAT 都是共享 IP,极易撞 403;带 token 后按账号 5000/h。 */
+function ghHeaders(accept) {
+    const h = { accept, 'user-agent': 'dsh-paper-reader' };
+    const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+    if (token)
+        h.authorization = `Bearer ${token}`;
+    return h;
+}
+/**
+ * fetch 带重试：用户网络抖一下（尤其国内到 GitHub）就直接失败太脆了。
+ * 只对网络错误和 5xx 重试，4xx 是确定性错误直接抛。
+ */
+async function fetchWithRetry(url, init, tries = 3) {
+    let lastErr = null;
+    for (let i = 0; i < tries; i++) {
+        try {
+            const r = await fetch(url, init);
+            if (r.ok || (r.status >= 400 && r.status < 500))
+                return r;
+            lastErr = new Error(`HTTP ${r.status}`);
+        }
+        catch (e) {
+            lastErr = e;
+        }
+        if (i < tries - 1)
+            await new Promise((r) => setTimeout(r, 2000 * (i + 1)));
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
 /**
  * 下载 uv 独立二进制。全程走 api.github.com（资产接口 + octet-stream 直连），
  * 不依赖 github.com 页面域——后者在部分网络环境不可达，而 API 域通常可达。
@@ -92,8 +126,8 @@ async function downloadUv(home, onPhase) {
     await mkdir(tmp, { recursive: true });
     try {
         onPhase('正在安装翻译引擎（1/3 下载 uv）…');
-        const rel = await fetch('https://api.github.com/repos/astral-sh/uv/releases/latest', {
-            headers: { accept: 'application/vnd.github+json', 'user-agent': 'dsh-paper-reader' },
+        const rel = await fetchWithRetry('https://api.github.com/repos/astral-sh/uv/releases/latest', {
+            headers: ghHeaders('application/vnd.github+json'),
             signal: AbortSignal.timeout(30_000),
         });
         if (!rel.ok)
@@ -104,8 +138,8 @@ async function downloadUv(home, onPhase) {
             throw new Error(`uv 最新版没有 ${want} 资产`);
         const sumAsset = assets.find((a) => a.name === want + '.sha256');
         const download = async (a) => {
-            const r = await fetch(`https://api.github.com/repos/astral-sh/uv/releases/assets/${a.id}`, {
-                headers: { accept: 'application/octet-stream', 'user-agent': 'dsh-paper-reader' },
+            const r = await fetchWithRetry(`https://api.github.com/repos/astral-sh/uv/releases/assets/${a.id}`, {
+                headers: ghHeaders('application/octet-stream'),
                 signal: AbortSignal.timeout(180_000),
             });
             if (!r.ok)
@@ -127,7 +161,10 @@ async function downloadUv(home, onPhase) {
         // 不带 -z：bsdtar（macOS 自带 / Win10 1803+ 的 tar.exe）和 GNU tar 解包时都自动探测格式，
         // 同一条命令通吃 tar.gz 与 zip（win32 的 uv 只发 zip）
         await run('tar', ['-xf', pkgPath, '-C', tmp], { timeout: 60_000 });
-        const extracted = join(tmp, `uv-${triple}`, isWin ? 'uv.exe' : 'uv');
+        // tar.gz 有顶层目录 uv-<triple>/;win32 的 zip 是平铺的(uv.exe 直接在根)
+        const binName = isWin ? 'uv.exe' : 'uv';
+        const nested = join(tmp, `uv-${triple}`, binName);
+        const extracted = existsSync(nested) ? nested : join(tmp, binName);
         if (!existsSync(extracted))
             throw new Error('uv 解包结果不符合预期');
         const dst = uvPath(home);
@@ -210,13 +247,24 @@ async function installBabeldoc(uv, venvDir, onPhase) {
         await run(uv, ['venv', venvDir, '--python', '3.12', '--python-preference', 'only-managed'], { timeout: 10 * 60_000 });
     }
     onPhase('正在安装翻译引擎（3/3 安装 babeldoc，首次约几分钟）…');
-    try {
-        await run(uv, ['pip', 'install', '--python', py, 'babeldoc'], { timeout: 20 * 60_000 });
-    }
-    catch (uvErr) {
+    const viaPipFallback = async (cause) => {
         onPhase('正在安装翻译引擎（3/3 备用通道：pip + 国内镜像）…');
-        console.warn('[dsh-paper-reader] uv 安装 babeldoc 失败，改用 pip 镜像通道:', uvErr instanceof Error ? uvErr.message : uvErr);
+        if (cause) {
+            console.warn('[dsh-paper-reader] uv 安装 babeldoc 失败，改用 pip 镜像通道:', cause instanceof Error ? cause.message : cause);
+        }
         await pipInstallBabeldoc(py);
+    };
+    // 测试钩子：DSH_PR_FORCE_PIP_CHANNEL=1 跳过 uv 通道，让 CI 确定性覆盖 pip 备用路径
+    //（杀软锁 uv 入口 exe、PyPI 截断时的逃生通道，Windows 上最关键的一条路径）
+    if (process.env.DSH_PR_FORCE_PIP_CHANNEL === '1')
+        await viaPipFallback(null);
+    else {
+        try {
+            await run(uv, ['pip', 'install', '--python', py, 'babeldoc'], { timeout: 20 * 60_000 });
+        }
+        catch (uvErr) {
+            await viaPipFallback(uvErr);
+        }
     }
     if (!existsSync(bin))
         throw new Error('babeldoc 安装完成但未找到可执行文件');

package/dist/host.js

@@ -3,8 +3,8 @@
 import { createReadStream } from 'node:fs';
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
-import { join } from 'node:path';
-import { listPapers, listTopics, resolveDataDir, resolvePaper } from "./library.js";
+import { basename, join } from 'node:path';
+import { deletePaper, deleteTopic, listPapers, listTopics, paperRefFor, renamePaper, renameTopic, resolveDataDir, resolvePaper, } from "./library.js";
 import { readTranscript, transcribePaper } from "./transcribe.js";
 import { pdfVariantPath, restartTranslation, startTranslation, zhStatus } from "./translate.js";
 import { clearTranslateConfig, maskApiKey, readTranslateConfig, resolveTranslateEndpoint, testTranslateEndpoint, writeTranslateConfig, } from "./translate-config.js";
@@ -169,7 +169,8 @@ export function registerRoutes(ctx, config) {
             return;
         }
         if (sub === '/api/library' && req.method === 'GET') {
-            json(res, 200, { dataDir, topics: listTopics(dataDir), papers: listPapers(dataDir) });
+            const papers = listPapers(dataDir).map((p) => ({ ...p, pdfPath: join(dataDir, p.topic, p.name + '.pdf') }));
+            json(res, 200, { dataDir, topics: listTopics(dataDir), papers });
             return;
         }
         // 新建专题（目录）
@@ -213,6 +214,123 @@ export function registerRoutes(ctx, config) {
             json(res, 200, { ok: true, topic: topic.trim(), name: safeName.slice(0, -4), bytes: buf.length });
             return;
         }
+        /* ---- 库管理：专题/文献 改名与删除。----
+         * 翻译进行中（busy）一律 409 拒绝——babeldoc 异步跑着会往旧路径写 -zh/-dual 产物，
+         * 改名/删除会让它写丢；busy 键控在旧路径上，动了就失联。
+         * Windows 下删除被阅读器 iframe 占用的文件可能 EBUSY/EPERM，转成可读文案。 */
+        const busyPapersInTopic = (topic) => listPapers(dataDir, topic)
+            .filter((p) => zhStatus(paperRefFor(dataDir, p.topic, p.name)).busy)
+            .map((p) => p.name);
+        const fsError = (res2, err) => {
+            const e = err;
+            if (e?.code === 'EBUSY' || e?.code === 'EPERM') {
+                json(res2, 409, { error: '文件被占用（可能正在阅读器或其他程序中打开），关闭后重试' });
+            }
+            else {
+                json(res2, 400, { error: e instanceof Error ? e.message : String(err) });
+            }
+        };
+        if (sub === '/api/library/rename-topic' && req.method === 'POST') {
+            const body = (await readBody(req));
+            if (!body.topic?.trim()) {
+                json(res, 400, { error: '缺少 topic' });
+                return;
+            }
+            const busy = busyPapersInTopic(body.topic.trim());
+            if (busy.length) {
+                json(res, 409, { error: `以下文献正在翻译，稍后再试：${busy.join('、')}` });
+                return;
+            }
+            try {
+                renameTopic(dataDir, body.topic.trim(), body.to ?? '');
+            }
+            catch (err) {
+                fsError(res, err);
+                return;
+            }
+            workspaceCache.delete(join(dataDir, body.topic.trim())); // 旧目录的工作区记录失效（残留无害）
+            json(res, 200, { ok: true, topic: body.to?.trim() });
+            return;
+        }
+        if (sub === '/api/library/delete-topic' && req.method === 'POST') {
+            const body = (await readBody(req));
+            if (!body.topic?.trim()) {
+                json(res, 400, { error: '缺少 topic' });
+                return;
+            }
+            const busy = busyPapersInTopic(body.topic.trim());
+            if (busy.length) {
+                json(res, 409, { error: `以下文献正在翻译，稍后再试：${busy.join('、')}` });
+                return;
+            }
+            try {
+                deleteTopic(dataDir, body.topic.trim());
+            }
+            catch (err) {
+                fsError(res, err);
+                return;
+            }
+            json(res, 200, { ok: true });
+            return;
+        }
+        if (sub === '/api/library/rename-paper' && req.method === 'POST') {
+            const body = (await readBody(req));
+            if (!body.topic?.trim() || !body.name?.trim()) {
+                json(res, 400, { error: '缺少 topic / name' });
+                return;
+            }
+            let ref;
+            try {
+                ref = resolvePaper(dataDir, { topic: body.topic.trim(), name: body.name.trim() });
+            }
+            catch (err) {
+                fsError(res, err);
+                return;
+            }
+            if (zhStatus(ref).busy) {
+                json(res, 409, { error: '该文献正在翻译，稍后再试' });
+                return;
+            }
+            let renamed;
+            try {
+                renamed = renamePaper(dataDir, ref.topic, ref.name, body.to ?? '');
+            }
+            catch (err) {
+                fsError(res, err);
+                return;
+            }
+            json(res, 200, { ok: true, topic: ref.topic, name: body.to?.trim(), renamed });
+            return;
+        }
+        if (sub === '/api/library/delete-paper' && req.method === 'POST') {
+            const body = (await readBody(req));
+            if (!body.topic?.trim() || !body.name?.trim()) {
+                json(res, 400, { error: '缺少 topic / name' });
+                return;
+            }
+            let ref;
+            try {
+                ref = resolvePaper(dataDir, { topic: body.topic.trim(), name: body.name.trim() });
+            }
+            catch (err) {
+                fsError(res, err);
+                return;
+            }
+            if (zhStatus(ref).busy) {
+                json(res, 409, { error: '该文献正在翻译，稍后再试' });
+                return;
+            }
+            let deleted;
+            try {
+                deleted = deletePaper(dataDir, ref.topic, ref.name);
+            }
+            catch (err) {
+                fsError(res, err);
+                return;
+            }
+            json(res, 200, { ok: true, deleted });
+            return;
+        }
         // 新建伴读会话（会话N+1）。最新可见会话还是空白草稿时直接复用它——
         // 连点「新建」不再堆积空会话（毫无意义的点击什么都不存）。
         // n 用全量扫描分配（含归档/空白），绝不与磁盘上已有目录撞号。
@@ -262,6 +380,7 @@ export function registerRoutes(ctx, config) {
             json(res, 200, {
                 topic: ref.topic,
                 name: ref.name,
+                pdfPath: ref.pdfPath,
                 pdfBytes: st.size,
                 hasTranscript: t !== null,
                 chars: t?.text.length ?? 0,
@@ -274,11 +393,18 @@ export function registerRoutes(ctx, config) {
             const ref = locate(url);
             const pdfPath = pdfVariantPath(ref, url.searchParams.get('variant'));
             const st = await stat(pdfPath); // 变体不存在时 404/500 由外层兜底
-            res.writeHead(200, {
+            // download=1 → 附件下载（导出译文/原文）；文件名即磁盘名 <名>.pdf / -zh.pdf / -dual.pdf
+            const headers = {
                 'content-type': 'application/pdf',
                 'content-length': st.size,
                 'cache-control': 'no-cache', // 切换文献/重新生成后必须拿到新的
-            });
+            };
+            if (url.searchParams.get('download') === '1') {
+                const name = basename(pdfPath);
+                headers['content-disposition'] =
+                    `attachment; filename="paper.pdf"; filename*=UTF-8''${encodeURIComponent(name)}`;
+            }
+            res.writeHead(200, headers);
             createReadStream(pdfPath).pipe(res);
             return;
         }

package/dist/library.js

@@ -6,7 +6,7 @@
 //   <dataDir>/<专题>/<文献>.pages.json   页码偏移表（转录时生成，检索映射页码用）
 // pdf2zh 的产物（-en / -zh / -dual）不算用户文献。
 // （问答不落盘存档——会话持久化交给 dsh 自己；pdfqa 时代的 -qa/ 目录不再读写。）
-import { readdirSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { readdirSync, existsSync, mkdirSync, statSync, renameSync, rmSync } from 'node:fs';
 import { join, resolve, extname, basename } from 'node:path';
 import { homedir } from 'node:os';
 const PDF2ZH_SUFFIXES = ['-en', '-zh', '-dual'];
@@ -101,3 +101,94 @@ export function transcriptCached(ref) {
         return false;
     }
 }
+// ================= 库管理：改名/删除（纯文件系统操作，供 host 路由调用） =================
+/** 名字校验（专题/文献共用）。合法返回 null，否则返回中文错误文案。 */
+export function validateEntryName(raw) {
+    const name = raw.trim();
+    if (!name)
+        return '名字不能为空';
+    if (name.length > 120)
+        return '名字过长（最多 120 个字符）';
+    if (/[\\/]|\.\./.test(name))
+        return '名字不能包含 / \\ 或 ..';
+    if (name.startsWith('.'))
+        return '名字不能以 . 开头';
+    return null;
+}
+/** 构造文献引用（不做存在性校验；给只按路径判定的调用方用，如翻译 busy 检查）。 */
+export function paperRefFor(dataDir, topic, name) {
+    const pdfPath = join(dataDir, topic, name + '.pdf');
+    const base = pdfPath.slice(0, -'.pdf'.length);
+    return { topic, name, pdfPath, txtPath: base + '.txt', pagesPath: base + '.pages.json' };
+}
+/** 文献的全部关联文件后缀（含本体 .pdf）：转录缓存 + 页码索引 + babeldoc 译文 + 学习档案。
+ *  命名与 translate.ts（-zh/-dual）和 study.ts（.study.json）的产物规则一致。 */
+const PAPER_SIDECARS = ['.pdf', '.txt', '.pages.json', '-zh.pdf', '-dual.pdf', '.study.json'];
+/** 某文献的全部关联文件路径（存在与否由调用方自查）。 */
+export function derivedFilesFor(pdfPath) {
+    const stem = pdfPath.slice(0, -'.pdf'.length);
+    return PAPER_SIDECARS.map((s) => stem + s);
+}
+/** 改名专题（目录 rename）。from 不存在 / to 已存在 / 名字非法 → throw 中文 Error。
+ *  已知局限：大小写不敏感文件系统（macOS/Windows）上纯大小写改名会被「目标已存在」
+ *  拒绝——不做临时名两跳绕过，保持简单。 */
+export function renameTopic(dataDir, from, to) {
+    const err = validateEntryName(to);
+    if (err)
+        throw new Error(err);
+    if (to.trim() === from)
+        return;
+    const src = join(dataDir, from);
+    if (!existsSync(src))
+        throw new Error(`专题不存在: ${from}`);
+    const dst = join(dataDir, to.trim());
+    if (existsSync(dst))
+        throw new Error(`已存在同名专题: ${to.trim()}`);
+    renameSync(src, dst);
+}
+/** 改名文献：连带派生文件（转录/页码索引/译文/学习档案）逐个跟随，不存在的跳过。
+ *  返回实际改名的文件名清单（含 .pdf 本体）。 */
+export function renamePaper(dataDir, topic, from, to) {
+    const err = validateEntryName(to);
+    if (err)
+        throw new Error(err);
+    to = to.trim();
+    if (to === from)
+        return [];
+    const dir = join(dataDir, topic);
+    if (!existsSync(join(dir, from + '.pdf')))
+        throw new Error(`文献不存在: ${topic}/${from}`);
+    if (existsSync(join(dir, to + '.pdf')))
+        throw new Error(`已存在同名文献: ${to}`);
+    const renamed = [];
+    for (const suf of PAPER_SIDECARS) {
+        const src = join(dir, from + suf);
+        if (!existsSync(src))
+            continue;
+        renameSync(src, join(dir, to + suf));
+        renamed.push(from + suf);
+    }
+    return renamed;
+}
+/** 删除文献及其全部派生文件。返回实际删除的文件名清单。 */
+export function deletePaper(dataDir, topic, name) {
+    const dir = join(dataDir, topic);
+    const pdfPath = join(dir, name + '.pdf');
+    if (!existsSync(pdfPath))
+        throw new Error(`文献不存在: ${topic}/${name}`);
+    const deleted = [];
+    for (const f of derivedFilesFor(pdfPath)) {
+        if (!existsSync(f))
+            continue;
+        rmSync(f);
+        deleted.push(basename(f));
+    }
+    return deleted;
+}
+/** 删除专题（递归，含其下全部文献与派生文件）。 */
+export function deleteTopic(dataDir, topic) {
+    const dir = join(dataDir, topic);
+    if (!existsSync(dir))
+        throw new Error(`专题不存在: ${topic}`);
+    rmSync(dir, { recursive: true, force: true });
+}

package/lib/client.js

@@ -31,6 +31,8 @@ window.__ModuleLoader__.load({
       empty: '文献库为空', hint: '新建专题或上传 PDF 开始', newTopic: '新建专题',
       cancel: '取消', ok: '确定', defaultTopic: '默认专题', uploadBtn: '上传 PDF',
       newTopicFail: '新建专题失败',
+      rename: '重命名', renameTopic: '重命名专题', renamePaper: '重命名论文',
+      del: '删除', delArm: '确认删除?', renameFail: '重命名失败', delFail: '删除失败',
       upload: '上传 PDF 到此专题', newChat: '新建对话', session: '会话', pdfTab: '论文 PDF',
       history: '历史对话',
       sync: '对话还停在另一篇文献的会话里，点击切到当前文献',
@@ -52,6 +54,8 @@ window.__ModuleLoader__.load({
       empty: 'Library is empty', hint: 'Create a topic or upload a PDF to start', newTopic: 'New topic',
       cancel: 'Cancel', ok: 'OK', defaultTopic: 'Default', uploadBtn: 'Upload PDF',
       newTopicFail: 'Failed to create topic',
+      rename: 'Rename', renameTopic: 'Rename topic', renamePaper: 'Rename paper',
+      del: 'Delete', delArm: 'Delete?', renameFail: 'Rename failed', delFail: 'Delete failed',
       upload: 'Upload PDF into this topic', newChat: 'New chat', session: 'Session', pdfTab: 'Paper PDF',
       history: 'Chat history',
       sync: 'Chat is still on another paper — click to switch to the current one',
@@ -112,6 +116,37 @@ window.__ModuleLoader__.load({
       return r.json()
     }
 
+    /* ---------- 改名搬家：论文粒度的本地记忆键跟随新身份 ----------
+       dpr.variant.<topic>/<name>（语言版本记忆）、dpr.sessionN.<topic>/<name>（会话序号）、
+       dpr.last（上次打开）。论文改名精确搬单键；专题改名把该专题前缀的键整体搬。 */
+    function migrateLsKeys(oldTopic, newTopic, oldName, newName) {
+      try {
+        if (oldName != null) {
+          for (const base of ['dpr.variant.', 'dpr.sessionN.']) {
+            const from = base + oldTopic + '/' + oldName
+            const to = base + newTopic + '/' + newName
+            const v = localStorage.getItem(from)
+            if (v != null) { localStorage.setItem(to, v); localStorage.removeItem(from) }
+          }
+        } else {
+          for (const base of ['dpr.variant.', 'dpr.sessionN.']) {
+            const pre = base + oldTopic + '/'
+            for (let i = localStorage.length - 1; i >= 0; i--) {
+              const k = localStorage.key(i)
+              if (k && k.startsWith(pre)) {
+                localStorage.setItem(base + newTopic + '/' + k.slice(pre.length), localStorage.getItem(k))
+                localStorage.removeItem(k)
+              }
+            }
+          }
+        }
+        const last = JSON.parse(localStorage.getItem('dpr.last') || 'null')
+        if (last && last.topic === oldTopic && (oldName == null || last.name === oldName)) {
+          localStorage.setItem('dpr.last', JSON.stringify({ ...last, topic: newTopic, ...(oldName != null ? { name: newName } : {}) }))
+        }
+      } catch { /* 隐私模式等写不了就算了 */ }
+    }
+
     /* 当前在屏（主视图）会话 id：0.1.x 是会话列表快照的 .current 字段；
        0.2.0 起快照没有该字段，官方以 retainedBy.mainView>0 标记主视图保留的会话
        （dsh-client-ui-workspace 自己的 current() 就是这么读的）—— 两代都取到。 */
@@ -194,6 +229,8 @@ window.__ModuleLoader__.load({
       const lastShownRef = React.useRef(0)
       useEffect(() => {
         const on = (e) => {
+          // 空库（最后一篇被删）：撤掉阅读器 iframe，回到「从文献库选择一篇论文」占位
+          if (e.detail.empty) { try { localStorage.removeItem('dpr.last') } catch {}; setCur(null); return }
           // 跳转链接挂的页码/引文（jumpToPaperPage 的跨论文路径）：随 src 传给阅读器 bootstrap
           const j = pendingJump
           pendingJump = null
@@ -512,8 +549,8 @@ window.__ModuleLoader__.load({
        （实测同版本 Electron 调用即抛 "prompt() is not supported"，桌面端点「＋」
        曾因此毫无反应），一律走 createPortal 挂 document.body，避免被侧栏 overflow 裁剪。 ---------- */
     function AskText(props) {
-      const { title, confirmText, cancelText, onConfirm, onCancel } = props
-      const [v, setV] = useState('')
+      const { title, confirmText, cancelText, onConfirm, onCancel, initial } = props
+      const [v, setV] = useState(() => initial ?? '')
       const ref = React.useRef(null)
       useEffect(() => { ref.current?.focus() }, [])
       const submit = () => { const s = v.trim(); if (s) onConfirm(s) }
@@ -692,6 +729,76 @@ window.__ModuleLoader__.load({
       // supported"，点击无任何反应），改为 AskText 页内弹窗（见 LibraryTree return）。
       const newTopic = useCallback(() => setAskTopic(true), [])
 
+      /* ---------- 库管理：改名/删除（用户反馈补齐） ----------
+         已知代价（README 明示）：sessionId 编码旧 topic/name，改名后历史伴读会话从树上
+         消失（会话本体仍在 dsh 全局列表）；study.json/译文/转录缓存随文件改名全部保留。 */
+      const [renaming, setRenaming] = useState(null) // {kind:'topic'|'paper', topic, name}
+      const [armDel, setArmDel] = useState(null)     // {kind, topic, name}：两段式删除的待确认态
+
+      // 两段式删除的待确认态 3s 自动复位（复刻阅读器 ↻ 重译按钮的 arm 模式）
+      useEffect(() => {
+        if (!armDel) return undefined
+        const timer = setTimeout(() => setArmDel(null), 3000)
+        return () => clearTimeout(timer)
+      }, [armDel])
+
+      const doRename = useCallback(async (kind, topic, name, to) => {
+        const newTopicName = kind === 'topic' ? to : topic
+        const newName = kind === 'paper' ? to : name
+        try {
+          await api(`/library/rename-${kind}`, {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(kind === 'topic' ? { topic, to } : { topic, name, to }),
+          })
+        } catch (err) { toast(t('renameFail') + ': ' + err.message); return }
+        // 本地记忆（语言版本/会话序号/上次打开/折叠态）搬到新身份
+        migrateLsKeys(topic, newTopicName, kind === 'paper' ? name : null, kind === 'paper' ? newName : null)
+        setSessions((m) => { const c = { ...m }; delete c[`${topic}/${name}`]; return c })
+        if (kind === 'topic') setClosed((c) => {
+          if (!(topic in c)) return c
+          const n = { ...c }; n[to] = c[topic]; delete n[topic]
+          try { localStorage.setItem('dpr.treeClosed', JSON.stringify(n)) } catch {}
+          return n
+        })
+        // 改的是当前论文（或其所在专题）→ 树与阅读器 iframe 跟到新身份
+        if (cur && (kind === 'topic' ? cur.topic === topic : (cur.topic === topic && cur.name === name))) {
+          setCur((c) => ({ ...c, topic: newTopicName, name: newName }))
+          window.dispatchEvent(new CustomEvent('dpr:paper', { detail: { topic: newTopicName, name: newName } }))
+        }
+        refresh()
+      }, [cur, refresh])
+
+      const doDelete = useCallback(async (kind, topic, name) => {
+        try {
+          await api(`/library/delete-${kind}`, {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(kind === 'topic' ? { topic } : { topic, name }),
+          })
+        } catch (err) { toast(t('delFail') + ': ' + err.message); return }
+        setSessions((m) => { const c = { ...m }; delete c[`${topic}/${name}`]; return c })
+        refresh()
+        // 删的是当前论文（或其所在专题）→ 切到剩余第一篇；全空则收起阅读器
+        if (cur && (kind === 'topic' ? cur.topic === topic : (cur.topic === topic && cur.name === name))) {
+          const d = await api('/library').catch(() => null)
+          const next = d?.papers?.[0] || null
+          if (next) {
+            setCur({ topic: next.topic, name: next.name })
+            window.dispatchEvent(new CustomEvent('dpr:paper', { detail: { topic: next.topic, name: next.name } }))
+          } else {
+            setCur(null)
+            try { localStorage.removeItem('dpr.last') } catch {}
+            window.dispatchEvent(new CustomEvent('dpr:paper', { detail: { empty: true } }))
+          }
+        }
+      }, [cur, refresh])
+
+      // 两段式删除点击：第一击进入待确认（按钮变红显示「确认删除?」），第二击执行
+      const clickDelete = useCallback((kind, topic, name) => {
+        const armed = armDel && armDel.kind === kind && armDel.topic === topic && armDel.name === name
+        if (armed) { setArmDel(null); doDelete(kind, topic, name); return }
+        setArmDel({ kind, topic, name })
+      }, [armDel, doDelete])
+
       const upload = useCallback((topic) => {
         uploadTopic.current = topic
         fileInput.current?.click()
@@ -770,9 +877,10 @@ window.__ModuleLoader__.load({
                 h('button', { type: 'button', style: S.linkBtn, onClick: newTopic }, '＋ ', t('newTopic')))),
             topics.map((topic) => {
               const isClosed = !!closed[topic]
+              const topicArmed = armDel && armDel.kind === 'topic' && armDel.topic === topic
               return h('div', { key: topic },
                 h('div', {
-                  style: S.topicHead,
+                  style: S.topicHead, 'data-dpr-row': '',
                   onClick: () => {
                     const next = { ...closed, [topic]: !isClosed }
                     setClosed(next)
@@ -785,16 +893,39 @@ window.__ModuleLoader__.load({
                     style: S.iconBtn, title: t('upload'),
                     onClick: (e) => { e.stopPropagation(); upload(topic) },
                   }, '⬆'),
+                  h('button', {
+                    'data-dpr-act': 'rename', style: S.iconBtn, title: t('rename'),
+                    onClick: (e) => { e.stopPropagation(); setRenaming({ kind: 'topic', topic }) },
+                  }, '✎'),
+                  h('button', {
+                    'data-dpr-act': 'del', ...(topicArmed ? { 'data-dpr-armed': '' } : {}),
+                    style: topicArmed ? { ...S.iconBtn, color: 'var(--dsw-alias-state-error-primary, #cf222e)' } : S.iconBtn,
+                    title: t('del'),
+                    onClick: (e) => { e.stopPropagation(); clickDelete('topic', topic, undefined) },
+                  }, topicArmed ? t('delArm') : '🗑'),
                 ),
                 !isClosed && h('div', { style: S.items },
                   papers.filter((p) => p.topic === topic).map((p) => {
                     const isCurrentPaper = cur && cur.topic === p.topic && cur.name === p.name
+                    const paperArmed = armDel && armDel.kind === 'paper' && armDel.topic === p.topic && armDel.name === p.name
                     return h('div', {
                       key: p.name,
                       style: { ...S.item, ...(isCurrentPaper ? S.active : {}) },
-                      title: p.name,
+                      'data-dpr-row': '',
+                      title: p.pdfPath || p.name,
                       onClick: () => enter(p.topic, p.name),
-                    }, '📄 ', h('span', { style: { flex: 1, overflow: 'hidden', textOverflow: 'ellipsis' } }, p.name))
+                    }, '📄 ',
+                      h('span', { style: { flex: 1, overflow: 'hidden', textOverflow: 'ellipsis' } }, p.name),
+                      h('button', {
+                        'data-dpr-act': 'rename', style: S.iconBtn, title: t('rename'),
+                        onClick: (e) => { e.stopPropagation(); setRenaming({ kind: 'paper', topic: p.topic, name: p.name }) },
+                      }, '✎'),
+                      h('button', {
+                        'data-dpr-act': 'del', ...(paperArmed ? { 'data-dpr-armed': '' } : {}),
+                        style: paperArmed ? { ...S.iconBtn, color: 'var(--dsw-alias-state-error-primary, #cf222e)' } : S.iconBtn,
+                        title: t('del'),
+                        onClick: (e) => { e.stopPropagation(); clickDelete('paper', p.topic, p.name) },
+                      }, paperArmed ? t('delArm') : '🗑'))
                   }),
                 ),
               )
@@ -816,6 +947,19 @@ window.__ModuleLoader__.load({
             onCancel: () => setAskTopic(false),
           }),
           document.body),
+        renaming && createPortal(
+          h(AskText, {
+            title: (renaming.kind === 'topic' ? t('renameTopic') : t('renamePaper')) + '：',
+            initial: renaming.kind === 'topic' ? renaming.topic : renaming.name,
+            confirmText: t('ok'), cancelText: t('cancel'),
+            onConfirm: (name) => {
+              const r = renaming
+              setRenaming(null)
+              doRename(r.kind, r.topic, r.name, name)
+            },
+            onCancel: () => setRenaming(null),
+          }),
+          document.body),
       )
     }
 
@@ -979,6 +1123,9 @@ window.__ModuleLoader__.load({
             const styleEl = document.createElement('style')
             styleEl.id = 'dpr-surface-css'
             styleEl.textContent = '[data-dpr-rail]:hover,[data-dpr-mode]:hover{background:var(--dsw-alias-interactive-bg-hover)!important}'
+              // 树行内的 ✎🗑 操作按钮：默认隐身，行悬停才现身（两段式删除的待确认态常亮）
+              + '[data-dpr-act]{opacity:0!important;transition:opacity .12s}'
+              + '[data-dpr-row]:hover [data-dpr-act],[data-dpr-armed]{opacity:1!important}'
             document.head.appendChild(styleEl)
           }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggboy123/dsh-paper-reader",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "DeepSeek Harness 插件：论文伴读工作台 — PDF 转录 / 检索 / 原生对话伴读 + 内置阅读器页面。",
   "license": "MIT",
   "type": "module",
@@ -45,6 +45,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "smoke:engine": "node scripts/engine-smoke.mjs",
     "prepublishOnly": "tsc -p tsconfig.json"
   },
   "keywords": [

package/reader/index.html

@@ -32,12 +32,22 @@
   /* min-width:0 —— flex 项默认 min-width:auto 会拒绝收缩，空间不够时转而去挤按钮；
      让标题自己截断（已有 ellipsis），按钮才能保持原样 */
   #status { min-width: 0; color: var(--text-2); font-size: 12.5px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  /* PDF 文件路径：可点的只读文本（点击复制），窄列自动截断 */
+  #pdf-path { flex: none; max-width: 34%; padding: 0; border: none; background: none; color: var(--text-2); font-size: 11.5px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; cursor: pointer; }
+  #pdf-path:hover { color: var(--accent); }
 
   /* ---------- PDF 区 ---------- */
   #main { display: flex; flex: 1; min-height: 0; }
   #pdf-pane { flex: 1; overflow: auto; padding: 16px; }
   /* safe center：页宽超过视口时退回左对齐——普通 center 会让左右同时溢出且左侧滚不到 */
   #pdf-pages { display: flex; flex-direction: column; align-items: safe center; gap: 14px; }
+  /* 翻页模式：单页垂直居中（safe center 同理，放大后顶部仍可滚到） */
+  #pdf-pages.paged { min-height: 100%; justify-content: safe center; gap: 0; }
+
+  /* ---------- 翻页控件 ---------- */
+  #pager { display: flex; align-items: center; gap: 4px; flex: none; }
+  #page-input { width: 3.5em; padding: 3px 6px; border: 1px solid var(--border); border-radius: 6px; background: var(--panel); color: var(--text); font: inherit; font-size: 12.5px; text-align: right; }
+  #page-total { flex: none; color: var(--text-2); font-size: 12px; white-space: nowrap; }
   .page { position: relative; background: #fff; box-shadow: 0 1px 4px rgba(0,0,0,.18); }
   .page.flash { outline: 3px solid var(--hl); outline-offset: 2px; transition: outline .15s; }
   /* textLayer CSS 必须是 pdf.js 6.x 官方规则的子集：TextLayer 只往 span 写 --font-height/--scale-x/--rotate
@@ -99,9 +109,18 @@
 
 <div id="bar">
   <span id="status">论文伴读</span>
+  <button id="pdf-path" style="display:none" title="点击复制文件路径"></button>
   <button id="zh-toggle" class="tbtn" title="切换中文译文（没有译文时可生成）" style="display:none">中</button>
   <button id="zh-regen" class="tbtn" title="重新翻译：删除现有译文，用当前端点重跑（换模型后用）" style="display:none">↻</button>
+  <button id="dl-btn" class="tbtn" title="下载 PDF" style="display:none">⤓</button>
   <span class="spacer"></span>
+  <button id="mode-toggle" class="tbtn" title="切换 滚动/翻页模式" style="display:none">▣</button>
+  <span id="pager" style="display:none">
+    <button id="page-prev" class="tbtn" title="上一页">‹</button>
+    <input id="page-input" type="text" inputmode="numeric" title="页码，回车跳转">
+    <span id="page-total">/ ?</span>
+    <button id="page-next" class="tbtn" title="下一页">›</button>
+  </span>
   <button id="cfg-open" class="tbtn" title="翻译端点设置">⚙</button>
   <button id="zoom-out" class="tbtn">−</button>
   <span id="zoom-label">100%</span>
@@ -168,6 +187,18 @@ function toast(msg, ms = 3200) {
 }
 function esc(s) { return s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c])); }
 
+// 路径复制：clipboard API 失败（iframe 权限等）退回 textarea + execCommand
+$('pdf-path').onclick = async () => {
+  const p = $('pdf-path').textContent;
+  if (!p) return;
+  try { await navigator.clipboard.writeText(p); toast('路径已复制'); return; } catch { /* 走兜底 */ }
+  const ta = document.createElement('textarea');
+  ta.value = p; document.body.appendChild(ta); ta.select();
+  try { document.execCommand('copy'); toast('路径已复制'); }
+  catch { toast('复制失败，路径见按钮悬停提示'); }
+  ta.remove();
+};
+
 let current = null;        // { topic, name }
 let zhState = { zh: false, dual: false, busy: false };
 let statusMeta = ''; // openPaper 的「name · N 页」基线，翻译阶段标签褪去后恢复它
@@ -176,6 +207,11 @@ let zhVariant = null;      // null=原文 'dual'=中英对照 'zh'=纯中文
 // 加上这里的恢复，「中文界面跳中文」在同篇跳转/重开/跨论文三条路径上都成立
 const variantKey = (topic, name) => `dpr.variant.${topic}/${name}`;
 
+// 阅读模式：scroll=连续滚动（默认，原行为）paged=单页翻页；每读者记忆
+let pageMode = localStorage.getItem('dpr.pageMode') === 'paged' ? 'paged' : 'scroll';
+// 当前页：paged 是唯一渲染依据；scroll 由 IntersectionObserver 跟随回写（模式切换/跳页共享）
+let curPage = 1;
+
 /* ================= 打开文献 ================= */
 function pdfUrl(variant) {
   const q = `topic=${encodeURIComponent(current.topic)}&name=${encodeURIComponent(current.name)}`;
@@ -186,6 +222,7 @@ async function openPaper(topic, name, opts = {}) {
   if (!name) return;
   current = { topic, name };
   localStorage.setItem('dpr.last', JSON.stringify(current));
+  curPage = opts.page || 1; // 换论文从第一页（或跳转目标页）开始；变体切换/重译不走这里，页码保持
   $('status').textContent = '加载 PDF…';
   const q = `topic=${encodeURIComponent(topic)}&name=${encodeURIComponent(name)}`;
   const meta = await api('/paper?' + q);
@@ -193,16 +230,43 @@ async function openPaper(topic, name, opts = {}) {
     ? `${name} · ${meta.pageCount ?? '?'} 页`
     : `${name} · 未转录（提问时会自动转录）`;
   $('status').textContent = statusMeta;
+  // 文件路径展示（点击复制）：独立于 #status，翻译阶段的 phase 覆写不影响它
+  const pathBtn = $('pdf-path');
+  pathBtn.textContent = meta.pdfPath || '';
+  pathBtn.title = (meta.pdfPath || '') + '（点击复制）';
+  pathBtn.style.display = meta.pdfPath ? '' : 'none';
   await refreshZhState();
   // 恢复该论文上次的语言版本（译文已不存在时回落原文）
   const saved = localStorage.getItem(variantKey(topic, name));
   zhVariant = (saved === 'zh' && zhState.zh) || (saved === 'dual' && zhState.dual) ? saved : null;
   $('zh-toggle').classList.toggle('active', zhVariant !== null);
   if (zhVariant) { fitMode = true; fitBtn.classList.add('active'); } // 译文版页宽不同，强制适宽
+  updateDlBtn();
   await loadPdf(pdfUrl(zhVariant));
   if (opts.page) jumpTo(opts.page, opts.q); // 不 await：跳转内部自带「等页面渲出来」轮询
 }
 
+/* ================= 下载/导出 ================= */
+// 下载当前正在看的那个版本（原文/纯中文/中英对照）——导出译文的主要入口
+function updateDlBtn() {
+  const btn = $('dl-btn');
+  if (!current) { btn.style.display = 'none'; return; }
+  btn.style.display = '';
+  btn.title = zhVariant === 'zh' ? '下载：纯中文版 PDF'
+    : zhVariant === 'dual' ? '下载：中英对照版 PDF' : '下载：原文 PDF';
+}
+function downloadCurrent() {
+  if (!current) return;
+  // 同源请求自动带 cookie（鉴权围栏）；download 属性空值 → 文件名取 content-disposition
+  const a = document.createElement('a');
+  a.href = pdfUrl(zhVariant) + '&download=1';
+  a.download = '';
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+}
+$('dl-btn').onclick = downloadCurrent;
+
 /* ================= 中英切换 ================= */
 async function refreshZhState() {
   zhState = await api(`/zh?topic=${encodeURIComponent(current.topic)}&name=${encodeURIComponent(current.name)}`);
@@ -236,6 +300,7 @@ $('zh-toggle').onclick = async () => {
     zhVariant = zhVariant === null ? (zhState.zh ? 'zh' : 'dual') : null;
     localStorage.setItem(variantKey(current.topic, current.name), zhVariant ?? '');
     $('zh-toggle').classList.toggle('active', zhVariant !== null);
+    updateDlBtn();
     // 切换变体后强制适宽：译文版页宽与原文不同（对照双栏≈2×），不重算会溢出裁切
     fitMode = true; fitBtn.classList.add('active');
     await loadPdf(pdfUrl(zhVariant));
@@ -428,7 +493,7 @@ let renderToken = 0;
   mq.addEventListener('change', function onChange() {
     mq.removeEventListener('change', onChange);
     dpr = window.devicePixelRatio || 1;
-    if (pdfDoc) renderAllPages();
+    if (pdfDoc) rerender();
     watchDpr();
   });
 })();
@@ -437,62 +502,129 @@ async function loadPdf(url) {
   await ensurePdfjs(); // 就绪前禁止触 pdfjsLib（defer 竞态，见文件头注释）
   pdfDoc = await pdfjsLib.getDocument({ url }).promise; // v6 起不接受字符串参数，必须传对象
   $('empty').style.display = 'none';
-  if (fitMode) { fitToWidth(); return; } // fitToWidth 内部 setZoom → renderAllPages
-  await renderAllPages();
+  // 翻页控件与模式切换按钮：文档就绪后才出现
+  $('pager').style.display = '';
+  $('mode-toggle').style.display = '';
+  if (fitMode) { fitToWidth(); return; } // fitToWidth 内部 setZoom → rerender
+  await rerender();
+}
+
+/** 构建单页 DOM 骨架（.page + canvas + textLayer），位图与文本由 paintPage 异步填充。 */
+function makePageNode(i, viewport) {
+  const div = document.createElement('div');
+  div.className = 'page';
+  div.dataset.page = i;
+  div.style.width = viewport.width + 'px';
+
+  const canvas = document.createElement('canvas');
+  canvas.width = Math.ceil(viewport.width * dpr);
+  canvas.height = Math.ceil(viewport.height * dpr);
+  canvas.style.width = viewport.width + 'px';
+  canvas.style.height = viewport.height + 'px';
+  div.appendChild(canvas);
+
+  const tl = document.createElement('div');
+  tl.className = 'textLayer';
+  tl.style.width = viewport.width + 'px';
+  tl.style.height = viewport.height + 'px';
+  tl.style.setProperty('--scale-factor', String(viewport.scale));
+  div.appendChild(tl);
+  return div;
 }
 
+/** 渲染单页内容（canvas 位图 + pdf.js 6.x TextLayer 文本层）。token 失效（被更新的渲染
+    抢占）时中途放弃——旧 renderAllPages 循环体里的守卫原样搬进来。 */
+async function paintPage(page, div, viewport, token) {
+  const canvas = div.firstChild;
+  const tl = div.lastChild;
+  await page.render({
+    canvasContext: canvas.getContext('2d'),
+    viewport,
+    transform: dpr !== 1 ? [dpr, 0, 0, dpr, 0, 0] : null,
+  }).promise;
+  if (token !== renderToken) return;
+  const tc = await page.getTextContent();
+  if (token !== renderToken) return;
+  // pdf.js 6.x: renderTextLayer() 移除，改 TextLayer 类
+  await new pdfjsLib.TextLayer({ textContentSource: tc, container: tl, viewport }).render();
+}
+
+/** 当前模式的全量重渲入口：缩放/DPR/换文档/换变体统一走这里。 */
+function rerender() {
+  return pageMode === 'paged' ? renderPaged() : renderAllPages();
+}
+
+// 隐藏期间被跳过的重渲请求：尺寸恢复（resize）后补跑。
+// ⚠️ 曾经的坑（用户实测「点放大后全空白」）：守卫在 ++renderToken 之后——隐藏期间的
+// 渲染请求先作废在途渲染、自己又因高度 0 提前返回，容器已被清空却无人再画；且退出
+// 适宽模式后 resize 只重算适宽（if (fitMode)），不补渲 → 永久空白。改为：隐藏期间
+// 的请求直接跳过（不动 token、在途渲染照常画完），标记 pending 等恢复后补画。
+let pendingRerender = false;
+
 async function renderAllPages() {
+  const pane = $('pdf-pane');
+  if (pane.clientHeight === 0) { pendingRerender = true; return; } // 悬浮层隐藏期间不重渲（否则锚点恢复会把滚动清零）
   const token = ++renderToken;
   const container = $('pdf-pages');
-  const pane = $('pdf-pane');
-  if (pane.clientHeight === 0) return; // 悬浮层隐藏期间不重渲（否则锚点恢复会把滚动清零）
+  const scale = zoomScale; // 单次渲染内快照：隐藏期间的 setZoom 改全局值也不至于画出混合缩放
   // 滚动比例锚点：不用 DOM rect（并发重渲时旧页可能已被清空，rect 全灭 → 锚点归零）
   const range = pane.scrollHeight - pane.clientHeight;
   const anchorRatio = range > 0 ? pane.scrollTop / range : 0;
   container.innerHTML = '';
-  $('zoom-label').textContent = Math.round(zoomScale / 1.5 * 100) + '%';
+  container.classList.remove('paged');
+  $('zoom-label').textContent = Math.round(scale / 1.5 * 100) + '%';
 
   for (let i = 1; i <= pdfDoc.numPages; i++) {
     if (token !== renderToken) return;
     const page = await pdfDoc.getPage(i);
     if (token !== renderToken) return;
-    const viewport = page.getViewport({ scale: zoomScale });
-    const div = document.createElement('div');
-    div.className = 'page';
-    div.dataset.page = i;
-    div.style.width = viewport.width + 'px';
-
-    const canvas = document.createElement('canvas');
-    canvas.width = Math.ceil(viewport.width * dpr);
-    canvas.height = Math.ceil(viewport.height * dpr);
-    canvas.style.width = viewport.width + 'px';
-    canvas.style.height = viewport.height + 'px';
-    div.appendChild(canvas);
-
-    const tl = document.createElement('div');
-    tl.className = 'textLayer';
-    tl.style.width = viewport.width + 'px';
-    tl.style.height = viewport.height + 'px';
-    tl.style.setProperty('--scale-factor', String(zoomScale));
-    div.appendChild(tl);
+    const viewport = page.getViewport({ scale });
+    const div = makePageNode(i, viewport);
     container.appendChild(div);
-
-    await page.render({
-      canvasContext: canvas.getContext('2d'),
-      viewport,
-      transform: dpr !== 1 ? [dpr, 0, 0, dpr, 0, 0] : null,
-    }).promise;
-    if (token !== renderToken) return;
-    const tc = await page.getTextContent();
+    await paintPage(page, div, viewport, token);
     if (token !== renderToken) return;
-    // pdf.js 6.x: renderTextLayer() 移除，改 TextLayer 类
-    await new pdfjsLib.TextLayer({ textContentSource: tc, container: tl, viewport }).render();
   }
   const newRange = pane.scrollHeight - pane.clientHeight;
   pane.scrollTop = anchorRatio * Math.max(0, newRange);
+  observePages();
+}
+
+/** 翻页模式：只渲染 curPage 一页（按需渲染，天然无长文档性能问题）。 */
+async function renderPaged() {
+  if ($('pdf-pane').clientHeight === 0) { pendingRerender = true; return; } // 同 renderAllPages：跳过并标记，恢复后补画
+  const token = ++renderToken;
+  const container = $('pdf-pages');
+  const scale = zoomScale; // 同 renderAllPages：快照，防混合缩放
+  curPage = Math.min(Math.max(1, curPage), pdfDoc.numPages);
+  container.innerHTML = '';
+  container.classList.add('paged');
+  $('zoom-label').textContent = Math.round(scale / 1.5 * 100) + '%';
+  updatePager();
+  const page = await pdfDoc.getPage(curPage);
+  if (token !== renderToken) return;
+  const viewport = page.getViewport({ scale });
+  const div = makePageNode(curPage, viewport);
+  container.appendChild(div);
+  await paintPage(page, div, viewport, token);
+}
+
+/** 滚动模式当前页探测：视口竖直中线带（±45%）压到哪页，哪页就是当前页。
+    每次全量重渲后重建（页节点全换）。翻页控件与模式切换共享 curPage。 */
+let pageObserver = null;
+function observePages() {
+  pageObserver?.disconnect();
+  pageObserver = new IntersectionObserver((entries) => {
+    for (const en of entries) {
+      if (en.isIntersecting) {
+        curPage = +en.target.dataset.page || curPage;
+        updatePager();
+      }
+    }
+  }, { root: $('pdf-pane'), rootMargin: '-45% 0px -45% 0px', threshold: 0 });
+  document.querySelectorAll('#pdf-pages .page').forEach((d) => pageObserver.observe(d));
 }
 
-function setZoom(newScale) { if (!pdfDoc) return; zoomScale = Math.min(4.5, Math.max(0.6, newScale)); renderAllPages(); }
+function setZoom(newScale) { if (!pdfDoc) return; zoomScale = Math.min(4.5, Math.max(0.6, newScale)); rerender(); }
 // 默认适宽：rightbar 窄列里 1.5 倍缩放会把页面撑出视口（中英对照双栏页宽≈2×，更明显）
 let fitMode = true;
 const fitBtn = $('zoom-fit');
@@ -507,9 +639,99 @@ function fitToWidth() {
 $('zoom-in').onclick = () => { exitFitMode(); setZoom(zoomScale + 0.25); };
 $('zoom-out').onclick = () => { exitFitMode(); setZoom(zoomScale - 0.25); };
 fitBtn.onclick = () => { if (!pdfDoc) return; fitMode = true; fitBtn.classList.add('active'); fitBtn.blur(); fitToWidth(); };
-window.addEventListener('resize', () => { if (fitMode) fitToWidth(); });
+window.addEventListener('resize', () => {
+  if (fitMode) fitToWidth(); // setZoom → rerender，顺带消化 pendingRerender
+  else if (pendingRerender && pdfDoc) { pendingRerender = false; rerender(); } // 隐藏期间欠下的重渲，恢复尺寸后补画
+});
+
+/* ================= 翻页模式：页码控件 + 模式切换 + 键盘 ================= */
+function flashPage() {
+  const div = document.querySelector(`.page[data-page="${curPage}"]`);
+  if (!div) return;
+  div.classList.add('flash');
+  setTimeout(() => div.classList.remove('flash'), 1600);
+}
+
+/** 页码控件刷新：输入框（未聚焦时才回写，别打断正在敲页码的人）/总页数/首末页禁用。 */
+function updatePager() {
+  const total = pdfDoc ? pdfDoc.numPages : 0;
+  $('page-total').textContent = '/ ' + (total || '?');
+  const input = $('page-input');
+  if (document.activeElement !== input) input.value = total ? curPage : '';
+  $('page-prev').disabled = pageMode === 'paged' && curPage <= 1;
+  $('page-next').disabled = pageMode === 'paged' && curPage >= total;
+}
+
+/** 跳到第 n 页（夹取）：paged 重渲单页+闪烁；scroll 平滑滚到该页。 */
+async function goPage(n) {
+  if (!pdfDoc) return;
+  const p = Math.min(Math.max(1, (n | 0) || 1), pdfDoc.numPages);
+  if (pageMode === 'paged') {
+    if (p === curPage) { flashPage(); return; }
+    curPage = p;
+    await renderPaged();
+    flashPage();
+  } else {
+    curPage = p;
+    jumpToPage(p);
+  }
+}
+
+$('page-prev').onclick = () => goPage(curPage - 1);
+$('page-next').onclick = () => goPage(curPage + 1);
+function commitPageInput() {
+  const v = parseInt($('page-input').value, 10);
+  if (Number.isFinite(v) && v >= 1) goPage(v);
+  else updatePager(); // 非法输入：恢复当前页显示
+}
+// Enter 走 blur 统一提交；Escape 只恢复显示不跳页（标志位让 blur 知道这是放弃编辑）
+let pageInputEscaped = false;
+$('page-input').addEventListener('keydown', (e) => {
+  if (e.key === 'Enter') { e.preventDefault(); e.target.blur(); }
+  else if (e.key === 'Escape') { pageInputEscaped = true; e.target.blur(); }
+});
+$('page-input').addEventListener('blur', () => {
+  if (pageInputEscaped) { pageInputEscaped = false; updatePager(); return; }
+  commitPageInput();
+});
+
+/** 模式切换：paged→scroll 先全量渲染再跳回当前页；scroll→paged 用观察器最近回写的 curPage。
+    图标显示「当前模式」：▣ 单页翻页（active）/ ≣ 连续滚动。 */
+function updateModeToggle() {
+  const btn = $('mode-toggle');
+  btn.textContent = pageMode === 'paged' ? '▣' : '≣';
+  btn.classList.toggle('active', pageMode === 'paged');
+  btn.title = pageMode === 'paged' ? '当前：单页翻页，点击切回连续滚动' : '当前：连续滚动，点击切到单页翻页';
+  updatePager();
+}
+$('mode-toggle').onclick = async () => {
+  if (!pdfDoc) return;
+  pageMode = pageMode === 'paged' ? 'scroll' : 'paged';
+  localStorage.setItem('dpr.pageMode', pageMode);
+  updateModeToggle();
+  if (pageMode === 'paged') {
+    await renderPaged();
+    flashPage();
+  } else {
+    await renderAllPages();
+    jumpToPage(curPage);
+  }
+};
+updateModeToggle();
+
+// 键盘翻页（仅 paged）：输入框聚焦/带修饰键时不抢；Space 在单页模式下无滚动量，拿来做下一页
+document.addEventListener('keydown', (e) => {
+  if (pageMode !== 'paged' || !pdfDoc) return;
+  const tag = (e.target.tagName || '').toUpperCase();
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || e.metaKey || e.ctrlKey || e.altKey) return;
+  if (e.key === 'ArrowRight' || e.key === 'PageDown' || e.key === ' ') { e.preventDefault(); goPage(curPage + 1); }
+  else if (e.key === 'ArrowLeft' || e.key === 'PageUp') { e.preventDefault(); goPage(curPage - 1); }
+  else if (e.key === 'Home') { e.preventDefault(); goPage(1); }
+  else if (e.key === 'End') { e.preventDefault(); goPage(pdfDoc.numPages); }
+});
 
 function jumpToPage(n) {
+  if (pageMode === 'paged') { goPage(n); return; }
   const div = document.querySelector(`.page[data-page="${n}"]`);
   if (!div) return;
   div.scrollIntoView({ behavior: 'smooth', block: 'start' });
@@ -553,9 +775,17 @@ function highlightSnippet(page, q) {
 }
 
 /* 统一跳转入口：先等目标页渲染出来（fit 模式下 loadPdf 返回时页面可能还在渲），
-   有 q 就尝试片段高亮，否则整页跳转 + 边框闪烁 */
+   有 q 就尝试片段高亮，否则整页跳转 + 边框闪烁。
+   paged 模式目标页不在 DOM 里（只渲当前页），轮询永远等不到 → 直接设页渲染。 */
 async function jumpTo(page, q) {
   const p0 = Math.max(1, (page | 0) || 1);
+  if (pageMode === 'paged') {
+    if (!pdfDoc) return;
+    const p = Math.min(p0, pdfDoc.numPages);
+    if (p !== curPage) { curPage = p; await renderPaged(); }
+    if (!(q && highlightSnippet(p, q))) flashPage();
+    return;
+  }
   for (let i = 0; i < 100; i++) {
     if (pdfDoc && document.querySelector(`.page[data-page="${Math.min(p0, pdfDoc.numPages)}"]`)) {
       const p = Math.min(p0, pdfDoc.numPages);