@customize-agent/knowledge 4.0.1 → 4.0.3

package/dist/chunking/bge-tokenizer.d.ts

@@ -0,0 +1,12 @@
+/** BGE Tokenizer，使用 tokenizer.json 执行 BGE 模型的真实 Token 化 */
+export declare class BgeTokenizer {
+    private readonly vocab;
+    private readonly unkToken;
+    constructor(tokenizerPath?: string | undefined);
+    /** 统计文本的 Token 数量 */
+    countTokens(text: string): number;
+    encode(text: string): string[];
+    private preTokenize;
+    private wordPiece;
+    private static resolveTokenizerPath;
+}

package/dist/chunking/bge-tokenizer.js

@@ -0,0 +1,70 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** BGE Tokenizer，使用 tokenizer.json 执行 BGE 模型的真实 Token 化 */
+export class BgeTokenizer {
+    vocab;
+    unkToken;
+    constructor(tokenizerPath = BgeTokenizer.resolveTokenizerPath()) {
+        if (!tokenizerPath)
+            throw new Error('BGE tokenizer.json 缺失，无法执行真实 Token 计数');
+        const raw = JSON.parse(fs.readFileSync(tokenizerPath, 'utf8'));
+        this.vocab = new Set(Object.keys(raw.model?.vocab ?? {}));
+        this.unkToken = raw.model?.unk_token ?? '[UNK]';
+        if (this.vocab.size === 0)
+            throw new Error('BGE tokenizer vocab 为空，无法执行真实 Token 计数');
+    }
+    /** 统计文本的 Token 数量 */
+    countTokens(text) {
+        return this.encode(text).length;
+    }
+    encode(text) {
+        const tokens = [];
+        for (const token of this.preTokenize(text))
+            tokens.push(...this.wordPiece(token));
+        return tokens;
+    }
+    preTokenize(text) {
+        const normalized = Array.from(text, char => {
+            const code = char.charCodeAt(0);
+            return code < 32 || code === 127 ? ' ' : char;
+        }).join('')
+            .replace(/([\p{Script=Han}])/gu, ' $1 ')
+            .normalize('NFKC');
+        return normalized.match(/[\p{Script=Han}]|[\p{Letter}\p{Number}_]+|[^\s\p{Letter}\p{Number}_]/gu) ?? [];
+    }
+    wordPiece(token) {
+        if (this.vocab.has(token))
+            return [token];
+        const pieces = [];
+        let start = 0;
+        while (start < token.length) {
+            let end = token.length;
+            let current;
+            while (start < end) {
+                const piece = `${start > 0 ? '##' : ''}${token.slice(start, end)}`;
+                if (this.vocab.has(piece)) {
+                    current = piece;
+                    break;
+                }
+                end -= 1;
+            }
+            if (!current)
+                return Array.from(token).map(() => this.unkToken);
+            pieces.push(current);
+            start = end;
+        }
+        return pieces;
+    }
+    static resolveTokenizerPath() {
+        const currentDir = path.dirname(fileURLToPath(import.meta.url));
+        const candidates = [
+            process.env.CUSTOMIZE_BGE_TOKENIZER_PATH,
+            process.env.KB_BGE_TOKENIZER_PATH,
+            path.resolve(process.cwd(), 'packages', 'knowledge', 'models', 'bge-small-zh-v1.5', 'tokenizer.json'),
+            path.resolve(process.cwd(), 'models', 'bge-small-zh-v1.5', 'tokenizer.json'),
+            path.resolve(currentDir, '..', '..', 'models', 'bge-small-zh-v1.5', 'tokenizer.json'),
+        ].filter(Boolean);
+        return candidates.find(candidate => fs.existsSync(candidate));
+    }
+}

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

@@ -1,4 +1,5 @@
 import type { ClassifiedFile } from '../types.js';
+/** 文本切片结果 */
 export interface TextChunk {
     index: number;
     text: string;
@@ -8,23 +9,42 @@ export interface TextChunk {
     sectionTitle?: string;
     metadata: Record<string, unknown>;
 }
+/** 切片配置参数 */
 export interface ChunkConfig {
     maxChunkSize: number;
     overlap: number;
     headerInjection: boolean;
 }
+/** 文本切片器，支持文档、表格、代码等多类型文件的递归式切片 */
 export declare class TextChunker {
+    private readonly tokenizer;
+    /**
+     * 将文本内容按类型和配置分割为切片
+     * @param text 原始文本内容
+     * @param file 已分类的文件信息
+     * @param metadata 额外元数据
+     * @returns 切片列表
+     */
     chunk(text: string, file: ClassifiedFile, metadata?: Record<string, unknown>): TextChunk[];
     private createCandidates;
     private createTextCandidates;
     private createTableCandidates;
     private createDataCandidates;
     private createCodeCandidates;
+    private normalizeCodeLanguage;
+    private splitCodeByLanguage;
+    private collectIndentSensitiveBlocks;
+    private collectBraceBalancedBlocks;
+    private splitCodeByStructuralFallback;
     private splitIntoSections;
     private mergeLeadingHeader;
     private recursiveSplit;
     private mergeParts;
     private splitByWindow;
+    private splitBySentenceBoundary;
+    private isMarkdownTable;
+    private extractMarkdownTableRowRange;
+    private splitMarkdownTable;
     private enforceCandidateLimit;
     private withHeader;
     private createChunk;

package/dist/chunking/text-chunker.js

@@ -1,3 +1,4 @@
+import { BgeTokenizer } from './bge-tokenizer.js';
 const DEFAULT_CONFIGS = {
     document: { maxChunkSize: 800, overlap: 100, headerInjection: true },
     spreadsheet: { maxChunkSize: 1000, overlap: 120, headerInjection: true },
@@ -18,7 +19,26 @@ const RECURSIVE_SEPARATORS = [
     /(?<=[，、])\s*/u,
     /\s+/u,
 ];
+const LANGUAGE_ROUTER = {
+    typescript: { delimiters: /\n(?=(?:export\s+)?(?:async\s+)?(?:class|function|interface|type|const|let)\s)/u, blockStart: /\{\s*$/u, indentSensitive: false },
+    javascript: { delimiters: /\n(?=(?:export\s+)?(?:async\s+)?(?:class|function|const|let)\s)/u, blockStart: /\{\s*$/u, indentSensitive: false },
+    python: { delimiters: /\n(?=(?:class|def)\s)/u, blockStart: /:\s*$/u, indentSensitive: true },
+    go: { delimiters: /\n(?=(?:func|type|struct|interface)\s)/u, blockStart: /\{\s*$/u, indentSensitive: false },
+    java: { delimiters: /\n(?=(?:public|protected|private|static|final|abstract|\s)*(?:class|interface|enum|(?:\w|<|>|\[|\])+\s+\w+\s*\())/u, blockStart: /\{\s*$/u, indentSensitive: false },
+    csharp: { delimiters: /\n(?=(?:public|protected|private|internal|static|sealed|abstract|\s)*(?:class|interface|enum|(?:\w|<|>|\[|\])+\s+\w+\s*\())/u, blockStart: /\{\s*$/u, indentSensitive: false },
+    cpp: { delimiters: /\n(?=(?:class|struct|namespace|template)\s|[\w:*&<>]+\s+\w+\s*\()/u, blockStart: /\{\s*$/u, indentSensitive: false },
+    c: { delimiters: /\n(?=(?:struct|enum)\s|[\w*]+\s+\w+\s*\()/u, blockStart: /\{\s*$/u, indentSensitive: false },
+};
+/** 文本切片器，支持文档、表格、代码等多类型文件的递归式切片 */
 export class TextChunker {
+    tokenizer = new BgeTokenizer();
+    /**
+     * 将文本内容按类型和配置分割为切片
+     * @param text 原始文本内容
+     * @param file 已分类的文件信息
+     * @param metadata 额外元数据
+     * @returns 切片列表
+     */
     chunk(text, file, metadata = {}) {
         const source = text.trim();
         if (source.length === 0)
@@ -34,7 +54,7 @@ export class TextChunker {
         if (file.category === 'data')
             return this.createDataCandidates(text, config);
         if (file.category === 'code')
-            return this.createCodeCandidates(text, config);
+            return this.createCodeCandidates(text, file, config);
         return this.createTextCandidates(text, file.category, config);
     }
     createTextCandidates(text, category, config) {
@@ -62,43 +82,23 @@ export class TextChunker {
         return candidates;
     }
     createTableCandidates(text, config) {
-        const lines = text.split(/\r?\n/u).map(line => line.trim()).filter(Boolean);
-        const headerLines = lines.filter(line => /^(文件|类型|Sheet|表格|列|Columns?)[:：]/iu.test(line));
-        const dataLines = lines.filter(line => !headerLines.includes(line));
-        if (dataLines.length === 0)
-            return this.createTextCandidates(text, 'spreadsheet', config);
-        const header = headerLines.join('\n');
-        const candidates = [];
-        let rowStart = 0;
-        let parentIndex = 0;
-        while (rowStart < dataLines.length) {
-            const rows = [];
-            while (rowStart + rows.length < dataLines.length) {
-                const nextLine = dataLines[rowStart + rows.length];
-                if (!nextLine)
-                    break;
-                const nextRows = [...rows, nextLine];
-                const candidate = [header, `行范围: ${rowStart + 1}-${rowStart + nextRows.length}`, ...nextRows].filter(Boolean).join('\n');
-                if (rows.length > 0 && this.estimateTokens(candidate) > config.maxChunkSize)
-                    break;
-                rows.push(nextLine);
-            }
-            const textChunk = [header, `行范围: ${rowStart + 1}-${rowStart + rows.length}`, ...rows].filter(Boolean).join('\n');
-            candidates.push({
-                text: textChunk,
-                startChar: text.indexOf(rows[0] ?? ''),
-                endChar: text.indexOf(rows.at(-1) ?? '') + (rows.at(-1)?.length ?? 0),
-                sectionTitle: '表格数据',
-                kind: 'table',
-                parentId: `table-${parentIndex}`,
-                parentIndex,
-                childIndex: 0,
-                rowRange: `${rowStart + 1}-${rowStart + rows.length}`,
+        if (this.isMarkdownTable(text)) {
+            return this.splitMarkdownTable(text, config.maxChunkSize).map((part, index) => {
+                const startChar = Math.max(0, text.indexOf(part.slice(0, 40)));
+                return {
+                    text: part,
+                    startChar,
+                    endChar: startChar + part.length,
+                    sectionTitle: this.extractSectionTitle(part) ?? '表格数据',
+                    kind: 'table',
+                    parentId: `table-${index}`,
+                    parentIndex: index,
+                    childIndex: 0,
+                    rowRange: this.extractMarkdownTableRowRange(part),
+                };
             });
-            rowStart += Math.max(1, rows.length);
-            parentIndex += 1;
         }
-        return candidates;
+        return this.createTextCandidates(text, 'spreadsheet', config);
     }
     createDataCandidates(text, config) {
         const sections = text.split(/\n(?=[\w.[\]-]+[:：]\s)|\n{2,}/u).map(part => part.trim()).filter(Boolean);
@@ -114,19 +114,89 @@ export class TextChunker {
             childIndex: 0,
         }));
     }
-    createCodeCandidates(text, config) {
-        const blocks = text.split(/\n(?=(?:export\s+)?(?:async\s+)?(?:function|class|interface|type|const|let|var)\s)/u).map(part => part.trim()).filter(Boolean);
+    createCodeCandidates(text, file, config) {
+        const language = this.normalizeCodeLanguage(file.format);
+        const languageConfig = LANGUAGE_ROUTER[language];
+        const blocks = languageConfig
+            ? this.splitCodeByLanguage(text, languageConfig)
+            : this.splitCodeByStructuralFallback(text);
         const parts = blocks.length > 1 ? blocks : this.recursiveSplit(text, config.maxChunkSize);
-        return this.mergeParts(parts, config.maxChunkSize, config.overlap).map((part, index) => ({
-            text: part,
-            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),
-            kind: 'code',
-            parentId: `code-${index}`,
-            parentIndex: index,
-            childIndex: 0,
-        }));
+        return this.mergeParts(parts, config.maxChunkSize, config.overlap).map((part, index) => {
+            const startChar = Math.max(0, text.indexOf(part.slice(0, 40)));
+            return {
+                text: part,
+                startChar,
+                endChar: startChar + part.length,
+                sectionTitle: this.extractSectionTitle(part),
+                kind: 'code',
+                parentId: `code-${language}-${index}`,
+                parentIndex: index,
+                childIndex: 0,
+            };
+        });
+    }
+    normalizeCodeLanguage(format) {
+        const aliases = {
+            ts: 'typescript', tsx: 'typescript', typescript: 'typescript',
+            js: 'javascript', jsx: 'javascript', javascript: 'javascript',
+            py: 'python', python: 'python',
+            golang: 'go', go: 'go',
+            java: 'java', cs: 'csharp', csharp: 'csharp',
+            cpp: 'cpp', cxx: 'cpp', cc: 'cpp', hpp: 'cpp',
+            c: 'c', h: 'c',
+        };
+        return aliases[format.toLowerCase()] ?? format.toLowerCase();
+    }
+    splitCodeByLanguage(text, config) {
+        const raw = text.split(config.delimiters).map(part => part.trim()).filter(Boolean);
+        if (raw.length <= 1)
+            return raw;
+        return raw.flatMap(block => config.indentSensitive ? this.collectIndentSensitiveBlocks(block, config) : this.collectBraceBalancedBlocks(block, config));
+    }
+    collectIndentSensitiveBlocks(block, config) {
+        const lines = block.split(/\r?\n/u);
+        const result = [];
+        let current = [];
+        let baseIndent;
+        for (const line of lines) {
+            const indent = line.match(/^\s*/u)?.[0].length ?? 0;
+            if (current.length > 0 && baseIndent != null && indent <= baseIndent && config.blockStart.test(current[0] ?? '') && line.trim()) {
+                result.push(current.join('\n').trim());
+                current = [];
+                baseIndent = undefined;
+            }
+            if (current.length === 0)
+                baseIndent = indent;
+            current.push(line);
+        }
+        if (current.length > 0)
+            result.push(current.join('\n').trim());
+        return result.filter(Boolean);
+    }
+    collectBraceBalancedBlocks(block, _config) {
+        const lines = block.split(/\r?\n/u);
+        const result = [];
+        let current = [];
+        let depth = 0;
+        for (const line of lines) {
+            current.push(line);
+            depth += (line.match(/\{/gu) ?? []).length;
+            depth -= (line.match(/\}/gu) ?? []).length;
+            if (current.length > 1 && depth <= 0) {
+                result.push(current.join('\n').trim());
+                current = [];
+                depth = 0;
+            }
+        }
+        if (current.length > 0)
+            result.push(current.join('\n').trim());
+        return result.filter(Boolean);
+    }
+    splitCodeByStructuralFallback(text) {
+        const blocks = this.collectBraceBalancedBlocks(text, { delimiters: /\n/u, blockStart: /\{\s*$/u, indentSensitive: false });
+        if (blocks.length > 1)
+            return blocks;
+        return text.split(/\n(?=\S)/u).map(part => part.trim()).filter(Boolean);
     }
     splitIntoSections(text, category) {
         const pattern = category === 'cad' || category === 'diagram'
@@ -154,11 +224,13 @@ export class TextChunker {
     recursiveSplit(text, maxTokens, separatorIndex = 0) {
         if (this.estimateTokens(text) <= maxTokens)
             return [text.trim()].filter(Boolean);
+        if (this.isMarkdownTable(text))
+            return this.splitMarkdownTable(text, maxTokens);
         if (separatorIndex >= RECURSIVE_SEPARATORS.length)
-            return this.splitByWindow(text, maxTokens);
+            return this.splitBySentenceBoundary(text, maxTokens);
         const separator = RECURSIVE_SEPARATORS[separatorIndex];
         if (!separator)
-            return this.splitByWindow(text, maxTokens);
+            return this.splitBySentenceBoundary(text, maxTokens);
         const parts = text.split(separator).map(part => part.trim()).filter(Boolean);
         if (parts.length <= 1)
             return this.recursiveSplit(text, maxTokens, separatorIndex + 1);
@@ -183,8 +255,11 @@ export class TextChunker {
         return chunks.flatMap(chunk => this.estimateTokens(chunk) > maxTokens ? this.splitByWindow(chunk, maxTokens, overlapTokens) : [chunk]);
     }
     splitByWindow(text, maxTokens, overlapTokens = 0) {
-        const maxChars = Math.max(200, maxTokens * 4);
-        const overlapChars = Math.max(0, overlapTokens * 4);
+        const tokens = this.tokenizer.encode(text);
+        if (tokens.length <= maxTokens)
+            return [text.trim()].filter(Boolean);
+        const maxChars = Math.max(200, Math.ceil(text.length * (maxTokens / Math.max(1, tokens.length))));
+        const overlapChars = Math.max(0, Math.ceil(text.length * (overlapTokens / Math.max(1, tokens.length))));
         const step = Math.max(1, maxChars - overlapChars);
         const chunks = [];
         for (let start = 0; start < text.length; start += step) {
@@ -194,6 +269,44 @@ export class TextChunker {
         }
         return chunks.filter(Boolean);
     }
+    splitBySentenceBoundary(text, maxTokens) {
+        const units = text.split(/(?<=[。？！；;.!?])\s+|(?<=[。？！；;.!?])/u).map(part => part.trim()).filter(Boolean);
+        if (units.length <= 1)
+            return this.splitByWindow(text, maxTokens);
+        return this.mergeParts(units, maxTokens, 0);
+    }
+    isMarkdownTable(text) {
+        const lines = text.trim().split(/\r?\n/u);
+        return lines.length >= 3 && lines.some(line => /^\s*\|?\s*:?-{3,}:?\s*\|/u.test(line));
+    }
+    extractMarkdownTableRowRange(text) {
+        const lines = text.trim().split(/\r?\n/u).filter(line => /^\s*\|/u.test(line));
+        const rowCount = Math.max(0, lines.length - 2);
+        return rowCount > 0 ? `1-${rowCount}` : undefined;
+    }
+    splitMarkdownTable(text, maxTokens) {
+        const lines = text.trim().split(/\r?\n/u).filter(Boolean);
+        const separatorIndex = lines.findIndex(line => /^\s*\|?\s*:?-{3,}:?\s*\|/u.test(line));
+        if (separatorIndex <= 0)
+            return this.splitBySentenceBoundary(text, maxTokens);
+        const header = lines.slice(0, separatorIndex + 1);
+        const rows = lines.slice(separatorIndex + 1);
+        const chunks = [];
+        let current = [];
+        for (const row of rows) {
+            const candidate = [...header, ...current, row].join('\n');
+            if (current.length > 0 && this.estimateTokens(candidate) > maxTokens) {
+                chunks.push([...header, ...current].join('\n'));
+                current = [row];
+            }
+            else {
+                current.push(row);
+            }
+        }
+        if (current.length > 0)
+            chunks.push([...header, ...current].join('\n'));
+        return chunks.flatMap(chunk => this.estimateTokens(chunk) > maxTokens ? this.splitByWindow(chunk, maxTokens) : [chunk]);
+    }
     enforceCandidateLimit(candidates, config) {
         return candidates.flatMap(candidate => {
             if (this.estimateTokens(candidate.text) <= config.maxChunkSize)
@@ -263,6 +376,6 @@ export class TextChunker {
         return text.slice(Math.max(0, text.length - chars));
     }
     estimateTokens(text) {
-        return Math.max(1, Math.ceil(text.length / 4));
+        return Math.max(1, this.tokenizer.countTokens(text));
     }
 }

package/dist/classification/classifier.d.ts

@@ -1,5 +1,6 @@
 import type { Stats } from 'node:fs';
 import type { ClassifiedFile, FileCategory } from '../types.js';
+/** 文件分类器，根据扩展名将文件归类到预定义的分类体系 */
 export declare class FileClassifier {
     private readonly extensionMap;
     constructor();

package/dist/classification/classifier.js

@@ -1,5 +1,6 @@
 import * as path from 'node:path';
 const DEFAULT_MAX_FILE_SIZE_BYTES = 500 * 1024 * 1024;
+/** 文件分类器，根据扩展名将文件归类到预定义的分类体系 */
 export class FileClassifier {
     extensionMap;
     constructor() {
@@ -76,7 +77,6 @@ export class FileClassifier {
             ['.html', 'web', 'html'], ['.htm', 'web', 'html'], ['.xhtml', 'web', 'html'], ['.css', 'web', 'stylesheet'], ['.scss', 'web', 'stylesheet'], ['.sass', 'web', 'stylesheet'], ['.less', 'web', 'stylesheet'],
             ['.hbs', 'web', 'template'], ['.ejs', 'web', 'template'], ['.pug', 'web', 'template'], ['.j2', 'web', 'template'], ['.jinja2', 'web', 'template'],
             ['.drawio', 'diagram', 'drawio'], ['.dio', 'diagram', 'drawio'], ['.vsdx', 'diagram', 'visio'], ['.vdx', 'diagram', 'visio'], ['.puml', 'diagram', 'plantuml'], ['.plantuml', 'diagram', 'plantuml'], ['.mmd', 'diagram', 'mermaid'], ['.mermaid', 'diagram', 'mermaid'], ['.excalidraw', 'diagram', 'excalidraw'],
-            ['.zip', 'archive', 'zip'], ['.jar', 'archive', 'zip'], ['.war', 'archive', 'zip'], ['.apk', 'archive', 'zip'], ['.tar', 'archive', 'tar'], ['.gz', 'archive', 'other'], ['.tgz', 'archive', 'tar'], ['.bz2', 'archive', 'other'], ['.rar', 'archive', 'other'], ['.7z', 'archive', 'other'],
         ];
         return new Map(entries.map(([ext, category, format]) => [ext, [category, format]]));
     }

package/dist/constants.d.ts

@@ -1,8 +1,15 @@
 import type { FileCategory } from './types.js';
+/** 知识库数据目录名 */
 export declare const KNOWLEDGE_BASE_DIR = "knowledgeBase";
+/** 项目配置文件路径（相对于项目根目录） */
 export declare const PROJECT_CONFIG_PATH: readonly [".customize-agent", "kb", "project.json"];
+/** 自定义 Agent 用户数据目录 */
 export declare const USER_DATA_DIR = ".customize-agent";
+/** 全局知识库目录名 */
 export declare const GLOBAL_KNOWLEDGE_DIR = "global-knowledge";
+/** 所有支持的文件分类 */
 export declare const ALL_CATEGORIES: readonly FileCategory[];
+/** 各文件分类的默认目录（中文名称） */
 export declare const DEFAULT_CATEGORY_DIRS: Record<FileCategory, string>;
+/** 各文件分类对应的 Vector Collection 名称（英文，供存储使用） */
 export declare const COLLECTION_CATEGORY_NAMES: Record<FileCategory, string>;

package/dist/constants.js

@@ -1,7 +1,12 @@
+/** 知识库数据目录名 */
 export const KNOWLEDGE_BASE_DIR = 'knowledgeBase';
+/** 项目配置文件路径（相对于项目根目录） */
 export const PROJECT_CONFIG_PATH = ['.customize-agent', 'kb', 'project.json'];
+/** 自定义 Agent 用户数据目录 */
 export const USER_DATA_DIR = '.customize-agent';
+/** 全局知识库目录名 */
 export const GLOBAL_KNOWLEDGE_DIR = 'global-knowledge';
+/** 所有支持的文件分类 */
 export const ALL_CATEGORIES = [
     'document',
     'spreadsheet',
@@ -14,6 +19,7 @@ export const ALL_CATEGORIES = [
     'archive',
     'other',
 ];
+/** 各文件分类的默认目录（中文名称） */
 export const DEFAULT_CATEGORY_DIRS = {
     document: '文档资料',
     spreadsheet: '表格数据',
@@ -26,6 +32,7 @@ export const DEFAULT_CATEGORY_DIRS = {
     archive: '压缩包',
     other: '其他文件',
 };
+/** 各文件分类对应的 Vector Collection 名称（英文，供存储使用） */
 export const COLLECTION_CATEGORY_NAMES = {
     document: 'documents',
     spreadsheet: 'spreadsheets',

package/dist/core/change-tracker.d.ts

@@ -2,10 +2,23 @@ import type { FileClassifier } from '../classification/classifier.js';
 import type { DiffResult } from '../types.js';
 import type { DiskFileStat } from './file-scanner.js';
 import type { IndexStateStore } from './index-state-store.js';
+/** 文件变更追踪器，用于比对磁盘文件与索引状态之间的差异 */
 export declare class ChangeTracker {
     private readonly store;
     constructor(store: IndexStateStore);
+    /**
+     * 计算磁盘文件与索引状态之间的差异
+     * @param diskFiles 磁盘上的文件列表
+     * @param classifier 文件分类器
+     * @param kbPath 知识库路径
+     * @returns 文件差异对比结果
+     */
     computeDiff(diskFiles: Map<string, DiskFileStat>, classifier: FileClassifier, kbPath: string): Promise<DiffResult>;
+    /**
+     * 计算文件的 SHA-256 哈希值
+     * @param filePath 文件路径
+     * @returns SHA-256 哈希字符串
+     */
     hashFile(filePath: string): string;
     private parseMetadata;
 }

package/dist/core/change-tracker.js

@@ -1,11 +1,19 @@
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+/** 文件变更追踪器，用于比对磁盘文件与索引状态之间的差异 */
 export class ChangeTracker {
     store;
     constructor(store) {
         this.store = store;
     }
+    /**
+     * 计算磁盘文件与索引状态之间的差异
+     * @param diskFiles 磁盘上的文件列表
+     * @param classifier 文件分类器
+     * @param kbPath 知识库路径
+     * @returns 文件差异对比结果
+     */
     async computeDiff(diskFiles, classifier, kbPath) {
         const startTime = Date.now();
         const indexedFiles = this.store.loadActiveRecords();
@@ -73,6 +81,11 @@ export class ChangeTracker {
             diffTimeMs: Date.now() - startTime,
         };
     }
+    /**
+     * 计算文件的 SHA-256 哈希值
+     * @param filePath 文件路径
+     * @returns SHA-256 哈希字符串
+     */
     hashFile(filePath) {
         return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
     }

package/dist/core/file-scanner.d.ts

@@ -1,8 +1,21 @@
+/** 磁盘文件信息 */
 export interface DiskFileStat {
     size: number;
     mtime: number;
 }
+/** 知识库文件扫描器，用于扫描和加载知识库目录中的文件 */
 export declare class KnowledgeFileScanner {
+    /**
+     * 扫描知识库目录中的所有文件
+     * @param kbPath 知识库路径
+     * @param ignorePatterns 忽略模式列表
+     * @returns 文件相对路径到文件信息的映射
+     */
     scan(kbPath: string, ignorePatterns?: string[]): Promise<Map<string, DiskFileStat>>;
+    /**
+     * 加载 .kbignore 忽略规则文件
+     * @param kbPath 知识库路径
+     * @returns 忽略规则列表
+     */
     loadKbIgnore(kbPath: string): string[];
 }

package/dist/core/file-scanner.js

@@ -1,7 +1,14 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import fg from 'fast-glob';
+/** 知识库文件扫描器，用于扫描和加载知识库目录中的文件 */
 export class KnowledgeFileScanner {
+    /**
+     * 扫描知识库目录中的所有文件
+     * @param kbPath 知识库路径
+     * @param ignorePatterns 忽略模式列表
+     * @returns 文件相对路径到文件信息的映射
+     */
     async scan(kbPath, ignorePatterns = []) {
         if (!fs.existsSync(kbPath))
             return new Map();
@@ -20,6 +27,11 @@ export class KnowledgeFileScanner {
         }
         return files;
     }
+    /**
+     * 加载 .kbignore 忽略规则文件
+     * @param kbPath 知识库路径
+     * @returns 忽略规则列表
+     */
     loadKbIgnore(kbPath) {
         const ignorePath = path.join(kbPath, '.kbignore');
         if (!fs.existsSync(ignorePath))