@ggboy123/dsh-paper-reader 1.3.4 → 1.4.0

package/dist/embed.js

@@ -0,0 +1,349 @@
+// embed.ts — OpenAI 兼容嵌入端点客户端 + 分块嵌入缓存 + 混合召回（纯函数，不依赖 Cordis）。
+//
+// 形状对齐 rerank.ts：**可选增强、默认关闭、失败降级**而不是抛给用户。与重排的分工：
+//   - 重排（rerank.ts）：对关键词 shortlist **定序**（候选已经捞回来了）；
+//   - 嵌入（本文件）：**全量召回**——关键词一个词都没命中的语义相近片段也能进候选。
+// 两者可同时启用，顺序固定：关键词候选 ∪ 嵌入候选 → RRF 融合 →（配了 Jev/TypeSafe 则）既有重排 → top-k。
+//
+// 缓存：`<论文>.embeddings.json`，键 = {model, dimensions, 内容哈希}；命中时**不请求分块嵌入**。
+// 隐私：分块文本会发往配置的端点（README 有明确提示）；缓存与错误信息里都不出现 apiKey。
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { pageForOffset } from "./search.js";
+import { sanitizeDetail } from "./mineru.js";
+export const EMBED_DEFAULTS = { batchSize: 32, timeoutMs: 30_000, candidateSize: 20 };
+/** 嵌入链路错误的统一类型：调用方据此**整体降级**为纯关键词，不把它抛给用户。 */
+export class EmbedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EmbedError';
+    }
+}
+/** `<论文>.txt` → `<论文>.embeddings.json`（与 .txt/.pages.json 同目录同前缀）。 */
+export function embeddingsPathFor(txtPath) {
+    return txtPath.replace(/\.txt$/i, '') + '.embeddings.json';
+}
+/**
+ * 分块集合的内容哈希（缓存失效条件之一）：分块大小 + 分块数 + 每块长度 + 每块文本，顺序敏感。
+ * `.txt` 变了 / 分块大小变了 / 重新转录了 → 哈希变 → 缓存判定失效并重算。
+ */
+export function chunkSetHash(chunks, chunkSize = 1500) {
+    const h = createHash('sha256');
+    h.update(`chunkSize:${chunkSize};count:${chunks.length}\n`);
+    for (const c of chunks)
+        h.update(`${c.text.length}:${c.text}\n`);
+    return h.digest('hex');
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isFiniteNumber(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+/**
+ * 校验嵌入响应：形状（条数一致）、维度一致、**必须都是有限数**（NaN/Infinity/字符串一律拒绝）。
+ * 同时容忍两种常见形状：OpenAI 的 `{index, embedding}` 与部分本地实现直接给的数组。
+ */
+export function validateEmbeddings(raw, expected, where) {
+    if (!Array.isArray(raw))
+        throw new EmbedError(`${where}：data 不是数组`);
+    if (raw.length !== expected)
+        throw new EmbedError(`${where}：返回 ${raw.length} 条嵌入，期望 ${expected} 条`);
+    const out = [];
+    let dim = -1;
+    for (const row of raw) {
+        const vec = Array.isArray(row) ? row : isRecord(row) ? row['embedding'] : undefined;
+        if (!Array.isArray(vec))
+            throw new EmbedError(`${where}：条目缺少 embedding 数组`);
+        if (vec.length === 0)
+            throw new EmbedError(`${where}：嵌入维度为 0`);
+        for (const v of vec) {
+            if (!isFiniteNumber(v))
+                throw new EmbedError(`${where}：嵌入含非数值/NaN，已拒绝`);
+        }
+        if (dim === -1)
+            dim = vec.length;
+        else if (vec.length !== dim)
+            throw new EmbedError(`${where}：同批嵌入维度不一致（${dim} vs ${vec.length}）`);
+        out.push(vec);
+    }
+    return out;
+}
+/** 端点 URL：允许用户直接填到 `/embeddings`，否则拼在根后面。 */
+export function embeddingsUrl(baseUrl) {
+    const base = baseUrl.replace(/\/+$/, '');
+    return /\/embeddings$/i.test(base) ? base : `${base}/embeddings`;
+}
+function networkMessage(err) {
+    if (err instanceof Error) {
+        const cause = err.cause instanceof Error ? `：${err.cause.message}` : '';
+        return `${err.name === 'TimeoutError' ? '请求超时' : err.message}${cause}`;
+    }
+    return String(err);
+}
+/**
+ * 一次 `/embeddings` 调用（一批文本）。任何失败都抛 EmbedError（调用方整体降级）。
+ * 错误文案里的端点响应体片段一律经 sanitizeDetail(…, apiKey) 脱敏。
+ */
+export async function requestEmbeddings(req, texts) {
+    if (texts.length === 0)
+        return [];
+    const timeoutMs = req.timeoutMs ?? EMBED_DEFAULTS.timeoutMs;
+    const fetchImpl = req.fetchImpl ?? fetch;
+    const signals = [AbortSignal.timeout(timeoutMs)];
+    if (req.signal)
+        signals.push(req.signal);
+    let res;
+    try {
+        res = await fetchImpl(embeddingsUrl(req.baseUrl), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${req.apiKey}` },
+            body: JSON.stringify({ model: req.model, input: texts, encoding_format: 'float' }),
+            signal: signals.length === 1 ? signals[0] : AbortSignal.any(signals),
+        });
+    }
+    catch (err) {
+        throw new EmbedError(`嵌入端点请求失败：${sanitizeDetail(networkMessage(err), req.apiKey)}`);
+    }
+    const body = await res.text().catch(() => '');
+    if (!res.ok) {
+        const detail = sanitizeDetail(body.slice(0, 200), req.apiKey);
+        throw new EmbedError(`嵌入端点返回 HTTP ${res.status}${detail ? `：${detail}` : ''}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new EmbedError('嵌入端点返回的不是合法 JSON');
+    }
+    return validateEmbeddings(isRecord(parsed) ? parsed['data'] : undefined, texts.length, '嵌入端点响应');
+}
+// ── 缓存 ────────────────────────────────────────────────────────────────
+/** 读缓存：文件缺失/损坏/形状不对一律 null（与其余 *.json 读策略一致）。 */
+export async function readEmbedCache(path) {
+    try {
+        const data = JSON.parse(await readFile(path, 'utf8'));
+        if (!isRecord(data))
+            return null;
+        const vectors = data['vectors'];
+        if (!Array.isArray(vectors))
+            return null;
+        if (typeof data['model'] !== 'string' || typeof data['contentHash'] !== 'string')
+            return null;
+        if (!Number.isInteger(data['dimensions']))
+            return null;
+        return {
+            v: 1,
+            // 旧缓存没有 baseUrl 字段 → 记为空串 → 与任何真实 baseUrl 都不相等 → 判定失效重算（一次性的预期失效）
+            baseUrl: typeof data['baseUrl'] === 'string' ? data['baseUrl'] : '',
+            model: data['model'],
+            dimensions: data['dimensions'],
+            contentHash: data['contentHash'],
+            createdAt: typeof data['createdAt'] === 'string' ? data['createdAt'] : '',
+            vectors: vectors,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** 原子写缓存（临时文件 + rename），避免半截 JSON 被当成有效缓存。 */
+export async function writeEmbedCache(path, cache) {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+    await writeFile(tmp, JSON.stringify(cache), 'utf8');
+    await rename(tmp, path);
+}
+/** 删除缓存（模型/维度失效或用户显式清理时用）。 */
+export async function clearEmbedCache(path) {
+    await rm(path, { force: true });
+}
+/**
+ * 惰性计算分块嵌入：缓存有效则直接复用（零分块请求），否则按 batchSize 分批请求。
+ * 缓存键 = `{baseUrl, model, dimensions, 内容哈希}`（F-E2：baseUrl 与查询向量备忘对齐，
+ * 换端点必须重算）；缓存有效性 = v=1 ∧ baseUrl 一致 ∧ model 一致 ∧ 内容哈希一致 ∧ 条数一致
+ * ∧ 维度一致（含 expectedDimensions）∧ 全为有限数。
+ * 任一批次失败都抛 EmbedError（调用方整体降级），**不写缓存** —— 绝不产生半截缓存。
+ */
+export async function ensureChunkVectors(o) {
+    const model = o.req.model;
+    const hash = chunkSetHash(o.chunks, o.chunkSize ?? 1500);
+    const cached = await readEmbedCache(o.cachePath);
+    const cacheOk = cached !== null &&
+        cached.baseUrl === o.req.baseUrl &&
+        cached.model === model &&
+        cached.contentHash === hash &&
+        cached.vectors.length === o.chunks.length &&
+        cached.dimensions > 0 &&
+        cached.vectors.every((v) => Array.isArray(v) && v.length === cached.dimensions && v.every(isFiniteNumber)) &&
+        (o.expectedDimensions === undefined || o.expectedDimensions === cached.dimensions);
+    if (cacheOk)
+        return { vectors: cached.vectors, dimensions: cached.dimensions, fromCache: true };
+    if (o.chunks.length === 0)
+        return { vectors: [], dimensions: o.expectedDimensions ?? 0, fromCache: false };
+    const batchSize = Math.max(1, o.batchSize ?? EMBED_DEFAULTS.batchSize);
+    const vectors = [];
+    let dimensions = -1;
+    for (let i = 0; i < o.chunks.length; i += batchSize) {
+        const part = o.chunks.slice(i, i + batchSize);
+        const got = await requestEmbeddings(o.req, part.map((c) => c.text));
+        for (const v of got) {
+            if (dimensions === -1)
+                dimensions = v.length;
+            else if (v.length !== dimensions)
+                throw new EmbedError(`分批嵌入维度不一致（${dimensions} vs ${v.length}）`);
+            vectors.push(v);
+        }
+    }
+    if (o.expectedDimensions !== undefined && dimensions !== o.expectedDimensions) {
+        throw new EmbedError(`嵌入维度与查询向量不一致（${dimensions} vs ${o.expectedDimensions}），本次语义召回已放弃`);
+    }
+    await writeEmbedCache(o.cachePath, {
+        v: 1,
+        baseUrl: o.req.baseUrl,
+        model,
+        dimensions,
+        contentHash: hash,
+        createdAt: new Date().toISOString(),
+        vectors,
+    });
+    return { vectors, dimensions, fromCache: false };
+}
+/**
+ * 进程内查询向量备忘：同一查询重复检索（同一模型/端点）时**零网络请求**。
+ * 键含 endpoint+model，换模型/换端点自动失效；只留最近 32 条，不落盘（查询文本不进缓存文件）。
+ */
+const queryMemo = new Map();
+const QUERY_MEMO_MAX = 32;
+function memoKey(req, text) {
+    return `${req.baseUrl}|${req.model}|${text}`;
+}
+/** 清空查询向量备忘（测试/换模型时用）。 */
+export function clearEmbedQueryMemo() {
+    queryMemo.clear();
+}
+/** 查询向量（带进程内备忘）。 */
+export async function embedQuery(req, text) {
+    const key = memoKey(req, text);
+    const hit = queryMemo.get(key);
+    if (hit)
+        return hit;
+    const [vec] = await requestEmbeddings(req, [text]);
+    if (!vec)
+        throw new EmbedError('嵌入端点未返回查询向量');
+    queryMemo.set(key, vec);
+    if (queryMemo.size > QUERY_MEMO_MAX) {
+        const oldest = queryMemo.keys().next().value;
+        if (oldest !== undefined)
+            queryMemo.delete(oldest);
+    }
+    return vec;
+}
+// ── 召回与融合 ──────────────────────────────────────────────────────────
+/** 余弦相似度；维度不同/零向量一律返回 0（不抛错，避免脏数据中断检索）。 */
+export function cosineSimilarity(a, b) {
+    if (a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        dot += x * y;
+        na += x * x;
+        nb += y * y;
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/** 语义召回：按余弦取前 limit 块（相似度 ≤ 0 视为噪声，不进候选）。 */
+export function embeddingRecall(chunks, pages, queryVector, vectors, limit) {
+    const scored = [];
+    const n = Math.min(chunks.length, vectors.length);
+    for (let i = 0; i < n; i++) {
+        const sim = cosineSimilarity(queryVector, vectors[i]);
+        if (sim > 0) {
+            scored.push({ chunk: chunks[i], score: Math.round(sim * 1000) / 1000, page: pageForOffset(pages, chunks[i].start) });
+        }
+    }
+    scored.sort((a, b) => b.score - a.score || a.chunk.index - b.chunk.index);
+    return scored.slice(0, Math.max(1, limit));
+}
+/**
+ * RRF 融合（Reciprocal Rank Fusion，k=60）：关键词候选 ∪ 语义候选 → 按**名次**加权求和 → 去重。
+ * 为什么用名次而不是原始分数：关键词分（词频×词长）与余弦相似度量纲完全不同，直接相加没有意义。
+ *
+ * **实际语义（F-E1 如实记录，算法有意如此，不是 bug）**：
+ *   - 只吃名次、**完全不看分数大小**：关键词第 i 名与语义第 j 名的贡献分别是 1/(60+i) 与 1/(60+j)，
+ *     所以语义第 j 名会压过关键词第 i 名（当 j < i）——两列候选会**交替占用**最终 top-k 名额；
+ *   - 「关键词优先」只在**精确同分**时生效（两列名次相同、分数相等时关键词那列排前面）；
+ *   - 两列都命中的片段获得两份贡献，自然排最前。
+ * 这正是「嵌入作为召回、与关键词候选交替占位」的预期形态：关键词检索仍在跑并持续贡献候选，
+ * 并未被替换。**注意**：本机没有真实嵌入端点可用于调参，故不引入「按分数插值 / 名额保底」
+ * 这类无法验证的融合策略；若将来要改（例如给关键词列加权或保底名额），需先回报队长并补可验证证据。
+ */
+export function fuseHybridCandidates(keyword, semantic, limit) {
+    const RRF_K = 60;
+    const byRank = (hits) => hits.slice().sort((a, b) => b.score - a.score || a.chunk.index - b.chunk.index);
+    const kw = byRank(keyword);
+    const sem = byRank(semantic);
+    const byChunk = new Map();
+    const score = new Map();
+    const fromKeyword = new Set();
+    kw.forEach((h, i) => {
+        byChunk.set(h.chunk.index, h);
+        fromKeyword.add(h.chunk.index);
+        score.set(h.chunk.index, (score.get(h.chunk.index) ?? 0) + 1 / (RRF_K + i + 1));
+    });
+    sem.forEach((h, i) => {
+        if (!byChunk.has(h.chunk.index))
+            byChunk.set(h.chunk.index, h);
+        score.set(h.chunk.index, (score.get(h.chunk.index) ?? 0) + 1 / (RRF_K + i + 1));
+    });
+    const picked = [...byChunk.keys()]
+        .sort((a, b) => {
+        const d = (score.get(b) ?? 0) - (score.get(a) ?? 0);
+        if (d !== 0)
+            return d;
+        const ka = fromKeyword.has(a);
+        const kb = fromKeyword.has(b);
+        if (ka !== kb)
+            return ka ? -1 : 1;
+        return a - b;
+    })
+        .slice(0, Math.max(1, limit))
+        .map((idx) => byChunk.get(idx));
+    picked.sort((a, b) => a.chunk.index - b.chunk.index); // 与 searchChunks 一致：按原文顺序返回
+    return picked;
+}
+/**
+ * 惰性语义召回：查询向量（带进程内备忘）+ 分块向量（带磁盘缓存）→ 余弦 top-N。
+ * 任何失败（不可达/超时/HTTP 错误/形状或维度非法/非数值）都**吞成 degraded 原因**，
+ * 返回空候选让调用方继续用关键词结果——绝不抛错中断检索。
+ */
+export async function embeddingRecallFor(o) {
+    if (!o.configured || !o.req) {
+        return { hits: [], configured: false, used: false, fromCache: false, degraded: null };
+    }
+    try {
+        const queryVector = await embedQuery(o.req, o.query);
+        const { vectors, fromCache } = await ensureChunkVectors({
+            cachePath: o.cachePath,
+            chunks: o.chunks,
+            ...(o.chunkSize !== undefined ? { chunkSize: o.chunkSize } : {}),
+            req: o.req,
+            expectedDimensions: queryVector.length,
+            ...(o.batchSize !== undefined ? { batchSize: o.batchSize } : {}),
+        });
+        const hits = embeddingRecall(o.chunks, o.pages, queryVector, vectors, o.limit ?? EMBED_DEFAULTS.candidateSize);
+        return { hits, configured: true, used: hits.length > 0, fromCache, degraded: null };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { hits: [], configured: true, used: false, fromCache: false, degraded: msg };
+    }
+}

package/dist/formulas.js

@@ -0,0 +1,272 @@
+// formulas.ts — MinerU content_list → 阅读器可用的公式索引（纯函数 + 一次读盘）。
+//
+// 背景（docs/reader-ux-requirements.md §1）：PDF 文本层里的公式是乱码（`𝑧𝑧1 𝑧𝑧2` 这类
+// 重复字形），鼠标选中拿不到可用内容；MinerU 的 content_list 里每个 equation 块带
+// LaTeX（`text`）与 `bbox`，这才是可引用的真相源。
+//
+// bbox 坐标系（实测 + 源码实证，见需求文档 §1.1）：**页面归一化坐标 ×1000**
+//   x = bbox[0]/1000 * viewport.width ，y = bbox[1]/1000 * viewport.height
+// 原点左上、y 向下、与缩放无关。归一化只在 page_size 存在时才成立，所以这里做一次
+// 防御性判定：全页最大分量 ≤ 1000 → 'normalized-1000'，否则退回 'page-units'
+// （调用方按 pt/px × scale 处理），避免云端版本差异导致热区整体错位。
+//
+// ⚠️ 与需求文档的**显式偏离**（队长在 t2 进行中裁定的契约修订）：
+//   文档 §1.7 写的是「`latex` 原样含 `$$`」，本轮改为**紧凑形态**——服务端复用既有的
+//   投影函数 `compressMathSpaces` + `normalizeMathBraces`（src/mineru.ts 导出，与
+//   content_list → .txt 的投影同一套规则）。理由：MinerU 原始输出每个 token 之间都插空格
+//   （`\pi ( \mathbf { s } _ { t } )`），① 与同一产品 .txt 里的检索形态自相矛盾；
+//   ② 用户会把 LaTeX 粘到别处，紧凑写法才是地道 LaTeX。`$$` 定界符保留（模型友好）。
+//   `\text{}`/`\textrm`/`\mbox` 一族按既有规则整组原样保留（组内空格是排版语义）。
+import { readFile, stat } from 'node:fs/promises';
+import { compressMathSpaces, normalizeMathBraces } from "./mineru.js";
+/** 供测试与调用方复用的紧凑化：既有投影两步 + 算子名统一（见下）。 */
+export function compactLatex(rawLatex) {
+    return unifyOperatorNames(normalizeMathBraces(compressMathSpaces(rawLatex)));
+}
+/**
+ * `\operatorname` / `\operatorname*` 的算子名统一（**引用路径专用**，契约 t2 第 2 次修订）。
+ *
+ * 背景：MinerU 对算子名做**逐字符空格化**（`\operatorname { D o g }`），照原样渲染会出现
+ * `D o g` 这类多余空格；而既有投影函数把 `\operatorname` 整组保护起来（不压空格），
+ * 带 `*` 的变体因命令名扫描在 `*` 处断开而**没被保护**——于是两个变体行为不一致。
+ *
+ * 精确规则（两个变体完全一致）：
+ *   · 组内 token **全部是单字符** → 判为逐字符空格化产物，合并成一个词：
+ *     `{ m a x }`→`max`、`{ i f }`→`if`、`{ D o g }`→`Dog`、`{ s . t . }`→`s.t.`
+ *   · 否则**原样保留**：`{ arg max }`（token 是 `arg`/`max`）绝不能被合并成 `argmax`。
+ *   花括号不配对 / 组缺失 → 一律不碰。
+ *
+ * 上游根因已同步修掉（src/mineru.ts 的 scanCommandName）：命令名扫描原先在 `*` 处停下，
+ * 导致带 `*` 的变体压根没被当成受保护组、两个变体行为不一致；现在两变体走同一条路径。
+ * 「合并成一个词」这一步仍只放在**引用路径**（本模块）：.txt 投影里 `\operatorname{a b c}`
+ * 保持逐字符空格是被既有断言固定的行为（test/embed-search.test.mjs H1、
+ * test/embed-verification.test.mjs 6.1），在共享函数里合并会破坏那两条断言与
+ * 「既有 182 个用例保持通过」。
+ */
+export function unifyOperatorNames(latex) {
+    if (!latex.includes('\\operatorname'))
+        return latex;
+    const CMD = '\\operatorname';
+    let out = '';
+    let i = 0;
+    while (i < latex.length) {
+        const at = latex.indexOf(CMD, i);
+        if (at < 0) {
+            out += latex.slice(i);
+            break;
+        }
+        let k = at + CMD.length;
+        if (latex.startsWith('withlimits', k))
+            k += 'withlimits'.length;
+        else if (latex[k] === '*')
+            k += 1;
+        else if (isAsciiLetter(latex[k] ?? '')) {
+            out += latex.slice(i, k);
+            i = k;
+            continue;
+        } // 前缀同形命令不卷进来
+        const head = latex.slice(at, k);
+        let p = k;
+        while (p < latex.length && /\s/.test(latex[p]))
+            p++;
+        if (latex[p] !== '{') {
+            out += latex.slice(i, k);
+            i = k;
+            continue;
+        }
+        const end = matchBrace(latex, p);
+        if (end < 0) {
+            out += latex.slice(i, k);
+            i = k;
+            continue;
+        } // 花括号不配对：此后一律不碰
+        const inner = latex.slice(p + 1, end);
+        const tokens = inner.trim().split(/\s+/).filter((t) => t.length > 0);
+        if (tokens.length > 0 && tokens.every((t) => [...t].length === 1)) {
+            out += latex.slice(i, at) + head + '{' + tokens.join('') + '}'; // 逐字符空格化 → 合并成一个词
+        }
+        else {
+            // `{ arg max }` 等：组内容一字不动（绝不合并），只削掉紧贴花括号的填充空白——
+            // 让带 `*` 与不带 `*` 两个变体输出一致（`\operatorname{arg max}` / `\operatorname*{arg max}`）。
+            // 花括号内侧的空格在 \operatorname 组内无语义，削掉安全；\text 一族不走这里（保持逐字节原样）。
+            out += latex.slice(i, at) + head + '{' + inner.trim() + '}';
+        }
+        i = end + 1;
+    }
+    return out;
+}
+function isAsciiLetter(c) {
+    return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
+}
+/** `{` 起始的配对花括号：返回对应 `}` 的下标，失败返回 -1（转义 `\{` / `\}` 跳过）。 */
+function matchBrace(text, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i++) {
+        const c = text[i];
+        if (c === '\\') {
+            i++;
+            continue;
+        }
+        if (c === '{')
+            depth++;
+        else if (c === '}') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+const EMPTY = (reason, warning) => ({
+    source: reason === 'no-mineru-artifact' ? 'none' : 'mineru',
+    producer: null,
+    backend: null,
+    pageCount: null,
+    pageSize: null,
+    bboxSpace: 'normalized-1000',
+    equations: [],
+    reason,
+    ...(warning ? { warning } : {}),
+});
+function toBbox(v) {
+    if (!Array.isArray(v) || v.length !== 4)
+        return null;
+    const out = [];
+    for (const n of v) {
+        if (typeof n !== 'number' || !Number.isFinite(n))
+            return null;
+        out.push(n);
+    }
+    return out;
+}
+/** 从 `.mineru.json` 的原始文本建索引。`raw === null` = 文件不存在（走 pdfjs 或未转录）。 */
+export function buildFormulaIndex(raw, opts = {}) {
+    if (raw === null)
+        return EMPTY('no-mineru-artifact');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return EMPTY('bad-artifact', 'mineru.json 不是合法 JSON，已忽略');
+    }
+    if (!isRecord(parsed))
+        return EMPTY('bad-artifact', 'mineru.json 顶层不是对象，已忽略');
+    const list = parsed['contentList'];
+    if (list === undefined)
+        return EMPTY('bad-artifact', 'mineru.json 缺少 contentList，已忽略');
+    if (!Array.isArray(list))
+        return EMPTY('bad-artifact', 'contentList 不是数组，已忽略');
+    const producer = typeof parsed['producer'] === 'string' ? parsed['producer'] : (typeof opts.producer === 'string' ? opts.producer : null);
+    const backend = typeof parsed['backend'] === 'string' ? parsed['backend'] : (typeof opts.backend === 'string' ? opts.backend : null);
+    const pageCount = typeof parsed['pageCount'] === 'number' && Number.isFinite(parsed['pageCount'])
+        ? parsed['pageCount']
+        : (typeof opts.pageCount === 'number' && Number.isFinite(opts.pageCount) ? opts.pageCount : null);
+    // 逐块取 equation（缺 page_idx 的块沿用上一个有页码的块——与 transcribe.ts 的投影口径一致）
+    const raw_eq = [];
+    let lastPageIdx = 0;
+    let malformed = 0;
+    for (const b of list) {
+        if (!isRecord(b)) {
+            malformed++;
+            continue;
+        }
+        if (b['type'] !== 'equation')
+            continue;
+        const pi = b['page_idx'];
+        if (typeof pi === 'number' && Number.isFinite(pi) && pi >= 0)
+            lastPageIdx = Math.trunc(pi);
+        const text = b['text'];
+        const latex = typeof text === 'string' ? text : '';
+        const fmt = typeof b['text_format'] === 'string' ? b['text_format'] : null;
+        if (typeof pi !== 'number' && text === undefined)
+            malformed++;
+        raw_eq.push({ pageIdx: lastPageIdx, bbox: toBbox(b['bbox']), latex, fmt });
+    }
+    // 阅读序：先页码，再自上而下（bbox[1]），再自左而右（bbox[0]）。content_list 本身是
+    // 版面序（先左栏后右栏），直接照抄会给错序（实测：一页里 y 是 486,688,809,409,511）。
+    raw_eq.sort((a, b) => {
+        if (a.pageIdx !== b.pageIdx)
+            return a.pageIdx - b.pageIdx;
+        const ay = a.bbox ? a.bbox[1] : Number.MAX_SAFE_INTEGER;
+        const by = b.bbox ? b.bbox[1] : Number.MAX_SAFE_INTEGER;
+        if (ay !== by)
+            return ay - by;
+        const ax = a.bbox ? a.bbox[0] : Number.MAX_SAFE_INTEGER;
+        const bx = b.bbox ? b.bbox[0] : Number.MAX_SAFE_INTEGER;
+        return ax - bx;
+    });
+    const perPage = new Map();
+    const equations = raw_eq.map((e) => {
+        const index = (perPage.get(e.pageIdx) ?? 0) + 1;
+        perPage.set(e.pageIdx, index);
+        return {
+            id: `${e.pageIdx}:${index}`,
+            page: e.pageIdx + 1,
+            pageIdx: e.pageIdx,
+            index,
+            bbox: e.bbox,
+            // 紧凑形态：既有投影两步 + 算子名统一（见文件头与 unifyOperatorNames 的说明）
+            latex: compactLatex(e.latex),
+            textFormat: e.fmt,
+        };
+    });
+    if (equations.length === 0) {
+        const reason = malformed > 0 ? 'bad-artifact' : 'no-equations';
+        const idx = EMPTY(reason, malformed > 0 ? `contentList 中有 ${malformed} 个无法解析的块` : undefined);
+        return { ...idx, producer, backend, pageCount };
+    }
+    // 坐标空间判定：全页最大分量 ≤ 1000 → 归一化（MinerU 3.x 的口径）；否则按原始单位处理。
+    let maxComp = 0;
+    for (const e of equations) {
+        if (!e.bbox)
+            continue;
+        for (const v of e.bbox)
+            maxComp = Math.max(maxComp, v);
+    }
+    const bboxSpace = maxComp > 1000 ? 'page-units' : 'normalized-1000';
+    return {
+        source: 'mineru',
+        producer,
+        backend,
+        pageCount,
+        pageSize: null,
+        bboxSpace,
+        equations,
+        ...(bboxSpace === 'page-units' ? { warning: 'bbox 分量超过 1000，按原始单位（pt/px）处理' } : {}),
+    };
+}
+let cache = null;
+/** 读 `<ref.mineruJsonPath>` 并建索引。文件缺失/损坏一律返回可用的空索引，**不抛异常**。 */
+export async function readFormulaIndex(ref) {
+    let key = `${ref.mineruJsonPath}:absent`;
+    try {
+        const st = await stat(ref.mineruJsonPath);
+        key = `${ref.mineruJsonPath}:${st.mtimeMs}:${st.size}`;
+        if (cache && cache.key === key)
+            return cache.value;
+        const raw = await readFile(ref.mineruJsonPath, 'utf8');
+        const value = buildFormulaIndex(raw);
+        cache = { key, value };
+        return value;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'EISDIR') {
+            const value = buildFormulaIndex(null);
+            if (cache?.key === key)
+                return cache.value;
+            cache = { key, value };
+            return value;
+        }
+        // 权限等异常也不许把阅读器打崩：降级成 bad-artifact
+        return EMPTY('bad-artifact', `读取 mineru.json 失败：${code ?? 'unknown'}`);
+    }
+}
+/** 仅供测试：清空记忆化。 */
+export function resetFormulaCache() {
+    cache = null;
+}