⚡ 多仓库代码搜索引擎

一个生产级代码检索与搜索系统，用于同时查询和导航多个源代码仓库，并使用 OpenSpec 规范驱动开发框架进行设计和规划。排序结果（包含仓库、文件、行号、符号和图元数据）是与外部云 LLM 客户端的集成边界，这些客户端在各自环境中执行生成任务。

🌟 核心特性

1. 多仓库摄取与增量同步：

   • 管理本地代码库目录和远程 Git 仓库。

   • 自动遵循 .gitignore 规则并排除二进制文件/锁文件。

   • SHA-256 哈希跟踪和 Git 提交检测，实现即时增量更新。

2. AST 感知的语义代码分块：

   • 针对 Python、TypeScript/JavaScript、Go、Rust、Java、C/C++、HTML/CSS、SQL 和 Markdown 的语言感知结构解析。

   • 保留函数、方法、类和接口的边界。

   • 注入作用域头（// [Context] Repository | File | Scope | Imports | Doc）。

3. 混合稠密 + 词法索引：

   • 稠密向量搜索：语义子词特征向量 + 支持外部嵌入（Gemini、OpenAI、Voyage AI、Ollama）。本地 Ollama 嵌入默认使用 qwen3-embedding:0.6b，按需加载，空闲时释放。

   • 稀疏 BM25 搜索：针对代码优化的分词器，可拆分 camelCase 和 snake_case 标记，并支持符号加权。

   • 倒数排名融合（RRF）：融合稠密和稀疏排名，并支持精确标识符加权。

4. 符号图与跨仓库依赖关联：

   • 在 SQLite 中提取符号定义、调用方、被调用方和导入关系。

   • 自动将前端客户端 API 调用（例如 apiClient.post('/api/v1/auth/login')）映射到不同仓库中的后端 API 路由处理器。

5. 接口：

   • 现代 Web UI：以混合搜索为主要查询体验，包含仓库管理器、跨仓库 API 契约映射和代码检查器抽屉。

   • 模型上下文协议（MCP）服务器：向 AI 编码助手（Antigravity、Cursor、Claude Code、Windsurf）暴露 stdio 工具（search_codebases、get_symbol_definition、get_call_hierarchy、list_repositories）。

   • CLI：用于索引和搜索的快速终端命令。

   • REST API：POST /api/v1/search 为外部云 LLM 消费者返回排序后的代码块。

Related MCP server: CodeGraph

📂 OpenSpec 规范驱动规划

所有规范、架构契约和任务分解均维护在 openspec/ 目录下：

openspec/
├── config.json                     # OpenSpec project configuration
├── specs/                          # Living System Specifications (Source of Truth)
│   ├── repository-management.md    # Repo ingestion & git tracking
│   ├── ast-code-chunking.md        # AST semantic parsing & context injection
│   ├── hybrid-indexing.md          # Dense vector + BM25 lexical index
│   ├── symbol-graph-retrieval.md   # Call graph & cross-repo API linkage
│   ├── context-fusion-reranking.md # RRF fusion & citation packaging
│   ├── rag-generation.md           # LLM prompting & grounded citations
│   ├── mcp-server.md               # Model Context Protocol tools
│   └── api-and-web-ui.md           # REST & Web UI specifications
└── changes/
    └── 01-foundation-and-core-rag/ # Phase 1 Change Proposal
        ├── proposal.md             # Goals, scope, and motivation
        ├── design.md               # Technical architecture & contracts
        └── tasks.md                # Implementation checklist (Completed)

🚀 快速开始

1. 注册并索引仓库

# Add a local repository
python3 main.py add auth-service ./fixtures/repo_auth_service

# Add another repository
python3 main.py add web-client ./fixtures/repo_web_client

# List all indexed repositories
python3 main.py list

2. 管理仓库组与依赖关系

# Create a repository group
python3 main.py group create platform --repos auth-service shared-schemas

# Declare a dependency edge: web-client depends on auth-service
python3 main.py relation add web-client auth-service

# Inspect relations for a repository
python3 main.py relation show web-client

# Search with group scoping and upstream dependency expansion
python3 main.py search "jwt token" --group platform --expand upstream --expand-depth 1

3. 跨仓库搜索（CLI）

# Hybrid search across all codebases
python3 main.py search "login user authenticate"

# Search scoped to a group with upstream dependency expansion
python3 main.py search "How does authentication flow between web-client and auth-service?" --group platform --expand upstream

4. 启动交互式 Web UI

python3 main.py serve --host 127.0.0.1 --port 8000

在浏览器中打开 http://localhost:8000。

5. 通过 MCP（模型上下文协议）连接 AI IDE

将以下 MCP 服务器条目添加到你的 AI IDE 配置中（Antigravity / Cursor / Claude Code）：

{
  "mcpServers": {
    "multi-repo-code-rag": {
      "command": "python3",
      "args": ["/Users/nick-work-pc/.gemini/antigravity/scratch/multi-repo-code-rag/main.py", "mcp"]
    }
  }
}

🧠 嵌入模型运行时

引擎作为每个数据目录的单一实例运行，并且仅在工作期间保持本地嵌入模型驻留。

• 默认模型：qwen3-embedding:0.6b（使用 ollama pull qwen3-embedding:0.6b 安装一次）。可通过 --embedding-model 或 $OLLAMA_EMBEDDING_MODEL 覆盖。

• 按需驻留：模型在启动时从不加载。它会在索引运行或搜索的首次嵌入时加载，并在最后一个进行中的操作完成且空闲宽限期结束后释放。重叠的请求共享一次加载并产生一次释放。

• 驻留策略：通过 --keep-alive 或 $EMBEDDING_KEEP_ALIVE 设置：

  值	行为
  （未设置）	空闲 30 秒后释放（默认）
  0	最后一个操作完成后立即释放
  45s、5m	在该空闲宽限期后释放
  always	在进程生命周期内保持模型驻留

• 单一实例：启动时在 <data-dir>/.rag-instance.lock 上获取独占锁。第二个实例会因持有进程 ID 而快速失败；传递 --allow-multi-instance 可将此降级为警告。

• 手动检查 / 释放：GET /api/v1/models/status 报告驻留状态、活动操作、策略和索引来源。POST /api/v1/models/unload（或 python3 main.py unload）释放模型，当有操作正在进行时返回 409 busy。

模型变更时自动重新索引

稠密索引会记录生成其向量的提供方、模型和向量维度（<data-dir>/index_meta.json）。当配置的嵌入模型发生变更时——例如从 qwen3-embedding:4b（2560 维）升级到默认的 qwen3-embedding:0.6b（1024 维）——受影响的仓库会在提供搜索结果之前自动重新嵌入：

• 块文本、BM25 词法索引和符号图会被保留（仅重新嵌入，不重新解析）；

• 进度通过正常的索引进度输出报告；

• 来源信息按仓库写入，因此中断的重建会从未完成的仓库继续；

• 重建期间到达的搜索请求会返回 503 reindexing，而不是使用来自其他模型的向量进行评分。

回滚到先前行为：OLLAMA_EMBEDDING_MODEL=qwen3-embedding:4b EMBEDDING_KEEP_ALIVE=always 可恢复旧模型和常驻策略；来源检查随后会在无需代码变更的情况下重建回 4b 向量空间。

🏷️ 仓库组与依赖关系架构

拓扑与领域规则

• 命名仓库组：仓库的扁平集合（例如 core、platform、billing）。删除组绝不会删除底层仓库。

• 有向依赖 DAG：显式依赖边 A -> depends on -> B。添加边时执行写入时环检测（检测到环时抛出 DependencyCycleError）。

• 作用域解析：将显式仓库 ID 和组成员合并为主集合，然后沿图在 upstream（依赖项）、downstream（依赖方）或 both 方向上扩展，深度不超过 expand_depth。

• 跳数衰减排名：从扩展仓库检索到的块会获得分数乘数惩罚 (0.85 ** hops)，以确保主仓库排名靠前。

• 来源元数据：来自扩展仓库的结果携带元数据（repo_relation='expanded'、relation_direction、relation_hops），并在 UI 中以视觉徽章标识。

REST API 端点

MCP 工具

• manage_repository_relations：操作包括 create_group、delete_group、add_to_group、remove_from_group、add_dependency、remove_dependency。

• get_repository_relations：返回单个仓库或整个关系图的关联信息。

• search_codebases：扩展支持可选的 groups、expand 和 expand_depth 参数。

🧪 运行测试

python3 -m unittest discover -s tests -p "test_*.py" -v

所有单元测试和集成测试套件均通过，验证了 AST 分块、符号提取、跨仓库 API 检测、仓库关系 DAG 与环检测、作用域解析与跳数衰减检索、REST API 处理器、MCP 协议以及端到端混合搜索检索。