Сценарий 15: Поддержка отладки

Разработчик отлаживает проблемы с помощью навигации по коду, трассировки путей вызовов, предложений точек останова и стратегий анализа по типам проблем на основе CPG.

Содержание¶

• Быстрый старт
• Как это работает
• Двухуровневая детекция интентов
• Двухфазная архитектура
• Зарегистрированные обработчики
• Функции CPG-поиска
• Доменно-независимая загрузка паттернов
• Методы анализа DebuggingHandler
• Предложение точек останова
• Анализ стека вызовов
• Трассировка потока переменных
• Генерация стратегии отладки
• Детекция типа проблемы
• Форматтеры отчётов
• Использование CLI
• Примеры вопросов
• Связанные сценарии

Быстрый старт¶

# Выберите сценарий отладки
/select 15

Как это работает¶

Двухуровневая детекция интентов¶

S15 использует двухуровневую систему детекции интентов. Базовый уровень выбирает, какую функцию CPG-поиска выполнить; уровень обработчиков выбирает шаблонный обработчик для структурированных отчётов.

Уровень 1 (базовый): detect_debug_intent() в debugging/intent.py классифицирует запросы в 8 интентов с помощью keyword_match_count_morphological() по паттернам из доменного плагина через get_debug_patterns_from_plugin():

extract_error_level() также определяет конкретные уровни ошибок из запроса (ERROR, WARNING, INFO, LOG, DEBUG, TRACE, FATAL, CRITICAL), загружаемые из get_error_levels_from_plugin().

Уровень 2 (обработчики): DebuggingIntentDetector в debugging_handlers/intent_detector.py классифицирует запросы в 5 интентов обработчиков, отсортированных по приоритету:

Детектор также извлекает: - target_function — имя функции из запроса (7 regex-паттернов, включая русские: для palloc, функция palloc) - issue_type — классификация проблемы: crash, hang, memory_leak, performance, logic_error - topic — подсистема/категория из семантических маппингов доменного плагина

Двухфазная архитектура¶

S15 использует двухфазный подход:

Фаза 1: На основе обработчиков (без LLM). integrate_handlers() запускает DebuggingIntentDetector, проверяет уверенность по порогу cfg.thresholds.confidence_low, затем пробует 2 зарегистрированных обработчика. Если обработчик совпал и дал результаты, DebugReportFormatter форматирует структурированный отчёт без вызова LLM.

Фаза 2: Запасной вариант с LLM. Если ни один обработчик не совпал или уверенность слишком низкая, запускается полный конвейер: detect_debug_intent() выбирает одну из 8 функций поиска → CPG-запросы собирают отладочные конструкции → LLM генерирует анализ. Если LLM недоступен, generate_fallback_answer() создаёт структурированный ответ на основе секций доменного плагина.

Запрос -> DebuggingIntentDetector -> integrate_handlers()
  |                                      |
  |  Фаза 1: Обработчик совпал? Да -> DebugReportFormatter (без LLM)
  |                              Нет -> Фаза 2: Полный конвейер
  |
  Фаза 2: detect_debug_intent() -> 8 функций поиска -> CPG-запросы
           -> LLM с контекстом отладки -> Запасной ответ при недоступности LLM

Зарегистрированные обработчики¶

2 обработчика зарегистрированы в HandlerRegistry("debugging"):

Оба наследуют DebuggingHandler (расширяет BaseHandler), который предоставляет 4 метода анализа, описанных ниже.

Функции CPG-поиска¶

Фаза 2 диспетчеризует одну из 8 функций поиска на основе обнаруженного базового интента. Каждая функция строит SQL-запросы к таблицам nodes_call / nodes_method:

find_breakpoint_functions использует морфологическое сопоставление ключевых слов с паттернами подсистем из domain.get_breakpoint_subsystem_patterns() для выбора контекстно-специфичных SQL-запросов через build_breakpoint_query(subsystem, like_prefix).

generic_debug_search извлекает потенциальные имена функций через regex, фильтрует стоп-слова и ищет совпадения в nodes_method, возвращаясь к типичным отладочным паттернам при отсутствии результатов.

Доменно-независимая загрузка паттернов¶

Все отладочные паттерны загружаются из активного доменного плагина — никаких жёстко закодированных доменно-специфичных символов. get_debug_patterns_from_plugin() в debugging/patterns.py предоставляет 7 категорий с функциями и ключевыми словами:

При отсутствии доменного плагина используются универсальные значения по умолчанию (printf, assert, trace и т.д.).

Методы анализа DebuggingHandler¶

DebuggingHandler(BaseHandler) в debugging_handlers/handlers/base.py предоставляет 4 метода анализа, используемых зарегистрированными обработчиками:

Предложение точек останова¶

_suggest_breakpoint_locations(target_function, issue_type, topic, limit=15) — предлагает расположения точек останова с уровнями приоритета:

• Если указана target_function: добавляет саму функцию (высокий приоритет), её вызывающих (средний) и вызываемых (средний) из CPG
• Загружает доменно-специфичные функции точек останова через _get_breakpoint_functions_from_plugin(topic)
• Каждое предложение содержит: function, reason, priority (high/medium/low), type (entry_point/caller/callee/checkpoint/topic_function)

Анализ стека вызовов¶

_analyze_call_stack(start_function, depth=5) — анализирует цепочки вызовов от стартовой функции:

• Получает вызывающих (кто вызывает эту функцию) через cpg.get_callers()
• Получает вызываемых (что вызывает эта функция) через cpg.get_callees()
• Возвращает списки callers_chain и callees_chain с именами функций и путями файлов

Трассировка потока переменных¶

_trace_variable_flow(variable_name, function_name) — трассирует поток переменных через области видимости функций:

• Ищет функцию в CPG через cpg.find_method_by_name()
• Получает вызываемых для определения, куда могут распространяться значения переменных
• Возвращает точки потока с типом (function_scope, potential_propagation), именем файла и номером строки

Генерация стратегии отладки¶

_generate_debugging_strategy(issue_type, target_function) — генерирует стратегии отладки по типам проблем:

Детекция типа проблемы¶

DebuggingIntentDetector._extract_issue_type() классифицирует тип проблемы из запроса с помощью морфологического сопоставления с EN+RU ключевыми словами:

Обнаруженный тип проблемы влияет на предложения точек останова (какие функции приоритизировать) и стратегию отладки (какие инструменты и шаги рекомендовать).

Форматтеры отчётов¶

DebugReportFormatter(DebuggingFormatter) в debugging_handlers/formatters/debug_report.py предоставляет 2 формата отчётов:

• format_breakpoint_report(report_data, language) — markdown-отчёт с целевой функцией, типом проблемы, разбивкой по приоритетам (количество high/medium/low), таблицей предложений (значок приоритета, функция, значок типа, причина) и 3 рекомендациями
• format_call_stack_report(report_data, language) — markdown-отчёт с целевой функцией, сводкой (количество вызывающих/вызываемых, глубина анализа), списком цепочки вызывающих, списком цепочки вызываемых и 3 рекомендациями

Базовый класс DebuggingFormatter предоставляет форматирование значков: format_priority_badge(priority, language) и format_breakpoint_type_badge(bp_type, language) для типов entry_point, caller, callee, checkpoint.

Использование CLI¶

# Поиск точек останова для функции
python -m src.cli query "Suggest breakpoints for debugging heap_insert"

# Анализ стека вызовов
python -m src.cli query "Show call stack for ExecProcNode"

# Поиск обработчиков ошибок
python -m src.cli query "Find error handlers in the executor module"

# Трассировка потока переменных
python -m src.cli query "Trace variable flow through palloc"

# Стратегия отладки для падения
python -m src.cli query "How to debug a crash in heap_insert"

# Поиск вызовов логирования
python -m src.cli query "Find all logging calls at ERROR level"

# Поиск макросов assert
python -m src.cli query "Find assertion macros in the storage subsystem"

Примеры вопросов¶

• «Предложить точки останова для отладки [функции]»
• «Показать стек вызовов для [функции]»
• «Найти обработчики ошибок в [модуле]»
• «Какие функции вызывает [функция]?»
• «Отследить поток переменных через [функцию]»
• «Как отладить падение в [функции]»
• «Найти все вызовы логирования уровня ERROR»
• «Найти макросы assert в [подсистеме]»
• «Отладить утечку памяти в [модуле]»
• «Показать стратегию отладки для проблем взаимоблокировки»

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

• Производительность — Профилирование производительности и анализ узких мест (S06)
• Безопасность — Обнаружение уязвимостей безопасности (S02)
• Рефакторинг — Обнаружение запахов кода и мёртвого кода (S05)
• Ознакомление — Исследование и понимание кодовой базы (S01)

S15 vs S06 vs S02 vs S05: S15 фокусируется на интерактивной поддержке отладки — предложения точек останова, анализ стека вызовов, трассировка путей ошибок и стратегии отладки по типам проблем (crash, hang, memory leak). S06 фокусируется на профилировании производительности — обнаружение горячих точек, анализ узких мест и рекомендации по оптимизации. S02 фокусируется на безопасности — сканирование уязвимостей, анализ потоков данных и проверки соответствия. S05 фокусируется на качестве кода — обнаружение запахов, мёртвый код и планы рефакторинга. S15 разделяет CPG-запросы и анализ графа вызовов с этими сценариями, но применяет их конкретно к рабочим процессам отладки.