@ggboy123/dsh-paper-reader 1.3.4 → 1.4.0

package/dist/transcribe.js

@@ -1,21 +1,30 @@
 // transcribe.ts — PDF 转录（纯函数，不依赖 Cordis）。
 //
-// 移植 pdfqa 的三级策略（视觉兜底后置）：
-//  1. 缓存：.txt 已存在直接复用
+// 三级策略：
+//  1. 缓存：.txt 已存在直接复用（来源由 .transcript.json 标记；缺失 = legacy，等价 pdfjs）
 //  2. 快路径：pdfjs-dist（pdf.js）本地提取文本层（文本型 PDF 毫秒级，纯 Node，无需 Python）
-//  3. 慢路径：视觉转录（扫描件兜底）— 暂不支持，返回明确错误
+//  3. MinerU 后端：本地 legacy API / mineru.net v4 云端（扫描件/OCR 兜底，见 mineru.ts）
 //
-// 与 pdfqa 的差异：输出附带 pages.json 页码偏移表（每页文本在全文中的 [start,end) 区间），
-// 让 search_paper 能把片段映射回页码。清洗（连字/断词/段落重排）全部在偏移计算之前完成，
-// 保证偏移与最终文本严格一致。
-//
-// 历史上快路径用 python3 + PyMuPDF，0.3.0 起换成 pdfjs-dist：阅读器本来就用 pdf.js 渲染，
-// 提取能力等价，且消除了对用户机 Python 环境的依赖。清洗规则与 PyMuPDF 版逐条对齐，
-// 缓存格式（.txt + .pages.json）不变，旧缓存继续兼容。
-import { readFile, writeFile } from 'node:fs/promises';
-import { transcriptCached } from "./library.js";
-/** 扫描件信号：文本层过少，换提取器也没用，上层据此给专门提示。 */
-class ScannedPdfError extends Error {
+// 产出仍然是同一套 .txt + .pages.json（page 从 1 起），另加 .transcript.json（来源标记）
+// 与 MinerU 富产物 .mineru.md/.mineru.json（Markdown + content_list，供人工核对）。
+import { readFile, writeFile, rename, rm } from 'node:fs/promises';
+import { statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { parseCloudMineru, parseLocalMineru, MineruError } from "./mineru.js";
+import { MINERU_DEFAULTS } from "./mineru-config.js";
+/** 扫描件/文本过短信号：文本层过少，上层据此决定 MinerU 兜底。 */
+export class ShortTextError extends Error {
+    constructor(message) {
+        super(message);
+        // 显式设 name：上层可据此区分（否则 err.name 只是 'Error'，见验证报告 O3）
+        this.name = 'ShortTextError';
+    }
+}
+/** 扫描件信号（pdfjs 提取内部使用）。 */
+export class ScannedPdfError extends Error {
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 // ---- 以下为 PyMuPDF 版清洗规则的逐条 TS 移植 ----
 const LIGATURES = [
@@ -120,29 +129,137 @@ async function extractWithPdfjs(pdfPath) {
         await loadingTask.destroy();
     }
 }
+/** 来源入参 → 目标 producer；auto 按配置 mode 决定。 */
+function producerForSource(source) {
+    if (source === 'pdfjs')
+        return 'pdfjs';
+    if (source === 'mineru-local')
+        return 'mineru-local';
+    if (source === 'mineru-cloud')
+        return 'mineru-cloud';
+    throw new Error(`内部错误：未知 source ${source}`);
+}
+function producerForMode(mode) {
+    if (mode === 'local')
+        return 'mineru-local';
+    if (mode === 'cloud')
+        return 'mineru-cloud';
+    return 'pdfjs';
+}
+/** 缓存命中判定：source='pdfjs' 命中 legacy/pdfjs；显式 mineru-* 只命中同源。 */
+function producerMatches(requested, actual) {
+    if (requested === 'pdfjs')
+        return actual === 'pdfjs' || actual === 'legacy';
+    return requested === actual;
+}
+/** 读 .transcript.json 的来源标记；缺失/损坏/形状不对返回 null（归类 legacy）。 */
+export async function readTranscriptMeta(ref) {
+    try {
+        const raw = JSON.parse(await readFile(ref.transcriptPath, 'utf8'));
+        if (!isRecord(raw))
+            return null;
+        const producer = raw['producer'];
+        if (producer !== 'pdfjs' && producer !== 'mineru-local' && producer !== 'mineru-cloud')
+            return null;
+        const engine = isRecord(raw['engine']) ? raw['engine'] : null;
+        let backend = null;
+        if (engine) {
+            if (typeof engine['backend'] === 'string')
+                backend = engine['backend'];
+            else if (typeof engine['modelVersion'] === 'string')
+                backend = engine['modelVersion'];
+        }
+        return { producer, backend };
+    }
+    catch {
+        return null;
+    }
+}
+/** 读现有缓存 + 来源标记；txt 缺失返回 null。 */
+async function readCached(ref) {
+    let text;
+    try {
+        text = await readFile(ref.txtPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const pages = await readPages(ref);
+    let producer = 'legacy';
+    let backend = null;
+    let corrupted = false;
+    try {
+        const raw = JSON.parse(await readFile(ref.transcriptPath, 'utf8'));
+        if (isRecord(raw)) {
+            const p = raw['producer'];
+            if (p === 'pdfjs' || p === 'mineru-local' || p === 'mineru-cloud')
+                producer = p;
+            const engine = isRecord(raw['engine']) ? raw['engine'] : null;
+            if (engine) {
+                if (typeof engine['backend'] === 'string')
+                    backend = engine['backend'];
+                else if (typeof engine['modelVersion'] === 'string')
+                    backend = engine['modelVersion'];
+            }
+            const tb = isRecord(raw['text']) ? raw['text']['bytes'] : undefined;
+            if (typeof tb === 'number' && tb !== Buffer.byteLength(text, 'utf8'))
+                corrupted = true;
+        }
+    }
+    catch { /* transcript.json 缺失/损坏 → legacy，不判损坏 */ }
+    return { text, pages, producer, backend, corrupted };
+}
 /**
- * 转录一篇文献：缓存优先，否则本地 pdfjs 提取并落盘（.txt + .pages.json）。
- * 扫描件（文本层过少）抛错并说明视觉兜底尚未实现。
+ * 转录一篇文献：缓存优先（来源语义见 §8），否则按 source/mode 选引擎解析并落盘。
+ * @param opts.source 入参来源（默认 auto）；auto 命中缓存即复用，无缓存按配置 mode。
+ * @param opts.mineru 已解析的 MinerU 配置（缺省 mode=off，行为与改造前一致）。
  */
 export async function transcribePaper(ref, opts = {}) {
-    if (!opts.force && transcriptCached(ref)) {
-        const text = await readFile(ref.txtPath, 'utf8');
-        let pages = await readPages(ref);
-        if (!pages) {
-            // 兼容升级：pdfqa 时代的缓存只有 .txt 没有页码索引。
-            // 重新提取生成页码索引；新旧文本长度接近才覆盖（视觉转录的扫描件缓存不容侵犯）。
-            const upgraded = await tryUpgradePageIndex(ref, text.length);
-            if (upgraded) {
-                pages = upgraded.pages;
-                return { text: upgraded.text, pages, pageCount: pages.length, chars: upgraded.text.length, source: 'cache' };
+    const source = opts.source ?? 'auto';
+    const mineru = opts.mineru ?? { config: MINERU_DEFAULTS, source: 'none' };
+    const force = opts.force === true;
+    // auto 无缓存时按配置 mode 决定目标引擎；显式 source 优先于 mode（mode=off 不阻止显式来源）
+    const targetProducer = source === 'auto' ? producerForMode(mineru.config.mode) : producerForSource(source);
+    if (!force) {
+        const cached = await readCached(ref);
+        // 沿用 v1.2.0 的「缓存有效」门槛（.txt 字节数 > 1000）：过短的缓存视为无效，重新解析。
+        const valid = cached !== null && !cached.corrupted && Buffer.byteLength(cached.text, 'utf8') > 1000;
+        if (valid) {
+            const hit = source === 'auto' ? true : producerMatches(targetProducer, cached.producer);
+            if (hit) {
+                let pages = cached.pages;
+                // 兼容升级：pdfqa 时代的缓存只有 .txt 没有页码索引。重新提取生成页码索引；
+                // 新旧文本长度接近才覆盖（视觉转录的扫描件缓存不容侵犯）。
+                if (!pages && cached.producer === 'legacy') {
+                    const upgraded = await tryUpgradePageIndex(ref, cached.text.length);
+                    if (upgraded) {
+                        pages = upgraded.pages;
+                        return { text: upgraded.text, pages, pageCount: pages.length, chars: upgraded.text.length, source: 'cache', producer: 'legacy', backend: null };
+                    }
+                }
+                return {
+                    text: cached.text,
+                    pages: pages ?? [],
+                    pageCount: pages?.length ?? 0,
+                    chars: cached.text.length,
+                    source: 'cache',
+                    producer: cached.producer,
+                    backend: cached.backend,
+                };
             }
+            // 显式 source 与缓存 producer 不命中 → 判定 stale，重新解析并覆盖（§8）
         }
-        return { text, pages: pages ?? [], pageCount: pages?.length ?? 0, chars: text.length, source: 'cache' };
     }
-    const extracted = await extractAndStore(ref);
-    return extracted;
+    // 重新解析
+    if (targetProducer === 'pdfjs') {
+        return await parseAndStorePdfjs(ref, mineru);
+    }
+    if (targetProducer === 'mineru-local') {
+        return await parseAndStoreMineru(ref, 'mineru-local', mineru.config);
+    }
+    return await parseAndStoreMineru(ref, 'mineru-cloud', mineru.config);
 }
-/** 本地提取（不落盘）。 */
+/** 本地提取（不落盘）。文本过少抛 ShortTextError，供上层做 MinerU 兜底。 */
 async function extractLocal(pdfPath) {
     let data;
     try {
@@ -150,21 +267,172 @@ async function extractLocal(pdfPath) {
     }
     catch (err) {
         if (err instanceof ScannedPdfError) {
-            throw new Error('本地提取的文本过少，该 PDF 可能是扫描件。视觉转录兜底尚未实现（Phase 1 后置项），请换文本型 PDF 或手动放置同名 .txt 缓存。');
+            // 文案只描述「发生了什么」，可执行指引由上层按 MinerU 是否启用补充（见 parseAndStorePdfjs）。
+            // 不再声称「视觉转录兜底尚未实现」——1.3.0 起 MinerU 就是那个兜底（验证报告 O2）。
+            throw new ShortTextError('本地提取的文本过少，该 PDF 可能是扫描件（没有可用文本层）。');
         }
         throw new Error(`PDF 文本提取失败：${err instanceof Error ? err.message : String(err)}`);
     }
     if (data.text.length < 1000) {
-        throw new Error(`转录结果过短(${data.text.length} 字符)，疑似失败，请重试`);
+        throw new ShortTextError(`转录结果过短(${data.text.length} 字符)，疑似失败，请重试`);
     }
-    return { text: data.text, pages: data.pages, pageCount: data.pageCount, chars: data.chars, source: 'local' };
+    return { text: data.text, pages: data.pages, pageCount: data.pageCount, chars: data.chars, source: 'local', producer: 'pdfjs', backend: null };
+}
+/**
+ * 原子写的临时文件路径：pid + 随机后缀。
+ * 只用 pid 时，同一进程内并发写同一目标会撞名并交叉覆盖多文件提交序列（验证报告 F6）。
+ */
+export function atomicTempPath(path) {
+    return `${path}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`;
 }
-/** 本地提取并落盘。 */
-async function extractAndStore(ref) {
-    const t = await extractLocal(ref.pdfPath);
-    await writeFile(ref.txtPath, t.text, 'utf8');
-    await writeFile(ref.pagesPath, JSON.stringify({ pageCount: t.pageCount, pages: t.pages }, null, 2), 'utf8');
-    return t;
+/** 原子写：写临时文件再 rename，POSIX rename 原子覆盖，避免半成品缓存。 */
+async function atomicWrite(path, content) {
+    const tmp = atomicTempPath(path);
+    await writeFile(tmp, content, 'utf8');
+    await rename(tmp, path);
+}
+/** pdfjs 提取并落盘（.txt + .pages.json + .transcript.json），并清理 MinerU 富产物。 */
+async function parseAndStorePdfjs(ref, mineru) {
+    try {
+        const t = await extractLocal(ref.pdfPath);
+        await writeFile(ref.txtPath, t.text, 'utf8');
+        await writeFile(ref.pagesPath, JSON.stringify({ pageCount: t.pageCount, pages: t.pages }, null, 2), 'utf8');
+        await writeFile(ref.transcriptPath, JSON.stringify(pdfjsTranscriptMeta(t), null, 2), 'utf8');
+        // 非 MinerU 来源重写成功后删除 MinerU 富产物（避免富产物与文本不同源，AC-C9）
+        await rm(ref.mineruMdPath, { force: true });
+        await rm(ref.mineruJsonPath, { force: true });
+        return t;
+    }
+    catch (err) {
+        // 扫描件/文本过短：若 MinerU 已配置可用 → 自动兜底改走 MinerU（S10）
+        if (err instanceof ShortTextError && mineru.config.mode !== 'off') {
+            const fallback = mineru.config.mode === 'cloud' ? 'mineru-cloud' : 'mineru-local';
+            try {
+                return await parseAndStoreMineru(ref, fallback, mineru.config);
+            }
+            catch (mineruErr) {
+                // MinerU 兜底也失败：报扫描件错误 + MinerU 指引，不静默吞掉
+                throw new ShortTextError(`${err.message}（已尝试 MinerU 兜底也失败：${mineruErr instanceof Error ? mineruErr.message : String(mineruErr)}）`);
+            }
+        }
+        if (err instanceof ShortTextError) {
+            throw new ShortTextError(`${err.message}（可在「设置 → 论文伴读」启用 MinerU 后端自动解析扫描件，或换文本型 PDF、手动放置同名 .txt 缓存）`);
+        }
+        throw err;
+    }
+}
+/** MinerU 解析并落盘（§7.3/§7.5：先写富产物，最后写 .transcript.json 提交标记）。 */
+async function parseAndStoreMineru(ref, producer, cfg) {
+    const pdfBytes = new Uint8Array(await readFile(ref.pdfPath));
+    const fileName = ref.name + '.pdf';
+    const result = producer === 'mineru-local'
+        ? await parseLocalMineru({
+            baseUrl: cfg.local.baseUrl,
+            apiKey: cfg.local.apiKey,
+            backend: cfg.local.backend,
+            effort: cfg.local.effort,
+            parseMethod: cfg.local.parseMethod,
+            serverUrl: cfg.local.serverUrl,
+            langList: cfg.local.langList,
+            imageAnalysis: cfg.local.imageAnalysis,
+            requestTimeoutMs: cfg.local.requestTimeoutMs,
+            pollIntervalMs: cfg.local.pollIntervalMs,
+            noResponseTimeoutMs: cfg.local.noResponseTimeoutMs,
+            jobTimeoutMs: cfg.local.jobTimeoutMs,
+            pdfBytes,
+            fileName,
+        })
+        : await parseCloudMineru({
+            baseUrl: cfg.cloud.baseUrl,
+            apiKey: cfg.cloud.apiKey,
+            modelVersion: cfg.cloud.modelVersion,
+            pollIntervalMs: cfg.cloud.pollIntervalMs,
+            zipTimeoutMs: cfg.cloud.zipTimeoutMs,
+            pdfBytes,
+            fileName,
+        });
+    const { projection, markdown, blocks, meta } = result;
+    const text = projection.text;
+    const hasMd = markdown.trim().length > 0;
+    // 写盘前校验（§7.5.1）：至少 md_content 或投影文本有一个非空；有 content_list 能建页码索引；文本 >=1000。
+    // 任一不过直接抛错，不写任何文件（失败不得污染缓存）。
+    // 顺序刻意把「content_list 缺失」放在「文本过短」之前：md 好但 content_list 为 null 时，
+    // 真正原因是拿不到页码索引，而不是解析失败（验证报告 F4）。
+    if (!hasMd && !text.trim())
+        throw new MineruError('MinerU 未返回可用内容（md_content 与投影文本均为空）');
+    if (projection.pages.length < 1) {
+        throw new MineruError('MinerU 未返回 content_list（或该字段为空），无法建立页码索引；请确认服务端请求带了 return_content_list=true，或改用 pdfjs 后端。');
+    }
+    if (text.length < 1000)
+        throw new MineruError(`MinerU 转录结果过短(${text.length} 字符)，疑似失败，请重试`);
+    const createdAt = new Date().toISOString();
+    const warnings = projection.warnings;
+    // 写盘顺序：mineru.md → mineru.json → pages.json → txt → transcript.json（最后=提交标记）
+    await atomicWrite(ref.mineruMdPath, markdown);
+    await atomicWrite(ref.mineruJsonPath, JSON.stringify(mineruJsonPayload(producer, meta, projection, blocks, createdAt), null, 2));
+    await atomicWrite(ref.pagesPath, JSON.stringify({ pageCount: projection.pageCount, pages: projection.pages }, null, 2));
+    await atomicWrite(ref.txtPath, text);
+    await atomicWrite(ref.transcriptPath, JSON.stringify(mineruTranscriptMeta(producer, meta, text, projection, warnings, createdAt), null, 2));
+    const backend = producer === 'mineru-local' ? (meta.backend ?? null) : (meta.modelVersion ?? null);
+    return {
+        text,
+        pages: projection.pages,
+        pageCount: projection.pageCount,
+        chars: text.length,
+        source: producer,
+        producer,
+        backend,
+    };
+}
+function pdfjsTranscriptMeta(t) {
+    return {
+        v: 1,
+        producer: 'pdfjs',
+        createdAt: new Date().toISOString(),
+        text: { bytes: Buffer.byteLength(t.text, 'utf8'), chars: t.chars, pageCount: t.pageCount },
+    };
+}
+function mineruTranscriptMeta(producer, meta, text, projection, warnings, createdAt) {
+    const engine = producer === 'mineru-local'
+        ? {
+            kind: 'mineru-local',
+            api: 'legacy',
+            baseUrl: meta.baseUrl,
+            ...(meta.serverVersion ? { serverVersion: meta.serverVersion } : {}),
+            ...(meta.backend ? { backend: meta.backend } : {}),
+            ...(meta.effort ? { effort: meta.effort } : {}),
+            ...(meta.parseMethod ? { parseMethod: meta.parseMethod } : {}),
+            ...(meta.langList ? { langList: meta.langList } : {}),
+            ...(meta.taskId ? { taskId: meta.taskId } : {}),
+            elapsedMs: meta.elapsedMs,
+        }
+        : {
+            kind: 'mineru-cloud',
+            api: 'v4',
+            baseUrl: meta.baseUrl,
+            ...(meta.batchId ? { batchId: meta.batchId } : {}),
+            modelVersion: meta.modelVersion ?? 'pipeline',
+        };
+    return {
+        v: 1,
+        producer,
+        createdAt,
+        text: { bytes: Buffer.byteLength(text, 'utf8'), chars: text.length, pageCount: projection.pageCount },
+        engine,
+        warnings,
+    };
+}
+function mineruJsonPayload(producer, meta, projection, blocks, createdAt) {
+    return {
+        v: 1,
+        producer,
+        createdAt,
+        ...(meta.serverVersion ? { serverVersion: meta.serverVersion } : {}),
+        ...(meta.backend ? { backend: meta.backend } : {}),
+        pageCount: projection.pageCount,
+        imagesAvailable: false,
+        contentList: blocks,
+    };
 }
 /** 为旧缓存补建页码索引：成功且长度相近才覆盖 .txt，返回新内容；否则返回 null。 */
 async function tryUpgradePageIndex(ref, cachedLen) {
@@ -201,3 +469,12 @@ export async function readTranscript(ref) {
         return null;
     }
 }
+/** 转录缓存大小（供外部快速判断，保留 v1.2.0 语义）。 */
+export function transcriptBytes(ref) {
+    try {
+        return statSync(ref.txtPath).size;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/translate-config.js

@@ -7,6 +7,11 @@
 import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { dshHome } from "./library.js";
+// 预检会把端点响应体片段拼进错误文案，必须先脱敏（否则端点回显 Authorization 时 key 会泄露）。
+// 这里复用 MinerU 客户端里已经过三轮评审的 sanitizeDetail（含 URL 编码 / JSON 转义 / 短 key
+// 词边界处理）。mineru.ts 运行时只 import node:zlib（对 mineru-config.ts 是 type-only import），
+// 所以 translate-config → mineru 是单向依赖，**不会形成运行时循环**。
+import { sanitizeDetail } from "./mineru.js";
 export function translateConfigPath(home = dshHome()) {
     return join(home, '.dsh-paper-reader', 'translate.json');
 }
@@ -102,10 +107,11 @@ export async function testTranslateEndpoint(ep) {
                     return { ok: true };
             }
             catch { /* 非 JSON 也算失败，走下面报 body */ }
-            return { ok: false, detail: `HTTP 200 但响应不是补全结果：${text.slice(0, 200)}（多半是端点路径不对，如智谱应为 /api/paas/v4）` };
+            // 响应体可能回显 Authorization / 错误页：先按本次 key 脱敏再截断展示（保留排查价值）
+            return { ok: false, detail: `HTTP 200 但响应不是补全结果：${sanitizeDetail(text.slice(0, 200), apiKey)}（多半是端点路径不对，如智谱应为 /api/paas/v4）` };
         }
         const text = (await r.text().catch(() => '')).slice(0, 200);
-        return { ok: false, detail: `HTTP ${r.status}${text ? ' ' + text : ''}` };
+        return { ok: false, detail: `HTTP ${r.status}${text ? ' ' + sanitizeDetail(text, apiKey) : ''}` };
     }
     catch (err) {
         // Node 的 fetch 把真实原因（ECONNREFUSED / 证书错误 / 超时）塞在 cause 里，