@customize-agent/knowledge 4.0.1 → 4.0.3

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

@@ -10,7 +10,7 @@ import { createEmbeddingProviderFromEnvironment } from '../embedding/embedding-p
 import { ContentExtractor } from '../extraction/content-extractor.js';
 import { FederationSearch } from '../search/federation-search.js';
 import { CollectionManager } from '../vector/collection-manager.js';
-import { SQLiteVecClient, SQLiteVecVectorStore } from '../vector/sqlite-vec-store.js';
+import { HNSWVectorStore } from '../vector/hnsw-vector-store.js';
 import { VectorIndexer } from '../vector/vector-indexer.js';
 import { ChangeTracker } from './change-tracker.js';
 import { KnowledgeFileScanner } from './file-scanner.js';
@@ -22,7 +22,7 @@ export class KnowledgeBaseManager {
     projectId;
     kbPath;
     store;
-    sqliteVecClient;
+    vectorRoot;
     classifier = new FileClassifier();
     scanner = new KnowledgeFileScanner();
     collections = new CollectionManager();
@@ -61,7 +61,7 @@ export class KnowledgeBaseManager {
             dbPath = path.join(storageRoot, 'projects', options.projectId, 'kb.db');
         }
         this.store = new IndexStateStore(dbPath);
-        this.sqliteVecClient = new SQLiteVecClient({ dbPath });
+        this.vectorRoot = path.join(path.dirname(dbPath), 'hnsw');
     }
     initialize() {
         if (this.scope === 'project' && this.projectRoot) {
@@ -76,6 +76,22 @@ export class KnowledgeBaseManager {
             fs.mkdirSync(this.kbPath, { recursive: true });
         }
     }
+    async forceReindexAll(options = {}) {
+        this.initialize();
+        const records = this.store.listRecords();
+        for (const record of records) {
+            await this.deleteVectorFile(record.collectionName, record.relativePath);
+            this.store.deleteRecord(record.relativePath);
+        }
+        return this.incrementalIndex(options);
+    }
+    async consumePendingIndexJobs(options = {}) {
+        this.initialize();
+        const jobs = this.store.listPendingIndexJobs(options.limit ?? 50);
+        if (jobs.length === 0)
+            return this.incrementalIndex(options);
+        return this.incrementalIndex({ ...options, onlyRelativePaths: jobs.map(job => job.relativePath) });
+    }
     async incrementalIndex(options = {}) {
         this.initialize();
         const previousOnProgress = this.onProgress;
@@ -88,9 +104,22 @@ export class KnowledgeBaseManager {
             const diskFiles = await this.scanner.scan(this.kbPath, [...kbIgnore, ...configIgnore]);
             const tracker = new ChangeTracker(this.store);
             const diff = await tracker.computeDiff(diskFiles, this.classifier, this.kbPath);
+            const onlyRelativePaths = options.onlyRelativePaths ? new Set(options.onlyRelativePaths) : undefined;
+            if (onlyRelativePaths) {
+                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, '待索引文件不存在或未发生变化', '待索引文件不存在或未发生变化');
+                }
+            }
             for (const deleted of diff.deletedFiles) {
                 await this.deleteVectorFile(deleted.collectionName, deleted.relativePath);
                 this.store.deleteRecord(deleted.relativePath);
+                this.updateJobsForFile(deleted.relativePath, 'SUCCESS', 100, '文件已删除，索引记录和向量已清理');
             }
             const now = Date.now();
             const indexedBefore = [...this.store.loadActiveRecords().values()];
@@ -102,12 +131,14 @@ export class KnowledgeBaseManager {
                     ? this.collections.getCollectionName('global', file.category)
                     : this.collections.getCollectionName('project', file.category, this.projectId);
                 const basePercent = filesToIndex.length === 0 ? 40 : 20 + Math.round((index / filesToIndex.length) * 45);
+                this.updateJobsForFile(file.relativePath, 'PARSING', basePercent, `正在解析 ${file.relativePath}`);
                 this.reportProgress({ stage: 'parsing', percent: basePercent, message: `正在解析 ${file.relativePath}`, filePath: file.relativePath });
                 const extraction = await this.extractor.extract(file);
                 extraction.metadata.textLength = extraction.text.length;
                 if (!this.hasUsableContent(extraction.text, extraction.metadata)) {
                     const reason = extraction.warnings[0] ?? '未解析出可用于模型的正文内容，已跳过向量化';
                     diff.skippedFiles.push({ file, reason });
+                    this.updateJobsForFile(file.relativePath, 'ERROR', 100, reason, reason);
                     this.store.upsertRecord({
                         relativePath: file.relativePath,
                         category: file.category,
@@ -129,6 +160,7 @@ export class KnowledgeBaseManager {
                 const normalizedDuplicate = !duplicate && normalizedHash
                     ? this.store.findNormalizedDuplicate(normalizedHash, file.relativePath)
                     : undefined;
+                this.updateJobsForFile(file.relativePath, 'CHUNKING', Math.min(80, basePercent + 10), `正在切片 ${file.relativePath}`);
                 this.reportProgress({ stage: 'chunking', percent: Math.min(80, basePercent + 10), message: `正在切片 ${file.relativePath}`, filePath: file.relativePath });
                 const chunks = this.chunker.chunk(extraction.text, file, extraction.metadata);
                 this.reportProgress({ stage: 'chunking', percent: Math.min(84, basePercent + 14), message: `切片完成：${chunks.length} 块`, filePath: file.relativePath, chunkCount: chunks.length });
@@ -212,20 +244,31 @@ export class KnowledgeBaseManager {
                     format: file.format,
                     collectionName,
                 });
+                this.updateJobsForFile(file.relativePath, options.vectorMode === 'defer' ? 'SUCCESS' : 'INDEXING', options.vectorMode === 'defer' ? 100 : 85, options.vectorMode === 'defer' ? '解析和切片已完成' : '等待向量入库');
             }
             const stats = this.getStats();
             this.store.setMetadata('last_incremental_index_at', String(now));
             this.store.setMetadata('total_chunks', String(stats.chunkCount));
             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)
+                    this.store.setMetadata('vector_index_status', 'pending');
                 this.reportProgress({ stage: 'vectorizing', percent: 85, message: '解析和切片已完成，向量入库转入后台/稍后执行', chunkCount: stats.chunkCount, vectorStatus: this.getVectorStatus() });
-                void this.ensureVectorIndexFresh(stats.chunkCount, diff.newFiles.length + diff.modifiedFiles.length + diff.deletedFiles.length > 0).catch(() => undefined);
             }
             else {
-                await this.ensureVectorIndexFresh(stats.chunkCount, diff.newFiles.length + diff.modifiedFiles.length + diff.deletedFiles.length > 0);
+                await this.ensureVectorIndexFresh(stats.chunkCount, hasIndexChanges);
             }
             this.lastSkippedFiles = diff.skippedFiles;
             const vectorStatus = this.getVectorStatus();
+            if (options.vectorMode !== 'defer') {
+                for (const file of filesToIndex) {
+                    if (vectorStatus.status === 'error')
+                        this.updateJobsForFile(file.relativePath, 'ERROR', 100, 'HNSWLib 向量入库失败', vectorStatus.error);
+                    else
+                        this.updateJobsForFile(file.relativePath, 'SUCCESS', 100, '解析、切片和向量索引完成');
+                }
+            }
             const vectorDeferred = options.vectorMode === 'defer';
             this.reportProgress({
                 stage: vectorDeferred || vectorStatus.status !== 'error' ? 'done' : 'error',
@@ -233,7 +276,7 @@ export class KnowledgeBaseManager {
                 message: vectorDeferred
                     ? '解析、切片和 SQLite 入库已完成，向量入库后台执行'
                     : vectorStatus.status === 'error'
-                        ? '解析和切片已完成，sqlite-vec 向量待入库'
+                        ? '解析和切片已完成，HNSWLib 向量待入库'
                         : '知识库索引完成',
                 chunkCount: stats.chunkCount,
                 vectorStatus,
@@ -264,8 +307,10 @@ export class KnowledgeBaseManager {
         }
         const parentChunks = item.parentId ? this.store.getChunksByParent(item.filePath, item.parentId, 6) : [];
         const chunks = parentChunks.length > 0 ? parentChunks : this.store.getContextChunks(item.filePath, chunkIndex, 1);
-        if (chunks.length === 0)
-            return item;
+        if (chunks.length === 0) {
+            const document = this.store.getDocumentChunk(item.filePath);
+            return document ? { ...item, content: document.content, sectionTitle: item.sectionTitle ?? 'Document Parent' } : item;
+        }
         return {
             ...item,
             content: chunks.map(chunk => chunk.content).join('\n\n---\n\n'),
@@ -279,15 +324,19 @@ export class KnowledgeBaseManager {
         const start = Date.now();
         const weights = this.retrievalWeights(options.weights);
         const rewrittenQueries = await this.rewriteQueries(query);
-        const keywordItems = rewrittenQueries.flatMap((rewritten, index) => this.keywordSearchItems(rewritten, limit * 2).map(item => ({ ...item, score: item.score * (index === 0 ? 1 : (weights.rewrite ?? 0.72)) })));
-        const vectorItems = [];
-        for (const rewritten of rewrittenQueries.slice(0, 3)) {
-            try {
-                vectorItems.push(...(await this.semanticSearch(rewritten, { ...options, limit: limit * 2 })).results);
+        const rankedLists = [];
+        for (const [queryIndex, rewritten] of rewrittenQueries.entries()) {
+            rankedLists.push({ source: 'keyword', items: this.keywordSearchItems(rewritten, limit * 3), queryIndex });
+            if (queryIndex < 3) {
+                try {
+                    rankedLists.push({ source: 'vector', items: (await this.semanticSearch(rewritten, { ...options, limit: limit * 3 })).results, queryIndex });
+                }
+                catch { /* 向量搜索在混合搜索中是可选的 */ }
             }
-            catch { /* vector search is optional in hybrid search */ }
         }
-        const merged = this.mergeHybridItems([...keywordItems, ...vectorItems], limit * 2, weights).map(item => this.expandContext(item));
+        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;
@@ -310,7 +359,7 @@ export class KnowledgeBaseManager {
         const queryEmbedding = await this.embeddingProvider.embedQuery(query);
         const search = new FederationSearch(this.vectorStores);
         try {
-            return await search.search({
+            const result = await search.search({
                 query,
                 queryEmbedding,
                 topK: options.limit ?? 10,
@@ -319,6 +368,7 @@ export class KnowledgeBaseManager {
                 collections: options.collections,
                 filters: options.filters,
             });
+            return { ...result, results: this.hydrateVectorResultsFromSqlite(result.results) };
         }
         catch {
             return { results: [], scopesSearched: this.scope === 'global' ? ['global'] : ['project'], queryTimeMs: 0 };
@@ -372,22 +422,25 @@ export class KnowledgeBaseManager {
     async uploadFile(fileName, content, targetRelativePath, onProgress, options = {}) {
         return this.uploadFiles([{ fileName, content, targetRelativePath }], onProgress, options);
     }
-    async uploadFiles(files, onProgress, options = {}) {
+    async stageUploadedFiles(files, operationId = `upload-${Date.now()}`) {
         this.initialize();
-        const uploadedPaths = [];
-        for (const file of files) {
+        const jobs = [];
+        for (let index = 0; index < files.length; index++) {
+            const file = files[index];
             const relativePath = this.getUploadRelativePath(file.fileName, file.targetRelativePath);
             const targetPath = this.resolveKbRelativePath(relativePath);
             fs.mkdirSync(path.dirname(targetPath), { recursive: true });
             fs.writeFileSync(targetPath, file.content);
-            uploadedPaths.push(relativePath);
-        }
-        for (const relativePath of uploadedPaths) {
             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;
+    }
+    async uploadFiles(files, onProgress, options = {}) {
+        await this.stageUploadedFiles(files);
         return this.incrementalIndex({ onProgress, vectorMode: options.vectorMode });
     }
     listFailedFiles() {
@@ -398,12 +451,17 @@ export class KnowledgeBaseManager {
         const targetPath = this.resolveKbRelativePath(normalized);
         if (fs.existsSync(targetPath))
             fs.unlinkSync(targetPath);
-        // 同步删除 sqlite-vec 向量数据，避免孤儿向量污染搜索结果
+        // 同步删除 HNSWLib 向量数据，避免孤儿向量污染搜索结果
         const record = this.store.listRecords().find(r => r.relativePath === normalized);
         if (record) {
             await this.deleteVectorFile(record.collectionName, normalized);
         }
         this.store.deleteRecord(normalized);
+        const stats = this.getStats();
+        this.store.setMetadata('total_chunks', String(stats.chunkCount));
+        this.store.setMetadata('total_files_indexed', String(stats.fileCount));
+        this.store.setMetadata('vector_indexed_chunks', String(stats.chunkCount));
+        this.store.setMetadata('last_vector_index_at', String(Date.now()));
     }
     tagFile(relativePath, tags) {
         this.store.setTags(this.normalizeRelativePath(relativePath), tags);
@@ -425,18 +483,39 @@ export class KnowledgeBaseManager {
     }
     async indexVectors(options = {}) {
         const chunks = this.store.listChunks(options);
-        for (const collectionName of new Set(chunks.map(chunk => chunk.collectionName)))
+        const collectionNames = new Set(chunks.map(chunk => chunk.collectionName));
+        for (const collectionName of collectionNames)
             this.ensureVectorStore(collectionName);
-        this.reportProgress({ stage: 'vectorizing', percent: 85, message: `正在写入 sqlite-vec 向量库，共 ${chunks.length} 个切片`, chunkCount: chunks.length });
+        if (!options.relativePath) {
+            for (const collectionName of collectionNames)
+                await this.vectorStores.get(collectionName)?.clearCollection?.();
+        }
+        else {
+            for (const collectionName of collectionNames)
+                await this.vectorStores.get(collectionName)?.deleteByFilePath(options.relativePath);
+        }
+        this.reportProgress({ stage: 'vectorizing', percent: 85, message: `正在写入 HNSWLib 向量库，共 ${chunks.length} 个切片`, chunkCount: chunks.length });
         const indexer = new VectorIndexer(this.embeddingProvider, this.vectorStores);
         try {
-            const results = await indexer.indexChunks(chunks);
-            this.store.setMetadata('embedding_model', this.embeddingProvider.model);
-            this.store.setMetadata('embedding_dimension', String(this.embeddingProvider.dimensions));
+            const results = await indexer.indexChunks(chunks, {
+                onProgress: progress => {
+                    const percent = 85 + Math.round((progress.processedChunks / Math.max(1, progress.totalChunks)) * 14);
+                    const message = `正在分批向量化并写入：${progress.processedChunks}/${progress.totalChunks} 个切片`;
+                    this.reportProgress({ stage: 'vectorizing', percent, message, chunkCount: progress.totalChunks });
+                    if (options.relativePath)
+                        this.updateJobsForFile(options.relativePath, 'INDEXING', percent, message);
+                },
+            });
+            const actualModel = results[0]?.embeddingModel ?? this.embeddingProvider.model;
+            const actualDimension = results[0]?.embeddingDimension ?? this.embeddingProvider.dimensions;
+            this.store.setMetadata('embedding_model', actualModel);
+            this.store.setMetadata('embedding_dimension', String(actualDimension));
             this.store.setMetadata('vector_indexed_chunks', String(chunks.length));
             this.store.setMetadata('vector_index_status', 'ready');
             this.store.setMetadata('vector_index_error', '');
             this.store.setMetadata('last_vector_index_at', String(Date.now()));
+            if (options.relativePath)
+                this.updateJobsForFile(options.relativePath, 'SUCCESS', 100, '解析、切片和向量索引完成');
             return results;
         }
         catch (error) {
@@ -444,7 +523,9 @@ export class KnowledgeBaseManager {
             this.store.setMetadata('vector_index_status', 'error');
             this.store.setMetadata('vector_index_error', message);
             this.store.setMetadata('last_vector_index_at', String(Date.now()));
-            this.reportProgress({ stage: 'error', percent: 85, message: 'sqlite-vec 向量入库失败', chunkCount: chunks.length, vectorStatus: this.getVectorStatus() });
+            this.reportProgress({ stage: 'error', percent: 85, message: 'HNSWLib 向量入库失败', chunkCount: chunks.length, vectorStatus: this.getVectorStatus() });
+            if (options.relativePath)
+                this.updateJobsForFile(options.relativePath, 'ERROR', 100, 'HNSWLib 向量入库失败', message);
             return [];
         }
     }
@@ -462,13 +543,23 @@ export class KnowledgeBaseManager {
             lastIndexedAt: stats.lastIndexedAt,
         };
     }
+    listIndexJobsByPrefix(prefix) {
+        return this.store.listIndexJobsByPrefix(prefix);
+    }
+    countPendingIndexJobs() {
+        return this.store.countPendingIndexJobs();
+    }
+    failPendingIndexJobs(message) {
+        for (const job of this.store.listPendingIndexJobs(1_000))
+            this.store.updateIndexJob(job.id, { status: 'ERROR', percent: 100, message, errorMessage: message });
+    }
     getVectorStatus() {
         return {
             status: this.store.getMetadata('vector_index_status') ?? 'pending',
             error: this.store.getMetadata('vector_index_error') || undefined,
             indexedChunks: Number(this.store.getMetadata('vector_indexed_chunks') ?? 0),
             lastIndexedAt: Number(this.store.getMetadata('last_vector_index_at') ?? 0),
-            backend: `SQLite + sqlite-vec (${this.sqliteVecClient.dbPath})`,
+            backend: `SQLite + HNSWLib (${this.vectorRoot})`,
         };
     }
     async rewriteQueries(query) {
@@ -599,10 +690,22 @@ ${resultsText}
             return this.heuristicRerank(query, items);
         }
     }
+    hydrateVectorResultsFromSqlite(items) {
+        return items.map(item => {
+            if (!item.rowid)
+                return item;
+            const chunk = this.store.getChunkByRowid(item.rowid);
+            if (!chunk)
+                return item;
+            const hydrated = this.toFederatedItem({ ...chunk, score: item.score, scoreDetails: item.scoreDetails }, 'vector');
+            return { ...hydrated, score: item.score, scoreDetails: item.scoreDetails };
+        });
+    }
     toFederatedItem(result, source) {
         const metadata = this.parseMetadata(result.metadataJson);
         return {
             id: result.id,
+            rowid: result.rowid,
             content: result.content,
             filePath: result.relativePath,
             scope: this.scope === 'global' ? 'global' : 'project',
@@ -618,32 +721,70 @@ ${resultsText}
             facets: this.metadataFacets(metadata),
         };
     }
-    mergeHybridItems(items, limit, weights = this.retrievalWeights()) {
+    mergeHybridRankedLists(lists, limit, weights = this.retrievalWeights()) {
+        const k = Number(process.env.KB_RETRIEVAL_RRF_K ?? 60);
+        const byKey = new Map();
+        for (const list of lists) {
+            const sourceWeight = list.source === 'vector' ? (weights.vector ?? 0.9) : (weights.keyword ?? 1);
+            const rewriteWeight = list.queryIndex === 0 ? 1 : (weights.rewrite ?? 0.72);
+            list.items.forEach((item, index) => {
+                const key = this.contextKey(item);
+                const rankScore = sourceWeight * rewriteWeight / (k + index + 1);
+                const existing = byKey.get(key);
+                if (!existing) {
+                    byKey.set(key, {
+                        ...item,
+                        score: rankScore,
+                        source: list.source,
+                        scoreDetails: { ...item.scoreDetails, hybridScore: rankScore },
+                        seenSources: new Set([list.source]),
+                    });
+                    return;
+                }
+                existing.score += rankScore;
+                existing.seenSources?.add(list.source);
+                existing.source = existing.seenSources && existing.seenSources.size > 1 ? 'hybrid' : existing.source;
+                existing.scoreDetails = { ...existing.scoreDetails, ...item.scoreDetails, hybridScore: existing.score };
+                if (item.score > (existing.scoreDetails?.keywordScore ?? existing.scoreDetails?.vectorScore ?? 0)) {
+                    existing.content = item.content;
+                    existing.sectionTitle = item.sectionTitle ?? existing.sectionTitle;
+                    existing.chunkIndex = item.chunkIndex ?? existing.chunkIndex;
+                    existing.parentId = item.parentId ?? existing.parentId;
+                }
+            });
+        }
+        const hybridBonus = weights.hybridBonus ?? 0.35;
+        return [...byKey.values()].map(item => {
+            const bonus = item.seenSources && item.seenSources.size > 1 ? item.score * hybridBonus : 0;
+            const { seenSources: _seenSources, ...result } = item;
+            return { ...result, score: result.score + bonus, scoreDetails: { ...result.scoreDetails, hybridScore: result.score + bonus } };
+        }).sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+    mergeContexts(items, limit) {
         const byKey = new Map();
         for (const item of items) {
-            const key = `${item.scope}:${item.filePath}:${item.parentId ?? item.chunkIndex ?? item.id}`;
-            const sourceWeight = item.source === 'vector' ? (weights.vector ?? 0.9) : item.source === 'keyword' ? (weights.keyword ?? 1) : 1.1;
-            const weighted = { ...item, score: item.score * sourceWeight, scoreDetails: { ...item.scoreDetails, hybridScore: item.score * sourceWeight } };
+            const key = this.contextKey(item);
             const existing = byKey.get(key);
             if (!existing) {
-                byKey.set(key, weighted);
-            }
-            else {
-                const score = Math.max(existing.score, weighted.score) + Math.min(existing.score, weighted.score) * (weights.hybridBonus ?? 0.35);
-                byKey.set(key, {
-                    ...existing,
-                    score,
-                    source: existing.source === weighted.source ? existing.source : 'hybrid',
-                    scoreDetails: {
-                        ...existing.scoreDetails,
-                        ...weighted.scoreDetails,
-                        hybridScore: score,
-                    },
-                });
+                byKey.set(key, item);
+                continue;
             }
+            const score = Math.max(existing.score, item.score);
+            byKey.set(key, {
+                ...existing,
+                score,
+                source: existing.source === item.source ? existing.source : 'hybrid',
+                content: existing.content.length >= item.content.length ? existing.content : item.content,
+                scoreDetails: { ...existing.scoreDetails, ...item.scoreDetails, hybridScore: 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}`;
+        return `${item.scope}:${item.filePath}:${item.parentId ?? item.chunkIndex ?? item.id}`;
+    }
     parseChunkIndex(id) {
         const match = /#(\d+)$/u.exec(id);
         return match ? Number(match[1]) : 0;
@@ -688,10 +829,16 @@ ${resultsText}
     reportProgress(progress) {
         this.onProgress?.(progress);
     }
+    updateJobsForFile(relativePath, status, percent, message, errorMessage) {
+        for (const job of this.store.listActiveIndexJobsByPath(relativePath)) {
+            this.store.updateIndexJob(job.id, { status, percent, message, errorMessage });
+        }
+    }
     ensureVectorStore(collectionName) {
         if (this.vectorStores.has(collectionName))
             return;
-        this.vectorStores.set(collectionName, new SQLiteVecVectorStore(this.sqliteVecClient, collectionName));
+        const safeName = collectionName.replace(/[^a-zA-Z0-9_.-]/gu, '_');
+        this.vectorStores.set(collectionName, new HNSWVectorStore(collectionName, path.join(this.vectorRoot, `${safeName}.hnsw`), this.embeddingProvider.dimensions));
     }
     async deleteVectorFile(collectionName, relativePath) {
         this.ensureVectorStore(collectionName);
@@ -706,10 +853,15 @@ ${resultsText}
     async ensureVectorIndexFresh(chunkCount, force = false) {
         if (chunkCount === 0)
             return;
+        for (const record of this.store.listRecords())
+            this.ensureVectorStore(record.collectionName);
+        if ([...this.vectorStores.values()].some(store => store.needsRebuild?.())) {
+            await this.indexVectors();
+            return;
+        }
         const indexedChunks = Number(this.store.getMetadata('vector_indexed_chunks') ?? 0);
-        const model = this.store.getMetadata('embedding_model');
-        const dimension = this.store.getMetadata('embedding_dimension');
-        if (!force && indexedChunks === chunkCount && model === this.embeddingProvider.model && dimension === String(this.embeddingProvider.dimensions))
+        const status = this.store.getMetadata('vector_index_status');
+        if (!force && indexedChunks === chunkCount && status === 'ready')
             return;
         await this.indexVectors();
     }

package/dist/core/multi-project-manager.d.ts

@@ -2,15 +2,24 @@ import type { FederatedResult, RetrievalWeights, SearchFilters, SearchScope } fr
 import type { CrossProjectDuplicate, ProjectInfo } from '../types.js';
 import { KnowledgeBaseManager } from './knowledge-base-manager.js';
 import type { LLMSearchProvider } from '../llm/llm-search-provider.js';
+/** 多项目管理器，管理多个项目的知识库并支持跨项目搜索 */
 export declare class MultiProjectManager {
     private readonly storageRoot;
     private readonly llmProvider?;
     private readonly registry;
     private readonly configManager;
     private readonly projects;
+    private readonly lastSearchIndexCheck;
     private globalKB?;
     constructor(storageRoot?: string, llmProvider?: LLMSearchProvider);
+    /**
+     * 获取或创建指定项目的知识库管理器
+     * @param projectRoot 项目根目录
+     */
     getProject(projectRoot: string): Promise<KnowledgeBaseManager>;
+    /**
+     * 获取或初始化全局知识库
+     */
     getGlobalKB(): Promise<KnowledgeBaseManager>;
     listProjects(): Promise<ProjectInfo[]>;
     search(projectRoot: string, query: string, options?: {
@@ -28,6 +37,7 @@ export declare class MultiProjectManager {
     forgetProject(projectId: string): Promise<void>;
     closeProject(projectId: string): Promise<void>;
     shutdown(): Promise<void>;
+    private ensureFreshForSearch;
     private mergeDebug;
     private updateRegistry;
 }

package/dist/core/multi-project-manager.js

@@ -6,12 +6,14 @@ import { KnowledgeBaseManager } from './knowledge-base-manager.js';
 import { computeProjectId } from './project-id.js';
 import { getProjectKbPath, ProjectConfigManager } from './project-config.js';
 import { ProjectRegistry } from './project-registry.js';
+/** 多项目管理器，管理多个项目的知识库并支持跨项目搜索 */
 export class MultiProjectManager {
     storageRoot;
     llmProvider;
     registry;
     configManager;
     projects = new Map();
+    lastSearchIndexCheck = new Map();
     globalKB;
     constructor(storageRoot = path.join(os.homedir(), USER_DATA_DIR), llmProvider) {
         this.storageRoot = storageRoot;
@@ -19,6 +21,10 @@ export class MultiProjectManager {
         this.registry = new ProjectRegistry(path.join(storageRoot, 'projects', 'registry.db'));
         this.configManager = new ProjectConfigManager(storageRoot);
     }
+    /**
+     * 获取或创建指定项目的知识库管理器
+     * @param projectRoot 项目根目录
+     */
     async getProject(projectRoot) {
         const resolvedRoot = path.resolve(projectRoot);
         const projectId = computeProjectId(resolvedRoot);
@@ -39,6 +45,9 @@ export class MultiProjectManager {
         this.updateRegistry(manager, resolvedRoot, config.projectName, config.lastOpenedAt);
         return manager;
     }
+    /**
+     * 获取或初始化全局知识库
+     */
     async getGlobalKB() {
         if (this.globalKB)
             return this.globalKB;
@@ -55,7 +64,7 @@ export class MultiProjectManager {
         const limit = options.limit ?? 10;
         const scope = options.scope ?? 'all';
         const project = await this.getProject(projectRoot);
-        await project.incrementalIndex();
+        await this.ensureFreshForSearch(projectRoot, project);
         if (scope === 'project')
             return project.hybridSearch(query, { limit, weights: options.weights });
         const projectResults = scope === 'all'
@@ -76,7 +85,7 @@ export class MultiProjectManager {
     async semanticSearch(projectRoot, query, options = {}) {
         const scope = options.scope ?? 'all';
         const project = await this.getProject(projectRoot);
-        await project.incrementalIndex();
+        await this.ensureFreshForSearch(projectRoot, project);
         if (scope === 'project') {
             return project.semanticSearch(query, options);
         }
@@ -141,6 +150,16 @@ export class MultiProjectManager {
         this.globalKB = undefined;
         this.registry.close();
     }
+    async ensureFreshForSearch(projectRoot, project) {
+        const now = Date.now();
+        const key = path.resolve(projectRoot);
+        const ttlMs = Number(process.env.KB_SEARCH_INDEX_TTL_MS ?? 30000);
+        const last = this.lastSearchIndexCheck.get(key) ?? 0;
+        if (now - last < ttlMs)
+            return;
+        this.lastSearchIndexCheck.set(key, now);
+        await project.incrementalIndex({ vectorMode: 'defer' });
+    }
     mergeDebug(projectDebug, globalDebug) {
         if (!projectDebug && !globalDebug)
             return undefined;

package/dist/core/project-config.d.ts

@@ -1,7 +1,11 @@
 import type { ProjectConfig } from '../types.js';
+/** 获取项目配置文件路径 */
 export declare function getProjectConfigPath(projectRoot: string, storageRoot?: string): string;
+/** 获取项目知识库目录路径 */
 export declare function getProjectKbPath(projectRoot: string): string;
+/** 确保项目存在 CUSTOMIZE.md 文件（如不存在则创建默认模板） */
 export declare function ensureProjectCustomizeFile(projectRoot: string): void;
+/** 项目配置管理器，负责加载和保存项目配置 */
 export declare class ProjectConfigManager {
     private readonly storageRoot;
     constructor(storageRoot?: string);

package/dist/core/project-config.js

@@ -3,10 +3,12 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import { DEFAULT_CATEGORY_DIRS, KNOWLEDGE_BASE_DIR, USER_DATA_DIR } from '../constants.js';
 import { computeProjectId } from './project-id.js';
+/** 获取项目配置文件路径 */
 export function getProjectConfigPath(projectRoot, storageRoot = path.join(os.homedir(), USER_DATA_DIR)) {
     const projectId = computeProjectId(projectRoot);
     return path.join(storageRoot, 'projects', projectId, 'project.json');
 }
+/** 获取项目知识库目录路径 */
 export function getProjectKbPath(projectRoot) {
     return path.join(projectRoot, KNOWLEDGE_BASE_DIR);
 }
@@ -27,6 +29,7 @@ const DEFAULT_CUSTOMIZE_MD = `# Customize Agent 配置示例
 - 使用中文回复。
 - 重要改动完成后运行必要的类型检查或构建检查。
 `;
+/** 确保项目存在 CUSTOMIZE.md 文件（如不存在则创建默认模板） */
 export function ensureProjectCustomizeFile(projectRoot) {
     const filePath = path.join(projectRoot, 'CUSTOMIZE.md');
     if (!fs.existsSync(filePath)) {
@@ -34,6 +37,7 @@ export function ensureProjectCustomizeFile(projectRoot) {
         fs.writeFileSync(filePath, DEFAULT_CUSTOMIZE_MD, 'utf8');
     }
 }
+/** 项目配置管理器，负责加载和保存项目配置 */
 export class ProjectConfigManager {
     storageRoot;
     constructor(storageRoot = path.join(os.homedir(), USER_DATA_DIR)) {

package/dist/core/project-id.d.ts

@@ -1 +1,6 @@
+/**
+ * 使用项目根目录计算项目唯一标识
+ * @param projectRoot 项目根目录路径
+ * @returns 项目 ID（SHA-256 前 12 位）
+ */
 export declare function computeProjectId(projectRoot: string): string;

package/dist/core/project-id.js

@@ -1,5 +1,10 @@
 import * as crypto from 'node:crypto';
 import * as path from 'node:path';
+/**
+ * 使用项目根目录计算项目唯一标识
+ * @param projectRoot 项目根目录路径
+ * @returns 项目 ID（SHA-256 前 12 位）
+ */
 export function computeProjectId(projectRoot) {
     return crypto.createHash('sha256')
         .update(path.resolve(projectRoot))

package/dist/core/project-registry.d.ts

@@ -1,4 +1,5 @@
 import type { ProjectInfo } from '../types.js';
+/** 项目注册表，使用 SQLite 管理已注册项目的元数据 */
 export declare class ProjectRegistry {
     private readonly db;
     constructor(dbPath: string);

package/dist/core/project-registry.js

@@ -1,6 +1,7 @@
 import Database from 'better-sqlite3';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+/** 项目注册表，使用 SQLite 管理已注册项目的元数据 */
 export class ProjectRegistry {
     db;
     constructor(dbPath) {