@ggboy123/dsh-paper-reader 1.3.4 → 1.4.0

package/dist/search.js

@@ -1,5 +1,8 @@
 // search.ts — 长文档分段检索（纯函数，不依赖 Cordis）。
 // 移植 pdfqa 的 chunkText + searchPaper，新增：片段 → 页码映射（经 pages.json 偏移表）。
+// 折叠项 1：查询侧归一化复用**投影侧同一个** token 级归一化函数（normalizeMathBody 的导出别名），
+// 规则逐字符一致，不存在「两套实现各自漂移」的可能。
+import { normalizeMathTokens } from "./mineru.js";
 /** 按空行分段后打包成 ~size 字符的片段（忠实移植 pdfqa chunkText）。 */
 export function chunkText(text, size = 1500) {
     const paras = text.split('\n\n');
@@ -96,3 +99,52 @@ export function formatHits(hits, totalChunks, query) {
     }
     return parts.join('\n');
 }
+/**
+ * 折叠项 1 —— 查询侧 LaTeX 归一化。
+ * 投影侧把 `.txt` 里单 token 的下标/上标去了花括号（`Q_{t}` → `Q_t`），代价是带花括号的查询
+ * 命中为 0。这里把同一个规则作用在**查询**上：`Q_{t}` → `Q_t`，于是两种写法命中同一页。
+ * 规则一致由代码保证（直接调投影侧同一个 normalizeMathBody）；无需归一化时返回 null：
+ * 纯散文查询（没有 `_{...}`/`^{...}` 形态）与多 token 参数（`x_{ij}`、`x_{t-1}`）都原样返回。
+ */
+export function compactQuery(query) {
+    const compact = normalizeMathTokens(query);
+    return compact === query ? null : compact;
+}
+/**
+ * 检索实际要用的查询写法：**原样永远保留**，有紧凑写法时追加一条。
+ * 保留原样是关键——归一化只增加召回，不会让任何既有命中消失（对 pdfjs 来源的论文同理）。
+ */
+export function queryVariants(query) {
+    const compact = compactQuery(query);
+    return compact === null ? [query] : [query, compact];
+}
+/**
+ * 按论文来源决定查询写法：投影侧的紧凑写法只出现在 **MinerU** 产物里，
+ * 所以查询侧的镜像变体也只在 MinerU 来源的论文上追加——pdfjs / 旧缓存论文保持
+ * 「原查询原样」（不引入任何新行为，也不丢任何既有命中）。
+ */
+export function queryVariantsFor(producer, query) {
+    const mineru = producer === 'mineru-local' || producer === 'mineru-cloud';
+    return mineru ? queryVariants(query) : [query];
+}
+/**
+ * 多写法关键词检索：逐个写法跑一遍 searchChunks，按 chunk 合并（取最高分），再按原有语义取 top-k
+ * 并按原文顺序返回。只有一个写法时**直接走 searchChunks**，与改造前逐字节一致。
+ */
+export function searchChunksMulti(chunks, pages, queries, k = 5) {
+    const use = queries.filter((q) => q !== '');
+    if (use.length <= 1)
+        return searchChunks(chunks, pages, use[0] ?? '', k);
+    const merged = new Map();
+    for (const q of use) {
+        for (const hit of searchChunks(chunks, pages, q, k)) {
+            const prev = merged.get(hit.chunk.index);
+            if (prev === undefined || hit.score > prev.score)
+                merged.set(hit.chunk.index, hit);
+        }
+    }
+    return [...merged.values()]
+        .sort((a, b) => b.score - a.score)
+        .slice(0, Math.max(1, k))
+        .sort((a, b) => a.chunk.index - b.chunk.index);
+}

package/dist/tools.js

@@ -2,10 +2,18 @@
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { listPapers, listTopics, resolveDataDir, resolvePaper } from "./library.js";
 import { transcribePaper, readTranscript } from "./transcribe.js";
-import { chunkText, searchChunks, formatHits } from "./search.js";
+import { chunkText, queryVariantsFor, searchChunksMulti, formatHits } from "./search.js";
+import { readTranscriptMeta } from "./transcribe.js";
+import { EMBED_DEFAULTS, embeddingsPathFor, embeddingRecallFor, fuseHybridCandidates } from "./embed.js";
+import { resolveEmbedConfig } from "./embed-config.js";
 import { resolveRerankClient, resolveShortlistSize, rerankHits } from "./rerank.js";
 import { completeStep, formatStudy, readStudy, recordQuiz, setPlan } from "./study.js";
 import { readerOrigin } from "./origin.js";
+import { resolveMineruConfig } from "./mineru-config.js";
+const MINERU_SOURCES = ['auto', 'pdfjs', 'mineru-local', 'mineru-cloud'];
+function sourceArg(v) {
+    return MINERU_SOURCES.includes(v) ? v : 'auto';
+}
 const locateParams = {
     path: { type: 'string', description: 'PDF 绝对路径。与 topic+name 二选一。' },
     topic: { type: 'string', description: '专题名（文献库一级目录）。' },
@@ -59,6 +67,24 @@ const readerUrlSchema = {
 };
 /** render 文本尾部统一带出的链接基址行（preset 规定了用法，这里只暴露值）。 */
 const readerUrlLine = (url) => (url ? `\n阅读器链接基址：${url}` : '');
+/** 4 个 source 值的文案（§10.1：不得把 MinerU 结果误报成「本地提取」）。 */
+function sourceLabel(source) {
+    switch (source) {
+        case 'cache': return '缓存复用';
+        case 'local': return '本地提取(pdf.js)';
+        case 'mineru-local': return '本地 MinerU 解析';
+        case 'mineru-cloud': return '云端 MinerU 解析';
+        default: return source;
+    }
+}
+function producerLabel(producer) {
+    switch (producer) {
+        case 'pdfjs': return 'pdf.js';
+        case 'mineru-local': return '本地 MinerU';
+        case 'mineru-cloud': return '云端 MinerU';
+        default: return producer;
+    }
+}
 export function registerTools(ctx, config) {
     const dataDir = resolveDataDir(config.dataDir);
     const shortlistSize = resolveShortlistSize(config.typesafe);
@@ -104,11 +130,18 @@ export function registerTools(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'transcribe_pdf',
-        description: '把一篇 PDF 论文转录为纯文本（本地 pdf.js 提取，带页码索引），结果落盘缓存。' +
+        description: '把一篇 PDF 论文转录为纯文本（默认本地 pdf.js 提取，带页码索引），结果落盘缓存。' +
+            '可指定 source=mineru-local/mineru-cloud 改走 MinerU 解析后端（本地/云端，适合扫描件）。' +
             '读一篇新论文的第一步：先转录，再用 search_paper 检索。已有缓存时秒回。',
         parameters: {
             ...locateParams,
             force: { type: 'boolean', description: '忽略缓存重新转录。' },
+            source: {
+                type: 'string',
+                enum: ['auto', 'pdfjs', 'mineru-local', 'mineru-cloud'],
+                description: '解析来源：auto=有缓存复用、无缓存按配置（默认 pdfjs）；pdfjs=本地 pdf.js 文本层；' +
+                    'mineru-local=本地 MinerU API；mineru-cloud=mineru.net v4 云端。',
+            },
         },
         output: {
             schema: {
@@ -119,7 +152,18 @@ export function registerTools(ctx, config) {
                     chars: { type: 'integer', required: true },
                     pageCount: { type: 'integer', required: true },
                     hasPageIndex: { type: 'boolean', required: true, description: '是否有页码索引（检索结果能否带页码）。' },
-                    source: { type: 'string', required: true, enum: ['cache', 'local'] },
+                    source: { type: 'string', required: true, enum: ['cache', 'local', 'mineru-local', 'mineru-cloud'] },
+                    producer: {
+                        type: 'string',
+                        required: true,
+                        enum: ['legacy', 'pdfjs', 'mineru-local', 'mineru-cloud'],
+                        description: '产出这份文本的引擎；legacy=旧缓存（缺来源标记，等价 pdfjs）。',
+                    },
+                    backend: {
+                        oneOf: [{ type: 'string' }, { type: 'null' }],
+                        required: true,
+                        description: '实际 MinerU backend（本地）或 modelVersion（云端）；非 MinerU 为 null。',
+                    },
                     readerUrl: readerUrlSchema,
                 },
                 additionalProperties: false,
@@ -128,7 +172,10 @@ export function registerTools(ctx, config) {
                 {
                     type: 'text',
                     text: `已转录《${value.paper}》：${value.chars} 字符，${value.pageCount} 页` +
-                        `（${value.source === 'cache' ? '缓存复用' : '本地提取'}${value.hasPageIndex ? '，含页码索引' : '，无页码索引'}）。` +
+                        `（${sourceLabel(value.source)}${value.hasPageIndex ? '，含页码索引' : '，无页码索引'}）。` +
+                        (value.source !== 'cache' && value.producer !== 'pdfjs' && value.producer !== 'legacy'
+                            ? ` 引擎：${producerLabel(value.producer)}${value.backend ? `（${value.backend}）` : ''}。`
+                            : '') +
                         `接下来可用 search_paper 检索具体内容。` +
                         readerUrlLine(value.readerUrl),
                 },
@@ -136,7 +183,8 @@ export function registerTools(ctx, config) {
         },
         execute: async (args, exec) => {
             const ref = locate(dataDir, args, exec);
-            const t = await transcribePaper(ref, { force: args.force === true });
+            const mineru = await resolveMineruConfig(config.mineru);
+            const t = await transcribePaper(ref, { force: args.force === true, source: sourceArg(args.source), mineru });
             return {
                 paper: `${ref.topic}/${ref.name}`,
                 txtPath: ref.txtPath,
@@ -144,6 +192,8 @@ export function registerTools(ctx, config) {
                 pageCount: t.pageCount,
                 hasPageIndex: t.pages.length > 0,
                 source: t.source,
+                producer: t.producer,
+                backend: t.backend,
                 readerUrl: readerUrl(ref),
             };
         },
@@ -153,7 +203,8 @@ export function registerTools(ctx, config) {
         description: '在论文全文中按关键词检索相关片段，返回带页码的原文片段。' +
             '当需要论文的具体内容（定义、算法步骤、章节细节、数据）时使用，基于检索到的原文回答并注明页码。' +
             '关键词建议：用论文中的英文术语、章节号（如 "Section 3.1"）或概念名，不要用完整长句；找不到时换同义词或更短的词重试。' +
-            '论文未转录时会自动先转录。',
+            '论文未转录时会自动先转录。' +
+            '（配置了嵌入端点时额外做语义召回；未配置则纯关键词，与改造前一致）',
         parameters: {
             query: { type: 'string', required: true, description: '检索关键词，如 "backup task" 或 "locality"。' },
             k: { type: 'integer', description: '返回片段数量，默认 5，最多 8。' },
@@ -171,6 +222,23 @@ export function registerTools(ctx, config) {
                         required: true,
                         description: '返回片段是否经过语义重排（配置了 Jev/TypeSafe 凭据且候选充足时为 true）。',
                     },
+                    compactQuery: {
+                        oneOf: [{ type: 'string' }, { type: 'null' }],
+                        required: true,
+                        description: '查询侧 LaTeX 紧凑写法（MinerU 来源论文才会一并匹配，如 Q_{t} → Q_t）；无需归一化时为 null。',
+                    },
+                    embedding: {
+                        type: 'object',
+                        required: true,
+                        description: '嵌入语义召回的状态：未配置时 configured=false 且不影响结果；降级时 degraded 给出原因。',
+                        properties: {
+                            configured: { type: 'boolean', required: true },
+                            used: { type: 'boolean', required: true },
+                            fromCache: { type: 'boolean', required: true },
+                            degraded: { oneOf: [{ type: 'string' }, { type: 'null' }], required: true },
+                        },
+                        additionalProperties: false,
+                    },
                     hits: {
                         type: 'array',
                         required: true,
@@ -192,32 +260,84 @@ export function registerTools(ctx, config) {
                 },
                 additionalProperties: false,
             },
-            render: (_args, value) => [
-                {
-                    type: 'text',
-                    text: formatHits(value.hits.map((h) => ({
-                        chunk: { index: h.chunk, start: 0, end: 0, text: h.text },
-                        score: 0,
-                        page: h.page,
-                    })), value.totalChunks, value.query) + readerUrlLine(value.readerUrl),
-                },
-            ],
+            render: (_args, value) => {
+                const notes = [];
+                if (value.compactQuery) {
+                    notes.push(`（查询已按紧凑写法 \`${value.compactQuery}\` 一并匹配；原查询保留）`);
+                }
+                if (value.embedding.degraded) {
+                    notes.push(`（嵌入检索不可用，已降级为纯关键词：${value.embedding.degraded}）`);
+                }
+                else if (value.embedding.configured && value.embedding.used) {
+                    notes.push(value.embedding.fromCache ? '（含嵌入语义召回；分块向量命中缓存）' : '（含嵌入语义召回）');
+                }
+                return [
+                    {
+                        type: 'text',
+                        text: formatHits(value.hits.map((h) => ({
+                            chunk: { index: h.chunk, start: 0, end: 0, text: h.text },
+                            score: 0,
+                            page: h.page,
+                        })), value.totalChunks, value.query) +
+                            (notes.length ? '\n' + notes.join('\n') : '') +
+                            readerUrlLine(value.readerUrl),
+                    },
+                ];
+            },
         },
         execute: async (args, exec) => {
             const ref = locate(dataDir, args, exec);
             let cached = await readTranscript(ref);
             if (!cached) {
-                await transcribePaper(ref);
+                const mineru = await resolveMineruConfig(config.mineru);
+                await transcribePaper(ref, { source: 'auto', mineru });
                 cached = await readTranscript(ref);
             }
             if (!cached)
                 throw new Error('转录失败，无法检索');
             const chunks = chunkText(cached.text, 1500);
             const k = Math.max(1, Math.min(args.k ?? 5, 8));
-            // 两段式检索:关键词快搜捞 shortlist(宽召回),Jev 按语义重排取 top-k。
-            // 凭据每次现查(设置面板保存即生效);无凭据或候选不超过 k 时跳过重排。
+            // 折叠项 1（查询侧 LaTeX 归一化）：投影侧只对 MinerU 产物做紧凑写法归一化，
+            // 因此查询侧的同名变体也**只对 MinerU 来源的论文**追加；原查询永远保留 →
+            // pdfjs/旧缓存论文既不丢命中也不引入新行为（与改造前逐字节一致）。
+            const producer = (await readTranscriptMeta(ref))?.producer ?? null;
+            const variants = queryVariantsFor(producer, args.query);
+            const compact = variants.length > 1 ? variants[1] : null;
+            // 关键词快搜捞 shortlist（宽召回）→ 可选语义召回 → 既有重排 → top-k。
+            // 凭据每次现查（设置面板保存即生效）；未配置时三段都退回纯关键词，行为与改造前一致。
             const rerankClient = await resolveRerankClient(config.typesafe);
-            let hits = searchChunks(chunks, cached.pages, args.query, rerankClient ? shortlistSize : k);
+            const embedCfg = await resolveEmbedConfig(config.embed);
+            const wideRecall = Boolean(rerankClient) || embedCfg.enabled;
+            const recallSize = wideRecall ? Math.max(k, shortlistSize) : k;
+            let hits = searchChunksMulti(chunks, cached.pages, variants, recallSize);
+            // 嵌入召回：惰性（首次检索该论文才算）+ 缓存（<论文>.embeddings.json）；失败只影响本次召回。
+            const embedding = await embeddingRecallFor({
+                configured: embedCfg.enabled,
+                cachePath: embeddingsPathFor(ref.txtPath),
+                chunks,
+                pages: cached.pages,
+                query: args.query,
+                chunkSize: 1500,
+                limit: embedCfg.cfg.candidateSize ?? EMBED_DEFAULTS.candidateSize,
+                ...(embedCfg.enabled
+                    ? {
+                        req: {
+                            baseUrl: embedCfg.cfg.baseUrl,
+                            apiKey: embedCfg.cfg.apiKey,
+                            model: embedCfg.cfg.model,
+                            ...(embedCfg.cfg.timeoutMs !== undefined ? { timeoutMs: embedCfg.cfg.timeoutMs } : {}),
+                        },
+                        ...(embedCfg.cfg.batchSize !== undefined ? { batchSize: embedCfg.cfg.batchSize } : {}),
+                    }
+                    : {}),
+            });
+            if (embedding.hits.length > 0)
+                hits = fuseHybridCandidates(hits, embedding.hits, recallSize);
+            if (!wideRecall)
+                hits = hits.slice(0, k);
+            if (embedding.degraded) {
+                console.warn('[dsh-paper-reader] 嵌入检索降级为纯关键词:', embedding.degraded);
+            }
             let reranked = false;
             if (rerankClient && hits.length > k) {
                 try {
@@ -225,17 +345,26 @@ export function registerTools(ctx, config) {
                     reranked = true;
                 }
                 catch (e) {
-                    // 超预算/网络/鉴权任何失败都退回关键词 top-k(结果已算好,零成本降级)
+                    // 超预算/网络/鉴权任何失败都退回关键词 top-k（结果已算好，零成本降级）
                     console.warn('[dsh-paper-reader] 检索重排失败，退回关键词排序:', e);
                     hits = hits.slice(0, k);
                 }
             }
+            if (!reranked)
+                hits = hits.slice(0, k);
             return {
                 paper: `${ref.topic}/${ref.name}`,
                 query: args.query,
                 totalChunks: chunks.length,
                 hits: hits.map((h) => ({ chunk: h.chunk.index, page: h.page, text: h.chunk.text })),
                 reranked,
+                compactQuery: compact,
+                embedding: {
+                    configured: embedding.configured,
+                    used: embedding.used,
+                    fromCache: embedding.fromCache,
+                    degraded: embedding.degraded,
+                },
                 readerUrl: readerUrl(ref),
             };
         },