@huyooo/ai-search 0.2.17 → 0.2.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huyooo/ai-search",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "本地文档语义搜索引擎 - 支持 Word、PDF、Excel、TXT、MD",
   "type": "module",
   "main": "./dist/index.js",
@@ -91,7 +91,7 @@
     "embedding"
   ],
   "author": "huyooo",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {
     "access": "public"
   }

package/README.md

@@ -1,431 +0,0 @@
-# @huyooo/ai-search
-
-本地文档语义搜索引擎，支持 Word、PDF、Excel、TXT、MD 等文档格式。
-
-## 特性
-
-- 🔍 **语义搜索**：基于向量的语义理解，不仅仅是关键词匹配
-- 📄 **多格式支持**：Word (.docx/.doc)、PDF、Excel (.xlsx/.xls)、PPT (.pptx/.ppt)、TXT、MD
-- 🏠 **本地优先**：所有数据存储在本地，保护隐私
-- ⚡ **高性能**：LanceDB 向量搜索 + FlexSearch 全文检索
-- 🤖 **AI 集成**：可作为 AI Agent 工具使用
-- 🔗 **兼容 file-explorer**：搜索结果兼容 FileItem 数据结构
-
-## 安装
-
-```bash
-npm install @huyooo/ai-search
-```
-
-## 快速开始
-
-### 环境变量
-
-使用前需要设置豆包 API Key：
-
-```bash
-export ARK_API_KEY=your_api_key_here
-```
-
-### 基础使用
-
-```typescript
-import { DocumentSearch } from '@huyooo/ai-search'
-
-// 创建搜索引擎
-const search = new DocumentSearch({
-  dataDir: './search-data',  // 索引数据存储目录
-  // arkApiKey: 'your_key',  // 也可以直接传入，默认从环境变量读取
-  // embeddingDimension: 1024,  // 向量维度（可选，默认 1024）
-})
-
-// 初始化
-await search.init()
-
-// 索引目录
-await search.indexDirectory('~/Documents')
-
-// 搜索
-const results = await search.search('去年的采购合同')
-
-console.log(results)
-// [
-//   {
-//     id: '/Users/xxx/Documents/采购合同.docx',
-//     name: '采购合同.docx',
-//     type: 'document',
-//     size: '1.2 MB',
-//     dateModified: '2024-03-15',
-//     score: 0.92,
-//     snippet: '...甲方与乙方就采购事宜...',
-//   },
-//   ...
-// ]
-```
-
-### 作为 AI Agent 工具（推荐）
-
-```typescript
-import { searchPlugin } from '@huyooo/ai-search'
-
-// Vite 插件风格 API
-const plugin = await searchPlugin({
-  dataDir: './search-data',
-  workspace: '~/Documents', // 可选：初始工作空间
-})
-
-// 注册工具到 Agent
-agent.registerTools(plugin.tools)
-
-// Agent 现在可以使用所有工具，包括：
-// - search_local_documents: 搜索文档
-// - index_document_file: 索引单个文件
-// - index_document_directory: 索引目录
-// - index_document_files: 批量索引文件
-// - watch_document_directory: 监听目录变化
-// - export_document_index: 导出索引
-// - optimize_document_index: 优化索引
-// ... 等 20+ 个工具
-```
-
-### 搜索选项
-
-```typescript
-const results = await search.search('合同', {
-  limit: 20,                    // 返回数量
-  mode: 'hybrid',               // semantic | keyword | hybrid
-  fileTypes: ['document', 'pdf'], // 文件类型过滤
-  dateRange: {                  // 时间范围
-    start: new Date('2024-01-01'),
-    end: new Date('2024-12-31'),
-  },
-  directories: ['/path/to/docs'], // 目录过滤
-  sizeRange: {                  // 文件大小过滤
-    min: 1024,                  // 最小 1KB
-    max: 10 * 1024 * 1024,      // 最大 10MB
-  },
-  fileNamePattern: '*.pdf',     // 文件名模式（通配符）
-  titleContains: '合同',         // 标题包含
-  combineMode: 'AND',           // 组合条件模式
-})
-```
-
-### 文件监听和自动更新
-
-```typescript
-// 监听目录变化，自动更新索引
-search.watchDirectory('/path/to/documents', {
-  ignoreInitial: true,  // 忽略初始扫描
-  debounce: 1000,       // 防抖延迟（毫秒）
-  onEvent: (event) => {
-    console.log('文件变化:', event.type, event.path)
-  },
-})
-
-// 停止监听
-search.unwatchDirectory('/path/to/documents')
-
-// 获取正在监听的目录
-const watched = search.getWatchedDirectories()
-```
-
-### 批量操作
-
-```typescript
-// 批量索引文件
-const result = await search.indexFiles([
-  '/path/to/file1.pdf',
-  '/path/to/file2.docx',
-], (progress) => {
-  console.log(`进度: ${progress.indexed}/${progress.total}`)
-})
-
-// 批量删除索引
-await search.removeFiles(['/path/to/file1.pdf', '/path/to/file2.docx'])
-
-// 批量更新索引（重新索引）
-await search.updateFiles(['/path/to/file1.pdf'])
-```
-
-### 索引导出和导入
-
-```typescript
-// 导出索引（备份）
-const exportInfo = await search.exportIndex('./backup/search-index')
-
-// 导入索引（恢复）
-await search.importIndex('./backup/search-index')
-
-// 列出备份
-const backups = await search.listBackups('./backup')
-```
-
-### 索引优化和维护
-
-```typescript
-// 清理无效索引（文件已删除但索引还在）
-const result = await search.cleanup()
-console.log(`清理了 ${result.removed} 个无效索引`)
-
-// 优化索引（压缩、碎片整理）
-await search.optimize()
-
-// 健康检查
-const health = await search.healthCheck()
-if (!health.healthy) {
-  console.log('索引存在问题，建议执行 optimize')
-}
-
-// 获取索引错误
-const errors = search.getIndexErrors()
-
-// 重试失败的索引
-await search.retryFailedIndexes()
-```
-
-## API
-
-### DocumentSearch
-
-```typescript
-class DocumentSearch {
-  constructor(config: SearchConfig)
-  
-  // ========== 初始化 ==========
-  init(): Promise<void>
-  
-  // ========== 索引 ==========
-  // 单文件索引
-  indexFile(filePath: string, retryCount?: number): Promise<void>
-  
-  // 目录索引
-  indexDirectory(
-    dir: string, 
-    onProgress?: (p: IndexProgress) => void
-  ): Promise<void>
-  
-  // 索引默认目录
-  indexDefaultDirectories(
-    onProgress?: (p: IndexProgress) => void
-  ): Promise<void>
-  
-  // 批量索引
-  indexFiles(
-    filePaths: string[],
-    onProgress?: (p: IndexProgress) => void
-  ): Promise<BatchOperationResult>
-  
-  // ========== 搜索 ==========
-  search(query: string, options?: SearchOptions): Promise<SearchResult[]>
-  
-  // ========== 文件监听 ==========
-  watchDirectory(directory: string, options?: WatchOptions): void
-  unwatchDirectory(directory: string): void
-  unwatchAll(): void
-  getWatchedDirectories(): string[]
-  
-  // ========== 批量操作 ==========
-  removeFiles(filePaths: string[]): Promise<BatchOperationResult>
-  updateFiles(
-    filePaths: string[],
-    onProgress?: (p: IndexProgress) => void
-  ): Promise<BatchOperationResult>
-  
-  // ========== 索引管理 ==========
-  removeFile(filePath: string): Promise<void>
-  getStats(): IndexStats
-  clear(): Promise<void>
-  save(): Promise<void>
-  
-  // ========== 索引优化 ==========
-  cleanup(): Promise<{ removed: number; updated: number }>
-  optimize(): Promise<void>
-  healthCheck(): Promise<HealthCheckResult>
-  
-  // ========== 错误处理 ==========
-  getIndexErrors(): IndexError[]
-  retryFailedIndexes(): Promise<BatchOperationResult>
-  
-  // ========== 导出/导入 ==========
-  exportIndex(outputPath: string): Promise<ExportInfo>
-  importIndex(inputPath: string): Promise<void>
-  listBackups(backupDir: string): Promise<BackupInfo[]>
-  
-  // ========== 资源清理 ==========
-  destroy(): Promise<void>
-}
-```
-
-### SearchResult（兼容 FileItem）
-
-```typescript
-interface SearchResult {
-  // 与 file-explorer FileItem 兼容
-  id: string           // 文件路径
-  name: string         // 文件名
-  type: FileType       // 文件类型
-  size?: string        // 格式化大小
-  dateModified?: string// 格式化日期
-  url?: string         // file:// URL
-  
-  // 搜索特有字段
-  score: number        // 相关度分数 (0-1)
-  snippet?: string     // 匹配摘要
-  matchType: 'semantic' | 'keyword' | 'hybrid'
-}
-```
-
-### SearchOptions
-
-```typescript
-interface SearchOptions {
-  limit?: number                    // 返回数量限制
-  mode?: 'semantic' | 'keyword' | 'hybrid'  // 搜索模式
-  fileTypes?: FileType[]            // 文件类型过滤
-  dateRange?: {                     // 时间范围过滤
-    start?: Date
-    end?: Date
-  }
-  directories?: string[]            // 目录过滤
-  sizeRange?: {                     // 文件大小过滤
-    min?: number                    // 字节
-    max?: number                    // 字节
-  }
-  fileNamePattern?: string          // 文件名模式（通配符 * ?）
-  titleContains?: string            // 文档标题包含
-  combineMode?: 'AND' | 'OR'        // 组合条件模式
-}
-```
-
-### SearchConfig
-
-```typescript
-interface SearchConfig {
-  dataDir: string                   // 索引数据存储目录
-  indexDirectories?: string[]        // 索引目录列表
-  excludeDirs?: string[]            // 排除目录
-  extensions?: string[]             // 支持的扩展名
-  maxFileSize?: number              // 最大文件大小（字节）
-  embeddingModel?: string           // Embedding 模型（默认 doubao-embedding-vision-250615）
-  arkApiKey?: string                // 豆包 API Key（也可通过环境变量 ARK_API_KEY 设置）
-  embeddingDimension?: number       // 向量维度（默认 1024）
-}
-```
-
-### AI Agent 工具列表
-
-使用 `searchPlugin` 后，Agent 可以使用以下工具：
-
-#### 搜索相关
-- `search_local_documents` - 搜索文档
-
-#### 索引相关
-- `index_document_file` - 索引单个文件
-- `index_document_directory` - 索引目录
-- `index_document_files` - 批量索引文件
-- `update_document_files` - 批量更新索引
-
-#### 工作空间管理
-- `set_search_workspace` - 设置工作空间
-- `get_search_workspace` - 获取工作空间状态
-
-#### 文件监听
-- `watch_document_directory` - 监听目录变化
-- `unwatch_document_directory` - 停止监听
-- `get_watched_directories` - 获取监听列表
-
-#### 索引管理
-- `get_document_index_stats` - 获取统计信息
-- `clear_document_index` - 清空索引
-- `remove_document_files` - 批量删除索引
-
-#### 索引优化
-- `cleanup_document_index` - 清理无效索引
-- `optimize_document_index` - 优化索引
-- `check_document_index_health` - 健康检查
-
-#### 错误处理
-- `get_document_index_errors` - 获取索引错误
-- `retry_failed_document_indexes` - 重试失败索引
-
-#### 导出/导入
-- `export_document_index` - 导出索引
-- `import_document_index` - 导入索引
-- `list_document_index_backups` - 列出备份
-```
-
-## 特性详解
-
-### 🔄 增量索引
-- 自动检测文件变化（路径 + 修改时间 + 文件大小）
-- 文件未变化时跳过索引，提升性能
-- 支持内容哈希去重，相同内容复用索引
-
-### 📁 文件监听
-- 自动监听目录变化
-- 新增/修改文件自动索引
-- 删除文件自动清理索引
-- 支持防抖，避免频繁触发
-
-### 🚀 批量操作
-- 批量索引、删除、更新
-- 支持进度回调
-- 错误处理和重试机制
-
-### 💾 索引管理
-- 导出/导入索引（备份和恢复）
-- 索引优化和维护
-- 健康检查和错误恢复
-
-## 技术栈
-
-| 组件 | 技术 |
-|-----|-----|
-| 向量存储 | LanceDB |
-| 全文搜索 | FlexSearch |
-| 元数据存储 | SQLite (better-sqlite3) |
-| 文本向量化 | 豆包 doubao-embedding-vision-250615（多模态） |
-| 中文分词 | nodejieba |
-| 文档解析 | mammoth, pdf-parse, xlsx |
-| 文件扫描 | fdir |
-| 文件监听 | chokidar |
-
-## 向量化模型
-
-使用字节跳动的 **doubao-embedding-vision-250615** 多模态向量化模型：
-
-- 支持文本、图片、视频向量化
-- 支持多模态混合输入
-- 默认 1024 维向量（可配置）
-- 需要豆包 API Key（ARK_API_KEY）
-
-### 高级向量化 API
-
-```typescript
-import { 
-  embed,           // 文本向量化
-  embedImage,      // 图片向量化
-  embedVideo,      // 视频向量化
-  embedMultimodal, // 多模态混合
-} from '@huyooo/ai-search'
-
-// 文本向量化
-const textVector = await embed('天很蓝，海很深')
-
-// 图片向量化
-const imageVector = await embedImage('https://example.com/image.jpg')
-
-// 视频向量化
-const videoVector = await embedVideo('https://example.com/video.mp4')
-
-// 多模态混合
-const mixedVector = await embedMultimodal([
-  { type: 'text', text: '这是什么？' },
-  { type: 'image_url', image_url: { url: 'https://example.com/image.jpg' } },
-])
-```
-
-## 许可证
-
-MIT
-