内容
# Corpus-KB
[](https://github.com/moliver28/corpus-kb/actions/workflows/ci.yml)
**本地 RAG 系统，适用于 AI 代码编辑器。摄入代码库，提出问题，获取答案。无需云服务。**
Corpus-KB 将检索增强生成（RAG）带到您的本地机器上。它摄入代码文件、文档和纯文本，然后通过 MCP（模型上下文协议）工具提供服务，任何 AI 编辑器都可以调用这些工具。可以把它看作是一个私有的搜索引擎，为您的代码库提供实时查询服务。
---
## 快速开始
从克隆到查询代码库的五个命令：
```bash
# 1. 安装软件包
pip install -e .
# 2. 拉取嵌入模型（Ollama 必须运行）
ollama pull nomic-embed-text
# 3. 启动 MCP 服务器
corpus-kb
# 4. 在单独的终端中运行演示
python scripts/demo.py
# 5. 或者开始摄入您自己的代码
corpus-kb # 然后使用 MCP 工具摄入文件、搜索、SQL 查询...
```
**Windows 用户** 可以运行自动化设置脚本，进行零配置安装：
```powershell
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1
```
**macOS / Linux：**
```bash
bash scripts/setup.sh
```
设置脚本安装 Python 依赖项、拉取嵌入模型、创建数据目录、将 MCP 配置复制到编辑器中，并运行演示冒烟测试。大约 2 分钟即可完成。
---
## 这是什么？
RAG 代表检索增强生成。它是一种模式，AI 模型不仅依赖其训练数据，还会搜索本地知识库（您的代码、文档）并利用找到的内容来支持其答案。不会出现关于您私有代码的幻觉。不会有数据离开您的机器。
Corpus-KB 将此实现为 **MCP 服务器**。MCP（模型上下文协议）是一种开放标准，允许 AI 编辑器与工具和数据源通信。任何与 MCP 兼容的客户端（OpenCode、Claude Code、Cursor、带有 Cline 的 VS Code 等）都可以连接到 Corpus-KB 并使用其工具。
```
┌─────────────────────────────────────────────────────────┐
│ 您的 AI 代码编辑器 │
│ (OpenCode / Claude Code / Cursor / VS Code + Cline) │
└─────────────────────┬───────────────────────────────────┘
│ MCP（stdio 或 SSE）
┌─────────────────────▼───────────────────────────────────┐
│ Corpus-KB 服务器 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │
│ │ 摄入 │ │ 搜索 │ │ SQL 查询 │ │ 图遍历 │
│ │ 工具 │ │ 工具 │ │ 查询 │ │ 遍历 │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘ │
│ │ │ │ │ │
│ ┌────▼─────────────▼─────────────▼─────────────▼────┐ │
│ │ 存储层 │ │
│ │ LanceDB（向量）+ DuckDB（SQL）+ SQLite（图）│ │
│ └───────────────────────────────────────────────────┘ │
│ │ │
│ ┌────▼──────────────────────────────────────────────┐ │
│ │ 嵌入服务（Ollama） │ │
│ │ nomic-embed-text / qwen3-embedding / 任意 Ollama │ │
│ └───────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
管道的工作原理如下：
1. **摄入** - 馈入文件、目录或原始文本。Corpus-KB 检测类型（代码、Markdown、纯文本）并使用正确的策略将内容分成块。
2. **嵌入** - 每个块都使用本地运行的 Ollama 转换为向量（一个捕获含义的数字列表）。
3. **存储** - 向量进入 LanceDB 进行相似性搜索。文档元数据进入 DuckDB 进行 SQL 查询。实体和关系进入图存储。
4. **搜索** - 当您的 AI 编辑器提出问题时，Corpus-KB 运行混合搜索（向量相似性 + 全文关键词搜索 + 互惠排名融合）并返回最相关的块。
5. **答案** - 您的 AI 编辑器读取块并根据您的实际代码回答问题。
---
## 功能
**摄入任意内容** - 文件、目录或原始文本。自动检测代码（通过 tree-sitter 支持 40+ 种语言）、Markdown（标题感知的分割）和纯文本（语义主题间隙检测）。代码块尊重 AST 边界：不会在函数或类中间分割。
**混合搜索** - 向量相似性查找概念相关的块。全文本搜索查找精确的关键词匹配。互惠排名融合将两个排名组合成一个结果列表。您将获得两种方法的最佳结果。
**关系 SQL** - 对摄入的数据进行完整的 DuckDB 支持的 SQL 查询。可以连接文档和块，按来源类型分组，过滤元数据。五个关系表，带有索引和模式 introspection。
**实体图** - SQLite 支持的知识图，包含实体（类、函数、概念、人员、地点）和类型关系（调用、依赖于、包含）。包括广度优先遍历（BFS）。可升级到 GraphQLite，支持 Cypher 查询、PageRank、Louvain 社区检测和最短路径。
**版本控制** - LanceDB 提供类似 Git 的版本控制功能开箱即用。每次写入都创建一个新版本。列出版本、标记它们、穿越时间查看代码库在任何时候的样子。为实验性摄入运行创建分支。
**100% 本地** - Ollama 执行嵌入。无需 OpenAI 密钥、无需云 API、无需 Docker。您的代码永远不会离开您的机器。
---
## 编辑器集成
Corpus-KB 通过 stdio 或 SSE 传输与任何与 MCP 兼容的编辑器连接。配置文件存放在 `mcp-configs/` 中。
| 客户端 | 配置文件 | 备注 |
|--------|-------------|-------|
| OpenCode | `mcp-configs/opencode.json` | 默认自动批准只读工具 |
| Claude Code | `mcp-configs/claude-code.json` | 安装到 `~/.claude/mcp.json` |
| Cursor | `mcp-configs/cursor.json` | 安装到 `.vscode/mcp.json` |
| VS Code (Cline) | `mcp-configs/cursor.json` | 与 Cursor 格式相同 |
| Windsurf | `mcp-configs/cursor.json` | 与 Cursor 格式相同 |
每个配置都将编辑器的 MCP 客户端指向 `corpus-kb` 服务器二进制文件。设置脚本会重写这些配置，以使用您虚拟环境中的绝对路径。
**OpenCode** 配置示例：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"corpus-kb": {
"type": "local",
"description": "适用于代码库的本地 RAG 系统",
"command": ["corpus-kb", "--transport", "stdio"],
"environment": {},
"autoApprove": [
"search", "search_context", "search_similar",
"retrieve_context", "list_documents", "get_stats",
"list_versions", "list_branches", "get_entity_relations",
"search_graph", "sql_query", "sql_tables",
"get_document_tags", "get_metadata", "query_document_stats",
"sync_database"
]
}
}
}
```
**Claude Code** 配置（`~/.claude/mcp.json`）：
```json
{
"mcpServers": {
"corpus-kb": {
"name": "Corpus-KB",
"command": "corpus-kb",
"args": ["--transport", "stdio"],
"env": {}
}
}
}
```
### MCP 工具参考
| 类别 | 工具 | 描述 |
|----------|------|-------------|
| 摄入 | `ingest_file` | 摄入单个文件（自动检测类型） |
| 摄入 | `ingest_text` | 摄入原始文本，可选类型提示 |
| 摄入 | `ingest_directory` | 摄入目录中的所有支持文件 |
| 摄入 | `list_documents` | 列出所有摄入的文档 |
| 摄入 | `delete_document` | 删除文档 ID |
| 搜索 | `search` | 混合搜索（向量 + 全文搜索 + 互惠排名融合） |
| 搜索 | `search_context` | 搜索带有父/兄弟/子上下文扩展 |
| 搜索 | `search_similar` | 查找与给定块相似的块 |
| 搜索 | `retrieve_context` | 搜索结果格式化为 LLM 上下文构建 |
| SQL | `sql_query` | 对文档、块、标签、元数据进行完整的 SQL SELECT |
| SQL | `sql_execute` | 参数化 INSERT/UPDATE/DELETE，带有安全防护 |
| SQL | `sql_tables` | 列出所有表及其模式 |
| SQL | `sync_database` | 将 LanceDB 数据同步到关系表 |
| 图 | `add_entity` | 将实体添加到知识图 |
| 图 | `add_relation` | 在两个实体之间添加关系 |
| 图 | `search_graph` | 按名称或类型搜索实体 |
| 图 | `bfs` | 从起始实体开始的 BFS 遍历 |
| 图 | `get_entity_relations` | 获取实体的所有关系 |
| 版本 | `list_versions` | 列出所有表版本 |
| 版本 | `create_tag` | 为引用标记版本 |
| 版本 | `checkout_version` | 穿越时间到特定版本 |
| 版本 | `restore_version` | 恢复到特定版本 |
| 版本 | `create_branch` | 创建新分支 |
| 版本 | `list_branches` | 列出所有分支 |
| 版本 | `switch_branch` | 切换到分支 |
| 标签 | `add_tag` | 创建新标签 |
| 标签 | `tag_document` | 将标签应用于文档 |
| 标签 | `untag_document` | 从文档中删除标签 |
| 标签 | `get_document_tags` | 列出文档上的标签 |
| 元数据 | `set_metadata` | 设置元数据键值对 |
| 元数据 | `get_metadata` | 检索元数据条目 |
| 统计 | `get_stats` | 数据库统计 |
| 统计 | `query_document_stats` | 文档统计聚合 |
---
## 配置
所有可调参数都位于项目根目录的 `config.yaml` 中。以下是每个部分的用途：
```yaml
# Corpus-KB：配置
server:
name: corpus-kb
transport: stdio # stdio | http
host: localhost
port: 8010
storage:
path: ~/.corpus-kb # 数据目录
lancedb_uri: ~/.corpus-kb/lancedb
graph_db: ~/.corpus-kb/graph.db
embedding:
provider: ollama
model: nomic-embed-text # ~274 MB, 768d. 默认值。
base_url: http://localhost:11434
batch_size: 32 # 大多数模型的批处理大小
dimensions: 768 # 必须与模型匹配
chunking:
max_size: 4096
overlap: 200
code:
enabled: true
max_size: 5000 # 大型实体适合一个块
parser: tree-sitter
supported_languages: [python, javascript, typescript, rust, go, ...]
markdown:
enabled: true
heading_levels: [1, 2, 3]
max_section_size: 5000
text:
enabled: true
strategy: semantic # 使用嵌入模型进行主题间隙检测
min_sentences: 3
max_sentences: 40
search:
hybrid: true
rrf_k: 60 # RRF 常数（越高，越重视全文搜索）
expand_context: true # 在结果中包含父/兄弟/子块
graph:
backend: sqlite # sqlite | graphqlite | latticedb (未来)
extract_entities: true
max_traversal_depth: 5
database:
filename: corpus.db # 持久化 DuckDB 文件
auto_sync: true # 在启动时自动将 LanceDB 同步到关系数据库
```
### 升级嵌入模型
更好的嵌入意味着更好的搜索结果。默认的 `nomic-embed-text`（768d，约 274 MB）适用于大多数代码库。对于更高质量的模型，可以尝试 Qwen3 嵌入模型：
```bash
ollama pull qwen3-embedding:8b-q8_0
```
然后更新 `config.yaml`:
```yaml
embedding:
model: qwen3-embedding:8b-q8_0
dimensions: 4096
batch_size: 128
```
该模型在 MTEB 中排名第一，提供明显更好的语义理解。它需要大约 8 GB 的 RAM。
---
## 架构
Corpus-KB 是一个分层系统。每一层都有明确的责任，可以独立更换或升级。
```
┌────────────────────────────────────────────────────────────┐
│ MCP 接口（FastMCP） │
│ stdio 传输（编辑器） | SSE 传输（网络） │
├────────────────────────────────────────────────────────────┤
│ 工具层 │
│ │
│ ingest_tools.py search_tools.py graph_tools.py │
│ database_tools.py version_tools.py sql_tools.py │
├────────────────────────────────────────────────────────────┤
│ RAG 层 │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌──────────────┐ │
│ │ OllamaEmbedder│ │ HybridSearcher │ │ Reranker │ │
│ │ - embed() │ │ - 向量搜索 │ │ - 身份 │ │
│ │ - embed_batch │ │ - 全文搜索 │ │ - LLM（可选）│ │
│ │ - embed_chunks│ │ - RRF 融合 │ └──────────────┘ │
│ └────────────────┘ └────────────────┘ │
├────────────────────────────────────────────────────────────┤
│ 分块层 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ 代码分块器 │ │ Markdown 分块器│ │ 文本分块器 │ │
│ │ （tree-sitter）│ │ （标题感知）│ │ （语义间隙） │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 文件类型检测│ │ 层次结构解析 │ │
│ └──────────────┘ └──────────────┘ │
├────────────────────────────────────────────────────────────┤
│ 存储层 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ LanceDB │ │ DuckDB │ │ 图存储 │ │ Ollama │ │
│ │ （向量）│ │ （SQL） │ │ （SQLite │ │ （嵌入服务）│ │
│ │ （版本）│ │ （标签） │ │ /GraphQL│ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └───────────┘ │
└────────────────────────────────────────────────────────────┘
```
### 存储后端
三个存储引擎，每个都针对不同的查询模式进行了优化：
- **LanceDB** - 列式向量数据库。存储块嵌入并支持向量搜索、全文本搜索（通过 LanceDB FTS）和混合搜索与 RRF。内置版本控制：每次写入都创建一个新的不可变版本，您可以穿越时间回到过去。
- **DuckDB** - 嵌入式分析 SQL 引擎。存储文档元数据、块记录、标签和灵活的键值元数据存储。完整的 SQL 支持，包括 CTE、窗口函数、所有表之间的 JOIN。启动时从 LanceDB 自动同步，摄入后再次同步。
- **SQLite / GraphQLite** - 实体关系图。级别 1 配备 SQLite（零额外依赖项）。级别 2 升级到 GraphQLite，支持 Cypher 查询、PageRank、Louvain 社区检测和最短路径。抽象的 `GraphStore` 接口意味着 MCP 工具永远不会改变。
### 嵌入服务
Corpus-KB 使用 Ollama 的嵌入 API。嵌入器在内存中缓存结果（SHA256 密钥，LRU 逐出 10,000 个条目），并为效率而批量请求。在连接失败时，它会返回零向量，以实现平滑降级。
---
## 常见问题
### 我需要 GPU 吗？
不需要。默认模型 `nomic-embed-text` 在 CPU 上运行良好。它约 274 MB，产生 768 维嵌入。在现代笔记本电脑上嵌入典型项目只需几秒钟。只有当您升级到更大的模型时，才需要 GPU。
### 我可以使用 OpenAI 嵌入代替 Ollama 吗？
目前，Corpus-KB 使用 Ollama 作为其嵌入提供商。嵌入器是一个薄类，调用 Ollama 的 HTTP API。您可以将其替换为 OpenAI 的嵌入 API，编写一个小适配器。欢迎提交拉取请求。
### 这与使用 Pinecone 等矢量数据库的 RAG 有何不同？
Pinecone 和其他云矢量数据库会将您的数发送到第三方。Corpus-KB 则是 100% 本地运行。不会有数据离开您的机器。它还具有三个存储后端（矢量、关系、图），而不只是矢量搜索。您可以对块运行 SQL 查询，并遍历实体关系，而纯矢量存储则无法做到。
### 这与 ripgrep 等代码搜索工具有何不同？
Ripgrep 是一个正则表达式搜索工具。它查找精确的字符串匹配。Corpus-KB 查找概念上相关的代码，即使关键字不同。它还理解代码结构（函数、类、方法），而不只是将代码视为纯文本。
### tree-sitter 支持哪些语言进行代码分块？
Python、JavaScript、TypeScript、JSX、TSX、Rust、Go、Java、C++、C、Ruby、PHP、Swift、Kotlin、Scala、Lua、Haskell、Elixir、Clojure。那是 tree-sitter 语法包支持的 40+ 种语言。代码文件的语言不受支持，会回落到基于行的分块，仍然会尊重函数和类边界的启发式。
### 我可以使用不同的嵌入模型吗？
是的。Ollama 上可用的任何模型都可以使用。只需在 `config.yaml` 中更改模型名称和维度，然后 `ollama pull <model>`。默认的 `nomic-embed-text` 是一个很好的起点。`qwen3-embedding:8b-q8_0` 是当前质量最高的模型。
### 如何版本化我的数据？
LanceDB 自动为每次写入创建版本。运行 `list_versions` 查看版本历史。使用 `checkout_version` 穿越时间到任何版本（只读）。使用 `restore_version` 回滚。使用 `create_tag` 标记重要版本（例如“before-refactor”或“v1.0”）。分支允许您尝试不同的摄入策略。
### 我可以在没有 Ollama 的情况下运行此程序吗？
不可以，Ollama 是嵌入的必要条件。它是将文本转换为语义搜索的向量所必需的组件。Ollama 是免费、开源的，完全在您的机器上运行。设置脚本会自动安装它。
### 是否适用于大型代码库？
是的。LanceDB 可以高效处理数百万个向量。DuckDB 适用于对大型数据集进行分析查询。分块引擎支持流式处理。对于非常大的代码仓库，可以使用 `ingest_directory` 一次性导入整个目录，并让管道批处理所有内容。
---
## 开发
### 项目结构
```
corpus-kb/
├── config.yaml # 所有可调参数
├── pyproject.toml # Python 包配置
├── scripts/
│ ├── demo.py # 快速演示 / 烟雾测试
│ ├── setup.ps1 # Windows 自动安装
│ └── setup.sh # macOS / Linux 自动安装
├── mcp-configs/
│ ├── opencode.json # OpenCode MCP 配置
│ ├── claude-code.json # Claude Code MCP 配置
│ └── cursor.json # Cursor / VS Code MCP 配置
├── src/
│ ├── server.py # FastMCP 入口，CLI
│ ├── chunking/ # 文件类型检测和分块
│ │ ├── code_chunker.py # AST 感知（tree-sitter）
│ │ ├── markdown_chunker.py
│ │ ├── text_chunker.py # 语义差距检测
│ │ ├── detector.py # 文件类型 -> 分块路由
│ │ └── hierarchy.py # 父/子关系
│ ├── storage/
│ │ ├── lancedb_store.py # 带版本控制的向量存储
│ │ ├── duckdb_engine.py # 关系型 SQL 引擎
│ │ └── graph_store.py # 实体图（SQLite + GraphQLite）
│ ├── rag/
│ │ ├── embedder.py # Ollama 嵌入服务
│ │ ├── hybrid_search.py # 向量 + FTS + RRF
│ │ └── reranker.py # 结果重新排序
│ ├── tools/
│ │ ├── ingest_tools.py # MCP 导入工具
│ │ ├── search_tools.py # MCP 搜索工具
│ │ ├── graph_tools.py # MCP 图工具
│ │ ├── database_tools.py # MCP SQL + 标签工具
│ │ ├── sql_tools.py # SQL 查询工具
│ │ └── version_tools.py # 版本控制工具
│ └── utils/
│ └── models.py # Pydantic 数据模型
├── tests/
│ ├── test_chunking.py
│ ├── test_rag.py
│ └── test_integration.py
└── README.md
```
### 运行测试
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 运行所有测试
pytest
# 带覆盖率
pytest --cov=src --cov-report=term-missing
```
### 贡献
欢迎 PR 和问题。项目遵循以下约定：
- 仅限 Python 3.11+。不允许使用 type: ignore。不允许在有真实类型的地方使用 `Any`。
- 源文件软限制为 250 行。如果模块超过此限制，请将其拆分。
- 新功能使用 TDD。测试位于 `tests/` 中，镜像 `src/` 结构。
- 抽象的 `GraphStore` 接口是可交换后端的模式。请遵循此模式添加新的存储层。
---
## 许可证
MIT。详情请参见 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器