@customize-agent/knowledge 4.0.32 → 4.0.34

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

@@ -130,11 +130,21 @@ export declare class IndexStateStore {
         format: string;
         collectionName: string;
     }): void;
+    private chunkQueryParts;
     listChunks(options?: {
         collectionName?: string;
         relativePath?: string;
         limit?: number;
     }): StoredChunk[];
+    countChunks(options?: {
+        collectionName?: string;
+        relativePath?: string;
+    }): number;
+    listChunksByContentBudget(options?: {
+        collectionName?: string;
+        relativePath?: string;
+        maxContentChars?: number;
+    }): StoredChunk[];
     getChunkByRowid(rowid: number): StoredChunk | undefined;
     getChunksByRowids(rowids: number[]): StoredChunk[];
     getContextChunks(relativePath: string, chunkIndex: number, window?: number): StoredChunk[];
@@ -152,6 +162,7 @@ export declare class IndexStateStore {
         filePaths?: string[];
     }): ChunkSearchResult[];
     private filePathFilterClause;
+    private resolveChunkSearchLimit;
     private searchChunksFts;
     private searchChunksLike;
     findExactDuplicate(contentHash: string, excludePath?: string): FileHashRecord | undefined;

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

@@ -182,7 +182,7 @@ export class IndexStateStore {
         });
         transaction();
     }
-    listChunks(options = {}) {
+    chunkQueryParts(options = {}) {
         const conditions = [];
         const params = [];
         if (options.collectionName) {
@@ -194,17 +194,47 @@ export class IndexStateStore {
             params.push(options.relativePath);
         }
         const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        return { where, params };
+    }
+    listChunks(options = {}) {
+        const { where, params } = this.chunkQueryParts(options);
         const limit = options.limit ? 'LIMIT ?' : '';
-        if (options.limit)
-            params.push(options.limit);
+        const queryParams = options.limit ? [...params, options.limit] : params;
         const rows = this.db.prepare(`
       SELECT rowid, * FROM kb_chunks
       ${where}
       ORDER BY relative_path, chunk_index
       ${limit}
-    `).all(...params);
+    `).all(...queryParams);
         return rows.map(row => this.rowToChunk(row, 0));
     }
+    countChunks(options = {}) {
+        const { where, params } = this.chunkQueryParts(options);
+        const row = this.db.prepare(`SELECT COUNT(*) AS count FROM kb_chunks ${where}`).get(...params);
+        return Number(row?.count || 0);
+    }
+    listChunksByContentBudget(options = {}) {
+        const maxContentChars = Number(options.maxContentChars);
+        if (!Number.isFinite(maxContentChars) || maxContentChars <= 0)
+            return this.listChunks(options);
+        const { where, params } = this.chunkQueryParts(options);
+        const rows = this.db.prepare(`
+      SELECT rowid, * FROM kb_chunks
+      ${where}
+      ORDER BY relative_path, chunk_index
+    `).iterate(...params);
+        const chunks = [];
+        let usedChars = 0;
+        for (const row of rows) {
+            const chunk = this.rowToChunk(row, 0);
+            const length = chunk.content?.length || 0;
+            if (chunks.length > 0 && usedChars + length > maxContentChars)
+                break;
+            chunks.push(chunk);
+            usedChars += length;
+        }
+        return chunks;
+    }
     getChunkByRowid(rowid) {
         const row = this.db.prepare('SELECT rowid, * FROM kb_chunks WHERE rowid = ?').get(rowid);
         return row ? this.rowToChunk(row, 0) : undefined;
@@ -264,20 +294,28 @@ export class IndexStateStore {
      * @param limit 返回结果数量上限
      * @returns 搜索结果列表（按相关性得分排序）
      */
-    searchChunks(query, limit = 10, filters = {}) {
+    searchChunks(query, limit, filters = {}) {
         const terms = this.expandSearchTerms(query);
         if (terms.length === 0)
             return [];
         const filePaths = [...new Set((filters.filePaths ?? []).filter(Boolean))];
+        const effectiveLimit = this.resolveChunkSearchLimit(limit, filePaths);
         const results = [
-            ...(this.ftsEnabled ? this.searchChunksFts(terms, limit, filePaths) : []),
-            ...this.searchChunksLike(terms, limit, filePaths),
+            ...(this.ftsEnabled ? this.searchChunksFts(terms, effectiveLimit, filePaths) : []),
+            ...this.searchChunksLike(terms, effectiveLimit, filePaths),
         ];
-        return this.mergeKeywordResults(results, limit);
+        return this.mergeKeywordResults(results, effectiveLimit);
     }
     filePathFilterClause(filePaths, column = 'relative_path') {
         return filePaths.length > 0 ? ` AND ${column} IN (${filePaths.map(() => '?').join(', ')})` : '';
     }
+    resolveChunkSearchLimit(limit, filePaths) {
+        if (Number.isFinite(limit) && limit > 0)
+            return Math.ceil(limit);
+        const row = this.db.prepare(`SELECT COUNT(*) as count FROM kb_chunks WHERE 1 = 1${this.filePathFilterClause(filePaths)}`)
+            .get(...filePaths);
+        return Math.max(1, Math.ceil(Number(row?.count) || 0));
+    }
     searchChunksFts(terms, limit, filePaths) {
         try {
             const matchQuery = this.toFtsQuery(terms);

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

@@ -66,6 +66,8 @@ export declare class KnowledgeBaseManager {
     }): Promise<DiffResult>;
     search(query: string, limit?: number, filters?: SearchFilters): ChunkSearchResult[];
     keywordSearchItems(query: string, limit?: number, filters?: SearchFilters): FederatedSearchItem[];
+    private resolveSearchLimit;
+    private searchCorpusSize;
     expandContext(item: FederatedSearchItem): FederatedSearchItem;
     hybridSearch(query: string, options?: {
         limit?: number;
@@ -81,11 +83,14 @@ export declare class KnowledgeBaseManager {
     }): Promise<FederatedResult>;
     listRelationships(filePath?: string): FileRelationship[];
     listFiles(): IndexStateRecord[];
-    getFileDetail(relativePath: string): {
+    getFileDetail(relativePath: string, options?: {
+        maxChunkContentChars?: number;
+    }): {
         file: IndexStateRecord;
         absolutePath: string;
         directory: string;
         chunks: import("./index-state-store.js").StoredChunk[];
+        totalChunkCount: number;
         parents: import("./index-state-store.js").StoredParentChunk[];
         relationships: FileRelationship[];
         tags: {
@@ -175,6 +180,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 {
@@ -298,11 +326,24 @@ export class KnowledgeBaseManager {
             this.onProgress = previousOnProgress;
         }
     }
-    search(query, limit = 10, filters) {
-        return this.store.searchChunks(query, limit, { filePaths: filters?.filePaths ?? (filters?.filePath ? [filters.filePath] : undefined) });
+    search(query, limit, filters) {
+        return this.store.searchChunks(query, this.resolveSearchLimit(limit, filters), { filePaths: filters?.filePaths ?? (filters?.filePath ? [filters.filePath] : undefined) });
+    }
+    keywordSearchItems(query, limit, filters) {
+        return this.store.searchChunks(query, this.resolveSearchLimit(limit, filters), { filePaths: filters?.filePaths ?? (filters?.filePath ? [filters.filePath] : undefined) }).map(result => this.toFederatedItem(result, 'keyword'));
+    }
+    resolveSearchLimit(limit, filters) {
+        if (Number.isFinite(limit) && limit > 0)
+            return Math.ceil(limit);
+        return this.searchCorpusSize(filters);
     }
-    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'));
+    searchCorpusSize(filters) {
+        const paths = filters?.filePaths ?? (filters?.filePath ? [filters.filePath] : undefined);
+        const pathSet = new Set(paths?.filter(Boolean));
+        const total = this.store.listRecords()
+            .filter(record => pathSet.size === 0 || pathSet.has(record.relativePath))
+            .reduce((sum, record) => sum + Math.max(0, Math.ceil(Number(record.chunkCount) || 0)), 0);
+        return Math.max(1, total);
     }
     expandContext(item) {
         const chunkIndex = item.chunkIndex ?? this.parseChunkIndex(item.id);
@@ -333,7 +374,9 @@ export class KnowledgeBaseManager {
         };
     }
     async hybridSearch(query, options = {}) {
-        const limit = options.limit ?? 10;
+        const requestedLimit = Number.isFinite(options.limit) && options.limit > 0 ? Math.ceil(options.limit) : undefined;
+        const corpusSize = this.searchCorpusSize(options.filters);
+        const effectiveLimit = requestedLimit ?? corpusSize;
         const start = Date.now();
         const weights = this.retrievalWeights(options.weights);
         const rewrittenQueries = options.generationMode ? [query.trim()].filter(Boolean) : await this.rewriteQueries(query);
@@ -342,10 +385,12 @@ 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, options.filters), queryIndex });
+            rankedLists.push({ source: 'keyword', items: this.keywordSearchItems(rewritten, effectiveLimit * 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 });
+                    const vectorLimit = effectiveLimit * vectorMultiplier;
+                    const keywordLimit = effectiveLimit * keywordMultiplier;
+                    rankedLists.push({ source: 'vector', items: (await this.semanticSearch(rewritten, { ...options, limit: vectorLimit })).results.slice(0, keywordLimit), queryIndex });
                 }
                 catch { /* 向量搜索在混合搜索中是可选的 */ }
             }
@@ -353,12 +398,14 @@ 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);
         // 1. 先进行初筛合并，合并相同的子块并计算混合初始分（不获取大片段，保留子块自身用于精确打分）
-        const mergedChildChunks = this.mergeContexts(this.mergeHybridRankedLists(rankedLists, limit * 4, weights), limit * 4);
+        const mergeLimit = effectiveLimit * 4;
+        const mergedChildChunks = this.mergeContexts(this.mergeHybridRankedLists(rankedLists, mergeLimit, weights), mergeLimit);
         // 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));
+            const rerankLimit = requestedLimit ? Math.min(30, mergeLimit) : mergedChildChunks.length;
+            const candidates = mergedChildChunks.slice(0, rerankLimit);
             // 这里使用的是子块自身内容，通常在 500 tokens 左右，不仅相关性判断最准，而且不会超出 Reranker 的 max_length
             const textsToRerank = candidates.map(item => `${item.titlePath ?? item.sectionTitle ?? ''}\n${item.content}`);
             try {
@@ -381,8 +428,8 @@ export class KnowledgeBaseManager {
                 reranked = this.heuristicRerank(query, mergedChildChunks);
             }
         }
-        // 3. 拿到精确打分后的 Top 结果，此时再进行 expandContext 向上追溯到完整的父块大片段
-        const finalExpandedResults = this.mergeExpandedContexts(reranked.map(item => this.expandContext(item)), limit);
+        // 3. 拿到精确打分后的结果，此时再进行 expandContext 向上追溯到完整的父块大片段
+        const finalExpandedResults = this.mergeExpandedContexts(reranked.map(item => this.expandContext(item)), effectiveLimit);
         return {
             results: finalExpandedResults,
             scopesSearched: this.scope === 'global' ? ['global'] : ['project'],
@@ -405,7 +452,7 @@ export class KnowledgeBaseManager {
             const result = await search.search({
                 query,
                 queryEmbedding,
-                topK: options.limit ?? 10,
+                topK: this.resolveSearchLimit(options.limit, options.filters),
                 scope: this.scope,
                 projectId: this.projectId,
                 collections: options.collections,
@@ -423,17 +470,21 @@ export class KnowledgeBaseManager {
     listFiles() {
         return this.store.listRecords();
     }
-    getFileDetail(relativePath) {
+    getFileDetail(relativePath, options = {}) {
         const normalized = this.normalizeRelativePath(relativePath);
         const file = this.store.listRecords().find(record => record.relativePath === normalized);
         if (!file)
             return undefined;
         const absolutePath = this.resolveKbRelativePath(normalized);
+        const chunks = options.maxChunkContentChars
+            ? this.store.listChunksByContentBudget({ relativePath: normalized, maxContentChars: options.maxChunkContentChars })
+            : this.store.listChunks({ relativePath: normalized });
         return {
             file,
             absolutePath,
             directory: path.dirname(absolutePath),
-            chunks: this.store.listChunks({ relativePath: normalized, limit: 500 }),
+            chunks,
+            totalChunkCount: this.store.countChunks({ relativePath: normalized }),
             parents: this.store.listParentChunks(normalized),
             relationships: this.store.listRelationships(normalized),
             tags: this.store.listTags(normalized),
@@ -474,10 +525,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 +539,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 +586,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 +603,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 +960,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 +995,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 +1003,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/core/multi-project-manager.js

@@ -59,7 +59,7 @@ export class MultiProjectManager {
         return this.registry.list();
     }
     async search(projectRoot, query, options = {}) {
-        const limit = options.limit ?? 10;
+        const limit = Number.isFinite(options.limit) && options.limit > 0 ? Math.ceil(options.limit) : undefined;
         const scope = options.scope ?? 'project';
         const project = await this.getProject(projectRoot);
         if (scope === 'project')
@@ -73,7 +73,8 @@ export class MultiProjectManager {
         }
         const global = await this.getGlobalKB();
         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');
+        const mergeLimit = limit ?? (projectResults.results.length + globalResults.results.length);
+        const merged = new FederationSearch().merge([...projectResults.results, ...globalResults.results], mergeLimit, 'all');
         return {
             ...merged,
             debug: this.mergeDebug(projectResults.debug, globalResults.debug),
@@ -94,7 +95,8 @@ export class MultiProjectManager {
         }
         const global = await this.getGlobalKB();
         const globalResults = await global.semanticSearch(query, options);
-        return new FederationSearch().merge([...projectResults.results, ...globalResults.results], options.limit ?? 10, 'all');
+        const mergeLimit = Number.isFinite(options.limit) && options.limit > 0 ? Math.ceil(options.limit) : projectResults.results.length + globalResults.results.length;
+        return new FederationSearch().merge([...projectResults.results, ...globalResults.results], mergeLimit, 'all');
     }
     async findCrossProjectDuplicates() {
         const projects = this.registry.list();

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.32",
+  "version": "4.0.34",
   "description": "Local knowledge base infrastructure for customize-agent",
   "type": "module",
   "main": "./dist/index.js",