@huyooo/ai-search 0.2.1

package/dist/index-B6UR8lRu.d.ts

@@ -0,0 +1,576 @@
+import { ToolPlugin, Tool } from '@huyooo/ai-chat-core';
+
+/**
+ * 文件类型（与 file-explorer 兼容）
+ */
+declare const FileType: {
+    readonly FOLDER: "folder";
+    readonly FILE: "file";
+    readonly IMAGE: "image";
+    readonly VIDEO: "video";
+    readonly MUSIC: "music";
+    readonly DOCUMENT: "document";
+    readonly CODE: "code";
+    readonly TEXT: "text";
+    readonly PDF: "pdf";
+    readonly ARCHIVE: "archive";
+    readonly APPLICATION: "application";
+    readonly UNKNOWN: "unknown";
+};
+type FileType = (typeof FileType)[keyof typeof FileType];
+/**
+ * 搜索结果（兼容 file-explorer 的 FileItem）
+ */
+interface SearchResult {
+    /** 唯一标识（文件路径） */
+    id: string;
+    /** 文件名 */
+    name: string;
+    /** 文件类型 */
+    type: FileType;
+    /** 格式化后的文件大小 */
+    size?: string;
+    /** 格式化后的修改日期 */
+    dateModified?: string;
+    /** 文件 URL */
+    url?: string;
+    /** 缩略图 URL（文档类型通常没有） */
+    thumbnailUrl?: string;
+    /** 相关度分数 0-1 */
+    score: number;
+    /** 匹配文本摘要 */
+    snippet?: string;
+    /** 匹配类型 */
+    matchType: 'semantic' | 'keyword' | 'hybrid';
+    /** 匹配的块索引（分块后可用） */
+    chunkIndex?: number;
+}
+/**
+ * 索引项（内部使用）
+ */
+interface IndexedDocument {
+    /** 唯一 ID */
+    id: string;
+    /** 文件路径 */
+    path: string;
+    /** 文件名 */
+    name: string;
+    /** 文件类型 */
+    fileType: FileType;
+    /** 文件扩展名 */
+    extension: string;
+    /** 文档标题（从内容提取） */
+    title?: string;
+    /** 文档内容（用于全文搜索） */
+    content: string;
+    /** 文件大小（字节） */
+    fileSize: number;
+    /** 创建时间 */
+    createdAt: Date;
+    /** 修改时间 */
+    modifiedAt: Date;
+    /** 索引时间 */
+    indexedAt: Date;
+    /** 内容哈希（用于检测变更） */
+    contentHash: string;
+    /** 分块数量（用于清理旧数据） */
+    chunkCount?: number;
+}
+/**
+ * 搜索配置
+ */
+interface SearchConfig {
+    /** 数据存储目录 */
+    dataDir: string;
+    /** 索引目录列表 */
+    indexDirectories?: string[];
+    /** 排除目录 */
+    excludeDirs?: string[];
+    /** 支持的扩展名 */
+    extensions?: string[];
+    /** 最大文件大小（字节） */
+    maxFileSize?: number;
+    /** Embedding 模型（默认 doubao-embedding-vision-250615） */
+    embeddingModel?: string;
+    /** 豆包 API Key（ARK_API_KEY），也可通过环境变量设置 */
+    arkApiKey?: string;
+    /** 向量维度（默认 1024） */
+    embeddingDimension?: number;
+    /** 并行索引并发数（默认 5） */
+    indexConcurrency?: number;
+    /** 是否启用并行索引（默认 true） */
+    enableParallelIndexing?: boolean;
+}
+/**
+ * 搜索选项
+ */
+interface SearchOptions {
+    /** 返回数量限制 */
+    limit?: number;
+    /** 文件类型过滤 */
+    fileTypes?: FileType[];
+    /** 时间范围过滤 */
+    dateRange?: {
+        start?: Date;
+        end?: Date;
+    };
+    /** 目录过滤 */
+    directories?: string[];
+    /** 搜索模式 */
+    mode?: 'semantic' | 'keyword' | 'hybrid';
+    /** 文件大小过滤 */
+    sizeRange?: {
+        min?: number;
+        max?: number;
+    };
+    /** 文件名模式过滤（支持通配符 * 和 ?） */
+    fileNamePattern?: string;
+    /** 文档标题包含 */
+    titleContains?: string;
+    /** 组合条件模式 */
+    combineMode?: 'AND' | 'OR';
+}
+/**
+ * 索引进度回调
+ */
+interface IndexProgress {
+    /** 当前已索引数量 */
+    indexed: number;
+    /** 总文件数量 */
+    total: number;
+    /** 当前正在处理的文件 */
+    currentFile?: string;
+    /** 阶段 */
+    stage: 'scanning' | 'parsing' | 'embedding' | 'storing' | 'done' | 'cancelled';
+}
+/**
+ * 索引统计
+ */
+interface IndexStats {
+    /** 总文档数 */
+    totalDocuments: number;
+    /** 按类型统计 */
+    byType: Record<FileType, number>;
+    /** 索引目录 */
+    directories: string[];
+    /** 最后更新时间 */
+    lastUpdated?: Date;
+    /** 索引大小（字节） */
+    indexSize: number;
+}
+/**
+ * 文件监听选项
+ */
+interface WatchOptions {
+    /** 是否忽略初始扫描（只监听后续变化） */
+    ignoreInitial?: boolean;
+    /** 防抖延迟（毫秒），避免频繁触发 */
+    debounce?: number;
+    /** 监听事件回调 */
+    onEvent?: (event: WatchEvent) => void;
+}
+/**
+ * 文件监听事件
+ */
+interface WatchEvent {
+    /** 事件类型 */
+    type: 'add' | 'change' | 'unlink' | 'unlinkDir';
+    /** 文件路径 */
+    path: string;
+    /** 时间戳 */
+    timestamp: Date;
+}
+/**
+ * 批量操作结果
+ */
+interface BatchOperationResult {
+    /** 成功数量 */
+    success: number;
+    /** 失败数量 */
+    failed: number;
+    /** 失败的文件路径和错误信息 */
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+/**
+ * 索引导出信息
+ */
+interface ExportInfo {
+    /** 导出路径 */
+    exportPath: string;
+    /** 导出时间 */
+    timestamp: Date;
+    /** 包含的组件 */
+    components: {
+        meta: boolean;
+        vectors: boolean;
+        fulltext: boolean;
+    };
+    /** 统计信息 */
+    stats: IndexStats;
+}
+/**
+ * 备份信息
+ */
+interface BackupInfo {
+    /** 备份路径 */
+    path: string;
+    /** 备份时间 */
+    timestamp: Date;
+    /** 备份大小（字节） */
+    size: number;
+}
+/**
+ * 索引错误信息
+ */
+interface IndexError {
+    /** 文件路径 */
+    filePath: string;
+    /** 错误信息 */
+    error: string;
+    /** 重试次数 */
+    retryCount: number;
+    /** 时间戳 */
+    timestamp: Date;
+}
+/**
+ * 健康检查结果
+ */
+interface HealthCheckResult {
+    /** 是否健康 */
+    healthy: boolean;
+    /** 总文档数 */
+    totalDocuments: number;
+    /** 无效索引数（文件不存在） */
+    invalidIndexes: number;
+    /** 过期索引数（文件已修改） */
+    staleIndexes: number;
+    /** 错误数 */
+    errorCount: number;
+    /** 索引完整性 */
+    integrity: {
+        meta: boolean;
+        vectors: boolean;
+        fulltext: boolean;
+    };
+}
+/**
+ * 默认配置
+ * 注意：详细的排除规则和文件类型规则现在由 rules.ts 中的规则管理器统一管理
+ * 这里的配置主要用于向后兼容和简单配置场景
+ */
+declare const DEFAULT_CONFIG: Partial<SearchConfig>;
+
+/**
+ * 文本分块模块
+ * 递归语义分割，保持上下文连贯性
+ */
+interface ChunkOptions {
+    /** 目标块大小（字符数） */
+    chunkSize?: number;
+    /** 重叠大小（字符数） */
+    overlap?: number;
+    /** 最小块大小（小于此值会合并到上一块） */
+    minChunkSize?: number;
+}
+interface TextChunk {
+    /** 块内容 */
+    content: string;
+    /** 块索引（从 0 开始） */
+    index: number;
+    /** 在原文中的起始位置 */
+    startOffset: number;
+    /** 在原文中的结束位置 */
+    endOffset: number;
+}
+/**
+ * 递归文本分块
+ *
+ * 算法：
+ * 1. 尝试用当前分隔符切分文本
+ * 2. 如果块太大，用下一个分隔符继续切分
+ * 3. 合并小块，添加重叠
+ */
+declare function splitText(text: string, options?: ChunkOptions): TextChunk[];
+/**
+ * 获取分块统计信息
+ */
+declare function getChunkStats(chunks: TextChunk[]): {
+    count: number;
+    avgSize: number;
+    minSize: number;
+    maxSize: number;
+    totalSize: number;
+};
+
+/**
+ * 索引流水线 - 支持文本分块
+ *
+ * 设计原则：
+ * 1. 一个文件 → 多个 chunk → 多个向量
+ * 2. 并发执行文件处理，每完成一个文件进度 +1
+ * 3. 分块后每个 chunk 单独向量化，提高检索精度
+ */
+
+/** 流水线配置 */
+interface PipelineConfig {
+    /** 并发数（同时处理的文件数） */
+    concurrency: number;
+    /** 分块配置（小于 chunkSize 的文档自然只有 1 个 chunk） */
+    chunk?: ChunkOptions;
+}
+/** 兼容旧接口 */
+interface EmbeddedDoc {
+    filePath: string;
+    content: string;
+    title: string;
+    contentHash: string;
+    vector: number[];
+    /** 新增：块信息 */
+    chunkIndex?: number;
+    totalChunks?: number;
+}
+/** 流水线统计 */
+interface PipelineStats {
+    totalFiles: number;
+    completed: number;
+    stored: number;
+    skipped: number;
+    failed: number;
+    totalTime: number;
+}
+/** 存储回调 */
+type StoreCallback = (doc: EmbeddedDoc) => Promise<{
+    stored: boolean;
+    skipped: boolean;
+}>;
+/** 跳过检查回调（基于 mtime） */
+type SkipCheckCallback = (filePath: string, mtime: Date) => boolean;
+/**
+ * 简化版索引流水线
+ */
+declare class IndexingPipeline {
+    private config;
+    private onProgress?;
+    private storeCallback?;
+    private skipCheck?;
+    private cancelled;
+    private stats;
+    constructor(config?: Partial<PipelineConfig>);
+    /** 取消正在执行的任务 */
+    cancel(): void;
+    /** 检查是否已取消 */
+    isCancelled(): boolean;
+    /**
+     * 处理单个文件（完整流程：解析 → 分块 → 嵌入 → 存储）
+     */
+    private processFile;
+    /**
+     * 执行流水线
+     */
+    run(files: string[], storeCallback: StoreCallback, onProgress?: (progress: IndexProgress) => void, skipCheck?: SkipCheckCallback): Promise<PipelineStats>;
+    /** 报告进度 */
+    private reportProgress;
+}
+/**
+ * 创建索引流水线
+ */
+declare function createIndexingPipeline(config?: Partial<PipelineConfig>): IndexingPipeline;
+
+declare class DocumentSearch {
+    private config;
+    private vectorStore;
+    private fullTextIndex;
+    private metaStore;
+    private initialized;
+    private directoryWatcher;
+    private indexErrors;
+    private maxRetries;
+    /** 索引锁：防止同一文件被并发索引 */
+    private indexingLocks;
+    /** 当前运行的流水线（用于取消） */
+    private currentPipeline;
+    constructor(config: SearchConfig);
+    /**
+     * 初始化搜索引擎
+     */
+    init(): Promise<void>;
+    /**
+     * 索引单个文件（带重试机制和并发安全）
+     */
+    indexFile(filePath: string, retryCount?: number): Promise<void>;
+    /**
+     * 索引目录（流水线架构）
+     * 三阶段并行处理：解析 → 嵌入 → 存储
+     * 智能增量索引：只处理新增、修改的文件，跳过未变化的文件
+     */
+    indexDirectory(directory: string, onProgress?: (progress: IndexProgress) => void, pipelineConfig?: Partial<PipelineConfig>): Promise<void>;
+    /**
+     * 取消正在进行的索引任务
+     * @returns 是否成功取消（如果没有运行中的任务则返回 false）
+     */
+    cancelIndexing(): boolean;
+    /**
+     * 检查是否正在索引
+     */
+    isIndexing(): boolean;
+    /**
+     * 索引默认目录
+     */
+    indexDefaultDirectories(onProgress?: (progress: IndexProgress) => void): Promise<void>;
+    /**
+     * 搜索文档
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * 检查文档是否匹配所有过滤条件
+     */
+    private matchesFilters;
+    /**
+     * 将通配符模式转换为正则表达式
+     * * 匹配任意字符
+     * ? 匹配单个字符
+     */
+    private wildcardToRegex;
+    /**
+     * 标准化向量搜索分数
+     * 将距离转换为 0-1 的相似度分数
+     */
+    private normalizeVectorScores;
+    /**
+     * 删除文件索引
+     */
+    removeFile(filePath: string): Promise<void>;
+    /**
+     * 获取统计信息
+     */
+    getStats(): IndexStats;
+    /**
+     * 清空所有索引
+     */
+    clear(): Promise<void>;
+    /**
+     * 保存索引
+     */
+    save(): Promise<void>;
+    /**
+     * 批量索引文件（根据配置自动选择串行或并行）
+     */
+    indexFiles(filePaths: string[], onProgress?: (progress: IndexProgress) => void): Promise<BatchOperationResult>;
+    /**
+     * 串行索引文件（原实现）
+     */
+    private indexFilesSerial;
+    /**
+     * 并行索引文件（控制并发数）
+     */
+    indexFilesParallel(filePaths: string[], onProgress?: (progress: IndexProgress) => void, concurrency?: number): Promise<BatchOperationResult>;
+    /**
+     * 批量删除文件索引
+     */
+    removeFiles(filePaths: string[]): Promise<BatchOperationResult>;
+    /**
+     * 批量更新文件索引（重新索引）
+     */
+    updateFiles(filePaths: string[], onProgress?: (progress: IndexProgress) => void): Promise<BatchOperationResult>;
+    /** 监听目录变化并自动更新索引 */
+    watchDirectory(directory: string, options?: WatchOptions): void;
+    /** 停止监听目录 */
+    unwatchDirectory(directory: string): void;
+    /** 停止所有监听 */
+    unwatchAll(): void;
+    /** 获取正在监听的目录列表 */
+    getWatchedDirectories(): string[];
+    /** 获取维护依赖 */
+    private getMaintenanceDeps;
+    /** 清理无效索引（文件已删除但索引还在） */
+    cleanup(): Promise<{
+        removed: number;
+        updated: number;
+    }>;
+    /** 优化索引（压缩、碎片整理） */
+    optimize(): Promise<void>;
+    /** 健康检查 */
+    healthCheck(): Promise<HealthCheckResult>;
+    /** 获取索引错误列表 */
+    getIndexErrors(): IndexError[];
+    /** 重试失败的索引 */
+    retryFailedIndexes(): Promise<BatchOperationResult>;
+    /** 确保已初始化 */
+    private ensureInitialized;
+    /** 获取备份依赖 */
+    private getBackupDeps;
+    /** 导出索引数据 */
+    exportIndex(outputPath: string): Promise<ExportInfo>;
+    /** 导入索引数据 */
+    importIndex(inputPath: string): Promise<void>;
+    /** 列出备份 */
+    listBackups(backupDir: string): Promise<BackupInfo[]>;
+    /** 销毁资源，释放所有占用的资源 */
+    destroy(): Promise<void>;
+}
+
+/**
+ * AI Agent 工具定义
+ *
+ * Vite 插件风格 API
+ */
+
+/** 工作空间状态 */
+interface WorkspaceState {
+    /** 当前工作空间目录 */
+    directory: string | null;
+    /** 是否已索引 */
+    indexed: boolean;
+    /** 索引文件数量 */
+    filesIndexed: number;
+}
+/** 搜索插件配置 */
+interface SearchPluginOptions {
+    /** 数据存储目录 */
+    dataDir: string;
+    /** 初始工作空间（可选，设置后自动索引） */
+    workspace?: string;
+    /** 豆包 API Key（用于向量化，也可通过环境变量 ARK_API_KEY 设置） */
+    arkApiKey?: string;
+    /** 向量维度（默认 1024） */
+    embeddingDimension?: number;
+}
+/** 搜索插件实例（扩展 ToolPlugin，兼容 Vite 插件风格） */
+interface SearchPluginInstance extends ToolPlugin {
+    /** AI Agent 工具数组 */
+    tools: Tool[];
+    /** 设置/切换工作空间 */
+    setWorkspace: (directory: string) => Promise<void>;
+    /** 获取工作空间状态 */
+    getWorkspaceState: () => WorkspaceState;
+    /** 底层 DocumentSearch 实例（高级用法） */
+    search: DocumentSearch;
+}
+/**
+ * 搜索插件（Vite 风格）
+ *
+ * @example
+ * ```typescript
+ * import { searchPlugin } from '@huyooo/ai-search';
+ *
+ * // 像 Vite 插件一样使用
+ * await createElectronBridge({
+ *   tools: [
+ *     getCwdTool,
+ *     searchPlugin({ dataDir, workspace }),  // 直接传入
+ *   ],
+ * });
+ *
+ * // 运行时控制（通过 getSearchPlugin 获取实例）
+ * import { getSearchPlugin } from '@huyooo/ai-search';
+ * await getSearchPlugin()?.setWorkspace('/new/path');
+ * ```
+ */
+declare function searchPlugin(options: SearchPluginOptions): Promise<SearchPluginInstance>;
+/** 获取搜索插件实例（用于运行时控制） */
+declare function getSearchPlugin(): SearchPluginInstance | null;
+
+export { type BatchOperationResult as B, type ChunkOptions as C, DocumentSearch as D, type ExportInfo as E, FileType as F, type HealthCheckResult as H, type IndexProgress as I, type PipelineConfig as P, type SearchConfig as S, type TextChunk as T, type WatchOptions as W, type IndexedDocument as a, type IndexStats as b, type SearchOptions as c, type SearchResult as d, type WatchEvent as e, type BackupInfo as f, type IndexError as g, DEFAULT_CONFIG as h, createIndexingPipeline as i, IndexingPipeline as j, type PipelineStats as k, type SkipCheckCallback as l, getChunkStats as m, searchPlugin as n, getSearchPlugin as o, type SearchPluginOptions as p, type SearchPluginInstance as q, splitText as s };