Skip to content

INSTALL.md

Latest commit

 

History

History
209 lines (151 loc) · 10.9 KB

INSTALL.md

File metadata and controls

209 lines (151 loc) · 10.9 KB
Raw

Установка MSCodebase Intelligence для Zed IDE

MSCodeBase Banner

🇬🇧 English • 🇷🇺 Русский • 🇨🇳 中文

MSCodebase Intelligence — MCP-сервер для семантического поиска кода в Zed IDE. Работает как расширение Zed. Разработка в D:\Project\MSCodeBase.

🔧 Системные требования

Компонент Требование
ОС Windows 10+ (основная поддержка), macOS 12+, Linux
Python 3.10+ (рекомендуется 3.11+)
ОЗУ 4 ГБ (рекомендуется 8+ ГБ)
Диск 500 МБ (с моделью — до 2 ГБ)
Zed IDE последняя версия
LM Studio (опционально) для векторного поиска через эмбеддинги
llama.cpp (автоустановка) встроенный эмбеддер/реранкер через GGUF-модели

📥 Быстрая установка

Шаг 1: Установка расширения

Откройте терминал в корне вашего проекта (где находится install.py) и выполните:

python install.py

Linux/macOS: Также можно использовать ./install.sh для направляемой установки. Windows: Также можно использовать install.bat (двойной щелчок или запуск в cmd).

Установщик выполнит:

  1. ✅ Проверку Python и совместимости
  2. ✅ Создание виртуального окружения и установку зависимостей
  3. ✅ Скачивание и установку llama.cpp + GGUF-моделей (bge-m3 + bge-reranker-v2-m3)
  4. ✅ Настройку MCP-сервера в settings.json Zed
  5. ✅ Копирование исходных файлов в установленное расширение
  6. ✅ Создание uninstall.bat

Важно: Установщик копирует файлы из текущей директории в расширение. Все изменения исходников вступают в силу только после python install.py.

Автоматическая установка

Начиная с v2.7.0, install.py автоматически:

  1. Скачивает llama-server.exe под вашу платформу (Windows/macOS/Linux, x64/ARM64)
  2. Скачивает GGUF-модели: bge-m3-Q4_K_M (417 МБ) для эмбеддингов и bge-reranker-v2-m3-Q4_K_M (418 МБ) для реранкинга
  3. Запускает llama-server при старте MCP — никаких внешних сервисов не требуется
  4. Освобождает до 5,3× ОЗУ по сравнению с LM Studio (227 МБ vs 1200 МБ)

Весь процесс полностью автоматический. Никаких дополнительных действий от пользователя не требуется.

Шаг 2: Перезапуск Zed

File → Quit, затем снова откройте проект. Простой window: reload недостаточен — MCP-сервер должен полностью перезапуститься.

Шаг 3: Проверка

Откройте Agent Panel (Ctrl+Shift+P → Agent Panel: Toggle) и выполните:

get_index_status()

Вы должны увидеть:

📂 <корень-вашего-проекта>
🟢 **MSCodeBase** — active
📦 **Chunks:** `2985` | **Files:** `170` | **Symbols:** `1357`
🧠 **Embedder:** 🦙 llama.cpp

Если проект определён неверно (показывается другой проект вместо вашего) — закройте все окна Zed и откройте только нужный проект.

🧠 Особенности Windows

На Windows есть критические особенности, которые нужно знать:

Проблема Симптом Решение
Restricted Mode LSP не запускается, MCP не видит проект Нажмите «Trust and Continue» при открытии проекта
CWD = директория Zed MCP-сервер запускается из папки установки Zed, а не из проекта Исправлено через SQLite fallback (проект берётся из БД Zed, а не из CWD)
MCP не перезапускается После убийства процесса инструменты не работают Только полный перезапуск Zed (File → Quit)
Проект определяется неверно Показывает gemma_agent вместо MSCodeBase Закройте все окна Zed, откройте только нужный проект

Подробнее: ZED_WINDOWS_QUIRKS.md

Как определяется проект (без LSP)

MCP-сервер определяет текущий проект в следующем порядке:

  1. Явный project_root из аргументов инструментов
  2. SQLite active_workspace_id (НОВЫЙ, основной!) — читает scoped_kv_store в базе данных Zed, которая хранит active_workspace_id — единственный механизм, работающий на Windows. Мгновенно переключается при смене проекта.
  3. SQLite workspaces (старый fallback) — выбирает последний проект из таблицы workspaces, если active_workspace_id не найден.
  4. LSP Bridge (JSON-файл от LSP — не работает на Windows, LSP не запускается)
  5. PROJECT_PATH из окружения
  6. CWD — всегда отклоняется защитой от самоиндексации
  7. ext_root (директория расширения) — fallback

На Windows шаги 1, 4-5 обычно недоступны, поэтому проект определяется через SQLite active_workspace_id (шаг 2). Этот механизм автоматически переключает проект при смене активного окна в Zed. Если определение всё ещё неверное — закройте лишние окна Zed.

🚀 Опционально: LM Studio

LM Studio обеспечивает более качественный поиск через векторные эмбеддинги.

  1. Установите LM Studio
  2. Скачайте модель эмбеддингов (например, BAAI/bge-m3)
  3. Запустите локальный сервер на порту 1234
  4. MCP-сервер подключится автоматически

Проверка:

intel_get_runtime_status()

В ответе должно быть "embedding_provider": "lm_studio" и "lm_studio_at_1234": "online".

📄 Удаление

:: Запустите деинсталлятор
uninstall.bat

Или вручную:

  1. Удалите секцию mscodebase-intelligence из %APPDATA%\Zed\settings.json
  2. Удалите папку расширения: 
    %LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence
  3. Удалите .codebase_indices из корня вашего проекта (если присутствует)

❗ Устранение неполадок

Проблема Причина Решение
Инструменты не отвечают MCP-сервер не запущен File → Quit → снова откройте проект. Логи: %LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence\.codebase_indices\logs\
Неверный проект SQLite выбрала другое рабочее пространство Закройте все окна Zed, откройте только нужный проект
0 chunks Индекс пуст intel_trigger_reindex() — подождите 1-5 минут
llama.cpp офлайн Эмбеддер не запущен Проверьте intel_get_runtime_status(). Логи: директория расширения + .codebase_indices/logs/
LM Studio офлайн Только если используется LM Studio Запустите LM Studio, проверьте порт 1234
Предупреждение settings.json Устаревшие ключи (lsp, mscodebase) Запустите python install.py — он очистит их
ModuleNotFoundError PYTHONATH не указывает на расширение python install.py — исправляет автоматически

Где хранятся данные:

  • Индекс (LanceDB): <проект>/.codebase_indices/lancedb_v2/ — векторная БД с чанками кода
  • Логи: %LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence\.codebase_indices\logs\
  • Память проекта (ADR, known_issues): <проект>/.codebase_indices/intelligence/

👨‍💻 Разработка (для контрибьюторов)

# Клонирование
git clone https://github.com/ManSio/mscodebase-intelligence.git
cd mscodebase-intelligence

# Установка в режиме разработки
pip install -e ".[dev]"

# Запуск тестов
pytest

# Установка в Zed (после изменений)
python install.py

Подробнее: CONTRIBUTING.md

🔗 Связанные документы

Документ Описание
README.md Основная документация, карта всех доков, список инструментов
ZED_WINDOWS_QUIRKS.md Особенности Windows: Restricted Mode, CWD, перезапуск MCP
ARCHITECTURE.md Архитектура проекта, DI, слои
TELEMETRY.md Метрики, ETA, сбор данных
LSP_WONTFIX.md Почему LSP не работает на Windows
CHANGELOG.md История версий
CONTRIBUTING.md Разработка, тесты, PR