@ggboy123/dsh-paper-reader 0.2.0 → 0.4.0

package/README.md

@@ -19,8 +19,8 @@
 - 📖 **PDF 阅读器居中**：中间是论文（PDF.js 缩放 / Retina 高清 / 文本层选择 / 适宽模式），最右是该论文的原生对话 —— 视觉换位实现，列宽拖拽/折叠仍是 dsh 原生行为，关掉 PDF 页签即还原官方布局
 - 💬 **选中即问**：阅读器里选中文字 → 弹出提问框 → 注入当前会话，原生对话区实时回答
 - 📍 **引用定位**：回答里的「第 N 页」可点击，平滑跳回 PDF 对应页并闪烁
-- 🀄 **中英切换**：顶栏「中」按钮原文 ↔ 纯中文切换；无译文时一键后台生成（babeldoc），生成需配置 `translate` 端点
-- 🔍 **PDF 转录 + 检索**：本地提取（python3 + PyMuPDF），页眉页脚剔除 / 连字 / 断词愈合 / 段落重排，产出页码偏移表；兼容 pdfqa 的 `data/` 缓存布局（旧缓存读取时自动补建页码索引）
+- 🀄 **中英切换**：顶栏「中」按钮原文 ↔ 纯中文切换；无译文时一键后台生成（babeldoc），生成需配置 `translate` 端点；**无需预装 Python**——首次生成时自动下载 uv + 托管 Python + babeldoc（macOS/Linux，约几分钟），全程落在用户目录
+- 🔍 **PDF 转录 + 检索**：本地提取（pdf.js，纯 Node 无需 Python），页眉页脚剔除 / 连字 / 断词愈合 / 段落重排，产出页码偏移表；兼容 pdfqa 的 `data/` 缓存布局（旧缓存读取时自动补建页码索引）
 
 ## 安装
 
@@ -55,6 +55,10 @@ dsh --profile web                                  # 侧栏变为文献库树
 > 中文版端点：**优先在阅读器 UI 里填**（点「中」→ 没配会自动弹表单，或点 ⚙）——填完会先测连接再落盘，不用重启。
 > 上面的 `translate` 配置退为**部署方默认值**，仅当 UI 未配置时生效。babeldoc 只支持 OpenAI 协议端点，
 > Anthropic 协议的端点（如 `api.kimi.com/coding/`）不能直连。
+>
+> 翻译引擎**零预装**：找不到 babeldoc 时自动走 uv 链路安装——uv 独立二进制（GitHub Releases API 下载 + sha256 校验）→
+> uv 托管 Python 3.12 → `uv pip install babeldoc`，落在 `~/.dsh/.dsh-paper-reader/bin/` 与文献库同级 `.venv-pdf2zh/`，
+> 不碰系统 Python。已装有 uv / babeldoc（含 pdfqa 的 `.venv-pdf2zh`）则直接复用。Windows 暂不支持自动安装，需手动装 uv 后重试。
 
 > 伴读模式是**按需开启**的：默认不注册 `sidebar.workspaces`（官方工作区/会话列表原样），侧栏底部「📚 论文伴读」开关点击才接管，再点还原；模式选择记在 localStorage。退出模式时已打开的 PDF 页签和伴读会话不受影响。
 
@@ -67,10 +71,11 @@ src/
   host.ts       webServer 路由（/paper-reader/*），connection.requestRejection 鉴权；
                 sessionController.create/prompt（agentPreset=paper-reader）+ follow SSE 桥
   library.ts    纯函数：文献库目录约定与解析
-  transcribe.ts 纯函数：PyMuPDF 提取 + 页码偏移表（视觉兜底后置）
+  transcribe.ts 纯函数：pdf.js 提取 + 页码偏移表（视觉兜底后置）
   search.ts     纯函数：分段 + 关键词打分 + 页码映射
   study.ts      纯函数：学习档案（计划 + 检验成绩）读写
   translate.ts  纯函数：babeldoc 调用（中文/中英对照 PDF 生成）
+  babeldoc-install.ts 纯函数：无 Python 环境时自动安装 babeldoc（uv → 托管 Python → venv）
   translate-config.ts 纯函数：翻译端点配置读写（$DSH_HOME 下 0600）+ 保存前连接预检
   preset.ts     纯函数：自带 agent preset 安装到 $DSH_HOME/.agent-presets/
 presets/paper-reader/  「论文伴读」agent preset（persona 完整提示词 + compaction）

package/dist/babeldoc-install.js

@@ -0,0 +1,167 @@
+// babeldoc-install.ts — 无 Python 环境用户的 babeldoc 自动安装（纯函数，不依赖 Cordis）。
+//
+// 链路：uv 独立二进制（GitHub Releases，带 sha256 校验）
+//   → `uv venv`（uv 自动下载托管 Python，系统没有 Python 也能跑）
+//   → `uv pip install babeldoc`
+// 全部落在用户目录：uv 二进制在 <dshHome>/.dsh-paper-reader/bin/uv，
+// venv 在 文献库同级 .venv-pdf2zh（必须与 translate.ts findBabeldoc 的第一候选位一致），
+// 不碰系统 Python、不需要 sudo。win32 不在支持范围（tar 解 zip、exe 后缀都要分叉），直接给手动指引。
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+/** uv 发布的 target triple；不支持的平台返回 null（给手动安装指引）。 */
+function uvTriple() {
+    const { platform, arch } = process;
+    if (platform === 'darwin')
+        return arch === 'arm64' ? 'aarch64-apple-darwin' : 'x86_64-apple-darwin';
+    // musl 静态构建：不依赖系统 glibc 版本，最省心
+    if (platform === 'linux') {
+        if (arch === 'x64')
+            return 'x86_64-unknown-linux-musl';
+        if (arch === 'arm64')
+            return 'aarch64-unknown-linux-musl';
+    }
+    return null;
+}
+function run(cmd, args, opts = {}) {
+    return new Promise((res, rej) => {
+        execFile(cmd, args, {
+            timeout: opts.timeout ?? 5 * 60_000,
+            maxBuffer: 16 * 1024 * 1024,
+            env: { ...process.env, ...opts.env },
+        }, (err, stdout, stderr) => {
+            if (err) {
+                const tail = (stdout + '\n' + stderr).trim().slice(-300);
+                rej(new Error(`${cmd} ${args.join(' ')} 失败：${err.message}${tail ? `\n${tail}` : ''}`));
+            }
+            else
+                res(stdout);
+        });
+    });
+}
+async function whichOk(cmd) {
+    return new Promise((res) => {
+        execFile('which', [cmd], (err, stdout) => res(!err && stdout.trim() !== ''));
+    });
+}
+/** 插件托管的 uv 位置（不落系统目录，删插件目录即清干净）。 */
+export function uvPath(home) {
+    return join(home, '.dsh-paper-reader', 'bin', 'uv');
+}
+/** 找 uv：插件托管 → PATH → 常见安装位。 */
+async function findUv(home) {
+    const own = uvPath(home);
+    if (existsSync(own))
+        return own;
+    if (await whichOk('uv'))
+        return 'uv';
+    for (const c of [join(homedir(), '.local', 'bin', 'uv'), join(homedir(), '.cargo', 'bin', 'uv')]) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+/**
+ * 下载 uv 独立二进制。全程走 api.github.com（资产接口 + octet-stream 直连），
+ * 不依赖 github.com 页面域——后者在部分网络环境不可达，而 API 域通常可达。
+ * 完整性用 releases API 返回的 digest（sha256）校验，下载完直接执行的二进制不校验等于裸奔。
+ * fetch 下载不带 quarantine xattr，macOS 不会拦。
+ */
+async function downloadUv(home, onPhase) {
+    const triple = uvTriple();
+    if (!triple) {
+        throw new Error(`当前平台（${process.platform}/${process.arch}）暂不支持自动安装：请手动安装 uv（https://docs.astral.sh/uv/）后重试`);
+    }
+    const want = `uv-${triple}.tar.gz`;
+    const tmp = join(home, '.dsh-paper-reader', 'bin', `.uv-install-${Date.now()}`);
+    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' },
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (!rel.ok)
+            throw new Error(`查询 uv 版本失败：HTTP ${rel.status}（可手动装 uv 后重试）`);
+        const assets = (await rel.json()).assets ?? [];
+        const asset = assets.find((a) => a.name === want);
+        if (!asset)
+            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' },
+                signal: AbortSignal.timeout(180_000),
+            });
+            if (!r.ok)
+                throw new Error(`下载 ${a.name} 失败：HTTP ${r.status}`);
+            return Buffer.from(await r.arrayBuffer());
+        };
+        const body = await download(asset);
+        // 校验和优先用 API 的 digest；老 GitHub 没有 digest 字段时退到 .sha256 资产（同通道）
+        let expect = asset.digest?.replace(/^sha256:/, '');
+        if (!expect && sumAsset)
+            expect = (await download(sumAsset)).toString('utf8').trim().split(/\s+/)[0];
+        if (!expect)
+            throw new Error('拿不到 uv 校验和，为安全起见放弃安装');
+        const actual = createHash('sha256').update(body).digest('hex');
+        if (actual !== expect)
+            throw new Error('uv 下载文件校验和不匹配，已丢弃（请重试）');
+        const tgzPath = join(tmp, 'uv.tar.gz');
+        await writeFile(tgzPath, body);
+        await run('tar', ['-xzf', tgzPath, '-C', tmp], { timeout: 60_000 });
+        const extracted = join(tmp, `uv-${triple}`, 'uv');
+        if (!existsSync(extracted))
+            throw new Error('uv 解包结果不符合预期');
+        const dst = uvPath(home);
+        await rename(extracted, dst);
+        await chmod(dst, 0o755);
+        return dst;
+    }
+    finally {
+        await rm(tmp, { recursive: true, force: true });
+    }
+}
+/** 建 venv + 装 babeldoc。uv 没有可用 Python 时会自己下载托管版，无需系统 Python。 */
+async function installBabeldoc(uv, venvDir, onPhase) {
+    onPhase('正在安装翻译引擎（2/3 安装 Python）…');
+    // --python-preference only-managed：不碰用户系统里可能残缺/带 externally-managed 标记的 Python
+    await run(uv, ['venv', venvDir, '--python', '3.12', '--python-preference', 'only-managed'], { timeout: 10 * 60_000 });
+    const py = join(venvDir, 'bin', 'python');
+    onPhase('正在安装翻译引擎（3/3 安装 babeldoc，首次约几分钟）…');
+    await run(uv, ['pip', 'install', '--python', py, 'babeldoc'], { timeout: 20 * 60_000 });
+    const bin = join(venvDir, 'bin', 'babeldoc');
+    if (!existsSync(bin))
+        throw new Error('babeldoc 安装完成但未找到可执行文件');
+    return bin;
+}
+// 单例：多次点击「中」只允许一个安装流程在跑，其余复用同一个 promise。
+let inflight = null;
+/**
+ * 确保 babeldoc 可用，返回可执行文件路径。
+ * 已存在（venv/PATH/miniconda）直接返回；否则后台走完 uv → python → babeldoc 全链路。
+ * venv 落 dirname(dataDir)/.venv-pdf2zh —— 与 translate.ts findBabeldoc 的第一候选位严格一致。
+ */
+export function ensureBabeldoc(dataDir, home, findExisting, onPhase) {
+    if (!inflight) {
+        inflight = (async () => {
+            const existing = await findExisting();
+            if (existing)
+                return existing;
+            const venvDir = join(dirname(dataDir), '.venv-pdf2zh');
+            const uv = (await findUv(home)) ?? (await downloadUv(home, onPhase));
+            return installBabeldoc(uv, venvDir, onPhase);
+        })().finally(() => {
+            // 成功后清掉单例让下次走快速路径；失败也清掉让下次可以重试
+            inflight = null;
+        });
+    }
+    else {
+        // 并发复用：把 phase 回调接到同一条进度线上（各自显示各自的状态栏）
+        inflight.then(() => onPhase('翻译引擎已就绪')).catch(() => { });
+    }
+    return inflight;
+}

package/dist/host.js

@@ -6,7 +6,7 @@ import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { listPapers, listTopics, resolveDataDir, resolvePaper } from "./library.js";
 import { readTranscript, transcribePaper } from "./transcribe.js";
-import { pdfVariantPath, startTranslation, zhStatus } from "./translate.js";
+import { pdfVariantPath, restartTranslation, startTranslation, zhStatus } from "./translate.js";
 import { clearTranslateConfig, maskApiKey, readTranslateConfig, resolveTranslateEndpoint, testTranslateEndpoint, writeTranslateConfig, } from "./translate-config.js";
 import { installPaperPreset, PAPER_PRESET_ID } from "./preset.js";
 function json(res, status, body) {
@@ -41,6 +41,7 @@ export function registerRoutes(ctx, config) {
     const dataDir = resolveDataDir(config.dataDir);
     // dist/host.js → 包根/reader/index.html
     const readerHtml = new URL('../reader/index.html', import.meta.url);
+    const readerVendorDir = new URL('../reader/vendor/', import.meta.url);
     // 自带「论文伴读」agent preset → $DSH_HOME/.agent-presets/（实时扫描，免重启）；
     // 失败（旧版 dsh/无权限）则回退默认 preset，功能不受影响。
     const presetDir = installPaperPreset(new URL('../', import.meta.url));
@@ -147,6 +148,24 @@ export function registerRoutes(ctx, config) {
             res.end(html);
             return;
         }
+        // 阅读器静态资源（本地 vendor 的 pdf.js 等；拒绝路径穿越）
+        if (sub.startsWith('/vendor/') && req.method === 'GET') {
+            const name = sub.slice('/vendor/'.length);
+            if (!/^[\w.-]+$/.test(name)) {
+                json(res, 400, { error: 'bad asset name' });
+                return;
+            }
+            const mime = { '.mjs': 'text/javascript', '.js': 'text/javascript', '.css': 'text/css', '.map': 'application/json' };
+            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': 'max-age=3600' });
+                res.end(body);
+            }
+            catch {
+                json(res, 404, { error: 'not found' });
+            }
+            return;
+        }
         if (sub === '/api/library' && req.method === 'GET') {
             json(res, 200, { dataDir, topics: listTopics(dataDir), papers: listPapers(dataDir) });
             return;
@@ -261,17 +280,26 @@ export function registerRoutes(ctx, config) {
             createReadStream(pdfPath).pipe(res);
             return;
         }
-        // 中文版状态：zh=纯中文 dual=中英对照 busy=翻译中
+        // 中文版状态：zh=纯中文 dual=中英对照 busy=翻译中。
+        // 顺带返回生效端点的脱敏信息，让 UI 能回答「正在用哪个模型/key 翻」——key 只给掩码。
         if (sub === '/api/zh' && req.method === 'GET') {
-            json(res, 200, zhStatus(locate(url)));
+            const { endpoint, source } = await resolveTranslateEndpoint(config.translate);
+            json(res, 200, {
+                ...zhStatus(locate(url)),
+                model: endpoint.model ?? null,
+                apiKeyHint: endpoint.apiKey ? maskApiKey(endpoint.apiKey) : null,
+                endpointSource: source,
+            });
             return;
         }
-        // 启动后台翻译（幂等）。端点：UI 里填的 > profile 的 translate
+        // 启动后台翻译（幂等；force=true 为重翻：先删已有译文再启动）。端点：UI 里填的 > profile 的 translate
         if (sub === '/api/zh/generate' && req.method === 'POST') {
             const body = (await readBody(req));
             const ref = resolvePaper(dataDir, body);
             const { endpoint } = await resolveTranslateEndpoint(config.translate);
-            const r = await startTranslation(ref, dataDir, endpoint);
+            const r = body.force
+                ? await restartTranslation(ref, dataDir, endpoint)
+                : await startTranslation(ref, dataDir, endpoint);
             json(res, r.started ? 200 : 409, r);
             return;
         }

package/dist/tools.js

@@ -86,7 +86,7 @@ export function registerTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'transcribe_pdf',
-        description: '把一篇 PDF 论文转录为纯文本（本地 PyMuPDF 提取，带页码索引），结果落盘缓存。' +
+        description: '把一篇 PDF 论文转录为纯文本（本地 pdf.js 提取，带页码索引），结果落盘缓存。' +
             '读一篇新论文的第一步：先转录，再用 search_paper 检索。已有缓存时秒回。',
         parameters: {
             ...locateParams,

package/dist/transcribe.js

@@ -2,111 +2,126 @@
 //
 // 移植 pdfqa 的三级策略（视觉兜底后置）：
 //  1. 缓存：.txt 已存在直接复用
-//  2. 快路径：python3 + PyMuPDF 本地提取文本层（文本型 PDF 毫秒级）
+//  2. 快路径：pdfjs-dist（pdf.js）本地提取文本层（文本型 PDF 毫秒级，纯 Node，无需 Python）
 //  3. 慢路径：视觉转录（扫描件兜底）— 暂不支持，返回明确错误
 //
 // 与 pdfqa 的差异：输出附带 pages.json 页码偏移表（每页文本在全文中的 [start,end) 区间），
-// 让 search_paper 能把片段映射回页码。清洗（连字/断词/段落重排）全部在 Python 侧、
-// 偏移计算之前完成，保证偏移与最终文本严格一致。
-import { execFile } from 'node:child_process';
+// 让 search_paper 能把片段映射回页码。清洗（连字/断词/段落重排）全部在偏移计算之前完成，
+// 保证偏移与最终文本严格一致。
+//
+// 历史上快路径用 python3 + PyMuPDF，0.3.0 起换成 pdfjs-dist：阅读器本来就用 pdf.js 渲染，
+// 提取能力等价，且消除了对用户机 Python 环境的依赖。清洗规则与 PyMuPDF 版逐条对齐，
+// 缓存格式（.txt + .pages.json）不变，旧缓存继续兼容。
 import { readFile, writeFile } from 'node:fs/promises';
-import { promisify } from 'node:util';
 import { transcriptCached } from "./library.js";
-const execFileP = promisify(execFile);
-// Python 脚本：提取文本层 → 剔页眉页脚 → 清洗 → 带偏移拼页。
-// 退出码 3 = 文本过少（扫描件），交给上层决定兜底策略。
-const EXTRACT_SCRIPT = String.raw `
-import fitz, sys, re, json
-from collections import Counter
-
-LIG = {'fi':'fi','fl':'fl','ff':'ff','ffi':'ffi','ffl':'ffl','ſt':'st'}
-def ligature(s):
-    for k, v in LIG.items():
-        s = s.replace(k, v)
-    return s
-
-doc = fitz.open(sys.argv[1])
-raw_pages = []
-for page in doc:
-    lines = [l.strip() for l in page.get_text().splitlines()]
-    raw_pages.append([l for l in lines if l])
-
-# 页眉页脚识别：页首 2 行/页尾 3 行归一化（去数字标点，页码归一为空串），
-# 在 >=1/5 页面边缘反复出现即剔除；只剔边缘行，正文相同行不受影响。
-thresh = max(3, len(raw_pages) // 5)
-def norm(l): return re.sub(r'[\d\W]+', '', l).lower()
-edge = Counter()
-for p in raw_pages:
-    for l in p[:2] + p[-3:]:
-        edge[norm(l)] += 1
-bad = {l for l, n in edge.items() if n >= thresh}
-
-page_texts = []
-for p in raw_pages:
-    while p and norm(p[0]) in bad:
-        p.pop(0)
-    while p and norm(p[-1]) in bad:
-        p.pop()
-    t = '\n'.join(p)
-    t = ligature(t)
-    t = re.sub(r'(\w)-\n(\w)', r'\1\2', t)  # 页内断词愈合
-    page_texts.append(t.strip())
-
-total = sum(len(t) for t in page_texts)
-if total < 100 * max(1, len(doc)):
-    sys.exit(3)  # 扫描件
-
-# 段落重排拼页：PDF 分页会把一个句子拆到相邻两页（页眉页脚剔除后就挨在一起）。
-# 上一页不以句末标点结束、且下一页以小写字母开头 → 同句延续，用空格衔接；
-# 该页的偏移区间只覆盖它自己的文字（跨页句引用起始页）。
-SENT_END = re.compile(r'[.!?:;]["\'”’)\]]*$')
-buf = ''
-spans = []
-for i, t in enumerate(page_texts):
-    if not t:
-        continue
-    if not buf:
-        spans.append((i + 1, 0, len(t)))
-        buf = t
-        continue
-    if not SENT_END.search(buf) and t[0].islower():
-        buf = buf.rstrip(' \n')
-        start = len(buf) + 1
-        buf = buf + ' ' + t
-    else:
-        start = len(buf) + 2
-        buf = buf + '\n\n' + t
-    spans.append((i + 1, start, len(buf)))
-
-print(json.dumps({
-    'pageCount': len(doc),
-    'chars': len(buf),
-    'text': buf,
-    'pages': [{'page': p, 'start': s, 'end': e} for p, s, e in spans],
-}, ensure_ascii=False))
-`;
-/** 逐个尝试 python 候选（多个 python 里不一定都装了 fitz）。 */
-async function runPyMuPDF(script, pdfPath) {
-    const candidates = ['python3', '/opt/homebrew/Caskroom/miniconda/base/bin/python3', '/usr/bin/python3'];
-    let sawScanned = false;
-    for (const py of candidates) {
-        try {
-            const { stdout } = await execFileP(py, ['-c', script, pdfPath], {
-                maxBuffer: 64 * 1024 * 1024,
-                timeout: 120_000,
-            });
-            return { ok: true, stdout, scanned: false };
+/** 扫描件信号：文本层过少，换提取器也没用，上层据此给专门提示。 */
+class ScannedPdfError extends Error {
+}
+// ---- 以下为 PyMuPDF 版清洗规则的逐条 TS 移植 ----
+const LIGATURES = [
+    ['fi', 'fi'], ['fl', 'fl'], ['ff', 'ff'], ['ffi', 'ffi'], ['ffl', 'ffl'], ['ſt', 'st'],
+];
+function ligature(s) {
+    for (const [k, v] of LIGATURES)
+        s = s.replaceAll(k, v);
+    return s;
+}
+/** 页眉页脚归一化：去数字标点（对应 Python re.sub(r'[\d\W]+','',l).lower()，保留 unicode 字母）。 */
+function norm(l) {
+    return l.replace(/[^\p{L}_]/gu, '').toLowerCase();
+}
+const SENT_END = /[.!?:;]["'”’)\]]*$/;
+/**
+ * pdfjs 提取文本层 → 剔页眉页脚 → 清洗 → 带偏移拼页。
+ * 扫描件（文本过少）抛 ScannedPdfError，交给上层决定兜底策略。
+ * pdfjs-dist 体积不小，动态 import，首次转录时才加载。
+ */
+async function extractWithPdfjs(pdfPath) {
+    const { getDocument } = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    const data = new Uint8Array(await readFile(pdfPath));
+    const loadingTask = getDocument({ data, disableFontFace: true, verbosity: 0 });
+    const doc = await loadingTask.promise;
+    try {
+        // 每页拼行：getTextContent 的 hasEOL 标记行尾，等价于 PyMuPDF get_text().splitlines()
+        const rawPages = [];
+        for (let i = 1; i <= doc.numPages; i++) {
+            const page = await doc.getPage(i);
+            const tc = await page.getTextContent();
+            const lines = [];
+            let cur = '';
+            for (const item of tc.items) {
+                if (typeof item.str !== 'string')
+                    continue;
+                cur += item.str;
+                if (item.hasEOL) {
+                    lines.push(cur.trim());
+                    cur = '';
+                }
+            }
+            if (cur.trim())
+                lines.push(cur.trim());
+            rawPages.push(lines.filter((l) => l));
+            page.cleanup();
+        }
+        // 页眉页脚识别：页首 2 行/页尾 3 行归一化（去数字标点），
+        // 在 >=1/5 页面边缘反复出现即剔除；只剔边缘行，正文相同行不受影响。
+        const thresh = Math.max(3, Math.floor(rawPages.length / 5));
+        const edge = new Map();
+        for (const p of rawPages) {
+            for (const l of [...p.slice(0, 2), ...p.slice(-3)]) {
+                const n = norm(l);
+                edge.set(n, (edge.get(n) ?? 0) + 1);
+            }
+        }
+        const bad = new Set([...edge].filter(([, n]) => n >= thresh).map(([l]) => l));
+        const pageTexts = [];
+        for (const p of rawPages) {
+            while (p.length && bad.has(norm(p[0])))
+                p.shift();
+            while (p.length && bad.has(norm(p[p.length - 1])))
+                p.pop();
+            let t = p.join('\n');
+            t = ligature(t);
+            t = t.replace(/(\w)-\n(\w)/g, '$1$2'); // 页内断词愈合
+            pageTexts.push(t.trim());
         }
-        catch (err) {
-            // 退出码 3 = 扫描件信号，换一个 python 也没用，但记住这个结论
-            if (err && typeof err === 'object' && err.code === 3)
-                sawScanned = true;
+        const total = pageTexts.reduce((s, t) => s + t.length, 0);
+        if (total < 100 * Math.max(1, doc.numPages))
+            throw new ScannedPdfError();
+        // 段落重排拼页：PDF 分页会把一个句子拆到相邻两页（页眉页脚剔除后就挨在一起）。
+        // 上一页不以句末标点结束、且下一页以小写字母开头 → 同句延续，用空格衔接；
+        // 该页的偏移区间只覆盖它自己的文字（跨页句引用起始页）。
+        let buf = '';
+        const spans = [];
+        for (let i = 0; i < pageTexts.length; i++) {
+            const t = pageTexts[i];
+            if (!t)
+                continue;
+            if (!buf) {
+                spans.push({ page: i + 1, start: 0, end: t.length });
+                buf = t;
+                continue;
+            }
+            let start;
+            if (!SENT_END.test(buf) && /^\p{Ll}/u.test(t)) {
+                buf = buf.replace(/[ \n]+$/, '');
+                start = buf.length + 1;
+                buf = buf + ' ' + t;
+            }
+            else {
+                start = buf.length + 2;
+                buf = buf + '\n\n' + t;
+            }
+            spans.push({ page: i + 1, start, end: buf.length });
         }
+        return { pageCount: doc.numPages, chars: buf.length, text: buf, pages: spans };
+    }
+    finally {
+        await loadingTask.destroy();
     }
-    return { ok: false, stdout: '', scanned: sawScanned };
 }
 /**
- * 转录一篇文献：缓存优先，否则本地 PyMuPDF 提取并落盘（.txt + .pages.json）。
+ * 转录一篇文献：缓存优先，否则本地 pdfjs 提取并落盘（.txt + .pages.json）。
  * 扫描件（文本层过少）抛错并说明视觉兜底尚未实现。
  */
 export async function transcribePaper(ref, opts = {}) {
@@ -129,13 +144,16 @@ export async function transcribePaper(ref, opts = {}) {
 }
 /** 本地提取（不落盘）。 */
 async function extractLocal(pdfPath) {
-    const { ok, stdout, scanned } = await runPyMuPDF(EXTRACT_SCRIPT, pdfPath);
-    if (!ok) {
-        throw new Error(scanned
-            ? '本地提取的文本过少，该 PDF 可能是扫描件。视觉转录兜底尚未实现（Phase 1 后置项），请换文本型 PDF 或手动放置同名 .txt 缓存。'
-            : '未找到可用的 python3 + PyMuPDF 环境。请安装：python3 -m pip install PyMuPDF');
+    let data;
+    try {
+        data = await extractWithPdfjs(pdfPath);
+    }
+    catch (err) {
+        if (err instanceof ScannedPdfError) {
+            throw new Error('本地提取的文本过少，该 PDF 可能是扫描件。视觉转录兜底尚未实现（Phase 1 后置项），请换文本型 PDF 或手动放置同名 .txt 缓存。');
+        }
+        throw new Error(`PDF 文本提取失败：${err instanceof Error ? err.message : String(err)}`);
     }
-    const data = JSON.parse(stdout);
     if (data.text.length < 1000) {
         throw new Error(`转录结果过短(${data.text.length} 字符)，疑似失败，请重试`);
     }
@@ -160,7 +178,7 @@ async function tryUpgradePageIndex(ref, cachedLen) {
         return { text: t.text, pages: t.pages };
     }
     catch {
-        return null; // 无 python 环境或扫描件：保持旧缓存，页码索引缺席
+        return null; // 提取失败或扫描件：保持旧缓存，页码索引缺席
     }
 }
 /** 读页码偏移表；旧缓存（pdfqa 时代）没有 pages.json 时返回 null。 */

package/dist/translate-config.js

@@ -90,8 +90,18 @@ export async function testTranslateEndpoint(ep) {
             body: JSON.stringify({ model, messages: [{ role: 'user', content: 'ping' }], max_tokens: 1 }),
             signal: AbortSignal.timeout(15_000),
         });
-        if (r.ok)
-            return { ok: true };
+        if (r.ok) {
+            // 智谱系网关切错路径时（如 /api/v1）会回 HTTP 200 + {"code":1001,"success":false}，
+            // 只看状态码会误判成功，babeldoc 跑起来才炸。真成功必须有 choices。
+            const text = (await r.text().catch(() => '')).slice(0, 300);
+            try {
+                const data = JSON.parse(text);
+                if (Array.isArray(data.choices))
+                    return { ok: true };
+            }
+            catch { /* 非 JSON 也算失败，走下面报 body */ }
+            return { ok: false, detail: `HTTP 200 但响应不是补全结果：${text.slice(0, 200)}（多半是端点路径不对，如智谱应为 /api/paas/v4）` };
+        }
         const text = (await r.text().catch(() => '')).slice(0, 200);
         return { ok: false, detail: `HTTP ${r.status}${text ? ' ' + text : ''}` };
     }