Решение проблем: обзор

Что это

Это точка входа в раздел диагностики. Здесь собран список типовых симптомов и ссылки на страницы, где каждый случай разобран по схеме: симптом → вероятная причина → безопасная диагностика → решение → когда открыть issue.

raytsystem работает локально и только на петле 127.0.0.1, поэтому почти любую проблему можно исследовать безопасными командами только для чтения. Начинайте с общей проверки, а к частной странице переходите уже с конкретной ошибкой в руках.

Когда использовать

Когда что-то повело себя не так, как ожидалось: интерфейс не открылся, команда завершилась с ошибкой, линза «Код» пустая или задача не сменила статус.

Пошагово

1. Сначала запустите общую проверку окружения и указателей проекта:

   uv run raytsystem doctor

   doctor не меняет состояние проекта. Он возвращает набор проверок (checks) и итоговый признак healthy. Если какая-то проверка равна false, начните со страницы doctor сообщает ошибку.

2. Дополнительно посмотрите общее состояние проекта без создания баз и индексов:

   uv run raytsystem status

3. Затем перейдите на страницу под ваш симптом.

Индекс проблем

• Интерфейс raytsystem ui не стартует или страница пустая → Интерфейс не запускается.
• doctor возвращает healthy: false или отдельные проверки false → doctor сообщает ошибку.
• Линза «Код» показывает «Не построено» или «Устарело», а graph query завершается ошибкой → Граф кода отсутствует или устарел.
• Задача не меняет статус, переход отклонён → Задача не меняет статус.
• Ошибка о несовпадении поколения (generation/snapshot) при записи → Конфликт поколения.
• Skill editor показывает skill_edit_conflict и не сохраняет → Конфликт редактирования Skill.
• Возможность описана, но не работает, потому что выключена по умолчанию → Флаг функции выключен.
• Tool Hub отклоняет URL, не находит ffmpeg/tesseract, возвращает partial или MCP не готов → Troubleshooting Tool Hub.

Ограничения и безопасность

• doctor и status работают только на чтение и ничего не меняют.
• Команды с суффиксами list, status, query, explain безопасны для диагностики: они не пишут в каноническое хранилище.
• Никогда не редактируйте вручную _raw/, объекты и поколения в ledger/, сгенерированные страницы knowledge/. Восстановление таких артефактов делается пересборкой, а не правкой файлов.

Частые ошибки

• Прыгать сразу к правке файлов, не запустив doctor. Сначала диагностика, потом действие.
• Считать выключенную по умолчанию функцию сломанной. Проверьте раздел Флаг функции выключен и справочник флагов.

Связанные страницы

• Флаг функции выключен
• Справочник CLI
• Справочник флагов функций

Источники истины

• src/raytsystem/cli.py
• docs/STATUS.md