@customize-agent/knowledge 4.0.29 → 4.0.31

package/dist/core/index-state-store.d.ts

@@ -148,7 +148,10 @@ export declare class IndexStateStore {
      * @param limit 返回结果数量上限
      * @returns 搜索结果列表（按相关性得分排序）
      */
-    searchChunks(query: string, limit?: number): ChunkSearchResult[];
+    searchChunks(query: string, limit?: number, filters?: {
+        filePaths?: string[];
+    }): ChunkSearchResult[];
+    private filePathFilterClause;
     private searchChunksFts;
     private searchChunksLike;
     findExactDuplicate(contentHash: string, excludePath?: string): FileHashRecord | undefined;

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

@@ -264,17 +264,21 @@ export class IndexStateStore {
      * @param limit 返回结果数量上限
      * @returns 搜索结果列表（按相关性得分排序）
      */
-    searchChunks(query, limit = 10) {
+    searchChunks(query, limit = 10, filters = {}) {
         const terms = this.expandSearchTerms(query);
         if (terms.length === 0)
             return [];
+        const filePaths = [...new Set((filters.filePaths ?? []).filter(Boolean))];
         const results = [
-            ...(this.ftsEnabled ? this.searchChunksFts(terms, limit) : []),
-            ...this.searchChunksLike(terms, limit),
+            ...(this.ftsEnabled ? this.searchChunksFts(terms, limit, filePaths) : []),
+            ...this.searchChunksLike(terms, limit, filePaths),
         ];
         return this.mergeKeywordResults(results, limit);
     }
-    searchChunksFts(terms, limit) {
+    filePathFilterClause(filePaths, column = 'relative_path') {
+        return filePaths.length > 0 ? ` AND ${column} IN (${filePaths.map(() => '?').join(', ')})` : '';
+    }
+    searchChunksFts(terms, limit, filePaths) {
         try {
             const matchQuery = this.toFtsQuery(terms);
             if (!matchQuery)
@@ -283,10 +287,10 @@ export class IndexStateStore {
         SELECT c.rowid, c.*, bm25(kb_chunks_fts, 1.2, 0.8, 0.6, 1.0, 2.0) as bm25_score
         FROM kb_chunks_fts
         INNER JOIN kb_chunks c ON c.id = kb_chunks_fts.id
-        WHERE kb_chunks_fts MATCH ?
+        WHERE kb_chunks_fts MATCH ?${this.filePathFilterClause(filePaths, 'c.relative_path')}
         ORDER BY bm25_score ASC
         LIMIT ?
-      `).all(matchQuery, limit * 8);
+      `).all(matchQuery, ...filePaths, limit * 8);
             return rows
                 .map(row => {
                 const keyword = this.scoreChunkDetailed(this.searchableRowText(row), terms);
@@ -301,13 +305,13 @@ export class IndexStateStore {
             return [];
         }
     }
-    searchChunksLike(terms, limit) {
+    searchChunksLike(terms, limit, filePaths) {
         const rows = this.db.prepare(`
       SELECT rowid, * FROM kb_chunks
-      WHERE ${terms.map(() => '(LOWER(search_content) LIKE ? OR LOWER(content) LIKE ? OR LOWER(relative_path) LIKE ? OR LOWER(category) LIKE ? OR LOWER(format) LIKE ? OR LOWER(COALESCE(title_path, \'\')) LIKE ? OR LOWER(COALESCE(chunk_kind, \'\')) LIKE ?)').join(' OR ')}
+      WHERE (${terms.map(() => '(LOWER(search_content) LIKE ? OR LOWER(content) LIKE ? OR LOWER(relative_path) LIKE ? OR LOWER(category) LIKE ? OR LOWER(format) LIKE ? OR LOWER(COALESCE(title_path, \'\')) LIKE ? OR LOWER(COALESCE(chunk_kind, \'\')) LIKE ?)').join(' OR ')})${this.filePathFilterClause(filePaths)}
       ORDER BY created_at DESC
       LIMIT ?
-    `).all(...terms.flatMap(term => [`%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`]), limit * 6);
+    `).all(...terms.flatMap(term => [`%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`]), ...filePaths, limit * 6);
         return rows
             .map(row => {
             const keyword = this.scoreChunkDetailed(this.searchableRowText(row), terms);

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

@@ -64,8 +64,8 @@ export declare class KnowledgeBaseManager {
         vectorMode?: 'sync' | 'defer';
         onlyRelativePaths?: string[];
     }): Promise<DiffResult>;
-    search(query: string, limit?: number): ChunkSearchResult[];
-    keywordSearchItems(query: string, limit?: number): FederatedSearchItem[];
+    search(query: string, limit?: number, filters?: SearchFilters): ChunkSearchResult[];
+    keywordSearchItems(query: string, limit?: number, filters?: SearchFilters): FederatedSearchItem[];
     expandContext(item: FederatedSearchItem): FederatedSearchItem;
     hybridSearch(query: string, options?: {
         limit?: number;

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

@@ -89,11 +89,8 @@ export class KnowledgeBaseManager {
     async consumePendingIndexJobs(options = {}) {
         this.initialize();
         const jobs = this.store.listPendingIndexJobs(options.limit ?? 500);
-        if (jobs.length === 0) {
-            if (options.waitForUploadId && this.uploadSessionIsOpen(options.waitForUploadId))
-                return this.emptyDiff();
-            return this.incrementalIndex(options);
-        }
+        if (jobs.length === 0)
+            return this.emptyDiff();
         return this.incrementalIndex({ ...options, onlyRelativePaths: jobs.map(job => job.relativePath) });
     }
     async incrementalIndex(options = {}) {
@@ -301,11 +298,11 @@ export class KnowledgeBaseManager {
             this.onProgress = previousOnProgress;
         }
     }
-    search(query, limit = 10) {
-        return this.store.searchChunks(query, limit);
+    search(query, limit = 10, filters) {
+        return this.store.searchChunks(query, limit, { filePaths: filters?.filePaths ?? (filters?.filePath ? [filters.filePath] : undefined) });
     }
-    keywordSearchItems(query, limit = 10) {
-        return this.store.searchChunks(query, limit).map(result => this.toFederatedItem(result, 'keyword'));
+    keywordSearchItems(query, limit = 10, filters) {
+        return this.store.searchChunks(query, limit, { filePaths: filters?.filePaths ?? (filters?.filePath ? [filters.filePath] : undefined) }).map(result => this.toFederatedItem(result, 'keyword'));
     }
     expandContext(item) {
         const chunkIndex = item.chunkIndex ?? this.parseChunkIndex(item.id);
@@ -345,7 +342,7 @@ export class KnowledgeBaseManager {
         const vectorMultiplier = options.generationMode ? 3 : 6;
         const vectorQueryLimit = options.generationMode ? 1 : 3;
         for (const [queryIndex, rewritten] of rewrittenQueries.entries()) {
-            rankedLists.push({ source: 'keyword', items: this.keywordSearchItems(rewritten, limit * keywordMultiplier), queryIndex });
+            rankedLists.push({ source: 'keyword', items: this.keywordSearchItems(rewritten, limit * keywordMultiplier, options.filters), queryIndex });
             if (queryIndex < vectorQueryLimit) {
                 try {
                     rankedLists.push({ source: 'vector', items: (await this.semanticSearch(rewritten, { ...options, limit: limit * vectorMultiplier })).results.slice(0, limit * keywordMultiplier), queryIndex });
@@ -460,7 +457,7 @@ export class KnowledgeBaseManager {
         const targetPath = this.resolveKbRelativePath(relativePath);
         fs.mkdirSync(path.dirname(targetPath), { recursive: true });
         fs.copyFileSync(resolvedSource, targetPath);
-        return this.incrementalIndex();
+        return this.incrementalIndex({ onlyRelativePaths: [relativePath] });
     }
     getUploadRelativePath(fileName, targetRelativePath) {
         return this.validateUploadRelativePath(targetRelativePath ? this.normalizeRelativePath(targetRelativePath) : this.defaultUploadRelativePath(fileName));
@@ -504,8 +501,8 @@ export class KnowledgeBaseManager {
         return jobs;
     }
     async uploadFiles(files, onProgress, options = {}) {
-        await this.stageUploadedFiles(files);
-        return this.incrementalIndex({ onProgress, vectorMode: options.vectorMode });
+        const jobs = await this.stageUploadedFiles(files);
+        return this.incrementalIndex({ onProgress, vectorMode: options.vectorMode, onlyRelativePaths: jobs.map(job => job.relativePath) });
     }
     listFailedFiles() {
         return this.lastSkippedFiles;

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

@@ -9,7 +9,6 @@ export declare class MultiProjectManager {
     private readonly registry;
     private readonly configManager;
     private readonly projects;
-    private readonly lastSearchIndexCheck;
     private globalKB?;
     constructor(storageRoot?: string, llmProvider?: LLMSearchProvider);
     /**
@@ -25,9 +24,9 @@ export declare class MultiProjectManager {
     search(projectRoot: string, query: string, options?: {
         limit?: number;
         scope?: SearchScope;
+        filters?: SearchFilters;
         weights?: RetrievalWeights;
         generationMode?: boolean;
-        skipFreshCheck?: boolean;
     }): Promise<FederatedResult>;
     semanticSearch(projectRoot: string, query: string, options?: {
         limit?: number;
@@ -39,7 +38,6 @@ 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

@@ -13,7 +13,6 @@ export class MultiProjectManager {
     registry;
     configManager;
     projects = new Map();
-    lastSearchIndexCheck = new Map();
     globalKB;
     constructor(storageRoot = path.join(os.homedir(), USER_DATA_DIR), llmProvider) {
         this.storageRoot = storageRoot;
@@ -53,7 +52,6 @@ export class MultiProjectManager {
             return this.globalKB;
         const manager = new KnowledgeBaseManager({ scope: 'global', storageRoot: this.storageRoot, llmProvider: this.llmProvider });
         manager.initialize();
-        await manager.incrementalIndex();
         this.globalKB = manager;
         return manager;
     }
@@ -64,19 +62,17 @@ export class MultiProjectManager {
         const limit = options.limit ?? 10;
         const scope = options.scope ?? 'project';
         const project = await this.getProject(projectRoot);
-        if (!options.skipFreshCheck)
-            await this.ensureFreshForSearch(projectRoot, project);
         if (scope === 'project')
-            return project.hybridSearch(query, { limit, weights: options.weights, generationMode: options.generationMode });
+            return project.hybridSearch(query, { limit, filters: options.filters, weights: options.weights, generationMode: options.generationMode });
         const projectResults = scope === 'all'
-            ? await project.hybridSearch(query, { limit, weights: options.weights, generationMode: options.generationMode })
+            ? await project.hybridSearch(query, { limit, filters: options.filters, weights: options.weights, generationMode: options.generationMode })
             : { results: [], scopesSearched: [], queryTimeMs: 0 };
         if (scope === 'global') {
             const global = await this.getGlobalKB();
-            return global.hybridSearch(query, { limit, weights: options.weights, generationMode: options.generationMode });
+            return global.hybridSearch(query, { limit, filters: options.filters, weights: options.weights, generationMode: options.generationMode });
         }
         const global = await this.getGlobalKB();
-        const globalResults = await global.hybridSearch(query, { limit, weights: options.weights, generationMode: options.generationMode });
+        const globalResults = await global.hybridSearch(query, { limit, filters: options.filters, weights: options.weights, generationMode: options.generationMode });
         const merged = new FederationSearch().merge([...projectResults.results, ...globalResults.results], limit, 'all');
         return {
             ...merged,
@@ -86,7 +82,6 @@ export class MultiProjectManager {
     async semanticSearch(projectRoot, query, options = {}) {
         const scope = options.scope ?? 'project';
         const project = await this.getProject(projectRoot);
-        await this.ensureFreshForSearch(projectRoot, project);
         if (scope === 'project') {
             return project.semanticSearch(query, options);
         }
@@ -151,16 +146,6 @@ 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/search/federation-search.d.ts

@@ -48,6 +48,7 @@ export interface FederatedResult {
 export interface SearchFilters {
     category?: string;
     filePath?: string;
+    filePaths?: string[];
 }
 /** 各检索方式权重配置 */
 export interface RetrievalWeights {

package/dist/search/federation-search.js

@@ -65,9 +65,12 @@ export class FederationSearch {
         if (!filters)
             return undefined;
         const where = {};
+        const filePaths = filters.filePaths?.filter(Boolean);
         if (filters.category)
             where.category = filters.category;
-        if (filters.filePath)
+        if (filePaths?.length)
+            where.file_path = filePaths;
+        else if (filters.filePath)
             where.file_path = filters.filePath;
         return Object.keys(where).length > 0 ? where : undefined;
     }

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

@@ -96,7 +96,10 @@ export class HNSWVectorStore {
     matchesWhere(document, where) {
         if (!where)
             return true;
-        return Object.entries(where).every(([key, value]) => document.metadata[key] === value);
+        return Object.entries(where).every(([key, value]) => {
+            const actual = document.metadata[key];
+            return Array.isArray(value) ? value.includes(actual) : actual === value;
+        });
     }
     persist() {
         this.index.writeIndexSync(this.indexPath);

package/dist/vector/types.d.ts

@@ -6,10 +6,11 @@ export interface VectorDocument {
     metadata: Record<string, string | number | boolean | null>;
 }
 /** 向量搜索查询参数 */
+export type VectorFilterValue = string | number | boolean | Array<string | number | boolean>;
 export interface VectorSearchQuery {
     queryEmbedding: number[];
     topK: number;
-    where?: Record<string, string | number | boolean>;
+    where?: Record<string, VectorFilterValue>;
 }
 /** 向量搜索结果 */
 export interface VectorSearchResult {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@customize-agent/knowledge",
-  "version": "4.0.29",
+  "version": "4.0.31",
   "description": "Local knowledge base infrastructure for customize-agent",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,7 +14,7 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=22.13.0"
+    "node": ">=20.19.0"
   },
   "author": "Pan-jijian",
   "repository": {

package/scripts/install-hnsw.cjs

@@ -13,6 +13,33 @@ function run(command, args, cwd) {
   if (result.status !== 0) process.exit(result.status || 1);
 }
 
+function markerPath(hnswDir) {
+  return path.join(hnswDir, 'build', '.customize-agent-hnsw-ok');
+}
+
+function findNativeBinding(hnswDir) {
+  const candidates = [
+    path.join(hnswDir, 'build', 'Release', 'addon.node'),
+    path.join(hnswDir, 'prebuilds', `${process.platform}-${process.arch}`, 'node.napi.node'),
+  ];
+  return candidates.find(candidate => fs.existsSync(candidate));
+}
+
+function isMarkerFresh(hnswDir) {
+  const marker = markerPath(hnswDir);
+  const binding = findNativeBinding(hnswDir);
+  if (!fs.existsSync(marker) || !binding) return false;
+  const markerStat = fs.statSync(marker);
+  const bindingStat = fs.statSync(binding);
+  return markerStat.mtimeMs >= bindingStat.mtimeMs;
+}
+
+function writeMarker(hnswDir) {
+  const marker = markerPath(hnswDir);
+  fs.mkdirSync(path.dirname(marker), { recursive: true });
+  fs.writeFileSync(marker, JSON.stringify({ node: process.version, platform: process.platform, arch: process.arch, updatedAt: Date.now() }));
+}
+
 function verify(hnswDir) {
   const hnsw = require(path.join(hnswDir, 'lib/index.js'));
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'hnsw-doctor-'));
@@ -35,10 +62,20 @@ function verify(hnswDir) {
 
 try {
   const hnswDir = packageDir('hnswlib-node');
+  if (isMarkerFresh(hnswDir)) {
+    try {
+      verify(hnswDir);
+      console.log('[hnsw] hnswlib-node 已可用，跳过 native rebuild');
+      process.exit(0);
+    } catch {
+      // 标记存在但运行验证失败，继续 rebuild。
+    }
+  }
   const nodeGypBin = require.resolve('node-gyp/bin/node-gyp.js', { paths: [process.cwd(), __dirname] });
   console.log(`[hnsw] 构建 hnswlib-node native binding: ${hnswDir}`);
   run(process.execPath, [nodeGypBin, 'rebuild'], hnswDir);
   verify(hnswDir);
+  writeMarker(hnswDir);
   console.log('[hnsw] hnswlib-node 安装和运行验证通过');
 } catch (error) {
   console.error('[hnsw] hnswlib-node 安装或运行验证失败。请确认当前平台已安装 native 编译工具链。');