@customize-agent/knowledge 4.0.12 → 4.0.14

package/dist/core/knowledge-base-manager.d.ts

@@ -1,5 +1,4 @@
 import { type EmbeddingProvider } from '../embedding/embedding-provider.js';
-import type { ExternalExtractorRegistry } from '../extraction/external-extractor.js';
 import type { LLMSearchProvider } from '../llm/llm-search-provider.js';
 import { type FederatedResult, type FederatedSearchItem, type RetrievalWeights, type SearchFilters } from '../search/federation-search.js';
 import type { DiffResult, IndexStateRecord, KBScope, KnowledgeBaseStats, ProjectConfig } from '../types.js';
@@ -23,7 +22,6 @@ export interface KnowledgeBaseManagerOptions {
     storageRoot?: string;
     embeddingProvider?: EmbeddingProvider;
     vectorStores?: Map<string, VectorStoreInterface>;
-    externalExtractors?: ExternalExtractorRegistry;
     onProgress?: (progress: KnowledgeIndexProgress) => void;
     /** 可选的 LLM Provider，用于查询扩展和语义重排序 */
     llmProvider?: LLMSearchProvider;

package/dist/core/knowledge-base-manager.js

@@ -43,7 +43,7 @@ export class KnowledgeBaseManager {
         this.projectId = options.projectId;
         this.embeddingProvider = options.embeddingProvider ?? createEmbeddingProviderFromEnvironment();
         this.vectorStores = options.vectorStores ?? new Map();
-        this.extractor = new ContentExtractor(options.externalExtractors);
+        this.extractor = new ContentExtractor();
         this.llmProvider = options.llmProvider;
         this.onProgress = options.onProgress;
         const storageRoot = options.storageRoot ?? path.join(os.homedir(), USER_DATA_DIR);

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

@@ -1,4 +1,3 @@
-import { ExternalExtractorRegistry } from './external-extractor.js';
 import type { ClassifiedFile } from '../types.js';
 /** 文件内容提取结果 */
 export interface ExtractionResult {
@@ -9,10 +8,7 @@ export interface ExtractionResult {
 }
 /** 文件内容提取器，支持文档、表格、图片、CAD 等多种文件格式的内容抽取 */
 export declare class ContentExtractor {
-    private readonly externalExtractors;
-    constructor(externalExtractors?: ExternalExtractorRegistry);
     extract(file: ClassifiedFile): Promise<ExtractionResult>;
-    private tryExternalExtractor;
     private extractTextClipping;
     private swapUtf16Bytes;
     private extractReadableFragments;
@@ -58,8 +54,7 @@ export declare class ContentExtractor {
     private formatBoundingBox;
     private validateRasterImage;
     private extractPdf;
-    private shouldAugmentPdfWithOcr;
-    private extractScannedPdfOcr;
+    private extractPdfHybridPages;
     private extractPdfText;
     private normalizedTextLength;
     private toPdfTextItem;

package/dist/extraction/content-extractor.js

@@ -3,16 +3,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { tmpdir } from 'node:os';
 import { pathToFileURL } from 'node:url';
-import { ExternalExtractorRegistry } from './external-extractor.js';
 import { resolveAndImport, resolvePackage, getNodeModulesRoot } from './module-resolver.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 等多种文件格式的内容抽取 */
 export class ContentExtractor {
-    externalExtractors;
-    constructor(externalExtractors = ExternalExtractorRegistry.fromEnvironment()) {
-        this.externalExtractors = externalExtractors;
-    }
     async extract(file) {
         const start = Date.now();
         const warnings = [];
@@ -22,86 +17,77 @@ export class ContentExtractor {
             category: file.category,
             format: file.format,
         };
-        const external = this.tryExternalExtractor(file);
-        if (external?.text.trim()) {
-            text = external.text;
-            Object.assign(metadata, external.metadata);
-            warnings.push(...external.warnings);
+        if (file.category === 'cad') {
+            const result = await this.extractCad(file);
+            text = result.text;
+            Object.assign(metadata, result.metadata);
+            warnings.push(...result.warnings);
+        }
+        else if (file.category === 'data') {
+            const result = this.extractData(file);
+            text = result.text;
+            Object.assign(metadata, result.metadata);
+            warnings.push(...result.warnings);
+        }
+        else if (file.category === 'diagram') {
+            const result = this.extractDiagram(file);
+            text = result.text;
+            Object.assign(metadata, result.metadata);
+            warnings.push(...result.warnings);
+        }
+        else if (file.category === 'document' && file.format === 'pdf') {
+            const result = await this.extractPdf(file);
+            text = result.text;
+            Object.assign(metadata, result.metadata);
+            warnings.push(...result.warnings);
+        }
+        else if (file.category === 'document' && ['office', 'presentation'].includes(file.format)) {
+            const result = await this.extractOfficeDocument(file);
+            text = result.text;
+            Object.assign(metadata, result.metadata);
+            warnings.push(...result.warnings);
+        }
+        else if (file.category === 'spreadsheet' && ['csv', 'tsv'].includes(file.format)) {
+            const result = this.extractDelimitedText(file);
+            text = result.text;
+            Object.assign(metadata, result.metadata);
+            warnings.push(...result.warnings);
+        }
+        else if (file.category === 'spreadsheet') {
+            const result = await this.extractSpreadsheet(file);
+            text = result.text;
+            Object.assign(metadata, result.metadata);
+            warnings.push(...result.warnings);
+        }
+        else if (file.category === 'image' && file.format !== 'vector') {
+            const result = await this.extractRasterImage(file);
+            text = result.text;
+            Object.assign(metadata, result.metadata);
+            warnings.push(...result.warnings);
+        }
+        else if (file.category === 'image' && file.format === 'vector') {
+            const result = this.extractSvg(file);
+            text = result.text;
+            Object.assign(metadata, result.metadata);
+            warnings.push(...result.warnings);
+        }
+        else if (file.format === 'text_clipping') {
+            const result = this.extractTextClipping(file);
+            text = result.text;
+            Object.assign(metadata, result.metadata);
+            warnings.push(...result.warnings);
+        }
+        else if (this.isTextReadable(file)) {
+            text = fs.readFileSync(file.absolutePath, 'utf8');
+            metadata.extractionMode = 'plain_text';
+            metadata.vectorizable = true;
         }
         else {
-            warnings.push(...(external?.warnings ?? []));
-            if (file.category === 'cad') {
-                const result = await this.extractCad(file);
-                text = result.text;
-                Object.assign(metadata, result.metadata);
-                warnings.push(...result.warnings);
-            }
-            else if (file.category === 'data') {
-                const result = this.extractData(file);
-                text = result.text;
-                Object.assign(metadata, result.metadata);
-                warnings.push(...result.warnings);
-            }
-            else if (file.category === 'diagram') {
-                const result = this.extractDiagram(file);
-                text = result.text;
-                Object.assign(metadata, result.metadata);
-                warnings.push(...result.warnings);
-            }
-            else if (file.category === 'document' && file.format === 'pdf') {
-                const result = await this.extractPdf(file);
-                text = result.text;
-                Object.assign(metadata, result.metadata);
-                warnings.push(...result.warnings);
-            }
-            else if (file.category === 'document' && ['office', 'presentation'].includes(file.format)) {
-                const result = await this.extractOfficeDocument(file);
-                text = result.text;
-                Object.assign(metadata, result.metadata);
-                warnings.push(...result.warnings);
-            }
-            else if (file.category === 'spreadsheet' && ['csv', 'tsv'].includes(file.format)) {
-                const result = this.extractDelimitedText(file);
-                text = result.text;
-                Object.assign(metadata, result.metadata);
-                warnings.push(...result.warnings);
-            }
-            else if (file.category === 'spreadsheet') {
-                const result = await this.extractSpreadsheet(file);
-                text = result.text;
-                Object.assign(metadata, result.metadata);
-                warnings.push(...result.warnings);
-            }
-            else if (file.category === 'image' && file.format !== 'vector') {
-                const result = await this.extractRasterImage(file);
-                text = result.text;
-                Object.assign(metadata, result.metadata);
-                warnings.push(...result.warnings);
-            }
-            else if (file.category === 'image' && file.format === 'vector') {
-                const result = this.extractSvg(file);
-                text = result.text;
-                Object.assign(metadata, result.metadata);
-                warnings.push(...result.warnings);
-            }
-            else if (file.format === 'text_clipping') {
-                const result = this.extractTextClipping(file);
-                text = result.text;
-                Object.assign(metadata, result.metadata);
-                warnings.push(...result.warnings);
-            }
-            else if (this.isTextReadable(file)) {
-                text = fs.readFileSync(file.absolutePath, 'utf8');
-                metadata.extractionMode = 'plain_text';
-                metadata.vectorizable = true;
-            }
-            else {
-                text = this.metadataOnlyText(file);
-                metadata.extractionMode = 'metadata_only';
-                metadata.vectorizable = true;
-                metadata.contentCoverage = 'metadata';
-                warnings.push(`暂不支持 ${file.category}/${file.format} 内容提取，未解析出正文，未入库`);
-            }
+            text = this.metadataOnlyText(file);
+            metadata.extractionMode = 'metadata_only';
+            metadata.vectorizable = true;
+            metadata.contentCoverage = 'metadata';
+            warnings.push(`暂不支持 ${file.category}/${file.format} 内容提取，未解析出正文，未入库`);
         }
         return {
             text: this.cleanExtractedText(text, file).trim(),
@@ -110,37 +96,6 @@ export class ContentExtractor {
             extractionTimeMs: Date.now() - start,
         };
     }
-    tryExternalExtractor(file) {
-        const extractors = this.externalExtractors.findAll(file);
-        if (extractors.length === 0)
-            return undefined;
-        const warnings = [];
-        for (const extractor of extractors) {
-            try {
-                const result = extractor.extract(file);
-                const text = result.text.trim();
-                if (!text) {
-                    warnings.push(`外部解析器 ${extractor.name} 未提取到正文`);
-                    continue;
-                }
-                return {
-                    text,
-                    metadata: {
-                        extractionMode: 'external_advanced_plugin',
-                        vectorizable: true,
-                        contentCoverage: 'external_full_text',
-                        externalExtractor: extractor.id,
-                        ...(result.metadata ?? {}),
-                    },
-                    warnings: [...warnings, ...(result.warnings ?? [])],
-                };
-            }
-            catch (error) {
-                warnings.push(`外部解析器 ${extractor.name} 失败: ${error instanceof Error ? error.message : String(error)}`);
-            }
-        }
-        return warnings.length > 0 ? { text: '', metadata: {}, warnings } : undefined;
-    }
     extractTextClipping(file) {
         const buffer = fs.readFileSync(file.absolutePath);
         const candidates = [
@@ -1054,83 +1009,58 @@ try {
         return undefined;
     }
     async extractPdf(file) {
+        const hybrid = await this.extractPdfHybridPages(file);
+        if (hybrid.text.trim())
+            return hybrid;
         const metadata = { extractionMode: 'pdf_text', vectorizable: true };
-        const warnings = [];
-        // 第一层：pdfjs-dist 文本提取（处理常规 PDF、压缩内容流、CJK 字体等）
+        const warnings = [...hybrid.warnings];
         try {
             const raw = fs.readFileSync(file.absolutePath);
             const text = await this.extractPdfText(raw);
             if (text.trim()) {
                 metadata.contentCoverage = 'pdf_text_streams_layout_markdown';
                 metadata.pdfExtractor = 'pdfjs-dist';
-                const markdownText = this.toMarkdownDocument(text);
-                if (!this.shouldAugmentPdfWithOcr(markdownText))
-                    return { text: [this.metadataOnlyText(file), markdownText].join('\n\n'), metadata, warnings };
-                const ocr = await this.extractScannedPdfOcr(file);
-                if (ocr.text.trim()) {
-                    metadata.contentCoverage = 'pdf_text_streams_plus_ocr';
-                    metadata.ocrAugmented = true;
-                    return { text: [this.metadataOnlyText(file), markdownText, '## PDF OCR 备用识别文本', ocr.text].join('\n\n'), metadata: { ...metadata, ocr: ocr.metadata }, warnings: [...warnings, ...ocr.warnings] };
-                }
-                return { text: [this.metadataOnlyText(file), markdownText].join('\n\n'), metadata: { ...metadata, ocrRecommended: true, ocrReason: ocr.metadata.ocrReason ?? 'pdf_text_low_quality' }, warnings: [...warnings, ...ocr.warnings] };
+                return { text: [this.metadataOnlyText(file), this.toMarkdownDocument(text)].join('\n\n'), metadata, warnings };
             }
         }
         catch (error) {
             warnings.push(`PDF 文本提取失败: ${error instanceof Error ? error.message : String(error)}`);
             metadata.parseError = error instanceof Error ? error.message : String(error);
         }
-        // 第二层：OCR（扫描件/图片型 PDF）—— 必须保留并确保可用
-        const ocr = await this.extractScannedPdfOcr(file);
-        if (ocr.text.trim())
-            return ocr;
-        // 第三层：仅索引元数据（兜底）
         metadata.extractionMode = 'pdf_metadata_only';
         metadata.contentCoverage = 'metadata_filename';
         metadata.ocrRecommended = true;
-        metadata.ocrReason = ocr.metadata.ocrReason ?? 'pdf_text_stream_empty_or_unavailable';
+        metadata.ocrReason = hybrid.metadata.ocrReason ?? 'pdf_text_stream_empty_or_unavailable';
         metadata.pdfPageOcrSupported = true;
         return {
             text: this.metadataOnlyText(file),
             metadata,
-            warnings: [...warnings, 'PDF 正文暂未提取到文本，已索引文件名、路径和类型元数据', ...ocr.warnings],
+            warnings: [...warnings, 'PDF 正文暂未提取到文本，已索引文件名、路径和类型元数据'],
         };
     }
-    shouldAugmentPdfWithOcr(text) {
-        const normalizedLength = this.normalizedTextLength(text);
-        if (normalizedLength < 1200)
-            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;
-        return shortLineRatio > 0.65 && cjkCount < 1200;
-    }
-    async extractScannedPdfOcr(file) {
+    async extractPdfHybridPages(file) {
         const metadata = {
-            extractionMode: 'pdf_page_ocr_embedded',
+            extractionMode: 'pdf_hybrid_pages',
             vectorizable: true,
-            pdfPageOcrSupported: true,
-            ocrProvider: 'tesseract.js',
-            ocrLanguages: 'chi_sim+eng',
-            pdfRenderer: 'pdfjs-dist + @napi-rs/canvas',
-            pdfOcrPageLimit: 'all',
+            contentCoverage: 'pdf_page_text_plus_selective_ocr',
+            pdfExtractor: 'pdfjs-dist',
         };
-        // 解析模块路径 —— 确保在打包 Server 等上下文中子进程也能正确加载
+        const warnings = [];
         let canvasPath;
         let pdfjsPath;
         let tesseractPath;
+        let sharpPath;
         try {
             canvasPath = resolvePackage('@napi-rs/canvas');
             pdfjsPath = resolvePackage('pdfjs-dist/legacy/build/pdf.mjs');
             tesseractPath = resolvePackage('tesseract.js');
+            sharpPath = resolvePackage('sharp');
         }
         catch (e) {
             metadata.ocrRecommended = true;
-            metadata.ocrReason = `OCR 依赖解析失败: ${e.message}`;
-            return { text: '', metadata, warnings: [`内置扫描 PDF OCR 不可用：${metadata.ocrReason}`] };
+            metadata.ocrReason = `PDF 混合解析依赖解析失败: ${e.message}`;
+            return { text: '', metadata, warnings: [`内置 PDF 混合解析不可用：${metadata.ocrReason}`] };
         }
-        // NODE_PATH 确保子进程能解析 tesseract.js 的依赖
         const childEnv = { ...process.env };
         const nmRoot = getNodeModulesRoot();
         if (nmRoot)
@@ -1144,52 +1074,133 @@ 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 pageLimit = doc.numPages;
-const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-pdf-ocr-'));
-const worker = await createWorker('chi_sim+eng');
-const pages = [];
+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 <= pageLimit; i += 1) {
-    const page = await doc.getPage(i);
-    const viewport = page.getViewport({ scale: 2 });
-    const canvas = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
-    const context = canvas.getContext('2d');
-    await page.render({ canvasContext: context, viewport }).promise;
-    const imagePath = path.join(tmpDir, 'page-' + i + '.png');
-    fs.writeFileSync(imagePath, canvas.toBuffer('image/png'));
-    const recognized = await worker.recognize(imagePath);
-    const text = (recognized.data.text || '').trim();
-    const lines = (recognized.data.lines || []).map((line, index) => ({ index: index + 1, text: line.text || '', bbox: line.bbox || null })).filter(line => line.text.trim());
-    if (text) pages.push('PDF OCR 第 ' + i + ' 页:\\n' + lines.map(line => '区域 ' + line.index + ' ' + JSON.stringify(line.bbox || {}) + ': ' + line.text).join('\\n') + '\\n\\n完整文本:\\n' + text);
+  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 {
-  await worker.terminate();
+  if (worker) await worker.terminate();
+  await doc.destroy();
   fs.rmSync(tmpDir, { recursive: true, force: true });
 }
-process.stdout.write(JSON.stringify({ pageCount: doc.numPages, pageLimit, text: pages.join('\\n\\n') }));`,
+process.stdout.write(JSON.stringify({ pageCount, text: pageTexts.join('\\n\\n'), ocrPages, failedPages }));`,
             file.absolutePath,
-        ], { encoding: 'utf8', timeout: 0, maxBuffer: 50 * 1024 * 1024, env: childEnv });
+            '80',
+        ], { encoding: 'utf8', timeout: 0, maxBuffer: 80 * 1024 * 1024, env: childEnv });
         if (result.status !== 0 || result.error) {
             metadata.ocrRecommended = true;
-            metadata.ocrReason = result.error?.message ?? result.stderr.trim() ?? `pdf_page_ocr_exit_${result.status ?? 'unknown'}`;
-            return { text: '', metadata, warnings: [`内置扫描 PDF OCR 失败：${metadata.ocrReason}`] };
+            metadata.ocrReason = result.error ? result.error.message : (result.stderr || 'PDF 混合解析子进程失败').trim();
+            return { text: '', metadata, warnings: [`内置 PDF 混合解析失败: ${metadata.ocrReason}`] };
         }
         try {
-            const parsed = JSON.parse(result.stdout);
-            const text = parsed.text?.trim() ?? '';
-            metadata.ocrPageCount = parsed.pageCount ?? 0;
-            metadata.pdfOcrPageLimit = parsed.pageLimit ?? 'all';
-            metadata.ocrTextLength = text.length;
-            metadata.contentCoverage = text ? 'pdf_page_ocr_text' : 'metadata_filename';
-            return { text: text ? [this.metadataOnlyText(file), text].join('\n') : '', metadata, warnings: text ? [] : ['内置扫描 PDF OCR 未识别到文字'] };
+            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';
+            }
+            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 };
         }
-        catch {
+        catch (error) {
             metadata.ocrRecommended = true;
-            metadata.ocrReason = 'pdf_page_ocr_output_parse_failed';
-            return { text: '', metadata, warnings: ['内置扫描 PDF OCR 输出解析失败'] };
+            metadata.ocrReason = `PDF 混合解析结果解析失败: ${error instanceof Error ? error.message : String(error)}`;
+            return { text: '', metadata, warnings: [`内置 PDF 混合解析输出异常：${metadata.ocrReason}`] };
         }
     }
     async extractPdfText(buffer) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@customize-agent/knowledge",
-  "version": "4.0.12",
+  "version": "4.0.14",
   "description": "Local knowledge base infrastructure for customize-agent",
   "type": "module",
   "main": "./dist/index.js",
@@ -43,12 +43,13 @@
     "dwgdxf": "^2.0.1",
     "dxf-parser": "^1.1.2",
     "fast-glob": "^3.3.3",
+    "hnswlib-node": "^3.0.0",
     "jszip": "^3.10.1",
     "mammoth": "^1.12.0",
+    "node-gyp": "^12.1.0",
     "pdf-parse": "^2.4.5",
     "pdfjs-dist": "^5.4.394",
-    "hnswlib-node": "^3.0.0",
-    "node-gyp": "^12.1.0",
+    "sharp": "0.34.5",
     "tesseract.js": "^7.0.0",
     "word-extractor": "^1.0.4",
     "xlsx": "^0.18.5"