@customize-agent/knowledge 4.0.31 → 4.0.33

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

@@ -175,6 +175,7 @@ export declare class KnowledgeBaseManager {
     private updateJobsForFile;
     private ensureVectorStore;
     private deleteVectorFile;
+    private consumePendingVectorRelativePaths;
     private ensureVectorIndexFresh;
     uploadSessionIsOpen(operationId: string): boolean;
     private emptyDiff;

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

@@ -91,7 +91,17 @@ export class KnowledgeBaseManager {
         const jobs = this.store.listPendingIndexJobs(options.limit ?? 500);
         if (jobs.length === 0)
             return this.emptyDiff();
-        return this.incrementalIndex({ ...options, onlyRelativePaths: jobs.map(job => job.relativePath) });
+        const lightweightJobs = [];
+        const heavyJobs = [];
+        for (const job of jobs) {
+            const ext = path.extname(job.relativePath).toLowerCase();
+            if (/\.(pdf|png|jpe?g|webp|gif|bmp|tiff?|xlsx?|xlsm|docx?|pptx?)$/iu.test(ext))
+                heavyJobs.push(job);
+            else
+                lightweightJobs.push(job);
+        }
+        const selectedJobs = [...lightweightJobs, ...heavyJobs].slice(0, options.limit ?? 500);
+        return this.incrementalIndex({ ...options, onlyRelativePaths: selectedJobs.map(job => job.relativePath) });
     }
     async incrementalIndex(options = {}) {
         this.initialize();
@@ -111,12 +121,25 @@ export class KnowledgeBaseManager {
                 diff.newFiles = diff.newFiles.filter(file => onlyRelativePaths.has(file.relativePath));
                 diff.modifiedFiles = diff.modifiedFiles.filter(file => onlyRelativePaths.has(file.relativePath));
                 diff.deletedFiles = diff.deletedFiles.filter(file => onlyRelativePaths.has(file.relativePath));
-                diff.hasChanges = diff.newFiles.length + diff.modifiedFiles.length + diff.deletedFiles.length > 0;
                 for (const relativePath of onlyRelativePaths) {
                     const exists = diff.newFiles.some(file => file.relativePath === relativePath) || diff.modifiedFiles.some(file => file.relativePath === relativePath) || diff.deletedFiles.some(file => file.relativePath === relativePath);
-                    if (!exists)
-                        this.updateJobsForFile(relativePath, 'ERROR', 100, '待索引文件不存在或未发生变化', '待索引文件不存在或未发生变化');
+                    if (exists)
+                        continue;
+                    const diskStat = diskFiles.get(relativePath);
+                    if (!diskStat) {
+                        this.updateJobsForFile(relativePath, 'ERROR', 100, '待索引文件不存在', '待索引文件不存在');
+                        continue;
+                    }
+                    const absolutePath = this.resolveKbRelativePath(relativePath);
+                    const stat = fs.statSync(absolutePath);
+                    const classified = this.classifier.classify(absolutePath, relativePath, stat);
+                    const skipReason = this.classifier.shouldSkip(classified);
+                    if (skipReason)
+                        this.updateJobsForFile(relativePath, 'ERROR', 100, skipReason, skipReason);
+                    else
+                        diff.modifiedFiles.push(classified);
                 }
+                diff.hasChanges = diff.newFiles.length + diff.modifiedFiles.length + diff.deletedFiles.length > 0;
             }
             for (const deleted of diff.deletedFiles) {
                 await this.deleteVectorFile(deleted.collectionName, deleted.relativePath);
@@ -263,8 +286,13 @@ export class KnowledgeBaseManager {
             this.store.setMetadata('total_files_indexed', String(stats.fileCount));
             const hasIndexChanges = diff.newFiles.length + diff.modifiedFiles.length + diff.deletedFiles.length > 0;
             if (options.vectorMode === 'defer') {
-                if (hasIndexChanges)
+                if (hasIndexChanges) {
                     this.store.setMetadata('vector_index_status', 'pending');
+                    const pending = new Set(this.consumePendingVectorRelativePaths());
+                    for (const relativePath of vectorRelativePaths)
+                        pending.add(relativePath);
+                    this.store.setMetadata('vector_pending_relative_paths', JSON.stringify([...pending]));
+                }
                 this.reportProgress({ stage: 'vectorizing', percent: 85, message: '解析和切片已完成，向量入库转入后台/稍后执行', chunkCount: stats.chunkCount, vectorStatus: this.getVectorStatus() });
             }
             else {
@@ -474,10 +502,6 @@ export class KnowledgeBaseManager {
             const targetPath = this.resolveKbRelativePath(relativePath);
             fs.mkdirSync(path.dirname(targetPath), { recursive: true });
             fs.writeFileSync(targetPath, file.content);
-            const record = this.store.listRecords().find(item => item.relativePath === relativePath);
-            if (record)
-                await this.deleteVectorFile(record.collectionName, relativePath);
-            this.store.deleteRecord(relativePath);
             jobs.push(this.store.enqueueIndexJob({ id: `${operationId}-${index}`, relativePath, message: '文件已落盘，等待后台解析' }));
         }
         return jobs;
@@ -492,10 +516,6 @@ export class KnowledgeBaseManager {
             const targetPath = this.resolveKbRelativePath(relativePath);
             fs.mkdirSync(path.dirname(targetPath), { recursive: true });
             this.moveUploadedFile(file.sourcePath, targetPath);
-            const record = this.store.listRecords().find(item => item.relativePath === relativePath);
-            if (record)
-                await this.deleteVectorFile(record.collectionName, relativePath);
-            this.store.deleteRecord(relativePath);
             jobs.push(this.store.enqueueIndexJob({ id: `${operationId}-${offset + index}`, relativePath, message: '文件已落盘，等待后台解析' }));
         }
         return jobs;
@@ -543,6 +563,11 @@ export class KnowledgeBaseManager {
         return this.store.listIgnoreRules();
     }
     async indexVectors(options = {}) {
+        const pendingRelativePaths = !options.rebuild && !options.relativePath && !options.relativePaths?.length
+            ? this.consumePendingVectorRelativePaths()
+            : [];
+        if (pendingRelativePaths.length > 0)
+            options = { ...options, relativePaths: pendingRelativePaths };
         const chunks = options.relativePaths?.length
             ? options.relativePaths.flatMap(relativePath => this.store.listChunks({ collectionName: options.collectionName, relativePath }))
             : this.store.listChunks(options);
@@ -555,9 +580,15 @@ export class KnowledgeBaseManager {
                 await this.vectorStores.get(collectionName)?.clearCollection?.();
         }
         else {
-            for (const relativePath of options.relativePaths ?? [options.relativePath].filter(Boolean)) {
-                for (const collectionName of cleanupCollectionNames)
-                    await this.vectorStores.get(collectionName)?.deleteByFilePath(relativePath, { persist: false });
+            const cleanupRelativePaths = options.relativePaths ?? [options.relativePath].filter(Boolean);
+            for (const collectionName of cleanupCollectionNames) {
+                const vectorStore = this.vectorStores.get(collectionName);
+                if (vectorStore?.deleteByFilePaths)
+                    await vectorStore.deleteByFilePaths(cleanupRelativePaths, { persist: false });
+                else {
+                    for (const relativePath of cleanupRelativePaths)
+                        await vectorStore?.deleteByFilePath(relativePath, { persist: false });
+                }
             }
             if (chunks.length === 0) {
                 for (const collectionName of cleanupCollectionNames)
@@ -906,6 +937,22 @@ export class KnowledgeBaseManager {
             this.store.setMetadata('vector_index_error', error instanceof Error ? error.message : String(error));
         }
     }
+    consumePendingVectorRelativePaths() {
+        const raw = this.store.getMetadata('vector_pending_relative_paths');
+        if (!raw)
+            return [];
+        try {
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                return [];
+            this.store.setMetadata('vector_pending_relative_paths', '');
+            return [...new Set(parsed.filter((item) => typeof item === 'string' && item.trim().length > 0))];
+        }
+        catch {
+            this.store.setMetadata('vector_pending_relative_paths', '');
+            return [];
+        }
+    }
     async ensureVectorIndexFresh(chunkCount, options = {}) {
         if (chunkCount === 0)
             return;
@@ -925,7 +972,7 @@ export class KnowledgeBaseManager {
             this.store.setMetadata('last_vector_index_at', String(Date.now()));
             return;
         }
-        if (changedRelativePaths.length > 0 && status === 'ready') {
+        if (changedRelativePaths.length > 0) {
             for (const collectionName of options.changedCollectionNames ?? [])
                 this.ensureVectorStore(collectionName);
             await this.indexVectors({ relativePaths: changedRelativePaths, cleanupCollectionNames: options.changedCollectionNames });
@@ -933,6 +980,8 @@ export class KnowledgeBaseManager {
         }
         if (indexedChunks === chunkCount && status === 'ready')
             return;
+        if (status === 'pending' || status === 'partial')
+            return;
         await this.indexVectors({ rebuild: true });
     }
     uploadSessionIsOpen(operationId) {

package/dist/embedding/embedding-provider.js

@@ -84,7 +84,7 @@ export class OpenAICompatibleEmbeddingProvider {
 }
 function resolveLocalEmbeddingBatchSize(configured) {
     const raw = configured ?? Number(process.env.CUSTOMIZE_EMBEDDING_BATCH_SIZE ?? process.env.KB_EMBEDDING_BATCH_SIZE);
-    const fallback = process.platform === 'win32' ? 8 : 16;
+    const fallback = process.platform === 'win32' ? 8 : 32;
     if (!Number.isFinite(raw) || raw <= 0)
         return fallback;
     return Math.max(1, Math.min(128, Math.floor(raw)));

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

@@ -52,11 +52,15 @@ export declare class ContentExtractor {
     private formatBoundingBox;
     private validateRasterImage;
     private extractPdf;
+    private hasUsablePdfText;
     private extractPdfHybridPages;
-    /** PyMuPDF 渲染（300 DPI 原生提取，质量远高于 pdfjs-dist） */
+    /** PyMuPDF 渲染（默认 200 DPI，低质量页可自适应提高） */
     private tryRenderWithPyMuPDF;
     /** pdfjs-dist + canvas 渲染（降级方案） */
     private tryRenderWithPdfJs;
+    private getPdfOcrDpi;
+    private getPdfOcrRetryDpi;
+    private shouldRetryPdfOcrAtHigherDpi;
     private scoreOcrText;
     private cleanOcrText;
     /** 加载图片像素数据（依赖 sharp） */

package/dist/extraction/content-extractor.js

@@ -1029,24 +1029,27 @@ export class ContentExtractor {
         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 = [...hybrid.warnings];
+        const metadata = { extractionMode: 'pdf_text_first', vectorizable: true };
+        const warnings = [];
         try {
             const raw = fs.readFileSync(file.absolutePath);
             const text = await this.extractPdfText(raw);
-            if (text.trim()) {
+            if (this.hasUsablePdfText(text)) {
                 metadata.contentCoverage = 'pdf_text_streams_layout_markdown';
                 metadata.pdfExtractor = 'pdfjs-dist';
+                metadata.ocrSkippedReason = 'pdf_text_stream_quality_sufficient';
                 return { text: [this.metadataOnlyText(file), this.toMarkdownDocument(text)].join('\n\n'), metadata, warnings };
             }
+            if (text.trim())
+                warnings.push('PDF 文本层质量不足，已尝试选择性 OCR 增强');
         }
         catch (error) {
             warnings.push(`PDF 文本提取失败: ${error instanceof Error ? error.message : String(error)}`);
             metadata.parseError = error instanceof Error ? error.message : String(error);
         }
+        const hybrid = await this.extractPdfHybridPages(file);
+        if (hybrid.text.trim())
+            return { text: hybrid.text, metadata: { ...metadata, ...hybrid.metadata }, warnings: [...warnings, ...hybrid.warnings] };
         metadata.extractionMode = 'pdf_metadata_only';
         metadata.contentCoverage = 'metadata_filename';
         metadata.ocrRecommended = true;
@@ -1055,9 +1058,17 @@ export class ContentExtractor {
         return {
             text: this.metadataOnlyText(file),
             metadata,
-            warnings: [...warnings, 'PDF 正文暂未提取到文本，已索引文件名、路径和类型元数据'],
+            warnings: [...warnings, ...hybrid.warnings, 'PDF 正文暂未提取到文本，已索引文件名、路径和类型元数据'],
         };
     }
+    hasUsablePdfText(text) {
+        const normalized = text.replace(/\s+/gu, ' ').trim();
+        if (normalized.length < Number(process.env.CUSTOMIZE_KB_PDF_TEXT_MIN_CHARS || 80))
+            return false;
+        const replacementRatio = (normalized.match(/[\uFFFD�]/gu)?.length ?? 0) / normalized.length;
+        const visibleRatio = (normalized.match(/[\p{L}\p{N}\p{Script=Han}]/gu)?.length ?? 0) / normalized.length;
+        return replacementRatio < 0.02 && visibleRatio > 0.35;
+    }
     async extractPdfHybridPages(file) {
         const metadata = {
             extractionMode: 'pdf_hybrid_pages',
@@ -1074,17 +1085,37 @@ export class ContentExtractor {
         };
         const failedPages = [];
         const ocrPages = [];
+        const ocrRetryPages = [];
         const ocrStrategies = [];
-        // 尝试 PyMuPDF 渲染（高质量）或降级到 pdfjs-dist
+        // 尝试 PyMuPDF 渲染（默认 200 DPI），低质量页自动升到 300 DPI 重试
         let pageImages;
+        let highDpiImages = null;
         let pageCount = 0;
         let renderer = 'unknown';
+        const initialDpi = this.getPdfOcrDpi();
+        const retryDpi = this.getPdfOcrRetryDpi(initialDpi);
         const tmpDir = fs.mkdtempSync(path.join(this.getTempRoot(), 'kb-pdf-'));
+        metadata.pdfOcrInitialDpi = initialDpi;
+        if (retryDpi > initialDpi)
+            metadata.pdfOcrRetryDpi = retryDpi;
+        const getHighDpiImage = (pageIndex) => {
+            if (retryDpi <= initialDpi)
+                return undefined;
+            if (!highDpiImages) {
+                const retryDir = path.join(tmpDir, `retry-${retryDpi}dpi`);
+                fs.mkdirSync(retryDir, { recursive: true });
+                highDpiImages = this.tryRenderWithPyMuPDF(file.absolutePath, retryDir, retryDpi);
+                if (!highDpiImages?.length)
+                    warnings.push(`PDF 高质量 OCR 重试渲染失败（${retryDpi} DPI）`);
+            }
+            const imagePath = highDpiImages?.[pageIndex];
+            return imagePath ? { imagePath, strategy: `PyMuPDF-${retryDpi}dpi` } : undefined;
+        };
         try {
-            // ── 方法1: PyMuPDF（300 DPI 原生渲染，质量最高） ──
-            pageImages = this.tryRenderWithPyMuPDF(file.absolutePath, tmpDir);
+            // ── 方法1: PyMuPDF（默认 200 DPI，低质量页再自适应升到 300 DPI） ──
+            pageImages = this.tryRenderWithPyMuPDF(file.absolutePath, tmpDir, initialDpi);
             if (pageImages && pageImages.length > 0) {
-                renderer = 'PyMuPDF';
+                renderer = `PyMuPDF-${initialDpi}dpi`;
                 pageCount = pageImages.length;
             }
             else {
@@ -1131,12 +1162,37 @@ export class ContentExtractor {
                     width: dimensions.width, height: dimensions.height, channels: 0,
                     filePath: imgPath,
                 });
-                const ocrText = this.cleanOcrText(ocrResult.text);
+                let ocrText = this.cleanOcrText(ocrResult.text);
+                let ocrScore = this.scoreOcrText(ocrText);
+                let strategy = renderer;
                 if (ocrResult.warnings?.length)
                     warnings.push(...ocrResult.warnings.map(item => `OCR 警告: ${item}`));
+                if (this.shouldRetryPdfOcrAtHigherDpi(ocrText, ocrScore)) {
+                    const retry = getHighDpiImage(i);
+                    if (retry) {
+                        const retryDimensions = await this.readImageDimensions(retry.imagePath);
+                        if (retryDimensions && !this.isTooSmallForOcr(retryDimensions.width, retryDimensions.height)) {
+                            const retryResult = await provider.recognize({
+                                data: new Uint8Array(0),
+                                width: retryDimensions.width, height: retryDimensions.height, channels: 0,
+                                filePath: retry.imagePath,
+                            });
+                            const retryText = this.cleanOcrText(retryResult.text);
+                            const retryScore = this.scoreOcrText(retryText);
+                            if (retryResult.warnings?.length)
+                                warnings.push(...retryResult.warnings.map(item => `OCR 重试警告: ${item}`));
+                            if (retryScore > ocrScore || (!ocrText && retryText)) {
+                                ocrText = retryText;
+                                ocrScore = retryScore;
+                                strategy = retry.strategy;
+                                ocrRetryPages.push(i + 1);
+                            }
+                        }
+                    }
+                }
                 if (ocrText) {
                     ocrPages.push(i + 1);
-                    ocrStrategies.push({ page: i + 1, strategy: renderer, score: this.scoreOcrText(ocrText) });
+                    ocrStrategies.push({ page: i + 1, strategy, score: ocrScore });
                     pageTexts.push(`## PDF 第 ${i + 1} 页（OCR）\n\n${ocrText}`);
                 }
                 else {
@@ -1158,6 +1214,7 @@ export class ContentExtractor {
         }
         metadata.ocrAugmented = ocrPages.length > 0;
         metadata.ocrPages = ocrPages;
+        metadata.ocrRetryPages = ocrRetryPages;
         metadata.ocrStrategies = ocrStrategies;
         metadata.failedPages = failedPages;
         metadata.ocrProvider = ocrProvider?.id ?? 'unknown';
@@ -1171,11 +1228,11 @@ export class ContentExtractor {
             warnings,
         };
     }
-    /** PyMuPDF 渲染（300 DPI 原生提取，质量远高于 pdfjs-dist） */
-    tryRenderWithPyMuPDF(pdfPath, outputDir) {
+    /** PyMuPDF 渲染（默认 200 DPI，低质量页可自适应提高） */
+    tryRenderWithPyMuPDF(pdfPath, outputDir, dpi = this.getPdfOcrDpi()) {
         try {
             const workerScript = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'scripts', 'render_pdf_pages.py');
-            spawnSync('python3', [workerScript, pdfPath, outputDir, '300'], {
+            spawnSync('python3', [workerScript, pdfPath, outputDir, String(dpi)], {
                 encoding: 'utf-8', timeout: 60_000, maxBuffer: 1024 * 1024,
             });
             // 检查输出文件（即使 Python 非零退出码也可能已渲染部分页面）
@@ -1226,6 +1283,21 @@ export class ContentExtractor {
             return null;
         }
     }
+    getPdfOcrDpi() {
+        return Math.max(120, Math.min(300, Number(process.env.CUSTOMIZE_KB_PDF_OCR_DPI || 200)));
+    }
+    getPdfOcrRetryDpi(initialDpi) {
+        const configured = Number(process.env.CUSTOMIZE_KB_PDF_OCR_RETRY_DPI || 300);
+        return Math.max(initialDpi, Math.min(300, Math.max(120, configured)));
+    }
+    shouldRetryPdfOcrAtHigherDpi(text, score) {
+        const normalizedLength = this.normalizedTextLength(text);
+        if (normalizedLength === 0)
+            return true;
+        const threshold = Number(process.env.CUSTOMIZE_KB_PDF_OCR_RETRY_MIN_SCORE || 120);
+        const replacementRatio = (text.match(/[�□]/gu)?.length ?? 0) / Math.max(1, text.length);
+        return score < threshold || replacementRatio > 0.02;
+    }
     scoreOcrText(value) {
         const text = String(value ?? '').trim();
         const normalizedLength = this.normalizedTextLength(text);

package/dist/vector/hnsw-vector-store.d.ts

@@ -9,11 +9,13 @@ export declare class HNSWVectorStore implements VectorStoreInterface {
     private deletedSinceRebuild;
     private dirty;
     private readonly documents;
+    private readonly rowidsByFilePath;
     constructor(collectionName: string, indexPath: string, dimensions?: number, maxElements?: number);
     ensureCollection(): Promise<void>;
     upsert(documents: VectorDocument[], options?: VectorWriteOptions): Promise<void>;
     clearCollection(): Promise<void>;
     deleteByFilePath(filePath: string, options?: VectorWriteOptions): Promise<void>;
+    deleteByFilePaths(filePaths: string[], options?: VectorWriteOptions): Promise<void>;
     flush(): Promise<void>;
     needsRebuild(): boolean;
     search(query: VectorSearchQuery): Promise<VectorSearchResult[]>;
@@ -21,5 +23,7 @@ export declare class HNSWVectorStore implements VectorStoreInterface {
     private persist;
     private toStoredDocument;
     private loadDocuments;
+    private trackDocumentFilePath;
+    private untrackDocumentFilePath;
     private metadataPath;
 }

package/dist/vector/hnsw-vector-store.js

@@ -12,6 +12,7 @@ export class HNSWVectorStore {
     deletedSinceRebuild = 0;
     dirty = false;
     documents = new Map();
+    rowidsByFilePath = new Map();
     constructor(collectionName, indexPath, dimensions = 512, maxElements = 500_000) {
         this.collectionName = collectionName;
         this.indexPath = indexPath;
@@ -36,8 +37,13 @@ export class HNSWVectorStore {
             const rowid = Number(document.metadata.sqlite_rowid);
             if (!Number.isFinite(rowid) || rowid <= 0)
                 throw new Error(`HNSW 向量写入缺少有效 sqlite_rowid: ${document.id}`);
+            const existing = this.documents.get(rowid);
+            if (existing)
+                this.untrackDocumentFilePath(rowid, existing);
             this.index.addPoint(document.embedding, rowid, true);
-            this.documents.set(rowid, this.toStoredDocument(document));
+            const stored = this.toStoredDocument(document);
+            this.documents.set(rowid, stored);
+            this.trackDocumentFilePath(rowid, stored);
             this.dirty = true;
         }
         if (options.persist !== false)
@@ -49,24 +55,43 @@ export class HNSWVectorStore {
         if (fs.existsSync(this.metadataPath()))
             fs.rmSync(this.metadataPath(), { force: true });
         this.documents.clear();
+        this.rowidsByFilePath.clear();
         this.deletedSinceRebuild = 0;
         this.dirty = false;
         this.index = undefined;
         await this.ensureCollection();
     }
     async deleteByFilePath(filePath, options = {}) {
+        await this.deleteByFilePaths([filePath], options);
+    }
+    async deleteByFilePaths(filePaths, options = {}) {
         await this.ensureCollection();
-        for (const [rowid, document] of this.documents.entries()) {
-            if (document.metadata.file_path === filePath) {
-                try {
-                    this.index.markDelete(rowid);
-                    this.deletedSinceRebuild += 1;
-                }
-                catch { /* 忽略缺失的标签 */ }
-                this.documents.delete(rowid);
-                this.dirty = true;
+        const rowids = new Set();
+        for (const filePath of filePaths) {
+            const tracked = this.rowidsByFilePath.get(filePath);
+            if (tracked) {
+                for (const rowid of tracked)
+                    rowids.add(rowid);
             }
         }
+        if (rowids.size === 0) {
+            if (options.persist !== false && this.dirty)
+                this.persist();
+            return;
+        }
+        for (const rowid of rowids) {
+            const document = this.documents.get(rowid);
+            if (!document)
+                continue;
+            try {
+                this.index.markDelete(rowid);
+                this.deletedSinceRebuild += 1;
+            }
+            catch { /* 忽略缺失的标签 */ }
+            this.documents.delete(rowid);
+            this.untrackDocumentFilePath(rowid, document);
+            this.dirty = true;
+        }
         if (options.persist !== false)
             this.persist();
     }
@@ -122,12 +147,40 @@ export class HNSWVectorStore {
             const entries = Array.isArray(parsed) ? parsed : parsed.documents ?? [];
             this.deletedSinceRebuild = Array.isArray(parsed) ? 0 : Number(parsed.deletedSinceRebuild ?? 0);
             this.documents.clear();
-            for (const [rowid, document] of entries)
-                this.documents.set(Number(rowid), { id: document.id, content: document.content ?? '', metadata: document.metadata });
+            this.rowidsByFilePath.clear();
+            for (const [rowid, document] of entries) {
+                const numericRowid = Number(rowid);
+                const stored = { id: document.id, content: document.content ?? '', metadata: document.metadata };
+                this.documents.set(numericRowid, stored);
+                this.trackDocumentFilePath(numericRowid, stored);
+            }
         }
         catch {
             this.documents.clear();
+            this.rowidsByFilePath.clear();
+        }
+    }
+    trackDocumentFilePath(rowid, document) {
+        const filePath = document.metadata.file_path;
+        if (typeof filePath !== 'string' || !filePath)
+            return;
+        let rowids = this.rowidsByFilePath.get(filePath);
+        if (!rowids) {
+            rowids = new Set();
+            this.rowidsByFilePath.set(filePath, rowids);
         }
+        rowids.add(rowid);
+    }
+    untrackDocumentFilePath(rowid, document) {
+        const filePath = document.metadata.file_path;
+        if (typeof filePath !== 'string' || !filePath)
+            return;
+        const rowids = this.rowidsByFilePath.get(filePath);
+        if (!rowids)
+            return;
+        rowids.delete(rowid);
+        if (rowids.size === 0)
+            this.rowidsByFilePath.delete(filePath);
     }
     metadataPath() {
         return `${this.indexPath}.documents.json`;

package/dist/vector/types.d.ts

@@ -33,6 +33,7 @@ export interface VectorStoreInterface {
     ensureCollection(metadata?: Record<string, unknown>): Promise<void>;
     upsert(documents: VectorDocument[], options?: VectorWriteOptions): Promise<void>;
     deleteByFilePath(filePath: string, options?: VectorWriteOptions): Promise<void>;
+    deleteByFilePaths?(filePaths: string[], options?: VectorWriteOptions): Promise<void>;
     flush?(): Promise<void>;
     clearCollection?(): Promise<void>;
     needsRebuild?(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@customize-agent/knowledge",
-  "version": "4.0.31",
+  "version": "4.0.33",
   "description": "Local knowledge base infrastructure for customize-agent",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,6 +36,9 @@
     "customize-agent",
     "knowledge-base"
   ],
+  "optionalDependencies": {
+    "hnswlib-node": "^3.0.0"
+  },
   "dependencies": {
     "@huggingface/transformers": "^3.8.0",
     "@napi-rs/canvas": "^0.1.82",
@@ -44,7 +47,6 @@
     "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",

package/scripts/install-hnsw.cjs

@@ -10,7 +10,7 @@ function packageDir(name) {
 
 function run(command, args, cwd) {
   const result = spawnSync(command, args, { cwd, stdio: 'inherit', shell: false });
-  if (result.status !== 0) process.exit(result.status || 1);
+  if (result.status !== 0) throw new Error(`${command} ${args.join(' ')} exited with ${result.status || 1}`);
 }
 
 function markerPath(hnswDir) {
@@ -61,7 +61,14 @@ function verify(hnswDir) {
 }
 
 try {
-  const hnswDir = packageDir('hnswlib-node');
+  let hnswDir;
+  try {
+    hnswDir = packageDir('hnswlib-node');
+  } catch {
+    console.log('[hnsw] 未安装可选依赖 hnswlib-node，跳过 native 初始化。');
+    process.exit(0);
+  }
+
   if (isMarkerFresh(hnswDir)) {
     try {
       verify(hnswDir);
@@ -78,7 +85,11 @@ try {
   writeMarker(hnswDir);
   console.log('[hnsw] hnswlib-node 安装和运行验证通过');
 } catch (error) {
-  console.error('[hnsw] hnswlib-node 安装或运行验证失败。请确认当前平台已安装 native 编译工具链。');
-  console.error(error && error.stack ? error.stack : error);
-  process.exit(1);
+  console.warn('[hnsw] hnswlib-node 当前不可用，已跳过可选向量索引 native 初始化，不影响主包安装。');
+  console.warn('[hnsw] 如需启用本地向量索引，请安装 native 编译工具链后运行 npm rebuild hnswlib-node 或在源码仓库执行 pnpm doctor:hnsw。');
+  if (process.env.CUSTOMIZE_AGENT_HNSW_STRICT === '1') {
+    console.warn(error && error.stack ? error.stack : error);
+    process.exit(1);
+  }
+  process.exit(0);
 }