项目简介

Dolphin 是一个为 AI 接口设计的语义代码搜索和知识管理系统。它包含一个用户管理的索引程序和一个 HTTP 检索服务器。其核心职责是以标准化的方式向 LLM 客户端提供上下文信息和功能，包括托管和管理代码资源、提供数据访问能力，以及注册和执行工具，允许 LLM 调用外部功能。Dolphin 通过 JSON-RPC 协议与客户端通信，接收并响应请求，为 LLM 应用提供安全、可扩展的上下文服务框架。

主要功能点

语义代码搜索: 支持通过自然语言查询对代码库进行语义搜索，利用 OpenAI 嵌入和 LanceDB 向量存储实现。
知识管理: 能够索引代码仓库，进行语言感知分块，并支持增量索引。
上下文检索: 提供按文件切片、按代码块 ID 检索内容的能力，并支持代码图谱上下文增强。
工具集成: 作为 MCP 服务器，对外提供多种工具，如 'search_knowledge'（搜索知识）、'fetch_chunk'（获取代码块）、'fetch_lines'（获取文件行）、'get_vector_store_info'（获取向量存储信息）、'open_in_editor'（在编辑器中打开文件）和 'get_metadata'（获取元数据），供 LLM 客户端调用。
灵活配置: 支持全局和仓库级别的配置，可定制嵌入模型、分块策略、忽略模式等。
API 服务器: 包含一个 Python FastAPI 后端，提供 REST API 接口，供 MCP Bridge 调用。

安装步骤

安装 Bun (用于 MCP Bridge):

curl -fsSL https://bun.sh/install | bash
# 或者对于 macOS/Linux:
# brew install bun

请确保 'bun' 命令在您的 PATH 中可用。

安装 Python 核心包: Dolphin 核心服务（索引、搜索 API）使用 Python 编写。推荐使用 'uv' 进行安装。

# 确保 Python >= 3.12
uv pip install pb-dolphin

# 设置 OpenAI API 密钥 (用于 embeddings，推荐用于生产环境)
export OPENAI_API_KEY="sk-your-openai-api-key-here"

可选：如果需要高级搜索质量改进（+20-30% MRR），可以安装 Cross-Encoder Reranking 依赖：

uv pip install "pb-dolphin[reranking]"

这将额外增加约 2GB 的安装大小，但会带来更精准的搜索结果。

初始化知识库: 第一次使用前，需要初始化 Dolphin 知识库。这会创建配置、SQLite 元数据存储和 LanceDB 向量存储。
```
dolphin init
```

服务器配置

Dolphin MCP 服务器是一个 TypeScript 应用，通过 'bunx dolphin-mcp' 命令启动，并与 Python FastAPI 后端进行通信。要将 Dolphin MCP 服务器集成到支持 MCP 协议的 LLM 客户端中，您需要在客户端配置中添加如下 JSON 格式的服务器信息。客户端将使用这些信息来启动和连接 Dolphin MCP 服务器。

{
  "mcpServers": {
    "dolphin": {
      "command": "bunx",               // 用于启动 Dolphin MCP 服务器的命令
      "args": ["dolphin-mcp"]          // 传递给启动命令的参数
    }
  }
}

请确保在启动 Dolphin MCP 服务器之前，Python FastAPI 检索服务器已在运行。

基本使用方法

启动 Dolphin API 服务器 (Python 后端): 这是 Dolphin MCP 服务器所依赖的 RESTful API 服务。
```
dolphin serve
```
默认运行在 'http://127.0.0.1:7777'。
注册和索引代码仓库: 首先，注册您的代码仓库。'my-project' 是您为仓库指定的逻辑名称，'/path/to/project' 是仓库的绝对路径。
```
dolphin add-repo my-project /path/to/project
dolphin index my-project
```
建议在代码仓库的 '.git/hooks/post-commit' 文件中添加 'uv run dolphin index {repo-name}' 以便在每次提交后自动更新索引。
在 LLM 客户端中使用 MCP 工具: 当您将 Dolphin MCP 服务器配置到您的 LLM 客户端后，客户端将可以调用以下工具：
- 'search_knowledge': 语义搜索代码和文档，获取排名靠前的代码片段。
- 'fetch_chunk': 根据代码块 ID 获取完整的代码内容。
- 'fetch_lines': 根据仓库、文件路径和行号范围获取文件内容片段。
- 'get_vector_store_info': 获取向量存储的元信息（如命名空间、维度、近似块数量）。
- 'open_in_editor': 生成一个 'vscode://file' URI，用于在 VS Code 中打开特定文件及位置。
- 'get_metadata': 返回代码块的元数据。
例如，您可以通过 LLM 客户端发起类似 "搜索认证逻辑" 的请求，它将调用 'search_knowledge' 工具返回相关代码。

直接通过 CLI 进行搜索 (本地测试/调试): 在没有 LLM 客户端的情况下，您可以直接使用 'dolphin' CLI 进行语义搜索：

dolphin search "authentication logic" --repo my-project
dolphin search "database migration" --path src/db --top-k 5 --show-content

其他命令

'dolphin init': 初始化配置 (自动创建 '~/.dolphin/config.toml')
'dolphin init --repo': 在当前目录创建仓库特定配置
'dolphin rm-repo <name>': 从知识库中移除一个仓库及其所有数据
'dolphin status': 报告知识库状态和详细的仓库列表
'dolphin prune-ignored <name>': 移除匹配忽略模式的文件所对应的代码块
'dolphin list-files <name>': 列出仓库中所有已索引的文件
'dolphin config --show': 显示当前配置
'dolphin reset-all': 重置整个知识库（删除所有数据），配置保持不变。

关键词