deeprepo

DeepRepo — 面向代码库的本地 RAG 引擎

一个用于对本地代码库执行 RAG（检索增强生成）的生产级 Python 库。无需庞大的框架、外部向量数据库或云服务。

功能介绍

DeepRepo 会摄取代码库并同时构建以下三部分：

层	存储内容	用途
代码知识图谱	类、函数、导入关系、调用边（SQLite）	符号查找、影响范围分析
嵌入向量 + FTS 索引	语义向量 + 全文搜索	检索相关代码
分层 Wiki	每个模块对应的纯英文 .md 文件	AI 解释、聊天上下文

智能查询路由器会对每个问题进行分类，并选择成本最低的上下文策略。与朴素 RAG 相比，可将大模型的令牌用量减少 5–50 倍。

---

功能

• 不依赖庞大的框架 — 纯 Python，基于 SQLite
• 支持多个 AI 提供商 — Ollama（免费／本地）、OpenAI、Anthropic、Gemini、HuggingFace
• CLI 优先 — deeprepo ingest . / deeprepo serve / deeprepo query "…"
• Wiki 查看器 — 可浏览、可搜索的 HTML Wiki，支持页面内聊天（deeprepo serve）
• 7 个专用 MCP 工具 — 将 DeepRepo 添加到 Cursor / Claude Desktop，作为 MCP 服务使用
• 分支隔离 — 每个分支使用独立的 SQLite 数据库，并通过写时复制继承基础分支
• 三级检索 — 嵌入向量 → FTS → 图谱回退，提供可靠的搜索能力
• 增量摄取 — 跳过未更改的文件；仅重新处理变更内容

---

快速开始

1. 安装

cd deeprepo_core
pip install -e .

要启用 MCP 服务支持：

pip install -e ".[mcp]"

2. 安装 Ollama（免费、本地运行 — 推荐）

# macOS
brew install ollama
ollama serve                          # keep this running

ollama pull nomic-embed-text          # embedding model
ollama pull llama3.1:8b               # LLM

3. 摄取代码库

cd /path/to/your/project
deeprepo ingest .

4. 浏览 Wiki

deeprepo serve                        # opens http://localhost:8080

5. 提问

deeprepo query "how does authentication work?"
deeprepo query "what breaks if I change auth.py?"

---

CLI 参考

deeprepo <command> [options]

命令	功能
deeprepo init	检测提供商配置，打印摄取命令
deeprepo ingest [PATH]	扫描代码库 → 构建图谱、Wiki 和嵌入向量
deeprepo wiki [PATH]	仅重新生成 Wiki 页面（跳过重新索引）
deeprepo serve	在端口 8080 启动 Wiki 查看器和页面内聊天
deeprepo query "QUESTION"	提出问题并获取 AI 答案
deeprepo status	显示分支隔离状态和缓存新鲜度

常用标志（适用于所有命令）

--llm ollama|openai|anthropic|gemini|huggingface   # LLM provider
--embed ollama|openai|huggingface                  # embedding provider (default: same as --llm)
--branch-isolation                                 # enable per-branch databases
--base-branch main                                 # seed feature-branch cache from main
--wiki-dir .deeprepo/wiki                          # override wiki output directory

ingest 标志

--chunk-size N      # chars per text chunk (default: 1000)
--overlap N         # overlap between chunks (default: 100)
--workers N         # wiki parallel workers (default: 3)
--no-wiki           # skip wiki generation

serve 标志

--port N            # HTTP port (default: 8080)

示例

# Ollama (free, fully local)
deeprepo ingest .

# OpenAI embeddings + Anthropic LLM
deeprepo ingest . --embed openai --llm anthropic

# Branch isolation for a feature branch
deeprepo ingest . --branch-isolation --base-branch main

# Serve wiki with chat on a custom port
deeprepo serve --llm openai --port 9000

# Query with specific top-k results
deeprepo query "where is AuthService defined?" --top-k 3

---

Python API

from deeprepo import DeepRepoClient

# Single provider (backward-compatible shorthand)
client = DeepRepoClient(provider_name="ollama")

# Split providers — Anthropic LLM + OpenAI embeddings
client = DeepRepoClient(
    embedding_provider_name="openai",
    llm_provider_name="anthropic",
)

# Branch isolation (team workflow)
client = DeepRepoClient(
    provider_name="ollama",
    branch_isolation=True,
    base_branches=["main"],
)

# Ingest (incremental — unchanged files are skipped)
result = client.ingest("/path/to/your/code")
print(f"Files: {result['files_scanned']}, Wiki pages: {result['wiki_generated']}")

# Query — smart routing selects the cheapest context strategy
response = client.query("How does authentication work?")
print(response['answer'])
print(f"Intent: {response['intent']}, Strategy: {response['strategy']}")
print(f"Sources: {response['sources']}")        # list of file paths

# Browse the generated wiki
print(f"Wiki at: {client.get_wiki_dir()}")

query() 返回值结构

{
    "answer":         str,           # LLM-generated answer
    "sources":        list[str],     # file paths used as context
    "intent":         str,           # navigate | impact | explain | debug | review | general
    "strategy":       str,           # e.g. symbol_lookup, blast_radius, wiki_plus_skeleton, …
    "retrieval":      str,           # embeddings | fts | graph
    "token_estimate": int,           # estimated tokens consumed
    "history":        list[dict],    # conversation history (last N exchanges)
}

---

支持的 AI 提供商

提供商	费用	配置	最适合
Ollama	免费，无限使用	安装应用 + ollama pull	本地开发、隐私保护、离线使用
OpenAI	付费	OPENAI_API_KEY	生产环境、最佳质量
Anthropic	付费	ANTHROPIC_API_KEY	生产环境、出色的推理能力
Gemini	免费层级	GEMINI_API_KEY	尝试与探索
HuggingFace	免费层级	HUGGINGFACE_API_KEY	云端嵌入，无需 GPU

注意： Anthropic 没有嵌入 API。请将其与其他提供商搭配使用：

client = DeepRepoClient(embedding_provider_name="openai", llm_provider_name="anthropic")

---

架构

deeprepo_core/src/deeprepo/
├── client.py         # Main facade — branch isolation, freshness, provider wiring
├── graph.py          # SQLite store: graph nodes/edges, embeddings, wiki index, state
├── graph_builder.py  # Tree-sitter AST parser → code knowledge graph
├── wiki.py           # Hierarchical wiki engine — bottom-up LLM synthesis
├── router.py         # Intent classifier + 6 context strategy selectors
├── ingestion.py      # File scanner, chunker, language detection
├── interfaces.py     # Abstract base classes (EmbeddingProvider, LLMProvider)
├── registry.py       # @register_embedding / @register_llm decorator system
├── ui.py             # Wiki viewer (HTTP server + mermaid renderer + chat)
├── mcp/
│   └── server.py     # 7 MCP tools for AI assistants (Cursor, Claude Desktop)
└── providers/
    ├── ollama_v.py
    ├── openai_v.py
    ├── anthropic_v.py
    ├── gemini_v.py
    └── huggingface_v.py

.deeprepo/            # Generated (gitignore this)
├── default.db        # SQLite: graph + embeddings + wiki index + state
├── <branch>.db       # Per-branch database when branch_isolation=True
└── wiki/             # Browsable .md wiki files
    ├── overview.md   # Whole-repo narrative overview
    └── *.md          # One page per module

存储

所有数据都存放在每个分支对应的单个 SQLite 文件中——无需 Redis、Postgres 或 Chroma。

表	内容
nodes	文件、类、函数及其元数据
edges	节点之间的导入／调用关系
embeddings	用于语义搜索的浮点向量
wiki_pages	生成的 Wiki Markdown（键 → 内容）
wiki_fts	Wiki 全文搜索索引
state	用于增量更新的每个文件的 SHA-256 哈希值

设计模式

• 门面 — DeepRepoClient 是唯一入口；内部实现均被隐藏
• 策略 — LLMProvider / EmbeddingProvider 抽象接口；可灵活替换提供方
• 注册表 — @register_llm("ollama") 装饰器会在导入时自动注册提供方
• 自底向上综合 — 按叶子优先的顺序生成 Wiki 页面；父页面使用子页面摘要
• 三级回退 — Embeddings → FTS → Graph；即使 Embeddings 尚未就绪，查询也能正常工作
• 写时复制分支 — 功能分支从基础分支缓存开始，然后增量更新

---

MCP 服务（AI 助手集成）

将 DeepRepo 连接为 MCP 服务，这样 Cursor、Claude Desktop 或任何兼容 MCP 的 AI 助手都可以直接调用它，而无需读取原始文件。

设置

pip install deeprepo[mcp]

Cursor — 创建 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "deeprepo": {
      "command": "python",
      "args": ["-m", "deeprepo.mcp.server"],
      "env": {
        "LLM_PROVIDER": "ollama"
      }
    }
  }
}

Claude Desktop — 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "deeprepo": {
      "command": "deeprepo-mcp",
      "env": {
        "EMBEDDING_PROVIDER": "openai",
        "LLM_PROVIDER": "anthropic",
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

可用的 MCP 工具（7 个工具）

工具	适用场景	Token 开销
ingest_codebase	一次性设置 — 为仓库目录建立索引	—
find_symbol	“X 在哪里定义 / X 位于哪一行”	约 50 个 Token
get_file_structure	“展示 X 中的 API / 函数”	约 150 个 Token
explain_file	“X 如何工作 / 解释 X / X 有什么作用”	约 300 个 Token
find_change_impact	“如果我修改 X，会有什么影响”	约 300 个 Token
ask_codebase	关于代码的任何开放式问题	约 600–2000 个 Token
get_project_overview	“概述一下 / 这个项目有什么作用”	约 600 个 Token

与朴素 RAG 相比的 Token 减少量

查询类型	朴素 RAG	DeepRepo	减少量
“X 在哪里定义”	约 4 000 个 Token	约 80 个 Token	50 倍
“如果我修改 X，会有什么影响”	约 4 000 个 Token	约 300 个 Token	13 倍
“X 如何工作”	约 4 000 个 Token	约 600 个 Token	7 倍
“修复 X 中的 Bug”	约 4 000 个 Token	约 900 个 Token	4 倍

CLAUDE.md 提示

将以下内容添加到项目的 CLAUDE.md，让 Claude 自动使用 DeepRepo：

## Code navigation
Before reading any source file directly, use these MCP tools:
- `find_symbol(name)` to locate a class or function
- `get_file_structure(filepath)` to see a file's API without reading it
- `explain_file(filepath)` to understand what a file does
- `find_change_impact(filepath)` before editing any file
- `ask_codebase(question)` for open-ended questions
- `get_project_overview()` at the start of a new session

Only call Read/Grep on a file after the above tools have been tried.

---

配置

环境变量

变量	默认值	描述
LLM_PROVIDER	openai	LLM 提供方名称
EMBEDDING_PROVIDER	与 LLM_PROVIDER 相同	Embedding 提供方名称
OPENAI_API_KEY	—	OpenAI 所需
ANTHROPIC_API_KEY	—	Anthropic 所需
GEMINI_API_KEY	—	Gemini 所需
HUGGINGFACE_API_KEY / HF_TOKEN	—	HuggingFace 所需
OLLAMA_MODEL	llama3.1:8b	Ollama LLM 模型名称
OLLAMA_EMBED_MODEL	nomic-embed-text	Ollama Embedding 模型
OLLAMA_BASE_URL	http://localhost:11434	Ollama 服务 URL
OLLAMA_TIMEOUT	300	LLM 响应超时时间（秒）

---

测试

# Full end-to-end test suite (runs ingest + all checks)
python3 test_deeprepo_flow.py

# Skip ingest, use cached index (faster iteration)
python3 test_deeprepo_flow.py --skip-ingest

# pytest unit tests
pytest tests/unit/ -v

# pytest with coverage
pytest tests/unit/ --cov=deeprepo --cov-report=html

test_deeprepo_flow.py 脚本会对全部 7 个部分进行端到端测试：

1. 客户端初始化与分支标志
2. 摄取（图谱 + Embeddings + Wiki）
3. WikiEngine — 页面生成、缓存、仓库概览
4. Graph API — 骨架、影响范围、符号查找
5. RAG / Router — 意图分类、查询执行
6. CLI 命令 — 所有子命令及帮助信息
7. 分支隔离标志组合

---

添加新的提供方

1. 创建 src/deeprepo/providers/myprovider.py
2. 实现 EmbeddingProvider 和/或 LLMProvider 接口
3. 添加 @register_embedding("myprovider") / @register_llm("myprovider") 装饰器
4. 导入时会自动发现，无需进行其他更改

from deeprepo.interfaces import EmbeddingProvider, LLMProvider
from deeprepo.registry import register_embedding, register_llm

@register_embedding("myprovider")
class MyEmbeddingProvider(EmbeddingProvider):
    def embed(self, text: str) -> list[float]:
        ...  # return a list of floats

@register_llm("myprovider")
class MyLLMProvider(LLMProvider):
    def generate(self, prompt: str, context: str | None = None) -> str:
        ...  # return generated text

---

文档

• DEVELOPER_WORKFLOW_GUIDE.md — 日常开发工作流和自动化方案
• deeprepo_core/README.md — 软件包 README（PyPI）
• docs/high-level-design.excalidraw — 流程图
• docs/class-interaction-design.excalidraw — 类图

---

许可证

MIT 许可证 — 详情请参阅 LICENSE 文件。

---

为希望完全掌控 RAG 流水线的开发者打造。