Skip to content

FAQ.md

Latest commit

 

History

History
141 lines (89 loc) · 6.86 KB

FAQ.md

File metadata and controls

141 lines (89 loc) · 6.86 KB
Raw

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

FAQ — MSCodeBase Intelligence

Часто задаваемые вопросы. Основано на реальном опыте разработки и эксплуатации.

📦 Установка и запуск

Что такое llama.cpp и зачем он нужен?

llama.cpp — это встроенный провайдер для эмбеддингов и реранкинга, который автоматически устанавливается через install.py. Он скачивает GGUF-модели (bge-m3 Q4_K_M 417 МБ и bge-reranker-v2-m3 Q4_K_M 418 МБ) и запускает llama-server.exe локально. Не требует внешних сервисов вроде LM Studio. Потребляет 227 МБ RAM вместо 1200 МБ — в 5,3× меньше.

MCP-сервер не отвечает после установки

Причина: Zed не был перезапущен. window: reload недостаточно. Решение: File → Quit → снова откройте проект.

Логи: %LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence\.codebase_indices\logs\

Ничего не изменилось после python install.py

Причина: Установщик скопировал файлы в расширение, но MCP-сервер уже запущен со старым кодом. Решение: File → Quit → снова откройте проект. Только полный перезапуск перезапускает MCP.

Индекс пуст (0 chunks)

Решение: Запустите intel_trigger_reindex() в Agent Panel. Подождите 1-5 минут. Отслеживайте прогресс через intel_get_job_status(<job_id>).

🔍 Поиск и инструменты

search_code возвращает 0 результатов

Причины:

  • Пустой индекс → см. выше
  • Эмбеддер не запущен → intel_get_runtime_status() показывает «offline»
  • Неверный проект → проверьте вывод get_index_status()

get_index_status() показывает неверный проект

Причина: Определение проекта через SQLite — если в Zed открыто несколько проектов, может быть выбран неверный. Особенно на Windows, где ZED_WORKTREE_ROOT не установлен.

Решение: Закройте все окна Zed, откройте только нужный проект. Подробнее: investigations/ACTIVE_WORKSPACE_RESOLUTION.md

Инструмент возвращает сырой JSON

Если это старая версия: Исправлено. После коммита 05de324 (2026-07-05) все 57 инструментов выводят читаемый Markdown. Решение: Запустите python install.py и перезапустите Zed.

🪟 Windows

LSP не запускается (mscodebase-lsp)

Причина: Zed на Windows не может зарегистрировать кастомные имена LSP. Требуется Rust/WASM-адаптер. settings.json бессилен. Статус: WONTFIX. MCP-сервер полноценно работает без LSP. Подробнее: investigations/LSP_WONTFIX.md

Zed показывает «Restricted Mode»

Решение: Нажмите «Trust and Continue». Отметьте «Trust all projects in...» Иначе LSP не запустится, MCP не увидит проект.

MCP не перезапускается автоматически

Решение: Только File → Quit → снова откройте проект. Авто-перезапуск не поддерживается Zed на Windows.

Проект определяется как «ext_root» (самоиндексация)

Причина: resolve_project_root() не смог найти проект через SQLite. Решение: Убедитесь, что проект открыт в Zed. Проверьте LocalAPPDATA/Zed/db/0-stable/db.sqlite. Если пусто — возможно, Restricted Mode блокирует его.

⚡ Производительность

Медленный поиск (>10s)

Причины:

  • llama.cpp или эмбеддер не готов (проверьте intel_get_runtime_status())
  • Индекс не оптимизирован (запустите intel_trigger_reindex())
  • Слишком высокий limit в search_code (рекомендуется 6-10)

Пинг LLM > 2000ms

Решение: Проверьте статус эмбеддера. Если используется llama.cpp: curl http://127.0.0.1:8080/health. Если используется LM Studio: Убедитесь, что модель эмбеддингов (например, BAAI/bge-m3) загружена.

Память > 500 МБ

Нормально: LanceDB использует mmap-файлы. Windows держит их в памяти. Решение: Перезапустите MCP для освобождения памяти (File → Quit).

🐛 Баги и ошибки

ModuleNotFoundError: No module named 'src'

Причина: PYTHONPATH не указывает на директорию расширения. Решение: Запустите python install.py — он устанавливает правильный PYTHONPATH.

ToolError: Refusing to index self

Причина: Защита от самоиндексации — MCP защищает себя от индексации собственных исходников. Решение: Откройте в Zed другой проект (не расширение).

MCP зависает после пачки notify_change

Было в старых версиях (до 2026-07-05): Deadlock в DebounceBatch. Исправлено. Если всё ещё происходит — проверьте версию (debug_runtime_passport → BUILD_ID). Решение: File → Quit.

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

Документ Описание
INSTALL.md Руководство по установке
ARCHITECTURE.md Архитектура проекта (10 слоёв)
ZED_WINDOWS_QUIRKS.md Особенности Windows
HANDFOFF.md Опыт разработки, архитектурные решения