@customize-agent/knowledge 4.0.14 → 4.0.15

package/dist/extraction/content-extractor.d.ts

@@ -48,13 +48,17 @@ export declare class ContentExtractor {
     private extractOfficeZip;
     private extractRasterImage;
     private tryPaddleOcrLayout;
-    private parseOcrJson;
-    private formatOcrRegions;
-    private classifyOcrRegion;
     private formatBoundingBox;
     private validateRasterImage;
     private extractPdf;
     private extractPdfHybridPages;
+    /** PyMuPDF 渲染（300 DPI 原生提取，质量远高于 pdfjs-dist） */
+    private tryRenderWithPyMuPDF;
+    /** pdfjs-dist + canvas 渲染（降级方案） */
+    private tryRenderWithPdfJs;
+    private scoreOcrText;
+    /** 加载图片像素数据（依赖 sharp） */
+    private loadImagePixels;
     private extractPdfText;
     private normalizedTextLength;
     private toPdfTextItem;

package/dist/extraction/content-extractor.js

@@ -2,8 +2,9 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { tmpdir } from 'node:os';
-import { pathToFileURL } from 'node:url';
-import { resolveAndImport, resolvePackage, getNodeModulesRoot } from './module-resolver.js';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolveAndImport, resolvePackage } from './module-resolver.js';
+import { createOcrProvider } from './ocr-providers.js';
 const CAD_INTERNAL_TOKEN_RE = /\b(?:TDbPipe|TDbPipeValve|TDbPipeFitting|TDbWellh|AcDb\w+|Dwg\w+|ObjectId|Handle|ByLayer|Continuous|Model|Layout\d*)\b/giu;
 const CAD_INTERNAL_LINE_RE = /^(?:TDb\w+|AcDb\w+|[A-F0-9]{8,}|\d+|Model|Layout\d*|ByLayer|Continuous)$/iu;
 /** 文件内容提取器，支持文档、表格、图片、CAD 等多种文件格式的内容抽取 */
@@ -857,7 +858,8 @@ export class ContentExtractor {
         }
     }
     async extractRasterImage(file) {
-        const metadata = { extractionMode: 'builtin_tesseract_ocr_isolated', vectorizable: true };
+        const metadata = { extractionMode: 'ocr_provider', vectorizable: true };
+        const warnings = [];
         if (process.env.CUSTOMIZE_AGENT_DISABLE_OCR === '1') {
             metadata.extractionMode = 'raster_image_metadata';
             metadata.contentCoverage = 'metadata_filename';
@@ -869,67 +871,56 @@ export class ContentExtractor {
             metadata.parseError = validationError;
             return { text: '', metadata, warnings: [`图片文件无效或不完整：${validationError}，未入库`] };
         }
-        const paddle = await this.tryPaddleOcrLayout(file.absolutePath);
-        if (paddle) {
+        // 1. 尝试外部 PaddleOCR 命令（CUSTOMIZE_PADDLE_OCR_CMD）
+        const paddleExternal = await this.tryPaddleOcrLayout(file.absolutePath);
+        if (paddleExternal) {
             metadata.contentCoverage = 'paddleocr_layout_regions';
-            metadata.ocrProvider = 'paddleocr';
-            metadata.ocrRegionCount = paddle.regionCount;
-            return { text: [this.metadataOnlyText(file), paddle.text].join('\n'), metadata, warnings: [] };
+            metadata.ocrProvider = 'paddleocr-external';
+            metadata.ocrRegionCount = paddleExternal.regionCount;
+            return { text: [this.metadataOnlyText(file), paddleExternal.text].join('\n'), metadata, warnings };
         }
-        let tesseractPath;
+        // 2. 加载图片像素数据
+        let imageData;
         try {
-            tesseractPath = resolvePackage('tesseract.js');
+            imageData = await this.loadImagePixels(file.absolutePath);
         }
         catch (e) {
-            metadata.contentCoverage = 'ocr_unavailable';
+            metadata.contentCoverage = 'image_decode_failed';
             metadata.parseError = e.message;
-            return { text: '', metadata, warnings: [`内置 OCR 不可用：${e.message}`] };
-        }
-        // 子进程用 createRequire 加载 tesseract.js（兼容打包 Server 的 vendor 目录）
-        const result = spawnSync(process.execPath, [
-            '--input-type=module',
-            '-e',
-            `import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
-
-const localRequire = createRequire(import.meta.url);
-const tesseractMod = localRequire(${JSON.stringify(tesseractPath)});
-const { createWorker } = tesseractMod;
-
-const worker = await createWorker('chi_sim+eng');
-try {
-  const result = await worker.recognize(process.argv[1]);
-  const lines = (result.data.lines || []).map((line, index) => ({
-    index: index + 1,
-    text: line.text || '',
-    bbox: line.bbox || line.baseline || null,
-  })).filter(line => line.text.trim());
-  process.stdout.write(JSON.stringify({ text: result.data.text || '', lines }));
-} finally {
-  await worker.terminate();
-}`,
-            file.absolutePath,
-        ], { encoding: 'utf8', timeout: 120_000, maxBuffer: 20 * 1024 * 1024 });
-        if (result.status !== 0 || result.error) {
-            const message = result.error?.message || result.stderr.trim() || `OCR 子进程退出码 ${result.status ?? 'unknown'}`;
+            return { text: '', metadata, warnings: [`图片解码失败：${e.message}，未入库`] };
+        }
+        // 3. OCR Provider（PaddleOCR ONNX → Tesseract CLI → Tesseract.js）
+        let provider = null;
+        try {
+            provider = await createOcrProvider();
+            metadata.ocrProvider = provider.id;
+            const ocrResult = await provider.recognize(imageData);
+            const text = ocrResult.text.trim();
+            if (text) {
+                metadata.contentCoverage = 'ocr_provider_text';
+                metadata.ocrTextLength = text.length;
+                metadata.ocrConfidence = ocrResult.confidence;
+                metadata.ocrRegionCount = ocrResult.regions.length;
+                const regionLines = ocrResult.regions.map((r, i) => `区域 ${i + 1} [置信度 ${r.confidence.toFixed(2)}] [bbox x0=${r.box.x}, y0=${r.box.y}, x1=${r.box.x + r.box.width}, y1=${r.box.y + r.box.height}]: ${r.text}`);
+                return {
+                    text: [this.metadataOnlyText(file), 'OCR 区域文本:', ...regionLines, `OCR 完整文本:\n${text}`].join('\n'),
+                    metadata,
+                    warnings,
+                };
+            }
+            metadata.contentCoverage = 'ocr_no_text';
+            warnings.push(`${metadata.ocrProvider} 未识别到文字，未入库`);
+            return { text: '', metadata, warnings };
+        }
+        catch (e) {
             metadata.contentCoverage = 'ocr_failed';
-            metadata.parseError = message;
-            return { text: '', metadata, warnings: [`内置 OCR 解析失败：${message}，未入库`] };
-        }
-        const parsed = this.parseOcrJson(result.stdout);
-        const text = parsed.text.trim();
-        const regions = this.formatOcrRegions(parsed.lines);
-        metadata.contentCoverage = text ? 'ocr_text_bounding_boxes' : 'metadata_filename';
-        metadata.ocrProvider = 'tesseract.js';
-        metadata.ocrLanguages = 'chi_sim+eng';
-        metadata.ocrTextLength = text.length;
-        metadata.ocrLineCount = parsed.lines.length;
-        return {
-            text: text ? [this.metadataOnlyText(file), 'OCR 区域文本:', ...regions, `OCR 完整文本:\n${text}`].join('\n') : '',
-            metadata,
-            warnings: text ? [] : ['内置 OCR 未识别到文字，未入库'],
-        };
+            metadata.parseError = e.message;
+            warnings.push(`OCR 识别失败（${metadata.ocrProvider ?? 'unknown'}）：${e.message}，未入库`);
+            return { text: '', metadata, warnings };
+        }
+        finally {
+            await provider?.dispose();
+        }
     }
     async tryPaddleOcrLayout(filePath) {
         const command = process.env.CUSTOMIZE_PADDLE_OCR_CMD || process.env.PADDLE_OCR_CMD;
@@ -948,32 +939,6 @@ try {
             return { text: ['OCR 版面分析区域:', ...lines].join('\n'), regionCount: lines.length };
         }
     }
-    parseOcrJson(raw) {
-        try {
-            const parsed = JSON.parse(raw);
-            return {
-                text: parsed.text ?? raw,
-                lines: (parsed.lines ?? []).map((line, index) => ({ index: line.index ?? index + 1, text: line.text ?? '', bbox: line.bbox })).filter(line => line.text.trim()),
-            };
-        }
-        catch {
-            return { text: raw, lines: raw.split(/\r?\n/u).map((text, index) => ({ index: index + 1, text })).filter(line => line.text.trim()) };
-        }
-    }
-    formatOcrRegions(lines) {
-        return lines.map(line => {
-            const bbox = this.formatBoundingBox(line.bbox);
-            const type = this.classifyOcrRegion(line.text);
-            return `区域 ${line.index} [${type}]${bbox ? ` ${bbox}` : ''}: ${line.text}`;
-        });
-    }
-    classifyOcrRegion(text) {
-        if (/\|/.test(text) || /\s{2,}/u.test(text) || /表\s*\d|合计|小计/u.test(text))
-            return 'table';
-        if (/图\s*\d|figure|image|示意图/iu.test(text))
-            return 'image-caption';
-        return 'text';
-    }
     formatBoundingBox(value) {
         if (!value || typeof value !== 'object')
             return '';
@@ -1043,165 +1008,168 @@ try {
             extractionMode: 'pdf_hybrid_pages',
             vectorizable: true,
             contentCoverage: 'pdf_page_text_plus_selective_ocr',
-            pdfExtractor: 'pdfjs-dist',
         };
         const warnings = [];
-        let canvasPath;
-        let pdfjsPath;
-        let tesseractPath;
-        let sharpPath;
+        // OCR Provider
+        let ocrProvider = null;
+        const getOcrProvider = async () => {
+            if (!ocrProvider)
+                ocrProvider = await createOcrProvider();
+            return ocrProvider;
+        };
+        const failedPages = [];
+        const ocrPages = [];
+        const ocrStrategies = [];
+        // 尝试 PyMuPDF 渲染（高质量）或降级到 pdfjs-dist
+        let pageImages;
+        let pageCount = 0;
+        let renderer = 'unknown';
+        const tmpDir = fs.mkdtempSync(path.join(this.getTempRoot(), 'kb-pdf-'));
         try {
-            canvasPath = resolvePackage('@napi-rs/canvas');
-            pdfjsPath = resolvePackage('pdfjs-dist/legacy/build/pdf.mjs');
-            tesseractPath = resolvePackage('tesseract.js');
-            sharpPath = resolvePackage('sharp');
+            // ── 方法1: PyMuPDF（300 DPI 原生渲染，质量最高） ──
+            pageImages = this.tryRenderWithPyMuPDF(file.absolutePath, tmpDir);
+            if (pageImages && pageImages.length > 0) {
+                renderer = 'PyMuPDF';
+                pageCount = pageImages.length;
+            }
+            else {
+                // ── 方法2: pdfjs-dist + canvas ──
+                const jsImages = await this.tryRenderWithPdfJs(file, tmpDir);
+                if (jsImages && jsImages.length > 0) {
+                    renderer = 'pdfjs-dist';
+                    pageCount = jsImages.length;
+                    pageImages = jsImages;
+                }
+            }
         }
         catch (e) {
             metadata.ocrRecommended = true;
-            metadata.ocrReason = `PDF 混合解析依赖解析失败: ${e.message}`;
-            return { text: '', metadata, warnings: [`内置 PDF 混合解析不可用：${metadata.ocrReason}`] };
-        }
-        const childEnv = { ...process.env };
-        const nmRoot = getNodeModulesRoot();
-        if (nmRoot)
-            childEnv.NODE_PATH = nmRoot;
-        const result = spawnSync(process.execPath, [
-            '--input-type=module',
-            '-e',
-            `import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { createCanvas } from ${JSON.stringify(canvasPath)};
-import * as pdfjs from ${JSON.stringify(pdfjsPath)};
-import { createWorker } from ${JSON.stringify(tesseractPath)};
-import sharp from ${JSON.stringify(sharpPath)};
-const filePath = process.argv[1];
-const minTextLength = Number(process.argv[2]);
-const bytes = new Uint8Array(fs.readFileSync(filePath));
-const doc = await pdfjs.getDocument({ data: bytes, verbosity: 0 }).promise;
-const pageCount = doc.numPages;
-const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-pdf-hybrid-'));
-const pageTexts = [];
-const ocrPages = [];
-const failedPages = [];
-let worker;
-function normalizeTextLength(value) { return String(value || '').replace(/\\s+/gu, '').length; }
-function isLowQualityText(value) {
-  const text = String(value || '');
-  const normalizedLength = normalizeTextLength(text);
-  if (normalizedLength < minTextLength) return true;
-  const lines = text.split(/\\r?\\n/u).map(line => line.trim()).filter(Boolean);
-  if (lines.length === 0) return true;
-  const shortLineRatio = lines.filter(line => line.length <= 12).length / lines.length;
-  const cjkCount = (text.match(/[\\p{Script=Han}]/gu) || []).length;
-  const replacementCount = (text.match(/[�□]/gu) || []).length;
-  return replacementCount > 5 || (shortLineRatio > 0.65 && cjkCount < 1200);
-}
-function itemsToMarkdown(items) {
-  const rows = [];
-  for (const item of items) {
-    if (!item || typeof item.str !== 'string' || !item.str.trim()) continue;
-    const transform = item.transform || [1, 0, 0, 1, 0, 0];
-    rows.push({ text: item.str.trim(), x: transform[4] || 0, y: transform[5] || 0 });
-  }
-  rows.sort((a, b) => Math.abs(b.y - a.y) > 3 ? b.y - a.y : a.x - b.x);
-  const lines = [];
-  let currentY = null;
-  let current = [];
-  for (const row of rows) {
-    if (currentY === null || Math.abs(row.y - currentY) <= 3) {
-      current.push(row);
-      currentY = currentY === null ? row.y : currentY;
-    } else {
-      lines.push(current.sort((a, b) => a.x - b.x).map(x => x.text).join(' '));
-      current = [row];
-      currentY = row.y;
-    }
-  }
-  if (current.length > 0) lines.push(current.sort((a, b) => a.x - b.x).map(x => x.text).join(' '));
-  return lines.join('\\n').trim();
-}
-async function recognizePage(page, pageNumber) {
-  if (!worker) worker = await createWorker('chi_sim+eng');
-  const viewport = page.getViewport({ scale: 2.5 });
-  const canvas = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
-  const context = canvas.getContext('2d');
-  await page.render({ canvasContext: context, viewport }).promise;
-  const rawPath = path.join(tmpDir, 'page-' + pageNumber + '-raw.png');
-  const processedPath = path.join(tmpDir, 'page-' + pageNumber + '-processed.png');
-  fs.writeFileSync(rawPath, canvas.toBuffer('image/png'));
-  await sharp(rawPath)
-    .resize({ width: Math.min(canvas.width, 4200), withoutEnlargement: true })
-    .grayscale()
-    .normalize()
-    .sharpen()
-    .threshold(170)
-    .png()
-    .toFile(processedPath);
-  const recognized = await worker.recognize(processedPath);
-  return (recognized.data.text || '').trim();
-}
-try {
-  for (let i = 1; i <= pageCount; i += 1) {
-    try {
-      const page = await doc.getPage(i);
-      const content = await page.getTextContent();
-      const text = itemsToMarkdown(content.items || []);
-      if (!isLowQualityText(text)) {
-        pageTexts.push('## PDF 第 ' + i + ' 页\\n\\n' + text);
-        continue;
-      }
-      const ocrText = await recognizePage(page, i);
-      if (ocrText) {
-        ocrPages.push(i);
-        pageTexts.push('## PDF 第 ' + i + ' 页（OCR）\\n\\n' + ocrText);
-      } else if (text) {
-        pageTexts.push('## PDF 第 ' + i + ' 页（低质量文本流）\\n\\n' + text);
-      } else {
-        failedPages.push({ page: i, reason: 'empty_text_and_ocr' });
-      }
-    } catch (error) {
-      failedPages.push({ page: i, reason: error instanceof Error ? error.message : String(error) });
-    }
-  }
-} finally {
-  if (worker) await worker.terminate();
-  await doc.destroy();
-  fs.rmSync(tmpDir, { recursive: true, force: true });
-}
-process.stdout.write(JSON.stringify({ pageCount, text: pageTexts.join('\\n\\n'), ocrPages, failedPages }));`,
-            file.absolutePath,
-            '80',
-        ], { encoding: 'utf8', timeout: 0, maxBuffer: 80 * 1024 * 1024, env: childEnv });
-        if (result.status !== 0 || result.error) {
+            metadata.ocrReason = `PDF 渲染失败: ${e.message}`;
+            return { text: '', metadata, warnings: [`PDF 渲染失败：${metadata.ocrReason}`] };
+        }
+        metadata.pdfPageCount = pageCount;
+        metadata.pdfRenderer = renderer;
+        if (!pageImages || pageImages.length === 0) {
             metadata.ocrRecommended = true;
-            metadata.ocrReason = result.error ? result.error.message : (result.stderr || 'PDF 混合解析子进程失败').trim();
-            return { text: '', metadata, warnings: [`内置 PDF 混合解析失败: ${metadata.ocrReason}`] };
+            metadata.ocrReason = '无法渲染PDF页面';
+            return { text: '', metadata, warnings: ['无法渲染PDF页面'] };
         }
+        // 逐页 OCR
+        const pageTexts = [];
+        for (let i = 0; i < pageImages.length; i++) {
+            const imgPath = pageImages[i];
+            try {
+                const provider = await getOcrProvider();
+                const ocrResult = await provider.recognize({
+                    data: new Uint8Array(0),
+                    width: 0, height: 0, channels: 0,
+                    filePath: imgPath,
+                });
+                const ocrText = ocrResult.text.trim();
+                if (ocrText) {
+                    ocrPages.push(i + 1);
+                    ocrStrategies.push({ page: i + 1, strategy: renderer, score: this.scoreOcrText(ocrText) });
+                    pageTexts.push(`## PDF 第 ${i + 1} 页（OCR）\n\n${ocrText}`);
+                }
+                else {
+                    failedPages.push({ page: i + 1, reason: 'empty_ocr' });
+                }
+            }
+            catch (error) {
+                failedPages.push({ page: i + 1, reason: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        // 清理临时文件
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            warnings.push('PDF OCR 临时文件清理失败');
+        }
+        metadata.ocrAugmented = ocrPages.length > 0;
+        metadata.ocrPages = ocrPages;
+        metadata.ocrStrategies = ocrStrategies;
+        metadata.failedPages = failedPages;
+        metadata.ocrProvider = ocrProvider?.id ?? 'unknown';
+        if (failedPages.length > 0) {
+            warnings.push(`PDF 部分页解析失败: ${failedPages.map((p) => `${p.page}:${p.reason}`).join('; ')}`);
+        }
+        const combined = pageTexts.join('\n\n').trim();
+        return {
+            text: combined ? [this.metadataOnlyText(file), combined].join('\n\n') : '',
+            metadata,
+            warnings,
+        };
+    }
+    /** PyMuPDF 渲染（300 DPI 原生提取，质量远高于 pdfjs-dist） */
+    tryRenderWithPyMuPDF(pdfPath, outputDir) {
         try {
-            const parsed = JSON.parse(result.stdout || '{}');
-            const ocrPages = parsed.ocrPages ?? [];
-            const failedPages = parsed.failedPages ?? [];
-            metadata.pdfPageCount = parsed.pageCount ?? 0;
-            metadata.ocrAugmented = ocrPages.length > 0;
-            metadata.ocrPages = ocrPages;
-            metadata.textPages = Math.max(metadata.pdfPageCount - ocrPages.length - failedPages.length, 0);
-            metadata.failedPages = failedPages;
-            if (ocrPages.length > 0) {
-                metadata.pdfRenderer = 'pdfjs-dist + @napi-rs/canvas';
-                metadata.ocrProvider = 'tesseract.js';
-                metadata.ocrLanguages = 'chi_sim+eng';
-                metadata.imagePreprocessor = 'sharp';
+            const workerScript = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'scripts', 'render_pdf_pages.py');
+            spawnSync('python3', [workerScript, pdfPath, outputDir, '300'], {
+                encoding: 'utf-8', timeout: 60_000, maxBuffer: 1024 * 1024,
+            });
+            // 检查输出文件（即使 Python 非零退出码也可能已渲染部分页面）
+            const images = [];
+            for (let i = 1; i <= 999; i++) {
+                const p = path.join(outputDir, `page-${i}.png`);
+                if (fs.existsSync(p) && fs.statSync(p).size > 100)
+                    images.push(p);
+                else
+                    break;
             }
-            if (failedPages.length > 0)
-                warnings.push(`PDF 部分页解析失败: ${failedPages.map(p => `${p.page}:${p.reason}`).join('; ')}`);
-            return { text: parsed.text?.trim() ? [this.metadataOnlyText(file), parsed.text.trim()].join('\n\n') : '', metadata, warnings };
+            return images.length > 0 ? images : null;
         }
-        catch (error) {
-            metadata.ocrRecommended = true;
-            metadata.ocrReason = `PDF 混合解析结果解析失败: ${error instanceof Error ? error.message : String(error)}`;
-            return { text: '', metadata, warnings: [`内置 PDF 混合解析输出异常：${metadata.ocrReason}`] };
+        catch {
+            return null;
+        }
+    }
+    /** pdfjs-dist + canvas 渲染（降级方案） */
+    async tryRenderWithPdfJs(file, outputDir) {
+        try {
+            const canvasMod = await resolveAndImport('@napi-rs/canvas');
+            const pdfjsLib = await resolveAndImport('pdfjs-dist/legacy/build/pdf.mjs');
+            const sharpMod = await resolveAndImport('sharp');
+            const createCanvas = canvasMod.createCanvas ?? canvasMod.default?.createCanvas;
+            const sharpFn = sharpMod.default ?? sharpMod;
+            if (!createCanvas || !sharpFn)
+                return null;
+            const raw = fs.readFileSync(file.absolutePath);
+            const doc = await pdfjsLib.getDocument({ data: new Uint8Array(raw), verbosity: 0 }).promise;
+            const pageCount = doc.numPages;
+            const images = [];
+            for (let i = 1; i <= pageCount; i++) {
+                const page = await doc.getPage(i);
+                const viewport = page.getViewport({ scale: 4 });
+                const canvas = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
+                const ctx = canvas.getContext('2d');
+                await page.render({ canvasContext: ctx, viewport }).promise;
+                const pngPath = path.join(outputDir, `page-${i}.png`);
+                await sharpFn(canvas.toBuffer('image/png'))
+                    .removeAlpha().normalize().linear(3.0, -150)
+                    .withMetadata({ density: 288 }).png().toFile(pngPath);
+                images.push(pngPath);
+            }
+            await doc.destroy();
+            return images.length > 0 ? images : null;
         }
+        catch {
+            return null;
+        }
+    }
+    scoreOcrText(value) {
+        const text = String(value ?? '').trim();
+        const normalizedLength = this.normalizedTextLength(text);
+        const cjkCount = (text.match(/[\p{Script=Han}]/gu) ?? []).length;
+        const latinCount = (text.match(/[A-Za-z]/g) ?? []).length;
+        const replacementCount = (text.match(/[�□]/gu) ?? []).length;
+        return cjkCount * 8 + normalizedLength - latinCount * 0.8 - replacementCount * 10;
+    }
+    /** 加载图片像素数据（依赖 sharp） */
+    async loadImagePixels(filePath) {
+        const sharpMod = await resolveAndImport('sharp');
+        const sharpFn = sharpMod.default ?? sharpMod;
+        const { data, info } = await sharpFn(filePath).raw().toBuffer({ resolveWithObject: true });
+        return { data: new Uint8Array(data), width: info.width, height: info.height };
     }
     async extractPdfText(buffer) {
         let pdfjsText = '';
@@ -1229,15 +1197,26 @@ process.stdout.write(JSON.stringify({ pageCount, text: pageTexts.join('\\n\\n'),
             if (process.env.KB_DEBUG === '1')
                 console.warn('[kb] pdfjs-dist extraction failed:', e.message);
         }
-        // 第二层：pdf-parse（兼容旧版 PDF），与 pdfjs 结果互补，避免单一解析器漏字
+        // 第二层：pdf-parse（兼容旧版 PDF），适配 v1.x 函数导出 和 v2.x 类导出
         try {
             const mod = await resolveAndImport('pdf-parse');
-            const pdfParse = typeof mod === 'function'
-                ? mod
-                : mod.default;
+            let pdfParse;
+            // v1.x: module.exports = function(buffer) { ... }
+            if (typeof mod === 'function') {
+                pdfParse = mod;
+            }
+            // v1.x ESM: { default: function(buffer) { ... } }
+            else if (mod && typeof mod.default === 'function') {
+                pdfParse = mod.default;
+            }
+            // v2.x: { PDFParse: class { parse(buffer) { ... } } }
+            else if (mod && typeof mod.PDFParse === 'function') {
+                const PDFParse = mod.PDFParse;
+                pdfParse = (buf) => new PDFParse().parse(buf);
+            }
             if (pdfParse) {
                 const result = await pdfParse(buffer);
-                const parseText = result.text.trim();
+                const parseText = (result?.text ?? '').trim();
                 if (pdfjsText && parseText && this.normalizedTextLength(parseText) > this.normalizedTextLength(pdfjsText) * 1.08)
                     return [pdfjsText, '## PDF 备用解析文本', parseText].join('\n\n');
                 if (parseText && !pdfjsText)

package/dist/extraction/ocr-providers.d.ts

@@ -0,0 +1,47 @@
+/**
+ * OCR 提供者 — tesseract.js 跨平台 WASM
+ *
+ * 使用 tesseract.js v7（WASM），bundled traineddata，
+ * 真正跨平台（Windows/macOS/Linux），无需系统依赖。
+ */
+export interface OcrRegion {
+    text: string;
+    confidence: number;
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface OcrResult {
+    text: string;
+    confidence: number;
+    regions: OcrRegion[];
+}
+export interface OcrProvider {
+    readonly id: string;
+    readonly available: boolean;
+    recognize(input: {
+        data: Uint8Array;
+        width: number;
+        height: number;
+        channels?: number;
+        filePath?: string;
+    }): Promise<OcrResult>;
+    dispose(): Promise<void>;
+}
+export declare class TesseractJsProvider implements OcrProvider {
+    readonly id = "tesseract.js";
+    private _available;
+    get available(): boolean;
+    recognize(input: {
+        data: Uint8Array;
+        width: number;
+        height: number;
+        channels?: number;
+        filePath?: string;
+    }): Promise<OcrResult>;
+    dispose(): Promise<void>;
+}
+export declare function createOcrProvider(): Promise<OcrProvider>;