@customize-agent/knowledge 4.0.2 → 4.0.4

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

@@ -1,7 +1,9 @@
+/** 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;

package/dist/chunking/bge-tokenizer.js

@@ -1,6 +1,7 @@
 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;
@@ -13,6 +14,7 @@ export class BgeTokenizer {
         if (this.vocab.size === 0)
             throw new Error('BGE tokenizer vocab 为空，无法执行真实 Token 计数');
     }
+    /** 统计文本的 Token 数量 */
     countTokens(text) {
         return this.encode(text).length;
     }

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,13 +9,22 @@ 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;

package/dist/chunking/text-chunker.js

@@ -29,8 +29,16 @@ const LANGUAGE_ROUTER = {
     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)

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() {

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))

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

@@ -84,12 +84,16 @@ export interface FileRelationship {
     userConfirmed: number;
     createdAt: number;
 }
+/** 索引状态存储器，使用 SQLite 管理知识库索引的持久化状态 */
 export declare class IndexStateStore {
     private readonly db;
     private ftsEnabled;
     constructor(dbPath: string);
+    /** 加载所有活跃的索引记录 */
     loadActiveRecords(): Map<string, IndexStateRecord>;
+    /** 插入或更新索引记录 */
     upsertRecord(record: IndexStateRecord): void;
+    /** 更新已验证文件的时间戳和状态 */
     updateVerified(relativePath: string, mtime: number): void;
     listRecords(): IndexStateRecord[];
     enqueueIndexJob(job: {
@@ -108,6 +112,12 @@ export declare class IndexStateStore {
     countPendingIndexJobs(): number;
     listActiveIndexJobsByPath(relativePath: string): KnowledgeIndexJob[];
     listIndexJobsByPrefix(prefix: string): KnowledgeIndexJob[];
+    /**
+     * 替换指定文件的切片数据（使用事务批量更新）
+     * @param relativePath 文件相对路径
+     * @param chunks 文本切片列表
+     * @param file 文件分类信息
+     */
     replaceChunks(relativePath: string, chunks: TextChunk[], file: {
         category: FileCategory;
         format: string;
@@ -125,6 +135,12 @@ export declare class IndexStateStore {
     getParentChunk(relativePath: string, parentId: string): StoredParentChunk | undefined;
     getDocumentChunk(relativePath: string): StoredDocumentChunk | undefined;
     getChunksByParent(relativePath: string, parentId: string, limit?: number): StoredChunk[];
+    /**
+     * 使用关键词搜索切片（支持 FTS5 全文搜索和 LIKE 模糊匹配）
+     * @param query 搜索查询
+     * @param limit 返回结果数量上限
+     * @returns 搜索结果列表（按相关性得分排序）
+     */
     searchChunks(query: string, limit?: number): ChunkSearchResult[];
     private searchChunksFts;
     private searchChunksLike;
@@ -149,6 +165,10 @@ export declare class IndexStateStore {
         enabled: boolean;
         createdAt: number;
     }>;
+    /**
+     * 删除指定文件的全部索引数据（含切片、哈希、MinHash、标签、关系等）
+     * @param relativePath 文件相对路径
+     */
     deleteRecord(relativePath: string): void;
     setMetadata(key: string, value: string): void;
     getMetadata(key: string): string | undefined;

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

@@ -1,6 +1,7 @@
 import Database from 'better-sqlite3';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+/** 索引状态存储器，使用 SQLite 管理知识库索引的持久化状态 */
 export class IndexStateStore {
     db;
     ftsEnabled = false;
@@ -10,6 +11,7 @@ export class IndexStateStore {
         this.db.pragma('journal_mode = WAL');
         this.initTables();
     }
+    /** 加载所有活跃的索引记录 */
     loadActiveRecords() {
         const rows = this.db.prepare(`
       SELECT * FROM kb_index_state
@@ -20,6 +22,7 @@ export class IndexStateStore {
             return [record.relativePath, record];
         }));
     }
+    /** 插入或更新索引记录 */
     upsertRecord(record) {
         this.db.prepare(`
       INSERT INTO kb_index_state (
@@ -41,6 +44,7 @@ export class IndexStateStore {
         metadata_json = excluded.metadata_json
     `).run(record.relativePath, record.category, record.format, record.contentHash, record.fileSize, Math.round(record.mtime), record.chunkCount, record.collectionName, record.indexedAt, record.lastVerifiedAt, record.status, record.errorMessage ?? null, record.metadataJson ?? null);
     }
+    /** 更新已验证文件的时间戳和状态 */
     updateVerified(relativePath, mtime) {
         this.db.prepare(`
       UPDATE kb_index_state
@@ -108,6 +112,12 @@ export class IndexStateStore {
     `).all(`${prefix}%`);
         return rows.map(row => this.rowToJob(row));
     }
+    /**
+     * 替换指定文件的切片数据（使用事务批量更新）
+     * @param relativePath 文件相对路径
+     * @param chunks 文本切片列表
+     * @param file 文件分类信息
+     */
     replaceChunks(relativePath, chunks, file) {
         const now = Date.now();
         const transaction = this.db.transaction(() => {
@@ -237,6 +247,12 @@ export class IndexStateStore {
     `).all(relativePath, `%"parentId":"${parentId.replace(/[%_]/gu, '')}"%`, limit);
         return rows.map(row => this.rowToChunk(row, 0));
     }
+    /**
+     * 使用关键词搜索切片（支持 FTS5 全文搜索和 LIKE 模糊匹配）
+     * @param query 搜索查询
+     * @param limit 返回结果数量上限
+     * @returns 搜索结果列表（按相关性得分排序）
+     */
     searchChunks(query, limit = 10) {
         const terms = this.expandSearchTerms(query);
         if (terms.length === 0)
@@ -410,6 +426,10 @@ export class IndexStateStore {
             createdAt: Number(row.created_at),
         }));
     }
+    /**
+     * 删除指定文件的全部索引数据（含切片、哈希、MinHash、标签、关系等）
+     * @param relativePath 文件相对路径
+     */
     deleteRecord(relativePath) {
         this.db.prepare('DELETE FROM kb_chunks WHERE relative_path = ?').run(relativePath);
         this.db.prepare('DELETE FROM kb_parent_chunks WHERE relative_path = ?').run(relativePath);

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

@@ -94,7 +94,10 @@ export declare class KnowledgeBaseManager {
             createdAt: number;
         }[];
     } | undefined;
-    reindexFile(relativePath: string): Promise<DiffResult>;
+    reindexFile(relativePath: string, options?: {
+        onProgress?: (progress: KnowledgeIndexProgress) => void;
+        vectorMode?: 'sync' | 'defer';
+    }): Promise<DiffResult>;
     addFile(sourcePath: string, targetRelativePath?: string): Promise<DiffResult>;
     getUploadRelativePath(fileName: string, targetRelativePath?: string): string;
     uploadFile(fileName: string, content: Buffer, targetRelativePath?: string, onProgress?: (progress: KnowledgeIndexProgress) => void, options?: {

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

@@ -331,7 +331,7 @@ export class KnowledgeBaseManager {
                 try {
                     rankedLists.push({ source: 'vector', items: (await this.semanticSearch(rewritten, { ...options, limit: limit * 3 })).results, queryIndex });
                 }
-                catch { /* vector search is optional in hybrid search */ }
+                catch { /* 向量搜索在混合搜索中是可选的 */ }
             }
         }
         const keywordItems = rankedLists.filter(list => list.source === 'keyword').flatMap(list => list.items);
@@ -396,7 +396,7 @@ export class KnowledgeBaseManager {
             tags: this.store.listTags(normalized),
         };
     }
-    async reindexFile(relativePath) {
+    async reindexFile(relativePath, options = {}) {
         const normalized = this.normalizeRelativePath(relativePath);
         const record = this.store.listRecords().find(item => item.relativePath === normalized);
         const targetPath = this.resolveKbRelativePath(normalized);
@@ -405,7 +405,7 @@ export class KnowledgeBaseManager {
         if (record)
             await this.deleteVectorFile(record.collectionName, normalized);
         this.store.deleteRecord(normalized);
-        return this.incrementalIndex();
+        return this.incrementalIndex({ ...options, onlyRelativePaths: [normalized] });
     }
     async addFile(sourcePath, targetRelativePath) {
         this.initialize();
@@ -497,7 +497,15 @@ export class KnowledgeBaseManager {
         this.reportProgress({ stage: 'vectorizing', percent: 85, message: `正在写入 HNSWLib 向量库，共 ${chunks.length} 个切片`, chunkCount: chunks.length });
         const indexer = new VectorIndexer(this.embeddingProvider, this.vectorStores);
         try {
-            const results = await indexer.indexChunks(chunks);
+            const results = await indexer.indexChunks(chunks, {
+                onProgress: progress => {
+                    const percent = 85 + Math.round((progress.processedChunks / Math.max(1, progress.totalChunks)) * 14);
+                    const message = `正在分批向量化并写入：${progress.processedChunks}/${progress.totalChunks} 个切片`;
+                    this.reportProgress({ stage: 'vectorizing', percent, message, chunkCount: progress.totalChunks });
+                    if (options.relativePath)
+                        this.updateJobsForFile(options.relativePath, 'INDEXING', percent, message);
+                },
+            });
             const actualModel = results[0]?.embeddingModel ?? this.embeddingProvider.model;
             const actualDimension = results[0]?.embeddingDimension ?? this.embeddingProvider.dimensions;
             this.store.setMetadata('embedding_model', actualModel);

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

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

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

@@ -6,6 +6,7 @@ import { KnowledgeBaseManager } from './knowledge-base-manager.js';
 import { computeProjectId } from './project-id.js';
 import { getProjectKbPath, ProjectConfigManager } from './project-config.js';
 import { ProjectRegistry } from './project-registry.js';
+/** 多项目管理器，管理多个项目的知识库并支持跨项目搜索 */
 export class MultiProjectManager {
     storageRoot;
     llmProvider;
@@ -20,6 +21,10 @@ export class MultiProjectManager {
         this.registry = new ProjectRegistry(path.join(storageRoot, 'projects', 'registry.db'));
         this.configManager = new ProjectConfigManager(storageRoot);
     }
+    /**
+     * 获取或创建指定项目的知识库管理器
+     * @param projectRoot 项目根目录
+     */
     async getProject(projectRoot) {
         const resolvedRoot = path.resolve(projectRoot);
         const projectId = computeProjectId(resolvedRoot);
@@ -40,6 +45,9 @@ export class MultiProjectManager {
         this.updateRegistry(manager, resolvedRoot, config.projectName, config.lastOpenedAt);
         return manager;
     }
+    /**
+     * 获取或初始化全局知识库
+     */
     async getGlobalKB() {
         if (this.globalKB)
             return this.globalKB;

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

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

package/dist/core/project-config.js

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

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

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

package/dist/core/project-id.js

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

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

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

package/dist/core/project-registry.js

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

package/dist/dedup/dedup-engine.d.ts

@@ -1,12 +1,15 @@
+/** MinHash 签名结果 */
 export interface MinHashSignature {
     signature: number[];
     shingleCount: number;
     buckets: string[];
 }
+/** 相似度匹配结果 */
 export interface SimilarityMatch {
     filePath: string;
     similarity: number;
 }
+/** 去重引擎，支持归一化哈希、MinHash 相似度计算和 LSH 分桶 */
 export declare class DedupEngine {
     private readonly hashCount;
     private readonly bandSize;

package/dist/dedup/dedup-engine.js

@@ -1,4 +1,5 @@
 import * as crypto from 'node:crypto';
+/** 去重引擎，支持归一化哈希、MinHash 相似度计算和 LSH 分桶 */
 export class DedupEngine {
     hashCount = 192;
     bandSize = 6;

package/dist/dedup/relationship-detector.d.ts

@@ -1,6 +1,13 @@
 import type { ClassifiedFile, IndexStateRecord } from '../types.js';
 import type { FileRelationship } from '../core/index-state-store.js';
+/** 文件关系检测器，自动识别版本链、翻译关系和互补关系 */
 export declare class RelationshipDetector {
+    /**
+     * 检测文件与已有索引记录之间的关系
+     * @param file 当前处理的文件
+     * @param indexedRecords 已有索引记录列表
+     * @returns 检测到的关系列表
+     */
     detect(file: ClassifiedFile, indexedRecords: IndexStateRecord[]): Array<Omit<FileRelationship, 'id' | 'createdAt'>>;
     private detectVersionChain;
     private detectTranslation;

package/dist/dedup/relationship-detector.js

@@ -1,5 +1,12 @@
 import * as path from 'node:path';
+/** 文件关系检测器，自动识别版本链、翻译关系和互补关系 */
 export class RelationshipDetector {
+    /**
+     * 检测文件与已有索引记录之间的关系
+     * @param file 当前处理的文件
+     * @param indexedRecords 已有索引记录列表
+     * @returns 检测到的关系列表
+     */
     detect(file, indexedRecords) {
         const relationships = [];
         for (const record of indexedRecords) {

package/dist/embedding/embedding-provider.d.ts

@@ -1,9 +1,11 @@
+/** Embedding Provider 接口，负责将文本转换为向量 */
 export interface EmbeddingProvider {
     readonly model: string;
     readonly dimensions: number;
     embedDocuments(texts: string[]): Promise<number[][]>;
     embedQuery(text: string): Promise<number[]>;
 }
+/** 基于哈希的本地 Embedding Provider（无需模型，使用哈希算法生成特征向量） */
 export declare class HashEmbeddingProvider implements EmbeddingProvider {
     readonly dimensions: number;
     readonly model = "hash-embedding-local";
@@ -20,6 +22,7 @@ export interface OpenAICompatibleEmbeddingOptions {
     model: string;
     dimensions?: number;
 }
+/** OpenAI 兼容的 Embedding Provider，支持任何兼容 OpenAI API 的嵌入服务 */
 export declare class OpenAICompatibleEmbeddingProvider implements EmbeddingProvider {
     readonly model: string;
     readonly dimensions: number;
@@ -34,11 +37,14 @@ export interface LocalTransformersEmbeddingOptions {
     model?: string;
     dimensions?: number;
     modelPath?: string;
+    batchSize?: number;
 }
+/** 本地 Transformers.js 模型 Embedding Provider，使用 BGE 小模型生成向量 */
 export declare class LocalTransformersEmbeddingProvider implements EmbeddingProvider {
     readonly model: string;
     readonly dimensions: number;
     private readonly modelPath?;
+    private readonly batchSize;
     private static pipelines;
     constructor(options?: LocalTransformersEmbeddingOptions);
     embedDocuments(texts: string[]): Promise<number[][]>;
@@ -52,4 +58,8 @@ export declare class LocalTransformersEmbeddingProvider implements EmbeddingProv
     private resizeVector;
     private normalize;
 }
+/**
+ * 根据环境变量或配置文件自动创建 Embedding Provider
+ * 优先级：环境变量 > 配置文件 > 本地 Transformers.js 默认
+ */
 export declare function createEmbeddingProviderFromEnvironment(): EmbeddingProvider;

package/dist/embedding/embedding-provider.js

@@ -3,6 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
+/** 基于哈希的本地 Embedding Provider（无需模型，使用哈希算法生成特征向量） */
 export class HashEmbeddingProvider {
     dimensions;
     model = 'hash-embedding-local';
@@ -48,6 +49,7 @@ export class HashEmbeddingProvider {
         return vector.map(value => value / norm);
     }
 }
+/** OpenAI 兼容的 Embedding Provider，支持任何兼容 OpenAI API 的嵌入服务 */
 export class OpenAICompatibleEmbeddingProvider {
     model;
     dimensions;
@@ -80,6 +82,13 @@ export class OpenAICompatibleEmbeddingProvider {
         return (payload.data ?? []).map(item => item.embedding ?? []);
     }
 }
+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;
+    if (!Number.isFinite(raw) || raw <= 0)
+        return fallback;
+    return Math.max(1, Math.min(128, Math.floor(raw)));
+}
 function resolveBundledBgeModelPath() {
     const currentDir = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
@@ -91,15 +100,18 @@ function resolveBundledBgeModelPath() {
     ].filter(Boolean);
     return candidates.find(candidate => fs.existsSync(path.join(candidate, 'config.json')) && fs.existsSync(path.join(candidate, 'tokenizer.json')));
 }
+/** 本地 Transformers.js 模型 Embedding Provider，使用 BGE 小模型生成向量 */
 export class LocalTransformersEmbeddingProvider {
     model;
     dimensions;
     modelPath;
+    batchSize;
     static pipelines = new Map();
     constructor(options = {}) {
         this.model = options.model?.trim() || 'BAAI/bge-small-zh-v1.5';
         this.dimensions = options.dimensions ?? 512;
         this.modelPath = options.modelPath || resolveBundledBgeModelPath();
+        this.batchSize = resolveLocalEmbeddingBatchSize(options.batchSize);
     }
     async embedDocuments(texts) {
         return this.embed(texts);
@@ -109,9 +121,13 @@ export class LocalTransformersEmbeddingProvider {
     }
     async embed(input) {
         const extractor = await this.getPipeline();
-        const output = await extractor(input, { pooling: 'mean', normalize: true });
-        const vectors = this.parseVectors(output, input.length);
-        return vectors.map(vector => this.resizeVector(vector));
+        const vectors = [];
+        for (let offset = 0; offset < input.length; offset += this.batchSize) {
+            const batch = input.slice(offset, offset + this.batchSize);
+            const output = await extractor(batch, { pooling: 'mean', normalize: true });
+            vectors.push(...this.parseVectors(output, batch.length).map(vector => this.resizeVector(vector)));
+        }
+        return vectors;
     }
     getPipeline() {
         const existing = LocalTransformersEmbeddingProvider.pipelines.get(this.model);
@@ -200,6 +216,10 @@ function readStoredEmbeddingConfig() {
         return undefined;
     }
 }
+/**
+ * 根据环境变量或配置文件自动创建 Embedding Provider
+ * 优先级：环境变量 > 配置文件 > 本地 Transformers.js 默认
+ */
 export function createEmbeddingProviderFromEnvironment() {
     const stored = readStoredEmbeddingConfig();
     const provider = process.env.CUSTOMIZE_EMBEDDING_PROVIDER ?? process.env.KB_EMBEDDING_PROVIDER ?? stored?.provider ?? 'transformers-local';

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

@@ -1,11 +1,13 @@
 import { ExternalExtractorRegistry } from './external-extractor.js';
 import type { ClassifiedFile } from '../types.js';
+/** 文件内容提取结果 */
 export interface ExtractionResult {
     text: string;
     metadata: Record<string, unknown>;
     warnings: string[];
     extractionTimeMs: number;
 }
+/** 文件内容提取器，支持文档、表格、图片、CAD 等多种文件格式的内容抽取 */
 export declare class ContentExtractor {
     private readonly externalExtractors;
     constructor(externalExtractors?: ExternalExtractorRegistry);

package/dist/extraction/content-extractor.js

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { ExternalExtractorRegistry } from './external-extractor.js';
 import { resolveAndImport, resolvePackage, getNodeModulesRoot } from './module-resolver.js';
+/** 文件内容提取器，支持文档、表格、图片、CAD 等多种文件格式的内容抽取 */
 export class ContentExtractor {
     externalExtractors;
     constructor(externalExtractors = ExternalExtractorRegistry.fromEnvironment()) {
@@ -694,7 +695,7 @@ export class ContentExtractor {
                 }
             }
             catch {
-                // fallback below
+                // 降级到下方 Office ZIP 解析
             }
         }
         return this.extractOfficeZip(file);
@@ -805,7 +806,7 @@ export class ContentExtractor {
         catch {
             if (ext === '.xls')
                 return this.extractLegacyOfficeBinary(file);
-            // fallback below
+            // 降级到下方 ZIP 文件内容提取
         }
         if (ext === '.xls')
             return this.extractLegacyOfficeBinary(file);
@@ -1026,7 +1027,7 @@ try {
     async extractPdf(file) {
         const metadata = { extractionMode: 'pdf_text', vectorizable: true };
         const warnings = [];
-        // Tier 1: pdfjs-dist 文本提取（处理常规 PDF、压缩内容流、CJK 字体等）
+        // 第一层：pdfjs-dist 文本提取（处理常规 PDF、压缩内容流、CJK 字体等）
         try {
             const raw = fs.readFileSync(file.absolutePath);
             const text = await this.extractPdfText(raw);
@@ -1040,11 +1041,11 @@ try {
             warnings.push(`PDF 文本提取失败: ${error instanceof Error ? error.message : String(error)}`);
             metadata.parseError = error instanceof Error ? error.message : String(error);
         }
-        // Tier 2: OCR（扫描件/图片型 PDF）—— 必须保留并确保可用
+        // 第二层：OCR（扫描件/图片型 PDF）—— 必须保留并确保可用
         const ocr = await this.extractScannedPdfOcr(file);
         if (ocr.text.trim())
             return ocr;
-        // Tier 3: 仅索引元数据（兜底）
+        // 第三层：仅索引元数据（兜底）
         metadata.extractionMode = 'pdf_metadata_only';
         metadata.contentCoverage = 'metadata_filename';
         metadata.ocrRecommended = true;
@@ -1143,7 +1144,7 @@ process.stdout.write(JSON.stringify({ pageCount: doc.numPages, pageLimit, text:
         }
     }
     async extractPdfText(buffer) {
-        // Tier 1: pdfjs-dist 文本提取（处理压缩内容流、CJK 字体、现代 PDF）
+        // 第一层：pdfjs-dist 文本提取（处理压缩内容流、CJK 字体、现代 PDF）
         try {
             const mod = await resolveAndImport('pdfjs-dist/legacy/build/pdf.mjs');
             const loadingTask = mod.getDocument({ data: new Uint8Array(buffer), verbosity: 0 });
@@ -1171,7 +1172,7 @@ process.stdout.write(JSON.stringify({ pageCount: doc.numPages, pageLimit, text:
             if (process.env.KB_DEBUG === '1')
                 console.warn('[kb] pdfjs-dist extraction failed:', e.message);
         }
-        // Tier 2: pdf-parse（兼容旧版 PDF）
+        // 第二层：pdf-parse（兼容旧版 PDF）
         try {
             const mod = await resolveAndImport('pdf-parse');
             const pdfParse = mod.default;
@@ -1182,9 +1183,9 @@ process.stdout.write(JSON.stringify({ pageCount: doc.numPages, pageLimit, text:
             }
         }
         catch {
-            // fallback to raw regex below
+            // 降级到下方纯正则提取
         }
-        // Tier 3: raw regex 回退（未压缩的古老 PDF）
+        // 第三层：raw regex 回退（未压缩的古老 PDF）
         const raw = buffer.toString('latin1');
         const matches = Array.from(raw.matchAll(/\(([^()]{2,500})\)\s*T[jJ]/gu), match => match[1] ?? '')
             .concat(Array.from(raw.matchAll(/\[([^\]]{2,2000})\]\s*TJ/gu), match => match[1] ?? ''));

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

@@ -1,9 +1,11 @@
 import type { ClassifiedFile, FileCategory } from '../types.js';
+/** 外部解析器提取结果 */
 export interface ExternalExtractionResult {
     text: string;
     metadata?: Record<string, unknown>;
     warnings?: string[];
 }
+/** 外部解析器接口 */
 export interface ExternalExtractor {
     readonly id: string;
     readonly name: string;
@@ -15,6 +17,7 @@ export interface ExternalExtractor {
     extract(file: ClassifiedFile): ExternalExtractionResult;
     describe(): ExternalExtractorCapability;
 }
+/** 外部解析器能力描述 */
 export interface ExternalExtractorCapability {
     id: string;
     name: string;
@@ -24,6 +27,7 @@ export interface ExternalExtractorCapability {
     available: boolean;
     kind: 'command';
 }
+/** 命令行外部解析器配置选项 */
 export interface CommandExternalExtractorOptions {
     id: string;
     name: string;
@@ -34,6 +38,7 @@ export interface CommandExternalExtractorOptions {
     extensions?: string[];
     timeoutMs?: number;
 }
+/** 命令行外部解析器，通过调用外部命令提取文件内容 */
 export declare class CommandExternalExtractor implements ExternalExtractor {
     readonly id: string;
     readonly name: string;
@@ -51,8 +56,13 @@ export declare class CommandExternalExtractor implements ExternalExtractor {
     private interpolate;
     private checkAvailable;
 }
+/** 外部解析器注册表，管理所有已注册的外部解析器 */
 export declare class ExternalExtractorRegistry {
     private readonly extractors;
+    /**
+     * 根据环境变量自动注册可用解析器
+     * @param env 环境变量（默认 process.env）
+     */
     static fromEnvironment(env?: NodeJS.ProcessEnv): ExternalExtractorRegistry;
     register(extractor: ExternalExtractor): void;
     findAll(file: ClassifiedFile): ExternalExtractor[];

package/dist/extraction/external-extractor.js

@@ -1,5 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import * as path from 'node:path';
+/** 命令行外部解析器，通过调用外部命令提取文件内容 */
 export class CommandExternalExtractor {
     id;
     name;
@@ -87,8 +88,13 @@ export class CommandExternalExtractor {
         return !result.error;
     }
 }
+/** 外部解析器注册表，管理所有已注册的外部解析器 */
 export class ExternalExtractorRegistry {
     extractors = [];
+    /**
+     * 根据环境变量自动注册可用解析器
+     * @param env 环境变量（默认 process.env）
+     */
     static fromEnvironment(env = process.env) {
         const registry = new ExternalExtractorRegistry();
         registry.registerConfiguredOrAuto('cad-dwg', 'DWG Advanced Parser', env.CUSTOMIZE_AGENT_DWG_PARSER, [{ command: 'dwg-parser' }, { command: 'oda-dwg-parser' }], { category: 'cad', formats: ['autocad'], extensions: ['.dwg', '.dwt'] });

package/dist/extraction/module-resolver.js

@@ -37,7 +37,7 @@ function findInPnpm(packageName) {
                     }
                 }
             }
-            catch { /* continue upward */ }
+            catch { /* 继续向上遍历 */ }
         }
         const parent = path.dirname(dir);
         if (parent === dir)
@@ -54,7 +54,7 @@ export function resolvePackage(specifier) {
     try {
         return localRequire.resolve(specifier);
     }
-    catch { /* fall through */ }
+    catch { /* 继续尝试后续回退方式 */ }
     const parts = specifier.split('/');
     let packageName;
     if (parts[0]?.startsWith('@')) {

package/dist/index.js

@@ -1,5 +1,5 @@
-// Types and constants from types.ts and constants.ts are not exported
-// as they are only used internally within the knowledge package.
+// types.ts 和 constants.ts 中的类型和常量不对外导出
+// 它们仅在 knowledge 包内部使用。
 export { TextChunker } from './chunking/text-chunker.js';
 export { FileClassifier } from './classification/classifier.js';
 export { DedupEngine } from './dedup/dedup-engine.js';

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

@@ -1,5 +1,7 @@
 import type { VectorStoreInterface } from '../vector/types.js';
+/** 搜索范围：项目级、全局级或全部 */
 export type SearchScope = 'project' | 'global' | 'all';
+/** 联合搜索结果项 */
 export interface FederatedSearchItem {
     id: string;
     rowid?: number;
@@ -26,6 +28,7 @@ export interface FederatedSearchItem {
     };
     facets?: Record<string, string | number | string[]>;
 }
+/** 联合搜索结果 */
 export interface FederatedResult {
     results: FederatedSearchItem[];
     scopesSearched: Array<'project' | 'global'>;
@@ -38,16 +41,19 @@ export interface FederatedResult {
         reranker?: string;
     };
 }
+/** 搜索过滤器 */
 export interface SearchFilters {
     category?: string;
     filePath?: string;
 }
+/** 各检索方式权重配置 */
 export interface RetrievalWeights {
     keyword?: number;
     vector?: number;
     rewrite?: number;
     hybridBonus?: number;
 }
+/** 联合搜索查询参数 */
 export interface FederatedQuery {
     query: string;
     queryEmbedding: number[];
@@ -57,6 +63,7 @@ export interface FederatedQuery {
     collections?: string[];
     filters?: SearchFilters;
 }
+/** 联合搜索器，支持跨向量存储的分布式搜索和结果合并 */
 export declare class FederationSearch {
     private readonly vectorStores;
     static readonly SCOPE_WEIGHTS: Record<'project' | 'global', number>;

package/dist/search/federation-search.js

@@ -1,5 +1,6 @@
 import { ALL_CATEGORIES } from '../constants.js';
 import { globalCollectionName, projectCollectionName } from '../vector/collection-manager.js';
+/** 联合搜索器，支持跨向量存储的分布式搜索和结果合并 */
 export class FederationSearch {
     vectorStores;
     static SCOPE_WEIGHTS = {

package/dist/types.d.ts

@@ -1,6 +1,10 @@
+/** 知识库作用域：项目级、全局级或会话级 */
 export type KBScope = 'project' | 'global' | 'session';
+/** 文件分类枚举 */
 export type FileCategory = 'document' | 'spreadsheet' | 'image' | 'cad' | 'code' | 'data' | 'web' | 'diagram' | 'archive' | 'other';
+/** 项目状态：活跃、空闲或错误 */
 export type ProjectStatus = 'active' | 'idle' | 'error';
+/** 项目信息 */
 export interface ProjectInfo {
     projectId: string;
     projectRoot: string;
@@ -13,6 +17,7 @@ export interface ProjectInfo {
     lastOpenedAt: number;
     status: ProjectStatus;
 }
+/** 项目配置 */
 export interface ProjectConfig {
     projectId: string;
     projectName?: string;
@@ -27,6 +32,7 @@ export interface ProjectConfig {
     createdAt: number;
     lastOpenedAt: number;
 }
+/** 已分类的文件信息 */
 export interface ClassifiedFile {
     absolutePath: string;
     relativePath: string;
@@ -36,6 +42,7 @@ export interface ClassifiedFile {
     mtime: number;
     mimeType: string;
 }
+/** 索引状态记录 */
 export interface IndexStateRecord {
     relativePath: string;
     category: FileCategory;
@@ -51,6 +58,7 @@ export interface IndexStateRecord {
     errorMessage?: string;
     metadataJson?: string;
 }
+/** 文件差异对比结果 */
 export interface DiffResult {
     newFiles: ClassifiedFile[];
     modifiedFiles: ClassifiedFile[];
@@ -64,6 +72,7 @@ export interface DiffResult {
     hasChanges: boolean;
     diffTimeMs: number;
 }
+/** 知识库统计信息 */
 export interface KnowledgeBaseStats {
     scope: Exclude<KBScope, 'session'>;
     projectId?: string;
@@ -72,6 +81,7 @@ export interface KnowledgeBaseStats {
     totalSizeBytes: number;
     lastIndexedAt: number;
 }
+/** 跨项目重复文件检测结果 */
 export interface CrossProjectDuplicate {
     contentHash: string;
     files: Array<{

package/dist/vector/collection-manager.d.ts

@@ -1,7 +1,10 @@
 import type { FileCategory } from '../types.js';
 import type { CollectionClient } from './types.js';
+/** 生成项目级 Collection 名称 */
 export declare function projectCollectionName(projectId: string, category: FileCategory): string;
+/** 生成全局 Collection 名称 */
 export declare function globalCollectionName(category: FileCategory): string;
+/** Collection 管理器，负责 Vector Collection 的创建和管理 */
 export declare class CollectionManager {
     private readonly client?;
     constructor(client?: CollectionClient | undefined);

package/dist/vector/collection-manager.js

@@ -1,10 +1,13 @@
 import { ALL_CATEGORIES, COLLECTION_CATEGORY_NAMES } from '../constants.js';
+/** 生成项目级 Collection 名称 */
 export function projectCollectionName(projectId, category) {
     return `proj_${projectId}_kb_${COLLECTION_CATEGORY_NAMES[category]}`;
 }
+/** 生成全局 Collection 名称 */
 export function globalCollectionName(category) {
     return `global_kb_${COLLECTION_CATEGORY_NAMES[category]}`;
 }
+/** Collection 管理器，负责 Vector Collection 的创建和管理 */
 export class CollectionManager {
     client;
     constructor(client) {

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

@@ -1,4 +1,5 @@
 import type { VectorDocument, VectorSearchQuery, VectorSearchResult, VectorStoreInterface } from './types.js';
+/** HNSW（分层可导航小世界图）向量存储，基于 hnswlib-node 实现的高效近似最近邻搜索 */
 export declare class HNSWVectorStore implements VectorStoreInterface {
     readonly collectionName: string;
     private readonly indexPath;

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

@@ -2,6 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
+/** HNSW（分层可导航小世界图）向量存储，基于 hnswlib-node 实现的高效近似最近邻搜索 */
 export class HNSWVectorStore {
     collectionName;
     indexPath;
@@ -57,7 +58,7 @@ export class HNSWVectorStore {
                     this.index.markDelete(rowid);
                     this.deletedSinceRebuild += 1;
                 }
-                catch { /* ignore missing labels */ }
+                catch { /* 忽略缺失的标签 */ }
                 this.documents.delete(rowid);
             }
         }

package/dist/vector/types.d.ts

@@ -1,24 +1,29 @@
+/** 向量文档，包含文本内容、嵌入向量和元数据 */
 export interface VectorDocument {
     id: string;
     content: string;
     embedding: number[];
     metadata: Record<string, string | number | boolean | null>;
 }
+/** 向量搜索查询参数 */
 export interface VectorSearchQuery {
     queryEmbedding: number[];
     topK: number;
     where?: Record<string, string | number | boolean>;
 }
+/** 向量搜索结果 */
 export interface VectorSearchResult {
     document: Omit<VectorDocument, 'embedding'>;
     score: number;
     collection: string;
 }
+/** Vector Collection 信息 */
 export interface VectorCollectionInfo {
     id?: string;
     name: string;
     metadata?: Record<string, unknown>;
 }
+/** 向量存储接口，定义所有向量存储实现必须支持的方法 */
 export interface VectorStoreInterface {
     readonly collectionName: string;
     ensureCollection(metadata?: Record<string, unknown>): Promise<void>;
@@ -28,6 +33,7 @@ export interface VectorStoreInterface {
     needsRebuild?(): boolean;
     search(query: VectorSearchQuery): Promise<VectorSearchResult[]>;
 }
+/** Collection Client 接口，用于管理远程 Vector Collection */
 export interface CollectionClient {
     getOrCreateCollection(name: string, metadata?: Record<string, unknown>): Promise<VectorCollectionInfo>;
     listCollections(): Promise<VectorCollectionInfo[]>;

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

@@ -1,17 +1,29 @@
 import type { EmbeddingProvider } from '../embedding/embedding-provider.js';
 import type { StoredChunk } from '../core/index-state-store.js';
 import type { VectorStoreInterface } from './types.js';
+/** 向量索引结果 */
 export interface VectorIndexResult {
     collectionName: string;
     chunkCount: number;
     embeddingModel: string;
     embeddingDimension: number;
 }
+export interface VectorIndexProgress {
+    collectionName: string;
+    processedChunks: number;
+    totalChunks: number;
+    batchSize: number;
+}
+export interface VectorIndexOptions {
+    batchSize?: number;
+    onProgress?: (progress: VectorIndexProgress) => void;
+}
+/** 向量索引器，负责将文本切片生成 Embedding 并写入向量存储 */
 export declare class VectorIndexer {
     private readonly embeddingProvider;
     private readonly vectorStores;
     constructor(embeddingProvider: EmbeddingProvider, vectorStores: Map<string, VectorStoreInterface>);
-    indexChunks(chunks: StoredChunk[]): Promise<VectorIndexResult[]>;
+    indexChunks(chunks: StoredChunk[], options?: VectorIndexOptions): Promise<VectorIndexResult[]>;
     deleteFile(collectionName: string, filePath: string): Promise<void>;
     private embedDocuments;
     private isValidEmbeddings;

package/dist/vector/vector-indexer.js

@@ -1,3 +1,10 @@
+function resolveVectorIndexBatchSize(configured) {
+    const raw = configured ?? Number(process.env.CUSTOMIZE_VECTOR_INDEX_BATCH_SIZE ?? process.env.KB_VECTOR_INDEX_BATCH_SIZE);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return 32;
+    return Math.max(1, Math.min(256, Math.floor(raw)));
+}
+/** 向量索引器，负责将文本切片生成 Embedding 并写入向量存储 */
 export class VectorIndexer {
     embeddingProvider;
     vectorStores;
@@ -5,24 +12,34 @@ export class VectorIndexer {
         this.embeddingProvider = embeddingProvider;
         this.vectorStores = vectorStores;
     }
-    async indexChunks(chunks) {
+    async indexChunks(chunks, options = {}) {
         const byCollection = this.groupByCollection(chunks);
         const results = [];
+        const totalChunks = chunks.length;
+        let processedTotalChunks = 0;
         for (const [collectionName, collectionChunks] of byCollection) {
             const store = this.vectorStores.get(collectionName);
             if (!store)
                 continue;
-            const texts = collectionChunks.map(chunk => chunk.content);
-            const embeddings = await this.embedDocuments(texts);
             await store.ensureCollection({
                 embedding_model: this.embeddingProvider.model,
                 embedding_dimension: this.embeddingProvider.dimensions,
             });
-            const documents = collectionChunks.map((chunk, index) => this.toVectorDocument(chunk, embeddings[index] ?? []));
-            await store.upsert(documents);
+            const batchSize = resolveVectorIndexBatchSize(options.batchSize);
+            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 embeddings = await this.embedDocuments(texts);
+                const documents = batchChunks.map((chunk, index) => this.toVectorDocument(chunk, embeddings[index] ?? []));
+                await store.upsert(documents);
+                processedChunks += documents.length;
+                processedTotalChunks += documents.length;
+                options.onProgress?.({ collectionName, processedChunks: processedTotalChunks, totalChunks, batchSize: documents.length });
+            }
             results.push({
                 collectionName,
-                chunkCount: documents.length,
+                chunkCount: processedChunks,
                 embeddingModel: this.embeddingProvider.model,
                 embeddingDimension: this.embeddingProvider.dimensions,
             });

package/package.json

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