⚡ Мультирепозиторный поисковый движок по коду

Промышленная система поиска и извлечения кода, предназначенная для запросов и навигации по нескольким исходным репозиториям одновременно, спроектированная и разработанная с использованием фреймворка разработки на основе спецификаций 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 | Imports | Doc).

3. Гибридное индексирование: плотные векторы + лексический поиск:

   • Плотные векторные поиски: семантические векторные признаки подслов с косинусным сходством + поддержка внешних эмбеддингов (Gemini, OpenAI, Voyage AI, Ollama). Локальные эмбеддинги Ollama по умолчанию используют qwen3-embedding:0.6b, загружаются по требованию и освобождаются в простое.

   • Разреженный поиск BM25: специализированный для кода токенизатор, разбивающий camelCase и snake_case токены с бустингом символов.

   • Слияние Reciprocal Rank Fusion (RRF): объединение плотных и разреженных ранжирований с бустингом точных идентификаторов.

4. Граф символов и межрепозиторные зависимости:

   • Извлечение определений символов, вызовов, вызываемых функций и импортов в SQLite.

   • Автоматическое сопоставление клиентских вызовов API (например, apiClient.post('/api/v1/auth/login')) с серверными обработчиками маршрутов API в разных репозиториях.

5. Интерфейсы:

   • Современный веб-интерфейс: гибридный поиск как основной способ запросов, менеджер репозиториев, карта межрепозиторных API-контрактов и инспектор кода.

   • Сервер Model Context Protocol (MCP): предоставляет инструменты stdio (search_codebases, get_symbol_definition, get_call_hierarchy, list_repositories) для AI-ассистентов (Antigravity, Cursor, Claude Code, Windsurf).

   • CLI: быстрые команды терминала для индексации и поиска.

   • REST API: POST /api/v1/search возвращает ранжированные фрагменты кода для внешних облачных LLM-потребителей.

Related MCP server: Synapse

📂 Планирование на основе спецификаций 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. Запуск интерактивного веб-интерфейса

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

Откройте http://localhost:8000 в вашем браузере.

5. Подключение к AI-IDE через MCP (Model Context Protocol)

Добавьте запись 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. Второй экземпляр быстро завершается с ошибкой, указывающей на владеющий PID; флаг --allow-multi-instance понижает это до предупреждения.

• Проверка и ручное освобождение: GET /api/v1/models/status сообщает о резидентности, активных операциях, политике и происхождении индекса. POST /api/v1/models/unload (или python 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 -> зависит от -> B. Добавление ребра запускает детектирование циклов во время записи (возникает ошибка DependencyCycleError при обнаружении цикла).

• Разрешение области видимости: объединяет явные ID репозиториев и членов групп в первичное множество, затем расширяется вдоль графа в направлениях upstream (зависимости), downstream (зависимые) или both до глубины expand_depth.

• Ранжирование с затуханием по хопам: фрагменты, полученные из расширенных репозиториев, получают штрафной множитель (0.85 ** hops), чтобы гарантировать, что первичные репозитории ранжируются первыми.

• Метаданные происхождения: результаты из расширенных репозиториев несут метаданные (repo_relation='expanded', relation_direction, relation_hops) и визуально помечаются значком в интерфейсе.

Конечные точки 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 и сквозной гибридный поиск.