Диагностика: книга рецептов

Как читать эту страницу #

Каждый рецепт: симптом (что видно) → причина (почему) → лечение. Источники: реальные прогоны пилота, реестр дефектов (DEFECTS.md, 43 находки) и журнал отладки установщика. Если рецепта нет — заведите Issue с выводом selftest и status --json.

Установка #

Симптом: install.ps1 висит на шаге pip. Причина: deadlock пайпов при большом выводе (исторический дефект установщика D-04: stdout переполнялся, процесс ждал читателя). Лечение: обновиться до рефакторенного установщика (async-дренаж + таймауты с TimeoutScale); временно — pip install -e . вручную в venv.

Симптом: certificate verify failed при первом скачивании модели. Причина: корпоративный TLS-прокси с подменой сертификата; pip/python не доверяют корневому CA. Лечение: install.ps1 -WithTruststore или pip install truststore; альтернатива — предварительно положить модель в RAGRAF_MODEL_CACHE.

Симптом: python из Microsoft Store открывается вместо настоящего. Причина: stub-алиасы Windows (python3.exe в WindowsApps) перехватывают команду. Лечение: рефакторенный установщик детектирует stub и говорит прямо; вручную — отключить алиасы (Settings → App execution aliases) или задавать полный путь интерпретатора.

Индексация #

Симптом: ensure каждый раз переиндексирует всё заново. Причина: файлы меняют mtime/содержимое между прогонами (генерируемый код, нормализация строк, antivirus-карантин) — corpus_hash расходится. Лечение: status --json → сравнить corpus_hash до/после; исключить генерируемые каталоги через exclude; проверить, что .ragraf/ не попадает в include.

Симптом: индексация большая (сотни файлов) и медленная. Причина: AST-обход последовательный (документированная цель «8 ядер параллельно» ещё не реализована — R-PERF-1); эмбеддинги на CPU. Лечение: сузить include; эмбеддинги — на GPU (см. gpu-compute); CPG отключить (joern_enabled: false), если slice не нужен: на пилоте CPG — 64 с из 71.

Симптом: write_check не знает таблицу, которая точно есть. Причина: таблица создаётся не в migrations/*.sql, а динамически/в другом каталоге. Лечение: расширить glob schema.migrations в конфиге; проверить schema --table X и coverage (конфликты источников пишутся туда).

Joern / CPG #

Симптом: slice отвечает кодом выхода 3. Причина: capability=degraded — Joern/JDK не установлены или CPG-этап упал. Лечение: это честный отказ, а не баг: install-joern.ps1 -Download (проверяет SHA-256); на больших корпусах — RAGRAF_JOERN_HEAP_GB; порт 9500 должен быть свободен (сервер стартует/останавливается автоматически).

Симптом: Joern стартует, но CPG пустая. Причина: php2cpg не поддержал диалект/конструкции корпуса; ошибки видны в логе стадии (index_status). Лечение: проверить coverage и лог; частичная CPG лучше никакой — slice по покрытым файлам работает, capability сообщает правду.

Эмбеддинги и поиск #

Симптом: search отвечает секунду и дольше. Причина: доминирует вычисление эмбеддинга запроса на CPU; кэша запросов нет (R-PERF-3). Лечение: для навигации — symbol/callers (0,5–0,7 мс); search — для семантических запросов; GPU ускоряет пакетную индексацию, но латентность одиночного запроса почти не меняется (~15 с разовая подготовка карты на GPU).

Симптом: векторные нормы в панели — нули/выбросы. Причина: битые чанки (обрыв парсинга) или mismatch dim. Лечение: reindex; проверить embedding.dim против модели; качество — вкладка Quality панели (нормы пилота: 0.0576–0.6627).

MCP и агенты #

Симптом: агент не видит инструментов ragraf_*. Причина: сервер не стартовал (неверный путь/интерпретатор в конфиге MCP) или substring-фильтр имён дал ложное срабатывание (дефект C-02). Лечение: запустить команду сервера руками — stderr покажет причину; в конфиге агента — точные имена инструментов; --agent-kind external для сторонних клиентов.

Симптом: ответы агента «по памяти», индекс игнорируется. Причина: регламент не подключён. Лечение: usage_stats: здоровый профиль — доминирование symbol/search, нулевое полное чтение файлов; добавить регламент AGENTS.md в контекст агента.

Панель #

Симптом: панель не открывается, порт занят. Причина: прошлый экземпляр не остановлен. Лечение: сервер сообщает причину (занятость 8777) явно; остановить процесс или сменить порт (аргумент запуска).

Симптом: настройки не сохраняются. Причина: мутации требуют токен (печатается в консоли старта); валидация full > fast отклонила значения. Лечение: токен из консоли/RAGRAF_ADMIN_TOKEN; проверить пороги — сервер валидирует строже формы.

Windows-специфика #

• Glob case-sensitivity: **/*.PHP не матчит file.php на Windows (дефект E-01) — в конфиге только нижний регистр расширений; исправление в roadmap.
• Пути: в конфиге — прямой слеш /; обратный работает, но каноничен /.
• Длинные пути (>260): включите LongPathsEnabled или держите корпус ближе к корню.
• PowerShell 5.1: не проверен; используйте pwsh 7.6+.

Смежное: CLI-справочник → · конфигурация → · замеры и границы →