@customize-agent/knowledge 4.0.9 → 4.0.11

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

@@ -37,6 +37,7 @@ export declare class TextChunker {
     private collectBraceBalancedBlocks;
     private splitCodeByStructuralFallback;
     private splitIntoSections;
+    private mergeSmallSections;
     private mergeLeadingHeader;
     private recursiveSplit;
     private mergeParts;
@@ -46,6 +47,7 @@ export declare class TextChunker {
     private extractMarkdownTableRowRange;
     private splitMarkdownTable;
     private enforceCandidateLimit;
+    private buildTitlePaths;
     private withHeader;
     private createChunk;
     private kindForCategory;

package/dist/chunking/text-chunker.js

@@ -15,8 +15,8 @@ const RECURSIVE_SEPARATORS = [
     /\n(?=#{1,6}\s)/u,
     /\n{2,}/u,
     /\n(?=(?:第[一二三四五六七八九十百千万\d]+[章节条]|[一二三四五六七八九十]+、|\d+[.)、]))/u,
-    /(?<=[。！？；])\s*/u,
-    /(?<=[，、])\s*/u,
+    /(?<=[。！？；])\s+/u,
+    /(?<=[，、])\s+/u,
     /\s+/u,
 ];
 const LANGUAGE_ROUTER = {
@@ -45,7 +45,8 @@ export class TextChunker {
             return [];
         const config = DEFAULT_CONFIGS[file.category];
         const normalized = this.withHeader(source, file, config);
-        const candidates = this.enforceCandidateLimit(this.createCandidates(normalized, file, config), config);
+        const rawCandidates = this.createCandidates(normalized, file, config);
+        const candidates = this.enforceCandidateLimit(rawCandidates, config);
         return candidates.map((candidate, index) => this.createChunk(index, candidate, file, metadata));
     }
     createCandidates(text, file, config) {
@@ -58,8 +59,9 @@ export class TextChunker {
         return this.createTextCandidates(text, file.category, config);
     }
     createTextCandidates(text, category, config) {
-        const sections = this.splitIntoSections(text, category);
+        const sections = this.mergeSmallSections(this.splitIntoSections(text, category), config);
         const candidates = [];
+        const titlePaths = this.buildTitlePaths(sections);
         sections.forEach((section, parentIndex) => {
             const parentId = `p${parentIndex}`;
             const parts = this.mergeLeadingHeader(this.recursiveSplit(section.text, config.maxChunkSize));
@@ -72,6 +74,7 @@ export class TextChunker {
                     startChar,
                     endChar: startChar + part.length,
                     sectionTitle: section.title,
+                    titlePath: titlePaths[parentIndex],
                     kind: this.kindForCategory(category),
                     parentId,
                     parentIndex,
@@ -90,6 +93,7 @@ export class TextChunker {
                     startChar,
                     endChar: startChar + part.length,
                     sectionTitle: this.extractSectionTitle(part) ?? '表格数据',
+                    titlePath: this.extractSectionTitle(part) ?? '表格数据',
                     kind: 'table',
                     parentId: `table-${index}`,
                     parentIndex: index,
@@ -108,6 +112,7 @@ export class TextChunker {
             startChar: Math.max(0, text.indexOf(part.slice(0, 40))),
             endChar: Math.max(0, text.indexOf(part.slice(0, 40))) + part.length,
             sectionTitle: this.extractSectionTitle(part),
+            titlePath: this.extractSectionTitle(part),
             kind: 'data',
             parentId: `data-${index}`,
             parentIndex: index,
@@ -128,6 +133,7 @@ export class TextChunker {
                 startChar,
                 endChar: startChar + part.length,
                 sectionTitle: this.extractSectionTitle(part),
+                titlePath: this.extractSectionTitle(part),
                 kind: 'code',
                 parentId: `code-${language}-${index}`,
                 parentIndex: index,
@@ -210,6 +216,29 @@ export class TextChunker {
             return { text: section, startChar, title: this.extractSectionTitle(section) };
         });
     }
+    mergeSmallSections(sections, config) {
+        const merged = [];
+        let current;
+        const targetTokens = Math.max(80, Math.floor(config.maxChunkSize * 0.75));
+        for (const section of sections) {
+            if (!current) {
+                current = { ...section };
+                continue;
+            }
+            const candidateText = `${current.text}\n\n${section.text}`;
+            const currentTokens = this.estimateTokens(current.text);
+            if (currentTokens < targetTokens && this.estimateTokens(candidateText) <= config.maxChunkSize) {
+                current = { ...current, text: candidateText, title: current.title ?? section.title };
+            }
+            else {
+                merged.push(current);
+                current = { ...section };
+            }
+        }
+        if (current)
+            merged.push(current);
+        return merged;
+    }
     mergeLeadingHeader(sections) {
         if (sections.length < 2)
             return sections;
@@ -232,7 +261,7 @@ export class TextChunker {
         if (!separator)
             return this.splitBySentenceBoundary(text, maxTokens);
         const parts = text.split(separator).map(part => part.trim()).filter(Boolean);
-        if (parts.length <= 1)
+        if (parts.length <= 1 || parts.some(part => part === text))
             return this.recursiveSplit(text, maxTokens, separatorIndex + 1);
         return parts.flatMap(part => this.recursiveSplit(part, maxTokens, separatorIndex + 1));
     }
@@ -321,6 +350,24 @@ export class TextChunker {
             }));
         });
     }
+    buildTitlePaths(sections) {
+        const stack = [];
+        return sections.map(section => {
+            const firstLine = section.text.trim().split(/\r?\n/u)[0] ?? '';
+            const heading = firstLine.match(/^(#{1,6})\s+(.+)$/u);
+            if (heading?.[1] && heading[2]) {
+                const level = heading[1].length;
+                const title = heading[2].trim();
+                while (stack.length > 0 && stack[stack.length - 1].level >= level)
+                    stack.pop();
+                stack.push({ level, title });
+            }
+            else if (section.title && stack.length === 0) {
+                stack.push({ level: 1, title: section.title });
+            }
+            return stack.map(item => item.title).join(' > ') || section.title;
+        });
+    }
     withHeader(text, file, config) {
         if (!config.headerInjection)
             return text;
@@ -344,9 +391,10 @@ export class TextChunker {
                 childIndex: candidate.childIndex,
                 rowRange: candidate.rowRange,
                 sectionTitle: candidate.sectionTitle ?? this.extractSectionTitle(text),
+                titlePath: candidate.titlePath ?? candidate.sectionTitle ?? this.extractSectionTitle(text),
                 startChar: candidate.startChar,
                 endChar: candidate.endChar,
-                splitStrategy: 'recursive_parent_child_v1',
+                splitStrategy: 'recursive_parent_child_v2',
             },
         };
     }

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

@@ -17,11 +17,18 @@ export interface StoredChunk {
     relativePath: string;
     chunkIndex: number;
     content: string;
+    searchContent?: string;
     category: FileCategory;
     format: string;
     collectionName: string;
     tokenCount: number;
     sectionTitle?: string;
+    titlePath?: string;
+    parentId?: string;
+    chunkKind?: string;
+    rowRange?: string;
+    startChar?: number;
+    endChar?: number;
     metadataJson?: string;
     createdAt: number;
 }
@@ -183,6 +190,7 @@ export declare class IndexStateStore {
         relativePath: string;
     }>;
     close(): void;
+    private resetLegacyChunkSchemaIfNeeded;
     private initTables;
     private initFts;
     private rebuildFtsIfNeeded;
@@ -194,6 +202,8 @@ export declare class IndexStateStore {
     private splitParentGroups;
     private rowToJob;
     private metadataString;
+    private buildChunkSearchContent;
+    private searchableRowText;
     private rowToChunk;
     private expandSearchTerms;
     private toFtsQuery;

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

@@ -128,13 +128,14 @@ export class IndexStateStore {
                 this.db.prepare('DELETE FROM kb_chunks_fts WHERE relative_path = ?').run(relativePath);
             const insert = this.db.prepare(`
         INSERT INTO kb_chunks (
-          id, relative_path, chunk_index, content, category, format,
-          collection_name, token_count, section_title, metadata_json, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          id, relative_path, chunk_index, content, search_content, category, format,
+          collection_name, token_count, section_title, title_path, parent_id, chunk_kind,
+          row_range, start_char, end_char, metadata_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `);
             const insertFts = this.ftsEnabled ? this.db.prepare(`
-        INSERT INTO kb_chunks_fts (id, relative_path, category, format, section_title, content)
-        VALUES (?, ?, ?, ?, ?, ?)
+        INSERT INTO kb_chunks_fts (id, relative_path, category, format, section_title, title_path, chunk_kind, content)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
       `) : undefined;
             const insertParent = this.db.prepare(`
         INSERT INTO kb_parent_chunks (
@@ -160,13 +161,18 @@ export class IndexStateStore {
             for (const [parentId, group] of parentGroups.entries()) {
                 const parentContent = group.map(chunk => chunk.text).join('\n\n---\n\n');
                 parentContents.push(parentContent);
-                insertParent.run(parentId, relativePath, parentId, parentContent, file.category, file.format, file.collectionName, group.find(chunk => chunk.sectionTitle)?.sectionTitle ?? null, group.length, JSON.stringify({ parentId, splitStrategy: this.metadataString(group[0]?.metadata.splitStrategy), chunkKind: this.metadataString(group[0]?.metadata.chunkKind) }), now);
+                insertParent.run(parentId, relativePath, parentId, parentContent, file.category, file.format, file.collectionName, group.find(chunk => chunk.sectionTitle)?.sectionTitle ?? null, group.length, JSON.stringify({ parentId, splitStrategy: this.metadataString(group[0]?.metadata.splitStrategy), chunkKind: this.metadataString(group[0]?.metadata.chunkKind), titlePath: this.metadataString(group[0]?.metadata.titlePath) }), now);
             }
             insertDocument.run(`${relativePath}#document`, relativePath, parentContents.join('\n\n=== SECTION ===\n\n'), file.category, file.format, file.collectionName, parentGroups.size, groupedChunks.length, JSON.stringify({ parentType: 'document', splitStrategy: 'document_section_child_v1' }), now);
             for (const chunk of groupedChunks) {
                 const chunkId = `${relativePath}#${chunk.index}`;
-                insert.run(chunkId, relativePath, chunk.index, chunk.text, file.category, file.format, file.collectionName, chunk.tokenCount, chunk.sectionTitle ?? null, JSON.stringify(chunk.metadata), now);
-                insertFts?.run(chunkId, relativePath, file.category, file.format, chunk.sectionTitle ?? '', chunk.text);
+                const titlePath = this.metadataString(chunk.metadata.titlePath) ?? chunk.sectionTitle ?? '';
+                const parentId = this.metadataString(chunk.metadata.parentId) ?? null;
+                const chunkKind = this.metadataString(chunk.metadata.chunkKind) ?? null;
+                const rowRange = this.metadataString(chunk.metadata.rowRange) ?? null;
+                const searchContent = this.buildChunkSearchContent(relativePath, file, chunk, titlePath);
+                insert.run(chunkId, relativePath, chunk.index, chunk.text, searchContent, file.category, file.format, file.collectionName, chunk.tokenCount, chunk.sectionTitle ?? null, titlePath || null, parentId, chunkKind, rowRange, Number(chunk.metadata.startChar ?? chunk.startChar), Number(chunk.metadata.endChar ?? chunk.endChar), JSON.stringify(chunk.metadata), now);
+                insertFts?.run(chunkId, relativePath, file.category, file.format, chunk.sectionTitle ?? '', titlePath, chunkKind ?? '', searchContent);
             }
         });
         transaction();
@@ -278,7 +284,7 @@ export class IndexStateStore {
       `).all(matchQuery, limit * 8);
             return rows
                 .map(row => {
-                const keyword = this.scoreChunkDetailed(`${String(row.section_title ?? '')}\n${String(row.category)}\n${String(row.format)}\n${String(row.content)}`, terms);
+                const keyword = this.scoreChunkDetailed(this.searchableRowText(row), terms);
                 const bm25Score = this.bm25ToPositiveScore(Number(row.bm25_score));
                 return this.rowToChunk(row, keyword.keywordScore + bm25Score, { ...keyword, bm25Score });
             })
@@ -293,13 +299,13 @@ export class IndexStateStore {
     searchChunksLike(terms, limit) {
         const rows = this.db.prepare(`
       SELECT rowid, * FROM kb_chunks
-      WHERE ${terms.map(() => '(LOWER(content) LIKE ? OR LOWER(relative_path) LIKE ? OR LOWER(category) LIKE ? OR LOWER(format) 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 ')}
       ORDER BY created_at DESC
       LIMIT ?
-    `).all(...terms.flatMap(term => [`%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`]), limit * 6);
+    `).all(...terms.flatMap(term => [`%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`, `%${term}%`]), limit * 6);
         return rows
             .map(row => {
-            const keyword = this.scoreChunkDetailed(`${String(row.section_title ?? '')}\n${String(row.category)}\n${String(row.format)}\n${String(row.content)}`, terms);
+            const keyword = this.scoreChunkDetailed(this.searchableRowText(row), terms);
             return this.rowToChunk(row, keyword.keywordScore, keyword);
         })
             .filter(row => row.score > 0)
@@ -479,7 +485,23 @@ export class IndexStateStore {
     close() {
         this.db.close();
     }
+    resetLegacyChunkSchemaIfNeeded() {
+        const table = this.db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'kb_chunks'").get();
+        if (!table)
+            return;
+        const columns = this.db.prepare('PRAGMA table_info(kb_chunks)').all();
+        const names = new Set(columns.map(column => column.name));
+        if (names.has('search_content') && names.has('title_path') && names.has('chunk_kind'))
+            return;
+        this.db.exec(`
+      DROP TABLE IF EXISTS kb_chunks_fts;
+      DROP TABLE IF EXISTS kb_chunks;
+      DROP TABLE IF EXISTS kb_parent_chunks;
+      DROP TABLE IF EXISTS kb_document_chunks;
+    `);
+    }
     initTables() {
+        this.resetLegacyChunkSchemaIfNeeded();
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS kb_index_state (
         relative_path     TEXT PRIMARY KEY,
@@ -506,17 +528,27 @@ export class IndexStateStore {
         relative_path   TEXT NOT NULL,
         chunk_index     INTEGER NOT NULL,
         content         TEXT NOT NULL,
+        search_content  TEXT NOT NULL,
         category        TEXT NOT NULL,
         format          TEXT NOT NULL,
         collection_name TEXT NOT NULL,
         token_count     INTEGER NOT NULL,
         section_title   TEXT,
+        title_path      TEXT,
+        parent_id       TEXT,
+        chunk_kind      TEXT,
+        row_range       TEXT,
+        start_char      INTEGER,
+        end_char        INTEGER,
         metadata_json   TEXT,
         created_at      INTEGER NOT NULL
       );
       CREATE INDEX IF NOT EXISTS idx_kb_chunks_path ON kb_chunks(relative_path);
       CREATE INDEX IF NOT EXISTS idx_kb_chunks_category ON kb_chunks(category);
       CREATE INDEX IF NOT EXISTS idx_kb_chunks_collection ON kb_chunks(collection_name);
+      CREATE INDEX IF NOT EXISTS idx_kb_chunks_parent ON kb_chunks(relative_path, parent_id);
+      CREATE INDEX IF NOT EXISTS idx_kb_chunks_kind ON kb_chunks(chunk_kind);
+      CREATE INDEX IF NOT EXISTS idx_kb_chunks_title_path ON kb_chunks(title_path);
 
       CREATE TABLE IF NOT EXISTS kb_parent_chunks (
         id              TEXT PRIMARY KEY,
@@ -626,8 +658,8 @@ export class IndexStateStore {
     `);
         this.initFts();
         try {
-            if (this.getMetadata('schema_version') !== '2')
-                this.setMetadata('schema_version', '2');
+            if (this.getMetadata('schema_version') !== '3')
+                this.setMetadata('schema_version', '3');
         }
         catch {
             // 受限环境中已有索引库可能以只读方式挂载；运行时元数据不是必需项。
@@ -642,6 +674,8 @@ export class IndexStateStore {
           category,
           format,
           section_title,
+          title_path,
+          chunk_kind,
           content,
           tokenize = 'unicode61 remove_diacritics 2'
         );
@@ -660,8 +694,8 @@ export class IndexStateStore {
         if (Number(row.count ?? 0) > 0)
             return;
         this.db.prepare(`
-      INSERT INTO kb_chunks_fts (id, relative_path, category, format, section_title, content)
-      SELECT id, relative_path, category, format, COALESCE(section_title, ''), content FROM kb_chunks
+      INSERT INTO kb_chunks_fts (id, relative_path, category, format, section_title, title_path, chunk_kind, content)
+      SELECT id, relative_path, category, format, COALESCE(section_title, ''), COALESCE(title_path, ''), COALESCE(chunk_kind, ''), COALESCE(search_content, content) FROM kb_chunks
     `).run();
     }
     rowToMinHash(row) {
@@ -747,6 +781,32 @@ export class IndexStateStore {
     metadataString(value) {
         return typeof value === 'string' ? value : undefined;
     }
+    buildChunkSearchContent(relativePath, file, chunk, titlePath) {
+        const metadata = chunk.metadata;
+        const fields = [
+            `文件路径: ${relativePath}`,
+            `资料类型: ${file.category}/${file.format}`,
+            chunk.sectionTitle ? `章节标题: ${chunk.sectionTitle}` : '',
+            titlePath ? `标题路径: ${titlePath}` : '',
+            this.metadataString(metadata.chunkKind) ? `切片类型: ${this.metadataString(metadata.chunkKind)}` : '',
+            this.metadataString(metadata.rowRange) ? `表格行范围: ${this.metadataString(metadata.rowRange)}` : '',
+            chunk.text,
+        ];
+        return fields.filter(Boolean).join('\n');
+    }
+    searchableRowText(row) {
+        return [
+            row.relative_path,
+            row.category,
+            row.format,
+            row.section_title,
+            row.title_path,
+            row.chunk_kind,
+            row.row_range,
+            row.search_content,
+            row.content,
+        ].map(value => value == null ? '' : String(value)).join('\n');
+    }
     rowToChunk(row, score, scoreDetails) {
         return {
             rowid: Number(row.rowid ?? 0),
@@ -754,11 +814,18 @@ export class IndexStateStore {
             relativePath: String(row.relative_path),
             chunkIndex: Number(row.chunk_index),
             content: String(row.content),
+            searchContent: row.search_content == null ? undefined : String(row.search_content),
             category: String(row.category),
             format: String(row.format),
             collectionName: String(row.collection_name),
             tokenCount: Number(row.token_count),
             sectionTitle: row.section_title == null ? undefined : String(row.section_title),
+            titlePath: row.title_path == null ? undefined : String(row.title_path),
+            parentId: row.parent_id == null ? undefined : String(row.parent_id),
+            chunkKind: row.chunk_kind == null ? undefined : String(row.chunk_kind),
+            rowRange: row.row_range == null ? undefined : String(row.row_range),
+            startChar: row.start_char == null ? undefined : Number(row.start_char),
+            endChar: row.end_char == null ? undefined : Number(row.end_char),
             metadataJson: row.metadata_json == null ? undefined : String(row.metadata_json),
             createdAt: Number(row.created_at),
             score,

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

@@ -315,6 +315,7 @@ export class KnowledgeBaseManager {
                 chunkIndex,
                 parentId: parent.parentId,
                 sectionTitle: parent.sectionTitle ?? item.sectionTitle,
+                titlePath: item.titlePath ?? this.parseMetadataString(parent.metadataJson, 'titlePath'),
             };
         }
         const parentChunks = item.parentId ? this.store.getChunksByParent(item.filePath, item.parentId, 6) : [];
@@ -328,6 +329,7 @@ export class KnowledgeBaseManager {
             content: chunks.map(chunk => chunk.content).join('\n\n---\n\n'),
             chunkIndex,
             parentId: item.parentId ?? this.parseMetadataString(chunks[0]?.metadataJson, 'parentId'),
+            titlePath: item.titlePath ?? chunks.map(chunk => this.parseMetadataString(chunk.metadataJson, 'titlePath')).find(Boolean),
             sectionTitle: item.sectionTitle ?? chunks.find(chunk => chunk.sectionTitle)?.sectionTitle,
         };
     }
@@ -341,7 +343,7 @@ export class KnowledgeBaseManager {
             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 });
+                    rankedLists.push({ source: 'vector', items: (await this.semanticSearch(rewritten, { ...options, limit: limit * 6 })).results.slice(0, limit * 3), queryIndex });
                 }
                 catch { /* 向量搜索在混合搜索中是可选的 */ }
             }
@@ -664,15 +666,21 @@ export class KnowledgeBaseManager {
         const terms = query.toLowerCase().split(/[\s,，。；;：:、]+/u).filter(Boolean);
         const phrase = query.toLowerCase().trim();
         return items.map(item => {
-            const content = `${item.filePath}\n${item.sectionTitle ?? ''}\n${item.content}`.toLowerCase();
+            const content = `${item.filePath}\n${item.titlePath ?? ''}\n${item.sectionTitle ?? ''}\n${item.chunkKind ?? ''}\n${item.content}`.toLowerCase();
             let rerankBoost = 0;
             if (phrase && content.includes(phrase))
                 rerankBoost += 120;
-            for (const term of terms)
-                if (term && content.includes(term))
+            const titleText = `${item.titlePath ?? ''}\n${item.sectionTitle ?? ''}`.toLowerCase();
+            for (const term of terms) {
+                if (!term)
+                    continue;
+                if (content.includes(term))
                     rerankBoost += 8;
-            if (item.chunkKind === 'table' && /表|行|列|金额|数量|报价|评分/u.test(query))
-                rerankBoost += 30;
+                if (titleText.includes(term))
+                    rerankBoost += 18;
+            }
+            if (item.chunkKind === 'table' && /表|行|列|金额|数量|报价|评分|清单|明细|统计|数据/u.test(query))
+                rerankBoost += 40;
             if (item.chunkKind === 'metadata' && /图纸|图层|轴网|标注|块|实体|cad|dxf|step|iges|模型/u.test(query))
                 rerankBoost += 60;
             if (item.chunkKind === 'data' && /json|xml|yaml|字段|配置|数据|路径|price|id|name/u.test(query))
@@ -695,7 +703,7 @@ export class KnowledgeBaseManager {
         const candidates = items.slice(0, 20);
         const resultsText = candidates.map((item, index) => {
             const contentPreview = item.content.slice(0, 300).replace(/[\n\r]+/g, ' ');
-            return `[DOC_${index}] 路径: ${item.filePath} | 类型: ${item.chunkKind ?? 'text'}\n  内容: ${contentPreview}`;
+            return `[DOC_${index}] 路径: ${item.filePath} | 标题路径: ${item.titlePath ?? item.sectionTitle ?? ''} | 类型: ${item.chunkKind ?? 'text'}\n  内容: ${contentPreview}`;
         }).join('\n\n');
         const prompt = `你是一个文档相关性评估器。根据用户查询，为以下文档片段打分（1-10）。
 1=完全不相关，10=高度相关。
@@ -767,8 +775,11 @@ ${resultsText}
             parentId: this.metadataString(metadata.parentId),
             source,
             sectionTitle: result.sectionTitle,
-            rowRange: this.metadataString(metadata.rowRange),
-            chunkKind: this.metadataString(metadata.chunkKind),
+            titlePath: result.titlePath ?? this.metadataString(metadata.titlePath),
+            rowRange: result.rowRange ?? this.metadataString(metadata.rowRange),
+            chunkKind: result.chunkKind ?? this.metadataString(metadata.chunkKind),
+            startChar: result.startChar,
+            endChar: result.endChar,
             scoreDetails: result.scoreDetails,
             facets: this.metadataFacets(metadata),
         };
@@ -800,8 +811,11 @@ ${resultsText}
                 if (item.score > (existing.scoreDetails?.keywordScore ?? existing.scoreDetails?.vectorScore ?? 0)) {
                     existing.content = item.content;
                     existing.sectionTitle = item.sectionTitle ?? existing.sectionTitle;
+                    existing.titlePath = item.titlePath ?? existing.titlePath;
                     existing.chunkIndex = item.chunkIndex ?? existing.chunkIndex;
                     existing.parentId = item.parentId ?? existing.parentId;
+                    existing.chunkKind = item.chunkKind ?? existing.chunkKind;
+                    existing.rowRange = item.rowRange ?? existing.rowRange;
                 }
             });
         }
@@ -858,7 +872,7 @@ ${resultsText}
         return typeof value === 'string' ? value : undefined;
     }
     metadataFacets(metadata) {
-        const keys = ['sheetNames', 'columnNames', 'rowCount', 'columnCount', 'dataPaths', 'layerNames', 'blockNames', 'entityTypes', 'productNames', 'materialNames', 'ocrRecommended', 'ocrReason'];
+        const keys = ['titlePath', 'sectionTitle', 'chunkKind', 'rowRange', 'sheetNames', 'columnNames', 'rowCount', 'columnCount', 'dataPaths', 'layerNames', 'blockNames', 'entityTypes', 'productNames', 'materialNames', 'ocrRecommended', 'ocrReason'];
         const facets = {};
         for (const key of keys) {
             const value = metadata[key];

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

@@ -58,10 +58,13 @@ export declare class ContentExtractor {
     private formatBoundingBox;
     private validateRasterImage;
     private extractPdf;
+    private shouldAugmentPdfWithOcr;
     private extractScannedPdfOcr;
     private extractPdfText;
+    private normalizedTextLength;
     private toPdfTextItem;
     private layoutPdfTextItems;
+    private joinPdfRowText;
     private groupPdfItemsIntoRows;
     private detectPdfColumnSplit;
     private rowsToPdfMarkdownWithTables;

package/dist/extraction/content-extractor.js

@@ -1063,7 +1063,16 @@ try {
             if (text.trim()) {
                 metadata.contentCoverage = 'pdf_text_streams_layout_markdown';
                 metadata.pdfExtractor = 'pdfjs-dist';
-                return { text: [this.metadataOnlyText(file), this.toMarkdownDocument(text)].join('\n\n'), metadata, warnings };
+                const markdownText = this.toMarkdownDocument(text);
+                if (!this.shouldAugmentPdfWithOcr(markdownText))
+                    return { text: [this.metadataOnlyText(file), markdownText].join('\n\n'), metadata, warnings };
+                const ocr = await this.extractScannedPdfOcr(file);
+                if (ocr.text.trim()) {
+                    metadata.contentCoverage = 'pdf_text_streams_plus_ocr';
+                    metadata.ocrAugmented = true;
+                    return { text: [this.metadataOnlyText(file), markdownText, '## PDF OCR 备用识别文本', ocr.text].join('\n\n'), metadata: { ...metadata, ocr: ocr.metadata }, warnings: [...warnings, ...ocr.warnings] };
+                }
+                return { text: [this.metadataOnlyText(file), markdownText].join('\n\n'), metadata: { ...metadata, ocrRecommended: true, ocrReason: ocr.metadata.ocrReason ?? 'pdf_text_low_quality' }, warnings: [...warnings, ...ocr.warnings] };
             }
         }
         catch (error) {
@@ -1086,6 +1095,17 @@ try {
             warnings: [...warnings, 'PDF 正文暂未提取到文本，已索引文件名、路径和类型元数据', ...ocr.warnings],
         };
     }
+    shouldAugmentPdfWithOcr(text) {
+        const normalizedLength = this.normalizedTextLength(text);
+        if (normalizedLength < 1200)
+            return true;
+        const lines = text.split(/\r?\n/u).map(line => line.trim()).filter(Boolean);
+        if (lines.length === 0)
+            return true;
+        const shortLineRatio = lines.filter(line => line.length <= 12).length / lines.length;
+        const cjkCount = (text.match(/[\p{Script=Han}]/gu) ?? []).length;
+        return shortLineRatio > 0.65 && cjkCount < 1200;
+    }
     async extractScannedPdfOcr(file) {
         const metadata = {
             extractionMode: 'pdf_page_ocr_embedded',
@@ -1173,6 +1193,7 @@ process.stdout.write(JSON.stringify({ pageCount: doc.numPages, pageLimit, text:
         }
     }
     async extractPdfText(buffer) {
+        let pdfjsText = '';
         // 第一层：pdfjs-dist 文本提取（处理压缩内容流、CJK 字体、现代 PDF）
         try {
             const mod = await resolveAndImport('pdfjs-dist/legacy/build/pdf.mjs');
@@ -1182,7 +1203,7 @@ process.stdout.write(JSON.stringify({ pageCount: doc.numPages, pageLimit, text:
             const pageLimit = doc.numPages;
             for (let i = 1; i <= pageLimit; i++) {
                 const page = await doc.getPage(i);
-                const content = await page.getTextContent();
+                const content = await page.getTextContent({ normalizeWhitespace: false, disableCombineTextItems: true });
                 const items = content.items
                     .map((item) => this.toPdfTextItem(item))
                     .filter((item) => !!item && item.str.trim().length > 0);
@@ -1191,29 +1212,32 @@ process.stdout.write(JSON.stringify({ pageCount: doc.numPages, pageLimit, text:
                     pages.push(pageText.trim());
             }
             await doc.destroy();
-            if (pages.length > 0) {
-                const combined = pages.join('\n\n');
-                if (combined.trim())
-                    return combined;
-            }
+            pdfjsText = pages.join('\n\n').trim();
         }
         catch (e) {
             if (process.env.KB_DEBUG === '1')
                 console.warn('[kb] pdfjs-dist extraction failed:', e.message);
         }
-        // 第二层：pdf-parse（兼容旧版 PDF）
+        // 第二层：pdf-parse（兼容旧版 PDF），与 pdfjs 结果互补，避免单一解析器漏字
         try {
             const mod = await resolveAndImport('pdf-parse');
-            const pdfParse = mod.default;
+            const pdfParse = typeof mod === 'function'
+                ? mod
+                : mod.default;
             if (pdfParse) {
                 const result = await pdfParse(buffer);
-                if (result.text.trim())
-                    return result.text;
+                const parseText = result.text.trim();
+                if (pdfjsText && parseText && this.normalizedTextLength(parseText) > this.normalizedTextLength(pdfjsText) * 1.08)
+                    return [pdfjsText, '## PDF 备用解析文本', parseText].join('\n\n');
+                if (parseText && !pdfjsText)
+                    return parseText;
             }
         }
         catch {
-            // 降级到下方纯正则提取
+            // pdfjs 结果已可用时忽略备用解析器失败
         }
+        if (pdfjsText)
+            return pdfjsText;
         // 第三层：raw regex 回退（未压缩的古老 PDF）
         const raw = buffer.toString('latin1');
         const matches = Array.from(raw.matchAll(/\(([^()]{2,500})\)\s*T[jJ]/gu), match => match[1] ?? '')
@@ -1229,6 +1253,9 @@ process.stdout.write(JSON.stringify({ pageCount: doc.numPages, pageLimit, text:
             .join('')
             .trim();
     }
+    normalizedTextLength(value) {
+        return value.replace(/\s+/gu, '').length;
+    }
     toPdfTextItem(item) {
         if (!item || typeof item !== 'object' || !('str' in item))
             return undefined;
@@ -1257,6 +1284,25 @@ process.stdout.write(JSON.stringify({ pageCount: doc.numPages, pageLimit, text:
         const markdown = this.rowsToPdfMarkdownWithTables(orderedRows);
         return [`## PDF 第 ${pageNumber} 页`, markdown].join('\n\n');
     }
+    joinPdfRowText(items) {
+        let output = '';
+        let previous;
+        for (const item of items) {
+            const text = item.str.trim();
+            if (!text)
+                continue;
+            if (!previous) {
+                output += text;
+            }
+            else {
+                const gap = item.x - (previous.x + previous.width);
+                const cjkJoin = /[\p{Script=Han}（(《“‘]$/u.test(output) || /^[\p{Script=Han}）)》”’、，。；：！？]/u.test(text);
+                output += gap > Math.max(3, previous.height * 0.35) && !cjkJoin ? ` ${text}` : text;
+            }
+            previous = item;
+        }
+        return output.replace(/\s+/gu, ' ').trim();
+    }
     groupPdfItemsIntoRows(items) {
         const sorted = [...items].sort((a, b) => b.y - a.y || a.x - b.x);
         const rows = [];
@@ -1270,7 +1316,7 @@ process.stdout.write(JSON.stringify({ pageCount: doc.numPages, pageLimit, text:
         return rows.map(row => {
             const rowItems = row.items.sort((a, b) => a.x - b.x);
             return {
-                text: rowItems.map(item => item.str.trim()).filter(Boolean).join(' ').replace(/\s+/gu, ' '),
+                text: this.joinPdfRowText(rowItems),
                 x: Math.min(...rowItems.map(item => item.x)),
                 y: row.y,
                 height: Math.max(...rowItems.map(item => item.height || 0)),

package/dist/search/federation-search.d.ts

@@ -15,8 +15,11 @@ export interface FederatedSearchItem {
     parentId?: string;
     source?: 'keyword' | 'vector' | 'hybrid';
     sectionTitle?: string;
+    titlePath?: string;
     rowRange?: string;
     chunkKind?: string;
+    startChar?: number;
+    endChar?: number;
     scoreDetails?: {
         keywordScore?: number;
         bm25Score?: number;

package/dist/search/federation-search.js

@@ -85,8 +85,11 @@ export class FederationSearch {
             parentId: typeof result.document.metadata.parent_id === 'string' ? result.document.metadata.parent_id : undefined,
             source: 'vector',
             sectionTitle: typeof result.document.metadata.section_title === 'string' ? result.document.metadata.section_title : undefined,
+            titlePath: typeof result.document.metadata.title_path === 'string' ? result.document.metadata.title_path : undefined,
             rowRange: typeof result.document.metadata.row_range === 'string' ? result.document.metadata.row_range : undefined,
             chunkKind: typeof result.document.metadata.chunk_kind === 'string' ? result.document.metadata.chunk_kind : undefined,
+            startChar: typeof result.document.metadata.start_char === 'number' ? result.document.metadata.start_char : undefined,
+            endChar: typeof result.document.metadata.end_char === 'number' ? result.document.metadata.end_char : undefined,
             scoreDetails: { vectorScore: result.score },
         };
     }

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

@@ -17,6 +17,7 @@ export declare class HNSWVectorStore implements VectorStoreInterface {
     flush(): Promise<void>;
     needsRebuild(): boolean;
     search(query: VectorSearchQuery): Promise<VectorSearchResult[]>;
+    private matchesWhere;
     private persist;
     private toStoredDocument;
     private loadDocuments;

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

@@ -81,17 +81,22 @@ export class HNSWVectorStore {
     }
     async search(query) {
         await this.ensureCollection();
-        const result = this.index.searchKnn(query.queryEmbedding, query.topK);
+        const hasFilter = !!query.where && Object.keys(query.where).length > 0;
+        const candidateK = hasFilter ? Math.min(this.documents.size, Math.max(query.topK * 10, query.topK + 50)) : query.topK;
+        const result = this.index.searchKnn(query.queryEmbedding, candidateK);
         return result.neighbors.flatMap((rowid, index) => {
             const document = this.documents.get(rowid);
-            if (!document)
-                return [];
-            if (typeof query.where?.file_path === 'string' && document.metadata.file_path !== query.where.file_path)
+            if (!document || !this.matchesWhere(document, query.where))
                 return [];
             const { embedding: _embedding, ...stored } = document;
             const distance = result.distances[index] ?? 0;
             return [{ collection: this.collectionName, document: stored, score: 1 / (1 + distance) }];
-        });
+        }).slice(0, query.topK);
+    }
+    matchesWhere(document, where) {
+        if (!where)
+            return true;
+        return Object.entries(where).every(([key, value]) => document.metadata[key] === value);
     }
     persist() {
         this.index.writeIndexSync(this.indexPath);

package/dist/vector/vector-indexer.d.ts

@@ -29,6 +29,7 @@ export declare class VectorIndexer {
     private embedDocuments;
     private isValidEmbeddings;
     private groupByCollection;
+    private embeddingText;
     private toVectorDocument;
     private parseMetadata;
     private metadataString;

package/dist/vector/vector-indexer.js

@@ -29,7 +29,7 @@ export class VectorIndexer {
             let processedChunks = 0;
             for (let offset = 0; offset < collectionChunks.length; offset += batchSize) {
                 const batchChunks = collectionChunks.slice(offset, offset + batchSize);
-                const texts = batchChunks.map(chunk => chunk.content);
+                const texts = batchChunks.map(chunk => this.embeddingText(chunk));
                 const embeddings = await this.embedDocuments(texts);
                 const documents = batchChunks.map((chunk, index) => this.toVectorDocument(chunk, embeddings[index] ?? []));
                 await store.upsert(documents, { persist: options.persistEachBatch === true });
@@ -72,6 +72,17 @@ export class VectorIndexer {
         }
         return grouped;
     }
+    embeddingText(chunk) {
+        return chunk.searchContent ?? [
+            `文件路径: ${chunk.relativePath}`,
+            `资料类型: ${chunk.category}/${chunk.format}`,
+            chunk.titlePath ? `标题路径: ${chunk.titlePath}` : '',
+            chunk.sectionTitle ? `章节标题: ${chunk.sectionTitle}` : '',
+            chunk.chunkKind ? `切片类型: ${chunk.chunkKind}` : '',
+            chunk.rowRange ? `表格行范围: ${chunk.rowRange}` : '',
+            chunk.content,
+        ].filter(Boolean).join('\n');
+    }
     toVectorDocument(chunk, embedding) {
         const chunkMetadata = this.parseMetadata(chunk.metadataJson);
         return {
@@ -86,11 +97,14 @@ export class VectorIndexer {
                 format: chunk.format,
                 token_count: chunk.tokenCount,
                 section_title: chunk.sectionTitle ?? null,
-                parent_id: this.metadataString(chunkMetadata.parentId),
+                title_path: chunk.titlePath ?? this.metadataString(chunkMetadata.titlePath),
+                parent_id: chunk.parentId ?? this.metadataString(chunkMetadata.parentId),
                 parent_index: this.metadataNumber(chunkMetadata.parentIndex),
                 child_index: this.metadataNumber(chunkMetadata.childIndex),
-                chunk_kind: this.metadataString(chunkMetadata.chunkKind),
-                row_range: this.metadataString(chunkMetadata.rowRange),
+                chunk_kind: chunk.chunkKind ?? this.metadataString(chunkMetadata.chunkKind),
+                row_range: chunk.rowRange ?? this.metadataString(chunkMetadata.rowRange),
+                start_char: chunk.startChar ?? this.metadataNumber(chunkMetadata.startChar),
+                end_char: chunk.endChar ?? this.metadataNumber(chunkMetadata.endChar),
                 split_strategy: this.metadataString(chunkMetadata.splitStrategy),
             },
         };

package/package.json

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