# 接口契约
<cite>
**本文档中引用的文件**
- [manager.ts](file://src/code-index/interfaces/manager.ts)
- [embedder.ts](file://src/code-index/interfaces/embedder.ts)
- [vector-store.ts](file://src/code-index/interfaces/vector-store.ts)
- [file-processor.ts](file://src/code-index/interfaces/file-processor.ts)
- [config.ts](file://src/code-index/interfaces/config.ts)
- [code-index/manager.ts](file://src/code-index/manager.ts)
- [code-index/embedders/openai-compatible.ts](file://src/code-index/embedders/openai-compatible.ts)
- [code-index/vector-store/qdrant-client.ts](file://src/code-index/vector-store/qdrant-client.ts)
- [code-index/processors/scanner.ts](file://src/code-index/processors/scanner.ts)
- [code-index/service-factory.ts](file://src/code-index/service-factory.ts)
</cite>
## 目录
1. [ICodeIndexManager 接口](#icodeindexmanager-接口)
2. [IEmbedder 接口](#iembedder-接口)
3. [IVectorStore 接口](#ivectorstore-接口)
4. [辅助接口](#辅助接口)
5. [实现与设计模式](#实现与设计模式)
## ICodeIndexManager 接口
`ICodeIndexManager` 接口是代码索引功能的核心契约，定义了 `CodeIndexManager` 类的公共 API。它作为系统的主要入口点，负责协调索引、搜索和状态管理等操作。
该接口的主要职责包括：
- **状态管理**：通过 `state` 属性提供索引过程的当前状态（如 "Standby", "Indexing", "Indexed", "Error"）。
- **功能开关**：通过 `isFeatureEnabled` 和 `isFeatureConfigured` 属性检查功能是否启用和配置。
- **生命周期控制**：提供 `startIndexing()` 和 `stopWatcher()` 方法来启动和停止索引进程。
- **数据管理**：提供 `clearIndexData()` 方法清除所有索引数据。
- **搜索功能**：提供 `searchIndex()` 方法执行向量搜索。
- **事件订阅**：通过 `onProgressUpdate` 事件，客户端可以订阅索引进度更新。
**Section sources**
- [manager.ts](file://src/code-index/interfaces/manager.ts#L9-L72)
- [code-index/manager.ts](file://src/code-index/manager.ts#L23-L351)
## IEmbedder 接口
`IEmbedder` 接口定义了代码嵌入（Embedding）服务的契约。它负责将文本（通常是代码片段）转换为高维浮点数向量，这是向量搜索的基础。
该接口的核心方法是 `createEmbeddings`，其规范如下：
- **输入**：一个字符串数组 `texts`，代表需要生成嵌入的代码片段或查询文本。
- **输出**：一个 `Promise<EmbeddingResponse>`，解析后包含嵌入向量数组和使用情况统计。
- **元数据**：通过 `embedderInfo` 属性提供嵌入器的元数据，如名称。
`EmbeddingResponse` 类型定义了响应结构，其中 `embeddings` 是一个二维浮点数数组，每个子数组代表一个输入文本的嵌入向量。
**Section sources**
- [embedder.ts](file://src/code-index/interfaces/embedder.ts#L4-L13)
- [code-index/embedders/openai-compatible.ts](file://src/code-index/embedders/openai-compatible.ts#L28-L292)
## IVectorStore 接口
`IVectorStore` 接口定义了向量数据库客户端的契约，用于存储和检索嵌入向量。它提供了对向量集合的 CRUD 操作。
核心操作包括：
- **初始化**：`initialize()` 方法用于创建或验证向量集合。
- **数据写入**：`upsertPoints()` 方法用于将向量点（包含向量和元数据）插入或更新到数据库。
- **向量搜索**：`search()` 方法根据查询向量在数据库中查找最相似的向量。
- **数据删除**：提供 `deletePointsByFilePath()` 和 `deletePointsByMultipleFilePaths()` 方法，支持根据单个或多个文件路径删除向量点，这对于处理文件删除或更新至关重要。
- **集合管理**：`clearCollection()` 和 `deleteCollection()` 方法用于清除或删除整个集合。
**Section sources**
- [vector-store.ts](file://src/code-index/interfaces/vector-store.ts#L9-L63)
- [code-index/vector-store/qdrant-client.ts](file://src/code-index/vector-store/qdrant-client.ts#L28-L340)
## 辅助接口
除了核心接口外，系统还定义了多个辅助接口以实现关注点分离：
- **IDirectoryScanner**：负责扫描目录以获取代码块。其 `scanDirectory()` 方法执行文件发现、解析和初步处理。`getAllFilePaths()` 方法用于获取所有文件路径，支持索引与文件系统状态的同步。
- **ICodeParser**：负责将单个代码文件解析成更小的代码块（CodeBlock），以便进行更细粒度的索引。
- **ICodeFileWatcher**：负责监听文件系统的变化（如创建、修改、删除），并在变化发生时触发相应的索引更新操作。
**Section sources**
- [file-processor.ts](file://src/code-index/interfaces/file-processor.ts#L26-L53)
- [code-index/processors/scanner.ts](file://src/code-index/processors/scanner.ts#L25-L394)
## 实现与设计模式
这些接口通过依赖注入（Dependency Injection）和适配器模式（Adapter Pattern）实现，极大地增强了系统的灵活性和可扩展性。
- **依赖注入**：`CodeIndexServiceFactory` 类是依赖注入的体现。它根据配置动态创建 `IEmbedder` 和 `IVectorStore` 的具体实例，并将它们注入到 `DirectoryScanner` 和 `CodeIndexOrchestrator` 等组件中。这使得组件之间松耦合，易于测试和替换。
- **适配器模式**：`IEmbedder` 和 `IVectorStore` 接口本身就是适配器模式的完美应用。例如，`OpenAICompatibleEmbedder` 类实现了 `IEmbedder` 接口，它将任何兼容 OpenAI API 的服务（如本地运行的 Ollama 或第三方服务）适配到统一的嵌入接口。同样，`QdrantVectorStore` 类将 Qdrant 向量数据库的特定 API 适配到通用的 `IVectorStore` 接口。
这种设计允许系统轻松集成不同的嵌入模型提供商（如 OpenAI, Ollama, Azure OpenAI）和不同的向量数据库（如 Qdrant, Pinecone, Weaviate），而无需修改核心业务逻辑。
**Section sources**
- [service-factory.ts](file://src/code-index/service-factory.ts#L16-L182)
- [code-index/embedders/openai-compatible.ts](file://src/code-index/embedders/openai-compatible.ts#L28-L292)
- [code-index/vector-store/qdrant-client.ts](file://src/code-index/vector-store/qdrant-client.ts#L28-L340)
