Сценарий 01: Онбординг в кодовую базу

Новый разработчик присоединяется к команде и быстро осваивает структуру кодовой базы с помощью CPG-анализа.

Содержание

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

# Выберите сценарий онбординга
/select 01

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

Детекция типа запроса

При получении запроса OnboardingQueryDetector классифицирует его с помощью 4 mixin-детекторов в 5-фазном конвейере:

Mixin-детектор Методы Детектирует
DefinitionDetectorMixin 4 Определение функций, сигнатуры, пути к файлам
CallGraphDetectorMixin 11 Вызывающие, вызываемые, пути, циклы, центральность, SCC/WCC
DataflowDetectorMixin 4 Потоки данных, распространение, границы привилегий
SubsystemDetectorMixin 14 Обзор подсистем, отладка, бизнес-логика, внешний контекст

Детекция выполняется в 5 фазах:

Запрос
  |
  v
[Фаза 1] Ранний выход — определения функций в скобках
  |
  v
[Фаза 2] Сложные структурные проверки (17 правил)
  |
  v
[Фаза 3] Трассировка жизненного цикла и выполнения
  |
  v
[Фаза 4] Таблица диспатчеризации — правила по приоритету
  |
  v
[Фаза 5] Цепочка отката
  |
  v
DetectionResult(type, target, target_variants, variable,
                module_filter, file_path_filter, directory_filter)

Поддержка русского и английского языков с морфологическим сопоставлением через keyword_match_morphological().

Архитектура обработчиков

Сценарий онбординга использует архитектуру на основе обработчиков с OnboardingHandlerRegistry, содержащим 65 зарегистрированных обработчиков в 7 категориях:

DetectionResult
    |
    v
OnboardingHandlerRegistry → поиск обработчика по типу запроса
    |
    v
OnboardingHandler.handle(query_info)
    |
    v
OnboardingResult
    |-- should_return=True  → возврат форматированного ответа (+ обогащение)
    |-- should_return=False → сбор данных, передача в LLM
    |
    v
Страховочная сеть постобработки (ловит пропущенные запросы)
    |
    v
Генерация ответа LLM (если обработчик не сработал)

Каждый обработчик наследует от OnboardingHandler и возвращает OnboardingResult с 8 полями:

Поле Тип Описание
cpg_results list Результаты CPG-запросов
retrieved_functions list Имена функций для контекста
answer str Форматированный ответ
evidence list Строки-доказательства
handled_flag str Флаг состояния для предотвращения повторной обработки
should_return bool Вернуть немедленно или продолжить к LLM
graph_context dict Дополнительные данные графа
skip_enrichment bool Отказ от обогащения через LLM

Стратегия извлечения

Базовый OnboardingHandler предоставляет 6 специализированных методов для многоисточникового извлечения:

Метод Источник Назначение
_vector_search_fallback() ChromaDB code_comments Семантический поиск в докстрингах, когда CPG ничего не возвращает
_snippet_search() ChromaDB code_snippets Поиск в реализациях функций
_domain_pattern_search() ChromaDB domain_patterns Поиск шаблонов безопасности
_vector_supplement() Все источники 4-фазное аддитивное слияние (см. ниже)
_get_pre_retrieval_names() state["pre_retrieval_results"] Интеграция результатов HybridRetriever
enrich_retrieved_functions() CPG Добавление типов сущностей (функция/класс/интерфейс)

Метод _vector_supplement() выполняет 4-фазное аддитивное слияние для максимального покрытия:

Фаза 1: Точные совпадения CPG (высший приоритет)
Фаза 2: Результаты предварительного извлечения (HybridRetriever)
Фаза 3: Дополнения векторного поиска (семантическое сходство)
Фаза 4: Дополнения из фрагментов кода (поиск по реализации)
    → Дедуплицированный объединённый список

Конвейер обогащения

Когда обработчик возвращает should_return=True и обогащение включено, запускается 3-фазный конвейер:

OnboardingResult (от обработчика)
    |
    v
[Фаза 1] CPG Comments
    |-- Пакетное извлечение описаний функций из комментариев
    |-- Слияние описаний в cpg_results
    |-- Переформатирование ответа с описаниями
    |
    v
[Фаза 2] Векторный контекст (параллельно, 4 воркера)
    |-- Пары вопрос-ответ (retrieve_qa)
    |-- Примеры SQL (retrieve_sql)
    |-- Сгенерированная документация (retrieve_generated_docs)
    |-- Комментарии к коду (retrieve_comments)
    |-- Добавление к evidence
    |
    v
[Фаза 3] Синтез LLM (опционально)
    |-- Построение промпта с CPG + векторный контекст
    |-- Генерация обогащённого ответа (кеширование по хешу запроса)
    |-- Сохранение оригинала как _original_answer

Обработчики могут установить skip_enrichment=True для отказа (напр., для структурированных табличных ответов).

Примеры использования

День 1: Обзор кодовой базы

Задайте общие вопросы о системе:

> Что такое подсистема исполнителя (executor)?

╭─────────────── Ответ ────────────────╮
│ Подсистема исполнителя отвечает за  │
│ выполнение планов запросов,          │
│ сгенерированных планировщиком.       │
│                                      │
│ Основные компоненты:                 │
│   - ExecutorStart: Инициализация     │
│   - ExecutorRun: Основной цикл       │
│   - ExecutorEnd: Освобождение ресурсов│
│                                      │
│ Точка входа: src/backend/executor/   │
│              execMain.c              │
╰──────────────────────────────────────╯

> Каковы основные точки входа в подсистему исполнителя?

> Покажи архитектуру выполнения запросов

Поиск определений

DefinitionOnboardingHandler находит реализации функций с сигнатурами и связанными функциями, форматирует через DefinitionFormatter:

> Где определена функция palloc?

╭─────────────── Ответ ────────────────╮
│ palloc определена в:                 │
│   src/backend/utils/mmgr/mcxt.c:1089 │
│                                      │
│ Сигнатура:                           │
│   void *palloc(Size size)            │
│                                      │
│ Связанные функции:                   │
│   palloc0(), palloc_extended(),      │
│   repalloc(), pfree()                │
╰──────────────────────────────────────╯

Понимание графа вызовов

Семейство CallGraphOnboardingHandler (8 обработчиков) предоставляет вызывающие, вызываемые, кратчайшие пути, обнаружение циклов, анализ SCC/WCC и метрики центральности, форматирует через CallGraphFormatter:

> Покажи все места, где вызывается palloc

╭─────────────── Вызывающие функции ──────────────╮
│ 1. heap_form_tuple()                           │
│ 2. ExecStoreTuple()                            │
│ 3. construct_array()                           │
│ 4. pnstrdup()                                  │
│ 5. SPI_connect()                               │
│ ... (показано первые 5 из 2 847 вызывающих)    │
╰────────────────────────────────────────────────╯

> Какие функции вызывает LWLockAcquire?

> Найди кратчайший путь вызовов от main до heap_insert

> Обнаружь циклы в графе вызовов executor

Отслеживание потока данных

Семейство DataflowOnboardingHandler (5 обработчиков) отслеживает потоки данных, распространение заражения, границы привилегий, достижимые определения и межпроцедурные потоки:

> Как проходят данные от pg_parse_query до исполнителя?

╭─────────────── Поток данных ─────────────╮
│ pg_parse_query()                         │
│     ↓                                    │
│ pg_analyze_and_rewrite()                 │
│     ↓                                    │
│ pg_plan_queries()                        │
│     ↓                                    │
│ PortalRun()                              │
│     ↓                                    │
│ ExecutorRun()                            │
│     ↓                                    │
│ ExecProcNode()                           │
╰──────────────────────────────────────────╯

Внешний контекст

Обработчики внешнего контекста запрашивают историю Git и трекеры задач:

> Кто написал heap_insert?                  → AuthorQueryOnboardingHandler
> Какие задачи связаны с executor?           → IssueQueryOnboardingHandler
> Покажи проблемные участки в parser         → ErrorHotspotOnboardingHandler
> Какие функции меняются чаще всего?         → ChurnAnalysisOnboardingHandler

Категории обработчиков

Основные обработчики

Категория Кол-во Ключевые обработчики
Определения 1 DefinitionOnboardingHandler — сигнатуры, местоположение, связанные функции
Граф вызовов 8 CallGraph, ShortestPath, CallDepth, CycleDetection, SCC, WCC, Centrality, Intersection
Потоки данных 5 Dataflow, TaintFlow, PrivilegeBoundary, ReachingDefinitions, InterproceduralFlow
Транзитивные вызовы 4 LimitedCallers, MultiLevelCallers, TransitiveCallees, CommonCallees
Типы запросов 3 Debug, BusinessLogic, Subsystem
Внешний контекст 4 Author, Issues, ErrorHotspot, ChurnAnalysis
Утилиты 5 General, MechanismExplanation, FunctionSearch, ProjectStatistics, FileStructure

Кросс-сценарные адаптеры

19 адаптеров связывают онбординг с другими сценариями без выхода из контекста онбординга:

  • Обнаружение клонов: CloneDetection, SemanticClone, StructuralClone, PatternClone
  • Документация: APIDoc, ModuleDoc, SystemDoc, FunctionDoc
  • Отладка: DebugPoints, Hooks, MacroDefinition, ErrorPaths, ErrorHandling
  • Прочее: ExtensionPoints, APIMigration, UnitTest, DMLFlow, TraceExecution

Обработчики безопасности и рефакторинга

Категория Кол-во Обработчики
Безопасность 5 MemorySafetyVuln, InputValidationVuln, AuthSecurity, RaceCondition, NetworkEntry
Рефакторинг 4 BulkOperations, ExtractionCandidates, FullAudit, DDLFlow
Подтипы анализа 14 DeadCode, Tracking, Memory, Concurrency, EntryPoint, TrustBoundary и др.

Конфигурация

Лимиты обработчиков в config.yaml через класс HandlerLimits:

workflows:
  handlers:
    limits:
      retrieved_functions: 25    # Размер финального списка результатов
      cpg_results: 50            # Лимит результатов CPG-запросов
      display_items: 15          # Элементов в выводе
      callers: 15                # Лимит вызывающих в графе
      callees: 15                # Лимит вызываемых в графе

Конфигурация обогащения (опционально, отключено по умолчанию):

workflows:
  onboarding:
    enrichment:
      enable: false              # Включить конвейер обогащения
      enable_vector: false       # Включить фазу векторного контекста
      enable_llm: false          # Включить фазу синтеза LLM
      vector_top_k: 3            # Результатов векторного поиска на коллекцию
      max_functions_to_describe: 10

Всё доменно-специфичное поведение (категории отладки, DML-функции, ключевые слова бизнес-логики, алиасы подсистем) поступает из активного доменного плагина через get_active_domain() — ничего не захардкожено.

CLI

# Онбординг по запросу
python -m src.cli query "Где определена функция palloc?"

# Глубокий анализ с LLM
python -m src.cli exec --prompt "Объясни архитектуру подсистемы executor"

# Исследование графа вызовов
python -m src.cli query "Покажи вызывающие heap_insert"

# Трассировка потока данных
python -m src.cli query "Как проходят данные от parser до executor?"

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

Определения и структура: - «Где определена функция palloc?» - «Что такое подсистема executor?» - «Покажи структуру файлов src/backend/executor» - «Сколько функций в кодовой базе?»

Граф вызовов: - «Покажи все вызывающие heap_insert» - «Какие функции вызывает ExecProcNode?» - «Найди кратчайший путь от main до SPI_execute» - «Обнаружь циклы в графе вызовов» - «Покажи центральность по посредничеству для функций executor»

Потоки данных: - «Как проходят данные от pg_parse_query до executor?» - «Отследи распространение данных от пользовательского ввода до SQL» - «Покажи пересечения границ привилегий»

Внешний контекст: - «Кто написал heap_insert?» - «Какие задачи связаны с parser?» - «Покажи проблемные участки в utils» - «Какие функции меняются чаще всего?»

Безопасность (через онбординг): - «Найди проблемы безопасности памяти в executor» - «Покажи пробелы в валидации ввода» - «Найди гонки данных в разделяемой памяти»

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