scud_orion_ai_v2/HOWTO/помощь со скриптами диагностики.md

🛠 HOWTO: Помощь в технической диагностике системы (scud_orion_ai_v2)

Данный документ содержит руководство по работе со служебными диагностическими утилитами проекта. Скрипты предназначены для быстрой оценки состояния базы данных SQLite, анализа файловой структуры и формирования контекстного снимка кодовой базы для ИИ.

---

📋 Содержимое папки scripts/diagnostics/

Рекомендуется размещать диагностические скрипты в отдельной директории scripts/diagnostics/:

1. inspect_db.py — Инспектор таблиц и записей базы данных SQLite.
2. inspect_files.py — Сканер дискового пространства и структуры файлов.
3. make_code_snapshot.py — Генератор единого текстового слепка кода для ИИ.

---

🚀 Назначение и запуск утилит

1. Инспектор базы данных SQLite (inspect_db.py)

• Назначение:

  • Проверяет доступность базы данных (data/scud_orion_ai.db).
  • Автоматически считывает список всех таблиц и их колонок.
  • Подсчитывает количество записей в каждой таблице (scud_logs, zup_staff, zup_absences и др.).
  • Выводит список всех активных правил из таблицы ai_knowledge_base.

• Команда для запуска:

  python scripts/diagnostics/inspect_db.py
  

2. Сканер файловой структуры (inspect_files.py) Назначение:

Обходит структуру каталогов проекта.

Показывает точный размер каждого файла в байтах и итоговый вес проекта в мегабайтах.

Автоматически игнорирует служебные и временные папки (.git, pycache, venv, .venv).

Команда для запуска:

Bash python scripts/diagnostics/inspect_files.py 3. Генератор контекстного снимка кода (make_code_snapshot.py) Назначение:

Собирает весь исходный код Python (.py), настройки (.json), инструкции (.md) и скрипты (.sh) в единый файл project_code_snapshot.md.

Исключает тяжелые архивы, логи и виртуальное окружение.

Сформированный файл передается нейросети (LLM) для быстрого погружения в контекст проекта без потери архитектурных деталей.

Команда для запуска:

Bash python scripts/diagnostics/make_code_snapshot.py 🎯 Чек-лист применения при сбоях Ошибка или несостыковка в отчетах: запустить inspect_db.py и проверить, заполнены ли таблицы scud_logs и zup_absences.

Передача задачи или кода ИИ-ассистенту: запустить make_code_snapshot.py и прикрепить итоговый project_code_snapshot.md к запросу.