@customize-agent/knowledge 4.0.16 → 4.0.18

package/dist/chunking/text-chunker.d.ts

@@ -44,6 +44,7 @@ export declare class TextChunker {
     private splitByWindow;
     private splitBySentenceBoundary;
     private isMarkdownTable;
+    private extractMarkdownTableBlocks;
     private extractMarkdownTableRowRange;
     private splitMarkdownTable;
     private enforceCandidateLimit;

package/dist/chunking/text-chunker.js

@@ -79,6 +79,7 @@ export class TextChunker {
                     parentId,
                     parentIndex,
                     childIndex,
+                    parentText: section.text, // <=== 记录原始完整的 Section 文本
                 });
             });
         });
@@ -86,21 +87,29 @@ export class TextChunker {
     }
     createTableCandidates(text, config) {
         if (this.isMarkdownTable(text)) {
-            return this.splitMarkdownTable(text, config.maxChunkSize).map((part, index) => {
-                const startChar = Math.max(0, text.indexOf(part.slice(0, 40)));
-                return {
-                    text: part,
-                    startChar,
-                    endChar: startChar + part.length,
-                    sectionTitle: this.extractSectionTitle(part) ?? '表格数据',
-                    titlePath: this.extractSectionTitle(part) ?? '表格数据',
-                    kind: 'table',
-                    parentId: `table-${index}`,
-                    parentIndex: index,
-                    childIndex: 0,
-                    rowRange: this.extractMarkdownTableRowRange(part),
-                };
-            });
+            const tableBlocks = this.extractMarkdownTableBlocks(text);
+            if (tableBlocks.length > 0) {
+                return tableBlocks.flatMap((block, parentIndex) => {
+                    const sectionTitle = this.extractSectionTitle(block.text) ?? '表格数据';
+                    return this.splitMarkdownTable(block.text, config.maxChunkSize).map((part, childIndex) => {
+                        const localStart = Math.max(0, block.text.indexOf(part.slice(0, 40)));
+                        const startChar = block.startChar + localStart;
+                        return {
+                            text: part,
+                            startChar,
+                            endChar: startChar + part.length,
+                            sectionTitle,
+                            titlePath: sectionTitle,
+                            kind: 'table',
+                            parentId: `table-${parentIndex}`,
+                            parentIndex,
+                            childIndex,
+                            rowRange: this.extractMarkdownTableRowRange(part),
+                            parentText: block.text,
+                        };
+                    });
+                });
+            }
         }
         return this.createTextCandidates(text, 'spreadsheet', config);
     }
@@ -114,9 +123,10 @@ export class TextChunker {
             sectionTitle: this.extractSectionTitle(part),
             titlePath: this.extractSectionTitle(part),
             kind: 'data',
-            parentId: `data-${index}`,
-            parentIndex: index,
-            childIndex: 0,
+            parentId: `data-0`,
+            parentIndex: 0,
+            childIndex: index,
+            parentText: text,
         }));
     }
     createCodeCandidates(text, file, config) {
@@ -135,9 +145,10 @@ export class TextChunker {
                 sectionTitle: this.extractSectionTitle(part),
                 titlePath: this.extractSectionTitle(part),
                 kind: 'code',
-                parentId: `code-${language}-${index}`,
-                parentIndex: index,
-                childIndex: 0,
+                parentId: `code-${language}-0`,
+                parentIndex: 0,
+                childIndex: index,
+                parentText: text,
             };
         });
     }
@@ -308,6 +319,40 @@ export class TextChunker {
         const lines = text.trim().split(/\r?\n/u);
         return lines.length >= 3 && lines.some(line => /^\s*\|?\s*:?-{3,}:?\s*\|/u.test(line));
     }
+    extractMarkdownTableBlocks(text) {
+        const lines = text.split(/\r?\n/u);
+        const lineStarts = [];
+        let cursor = 0;
+        for (const line of lines) {
+            lineStarts.push(cursor);
+            cursor += line.length + 1;
+        }
+        const blocks = [];
+        let index = 0;
+        while (index < lines.length) {
+            const separatorIndex = lines.findIndex((line, lineIndex) => lineIndex >= index && /^\s*\|?\s*:?-{3,}:?\s*\|/u.test(line));
+            if (separatorIndex <= index)
+                break;
+            const headerIndex = separatorIndex - 1;
+            let startLine = headerIndex;
+            const titleIndex = headerIndex - 1;
+            if (titleIndex >= 0 && lines[titleIndex]?.trim() === '' && titleIndex - 1 >= 0) {
+                const title = lines[titleIndex - 1]?.trim() ?? '';
+                if (title && title.length <= 120 && !/^\s*\|/u.test(title))
+                    startLine = titleIndex - 1;
+            }
+            let endLine = separatorIndex + 1;
+            while (endLine < lines.length && /^\s*\|/u.test(lines[endLine] ?? ''))
+                endLine += 1;
+            const startChar = lineStarts[startLine] ?? 0;
+            const endChar = endLine < lineStarts.length ? (lineStarts[endLine] ?? text.length) : text.length;
+            const blockText = text.slice(startChar, endChar).trim();
+            if (blockText)
+                blocks.push({ text: blockText, startChar });
+            index = endLine;
+        }
+        return blocks;
+    }
     extractMarkdownTableRowRange(text) {
         const lines = text.trim().split(/\r?\n/u).filter(line => /^\s*\|/u.test(line));
         const rowCount = Math.max(0, lines.length - 2);
@@ -395,6 +440,7 @@ export class TextChunker {
                 startChar: candidate.startChar,
                 endChar: candidate.endChar,
                 splitStrategy: 'recursive_parent_child_v2',
+                parentText: candidate.parentText, // <=== 原始父块内容
             },
         };
     }

package/dist/core/index-state-store.js

@@ -159,9 +159,14 @@ export class IndexStateStore {
             }
             const parentContents = [];
             for (const [parentId, group] of parentGroups.entries()) {
-                const parentContent = group.map(chunk => chunk.text).join('\n\n---\n\n');
+                const firstChunkMeta = group[0]?.metadata;
+                const parentContent = this.metadataString(firstChunkMeta?.parentText) || group.map(chunk => chunk.text).join('\n\n---\n\n');
                 parentContents.push(parentContent);
-                insertParent.run(parentId, relativePath, parentId, parentContent, file.category, file.format, file.collectionName, group.find(chunk => chunk.sectionTitle)?.sectionTitle ?? null, group.length, JSON.stringify({ parentId, splitStrategy: this.metadataString(group[0]?.metadata.splitStrategy), chunkKind: this.metadataString(group[0]?.metadata.chunkKind), titlePath: this.metadataString(group[0]?.metadata.titlePath) }), now);
+                // 我们不想把一整个大文本冗余在每个切片的 metadata 里，所以存完 parent 之后清理一下
+                for (const chunk of group) {
+                    delete chunk.metadata.parentText;
+                }
+                insertParent.run(parentId, relativePath, parentId, parentContent, file.category, file.format, file.collectionName, group.find(chunk => chunk.sectionTitle)?.sectionTitle ?? null, group.length, JSON.stringify({ parentId, splitStrategy: this.metadataString(firstChunkMeta?.splitStrategy), chunkKind: this.metadataString(firstChunkMeta?.chunkKind), titlePath: this.metadataString(firstChunkMeta?.titlePath) }), now);
             }
             insertDocument.run(`${relativePath}#document`, relativePath, parentContents.join('\n\n=== SECTION ===\n\n'), file.category, file.format, file.collectionName, parentGroups.size, groupedChunks.length, JSON.stringify({ parentType: 'document', splitStrategy: 'document_section_child_v1' }), now);
             for (const chunk of groupedChunks) {

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

@@ -158,11 +158,11 @@ export declare class KnowledgeBaseManager {
     private llmExpandQueries;
     private retrievalWeights;
     private heuristicRerank;
-    private llmRerank;
     private hydrateVectorResultsFromSqlite;
     private toFederatedItem;
     private mergeHybridRankedLists;
     private mergeContexts;
+    private mergeExpandedContexts;
     private contextKey;
     private parseChunkIndex;
     private parseMetadataString;

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

@@ -7,6 +7,7 @@ import { ALL_CATEGORIES, DEFAULT_CATEGORY_DIRS, GLOBAL_KNOWLEDGE_DIR, USER_DATA_
 import { DedupEngine } from '../dedup/dedup-engine.js';
 import { RelationshipDetector } from '../dedup/relationship-detector.js';
 import { createEmbeddingProviderFromEnvironment } from '../embedding/embedding-provider.js';
+import { LocalReranker } from '../embedding/local-reranker.js';
 import { ContentExtractor } from '../extraction/content-extractor.js';
 import { FederationSearch } from '../search/federation-search.js';
 import { CollectionManager } from '../vector/collection-manager.js';
@@ -350,20 +351,47 @@ export class KnowledgeBaseManager {
         }
         const keywordItems = rankedLists.filter(list => list.source === 'keyword').flatMap(list => list.items);
         const vectorItems = rankedLists.filter(list => list.source === 'vector').flatMap(list => list.items);
-        const merged = this.mergeContexts(this.mergeHybridRankedLists(rankedLists, limit * 4, weights).map(item => this.expandContext(item)), limit * 2);
-        const useLLMRerank = !!this.llmProvider;
-        const preReranked = useLLMRerank ? merged : this.heuristicRerank(query, merged);
-        const reranked = useLLMRerank ? (await this.llmRerank(query, preReranked)) : preReranked;
+        // 1. 先进行初筛合并，合并相同的子块并计算混合初始分（不获取大片段，保留子块自身用于精确打分）
+        const mergedChildChunks = this.mergeContexts(this.mergeHybridRankedLists(rankedLists, limit * 4, weights), limit * 4);
+        // 2. 对这些子块进行交叉编码器重排（Cross-Encoder Rerank）
+        let reranked = mergedChildChunks;
+        let rerankerName = 'local-heuristic-fallback';
+        if (mergedChildChunks.length > 0) {
+            const candidates = mergedChildChunks.slice(0, Math.min(30, limit * 4));
+            // 这里使用的是子块自身内容，通常在 500 tokens 左右，不仅相关性判断最准，而且不会超出 Reranker 的 max_length
+            const textsToRerank = candidates.map(item => `${item.titlePath ?? item.sectionTitle ?? ''}\n${item.content}`);
+            try {
+                const scores = await LocalReranker.rerank(query, textsToRerank);
+                const usableScores = scores.length === candidates.length && scores.some(score => Number.isFinite(score) && score > 0);
+                if (usableScores) {
+                    reranked = candidates.map((item, i) => ({
+                        ...item,
+                        score: scores[i] ?? item.score,
+                        scoreDetails: { ...item.scoreDetails, crossEncoderScore: scores[i] ?? 0 }
+                    })).sort((a, b) => b.score - a.score);
+                    rerankerName = 'bge-reranker-base';
+                }
+                else {
+                    reranked = this.heuristicRerank(query, mergedChildChunks);
+                    rerankerName = 'local-heuristic-fallback-empty-rerank';
+                }
+            }
+            catch {
+                reranked = this.heuristicRerank(query, mergedChildChunks);
+            }
+        }
+        // 3. 拿到精确打分后的 Top 结果，此时再进行 expandContext 向上追溯到完整的父块大片段
+        const finalExpandedResults = this.mergeExpandedContexts(reranked.map(item => this.expandContext(item)), limit);
         return {
-            results: reranked.slice(0, limit),
+            results: finalExpandedResults,
             scopesSearched: this.scope === 'global' ? ['global'] : ['project'],
             queryTimeMs: Date.now() - start,
             debug: {
                 originalQuery: query,
                 rewrittenQueries,
                 weights,
-                recallCounts: { keyword: keywordItems.length, vector: vectorItems.length, merged: merged.length },
-                reranker: useLLMRerank ? 'llm-semantic-reranker-v1' : 'local-statistical-reranker-v1',
+                recallCounts: { keyword: keywordItems.length, vector: vectorItems.length, merged: mergedChildChunks.length },
+                reranker: rerankerName,
             },
         };
     }
@@ -697,59 +725,6 @@ export class KnowledgeBaseManager {
             };
         }).sort((a, b) => b.score - a.score);
     }
-    async llmRerank(query, items) {
-        if (!this.llmProvider || items.length === 0)
-            return this.heuristicRerank(query, items);
-        const candidates = items.slice(0, 20);
-        const resultsText = candidates.map((item, index) => {
-            const contentPreview = item.content.slice(0, 300).replace(/[\n\r]+/g, ' ');
-            return `[DOC_${index}] 路径: ${item.filePath} | 标题路径: ${item.titlePath ?? item.sectionTitle ?? ''} | 类型: ${item.chunkKind ?? 'text'}\n  内容: ${contentPreview}`;
-        }).join('\n\n');
-        const prompt = `你是一个文档相关性评估器。根据用户查询，为以下文档片段打分（1-10）。
-1=完全不相关，10=高度相关。
-输出格式：每行 "DOC_ID:分数"，如 "DOC_0:8"
-
-查询：${query}
-
-${resultsText}
-
-相关性评分：`;
-        try {
-            const response = await this.llmProvider.chat([
-                { role: 'system', content: '你是一个精确的文档相关性评估器。只输出 DOC_ID:分数的列表。' },
-                { role: 'user', content: prompt },
-            ], { temperature: 0.1, maxTokens: 600 });
-            const scoreMap = new Map();
-            for (const line of response.content.split('\n')) {
-                const match = line.match(/DOC[_\s]*(\d+)[^\d]*(\d+)/i);
-                if (match)
-                    scoreMap.set(Number(match[1]), Math.min(10, Math.max(1, Number(match[2]))));
-            }
-            if (scoreMap.size === 0)
-                return this.heuristicRerank(query, items);
-            return items.map((item, index) => {
-                const llmScore = scoreMap.get(index);
-                if (llmScore == null || llmScore === undefined)
-                    return item;
-                // LLM 分数 (1-10) 映射为权重因子：10→2.0x, 5→1.0x, 1→0.2x
-                const llmFactor = 0.2 + (llmScore / 10) * 1.8;
-                const newScore = item.score * llmFactor;
-                return {
-                    ...item,
-                    score: newScore,
-                    scoreDetails: {
-                        ...item.scoreDetails,
-                        rerankBoost: newScore - (item.scoreDetails?.hybridScore ?? item.score),
-                        llmRelevanceScore: llmScore,
-                        hybridScore: newScore,
-                    },
-                };
-            }).sort((a, b) => b.score - a.score);
-        }
-        catch {
-            return this.heuristicRerank(query, items);
-        }
-    }
     hydrateVectorResultsFromSqlite(items) {
         return items.map(item => {
             if (!item.rowid)
@@ -846,6 +821,20 @@ ${resultsText}
         }
         return [...byKey.values()].sort((a, b) => b.score - a.score).slice(0, limit);
     }
+    mergeExpandedContexts(items, limit) {
+        const byKey = new Map();
+        for (const item of items) {
+            const key = `${item.scope}:${item.filePath}:${item.parentId ?? item.chunkIndex ?? item.id}`;
+            const existing = byKey.get(key);
+            if (!existing || item.score > existing.score) {
+                byKey.set(key, item);
+                continue;
+            }
+            existing.source = existing.source === item.source ? existing.source : 'hybrid';
+            existing.scoreDetails = { ...existing.scoreDetails, ...item.scoreDetails, hybridScore: existing.score };
+        }
+        return [...byKey.values()].sort((a, b) => b.score - a.score).slice(0, limit);
+    }
     contextKey(item) {
         if (item.rowid)
             return `${item.scope}:rowid:${item.rowid}`;

package/dist/embedding/local-reranker.d.ts

@@ -0,0 +1,13 @@
+export declare class LocalReranker {
+    private static instance;
+    private static loadingPromise;
+    private static disabledUntil;
+    private static modelName;
+    static getInstance(): Promise<any>;
+    /**
+     * 对多条文本和查询进行相关性重排
+     */
+    static rerank(query: string, texts: string[]): Promise<number[]>;
+    private static takeHeadTail;
+    private static extractScore;
+}

package/dist/embedding/local-reranker.js

@@ -0,0 +1,73 @@
+import { pipeline } from '@huggingface/transformers';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export class LocalReranker {
+    static instance = null;
+    static loadingPromise = null;
+    static disabledUntil = 0;
+    static modelName = process.env.KB_RERANKER_MODEL || 'Xenova/bge-reranker-base';
+    static async getInstance() {
+        if (this.instance)
+            return this.instance;
+        if (Date.now() < this.disabledUntil)
+            throw new Error('Local reranker is temporarily disabled after load failure');
+        if (process.env.KB_ENABLE_LOCAL_RERANKER === 'false')
+            throw new Error('Local reranker is disabled');
+        // 使用 loadingPromise 防止高并发下的重复加载
+        if (this.loadingPromise)
+            return this.loadingPromise;
+        this.loadingPromise = (async () => {
+            const cacheDir = process.env.TRANSFORMERS_CACHE || path.join(os.homedir(), '.customize-agent', 'models');
+            if (!fs.existsSync(cacheDir)) {
+                fs.mkdirSync(cacheDir, { recursive: true });
+            }
+            process.env.TRANSFORMERS_CACHE = cacheDir;
+            const pipe = await pipeline('text-classification', this.modelName, {
+                dtype: 'q8',
+            });
+            this.instance = pipe;
+            return pipe;
+        })().catch(error => {
+            this.loadingPromise = null;
+            this.disabledUntil = Date.now() + 60_000;
+            throw error;
+        });
+        return this.loadingPromise;
+    }
+    /**
+     * 对多条文本和查询进行相关性重排
+     */
+    static async rerank(query, texts) {
+        if (!texts.length)
+            return [];
+        const ranker = await this.getInstance();
+        const scores = [];
+        const safeQuery = this.takeHeadTail(query, 240);
+        for (const text of texts) {
+            try {
+                const safeText = this.takeHeadTail(text, 1400);
+                const out = await ranker({ text: safeQuery, text_pair: safeText });
+                scores.push(this.extractScore(out));
+            }
+            catch {
+                scores.push(0);
+            }
+        }
+        return scores;
+    }
+    static takeHeadTail(text, maxLength) {
+        if (text.length <= maxLength)
+            return text;
+        const headLength = Math.ceil(maxLength * 0.65);
+        const tailLength = maxLength - headLength;
+        return `${text.slice(0, headLength)}\n...\n${text.slice(-tailLength)}`;
+    }
+    static extractScore(output) {
+        const first = Array.isArray(output) ? output[0] : output;
+        if (Array.isArray(first))
+            return this.extractScore(first);
+        const score = Number(first?.score ?? 0);
+        return Number.isFinite(score) ? score : 0;
+    }
+}

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

@@ -60,6 +60,8 @@ export declare class ContentExtractor {
     private cleanOcrText;
     /** 加载图片像素数据（依赖 sharp） */
     private loadImagePixels;
+    private readImageDimensions;
+    private isTooSmallForOcr;
     private extractPdfText;
     private normalizedTextLength;
     private toPdfTextItem;

package/dist/extraction/content-extractor.js

@@ -776,8 +776,13 @@ export class ContentExtractor {
                 }
                 if (matrix.length > 0) {
                     const header = matrix[0] ?? [];
-                    const rows = matrix.slice(1);
-                    sheetTexts.push([`工作表：${name}`, this.toMarkdownTable(header, rows)].join('\n\n'));
+                    // 表格分页：为了防止超大 Excel 导致单块过大，将其每 500 行分为一个独立的 Markdown Table。
+                    const chunkSize = 500;
+                    for (let i = 1; i < matrix.length; i += chunkSize) {
+                        const rows = matrix.slice(i, i + chunkSize);
+                        const sheetSuffix = matrix.length > chunkSize ? ` (第 ${Math.floor(i / chunkSize) + 1} 部分)` : '';
+                        sheetTexts.push([`工作表：${name}${sheetSuffix}`, this.toMarkdownTable(header, rows)].join('\n\n'));
+                    }
                 }
             }
             if (sheetTexts.length > 0) {
@@ -804,17 +809,47 @@ export class ContentExtractor {
         const docXml = await zip.files['word/document.xml']?.async('string');
         if (!docXml)
             return '';
-        const paragraphs = Array.from(docXml.matchAll(/<w:p[\s\S]*?<\/w:p>/gu), match => match[0]);
+        // 我们需要按出现顺序提取 paragraph 和 table
+        // 在 xml 中 w:body 的一级子节点通常是 w:p 和 w:tbl
+        const elements = Array.from(docXml.matchAll(/<(w:p|w:tbl)[\s>][\s\S]*?<\/\1>/gu), match => ({ tag: match[1], xml: match[0] }));
         const lines = [];
-        for (const paragraph of paragraphs) {
-            const texts = Array.from(paragraph.matchAll(/<w:t[^>]*>([\s\S]*?)<\/w:t>/gu), match => this.stripXml(match[1] ?? '')).join('');
-            if (!texts.trim())
-                continue;
-            const style = /<w:pStyle\s+w:val="([^"]+)"/u.exec(paragraph)?.[1] ?? '';
-            const bold = /<w:b\b/u.test(paragraph);
-            const size = Number(/<w:sz\s+w:val="(\d+)"/u.exec(paragraph)?.[1] ?? 0);
-            const level = this.docxHeadingLevel(style, bold, size, texts);
-            lines.push(`${level > 0 ? `${'#'.repeat(level)} ` : ''}${texts.trim()}`);
+        for (const { tag, xml } of elements) {
+            if (tag === 'w:p') {
+                const texts = Array.from(xml.matchAll(/<w:t[^>]*>([\s\S]*?)<\/w:t>/gu), match => this.stripXml(match[1] ?? '')).join('');
+                if (!texts.trim())
+                    continue;
+                const style = /<w:pStyle\s+w:val="([^"]+)"/u.exec(xml)?.[1] ?? '';
+                const bold = /<w:b\b/u.test(xml);
+                const size = Number(/<w:sz\s+w:val="(\d+)"/u.exec(xml)?.[1] ?? 0);
+                const level = this.docxHeadingLevel(style, bold, size, texts);
+                lines.push(`${level > 0 ? `${'#'.repeat(level)} ` : ''}${texts.trim()}`);
+            }
+            else if (tag === 'w:tbl') {
+                const trList = Array.from(xml.matchAll(/<w:tr[\s>][\s\S]*?<\/w:tr>/gu), match => match[0]);
+                const rows = [];
+                for (const tr of trList) {
+                    const tcList = Array.from(tr.matchAll(/<w:tc[\s>][\s\S]*?<\/w:tc>/gu), match => match[0]);
+                    const cols = [];
+                    for (const tc of tcList) {
+                        const tcText = Array.from(tc.matchAll(/<w:t[^>]*>([\s\S]*?)<\/w:t>/gu), match => this.stripXml(match[1] ?? '')).join('');
+                        cols.push(tcText.trim().replace(/\r?\n/gu, ' '));
+                    }
+                    rows.push(cols);
+                }
+                if (rows.length > 0) {
+                    const maxCols = Math.max(...rows.map(r => r.length));
+                    // 补齐列数
+                    rows.forEach(r => { while (r.length < maxCols)
+                        r.push(''); });
+                    const header = rows[0] || Array(maxCols).fill('');
+                    const mdTable = [
+                        `| ${header.join(' | ')} |`,
+                        `| ${header.map(() => '---').join(' | ')} |`,
+                        ...rows.slice(1).map(row => `| ${row.join(' | ')} |`)
+                    ].join('\n');
+                    lines.push(mdTable);
+                }
+            }
         }
         return lines.join('\n\n');
     }
@@ -883,6 +918,12 @@ export class ContentExtractor {
         let imageData;
         try {
             imageData = await this.loadImagePixels(file.absolutePath);
+            if (this.isTooSmallForOcr(imageData.width, imageData.height)) {
+                metadata.contentCoverage = 'image_too_small_for_ocr';
+                metadata.imageWidth = imageData.width;
+                metadata.imageHeight = imageData.height;
+                return { text: this.metadataOnlyText(file), metadata, warnings: [`图片尺寸过小（${imageData.width}x${imageData.height}），已跳过 OCR 并仅索引元数据`] };
+            }
         }
         catch (e) {
             metadata.contentCoverage = 'image_decode_failed';
@@ -1059,10 +1100,16 @@ export class ContentExtractor {
         for (let i = 0; i < pageImages.length; i++) {
             const imgPath = pageImages[i];
             try {
+                const dimensions = await this.readImageDimensions(imgPath);
+                if (dimensions && this.isTooSmallForOcr(dimensions.width, dimensions.height)) {
+                    failedPages.push({ page: i + 1, reason: `image_too_small_for_ocr_${dimensions.width}x${dimensions.height}` });
+                    warnings.push(`PDF 第 ${i + 1} 页渲染图片尺寸过小（${dimensions.width}x${dimensions.height}），已跳过 OCR`);
+                    continue;
+                }
                 const provider = await getOcrProvider();
                 const ocrResult = await provider.recognize({
                     data: new Uint8Array(0),
-                    width: 0, height: 0, channels: 0,
+                    width: dimensions?.width ?? 0, height: dimensions?.height ?? 0, channels: 0,
                     filePath: imgPath,
                 });
                 const ocrText = this.cleanOcrText(ocrResult.text);
@@ -1184,6 +1231,22 @@ export class ContentExtractor {
         const { data, info } = await sharpFn(filePath).raw().toBuffer({ resolveWithObject: true });
         return { data: new Uint8Array(data), width: info.width, height: info.height };
     }
+    async readImageDimensions(filePath) {
+        try {
+            const sharpMod = await resolveAndImport('sharp');
+            const sharpFn = sharpMod.default ?? sharpMod;
+            const metadata = await sharpFn(filePath).metadata();
+            const width = Number(metadata.width ?? 0);
+            const height = Number(metadata.height ?? 0);
+            return width > 0 && height > 0 ? { width, height } : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    isTooSmallForOcr(width, height) {
+        return width < 8 || height < 8 || width * height < 128;
+    }
     async extractPdfText(buffer) {
         let pdfjsText = '';
         // 第一层：pdfjs-dist 文本提取（处理压缩内容流、CJK 字体、现代 PDF）

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

@@ -48,6 +48,8 @@ export declare class TesseractJsProvider implements OcrProvider {
         filePath?: string;
     }): Promise<OcrResult>;
     getWarnings(): string[];
+    private readImageDimensions;
+    private isTooSmallForOcr;
     private getWorker;
     private createReusableWorker;
     dispose(): Promise<void>;

package/dist/extraction/ocr-providers.js

@@ -44,9 +44,14 @@ export class TesseractJsProvider {
     async recognize(input) {
         let pngPath;
         let tmpDir = null;
+        let width = input.width;
+        let height = input.height;
         // 如果传了 filePath，直接使用；否则 raw pixels → PNG
         if (input.filePath && fs.existsSync(input.filePath)) {
             pngPath = input.filePath;
+            const dimensions = await this.readImageDimensions(pngPath);
+            width = dimensions?.width ?? width;
+            height = dimensions?.height ?? height;
         }
         else {
             const sharpMod = await resolveAndImport('sharp');
@@ -61,6 +66,9 @@ export class TesseractJsProvider {
                 .withMetadata({ density: 288 })
                 .png().toFile(pngPath);
         }
+        if (this.isTooSmallForOcr(width, height)) {
+            return { text: '', confidence: 0, regions: [], warnings: [`image too small for OCR: ${width}x${height}`] };
+        }
         try {
             const worker = await this.getWorker();
             const result = await worker.recognize(pngPath);
@@ -88,6 +96,22 @@ export class TesseractJsProvider {
     getWarnings() {
         return [...new Set(this.warnings)].slice(-20);
     }
+    async readImageDimensions(filePath) {
+        try {
+            const sharpMod = await resolveAndImport('sharp');
+            const sharpFn = sharpMod.default ?? sharpMod;
+            const metadata = await sharpFn(filePath).metadata();
+            const width = Number(metadata.width ?? 0);
+            const height = Number(metadata.height ?? 0);
+            return width > 0 && height > 0 ? { width, height } : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    isTooSmallForOcr(width, height) {
+        return width < 8 || height < 8 || width * height < 128;
+    }
     async getWorker() {
         if (this.worker)
             return this.worker;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@customize-agent/knowledge",
-  "version": "4.0.16",
+  "version": "4.0.18",
   "description": "Local knowledge base infrastructure for customize-agent",
   "type": "module",
   "main": "./dist/index.js",