Сценарий 04: Разработка функционала

Разработчик изучает существующий код для добавления новых функций.

Содержание

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

# Выберите сценарий разработки функций
/select 04

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

Классификация интентов

FeatureDevIntentDetector классифицирует запросы по одному из 4 интентов (+ запасной вариант). Каждый интент имеет ключевые слова на EN и RU с морфологическим сопоставлением.

Интент Приоритет Ключевые слова (EN) Ключевые слова (RU)
integration_points 10 where to add, hook point, implement feature куда добавить, точка интеграции
similar_features 20 similar to, pattern, existing feature похожая функция, паттерн, подобный
extension_points 30 extension point, plugin, hook, extend точка расширения, плагин, хук
dependency_analysis 40 dependency, prerequisite, required зависимость, требование, необходимый

Если ни один интент не совпал, используется запасной general_feature_dev (confidence=0.5).

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

S04 использует двухфазный подход для оптимальной производительности:

Фаза 1: На основе хендлеров (без LLM). Функция integrate_handlers() пробует шаблонные хендлеры, которые формируют структурированные отчёты непосредственно из данных CPG. Если хендлер совпадает с обнаруженным интентом и находит результаты, ответ возвращается без вызова LLM.

Фаза 2: Запасной вариант LLM. Если ни один хендлер не совпал или хендлер нашёл 0 результатов, запускается полный конвейер: извлечение ключевых слов, запросы к CPG (4-уровневая цепочка), CallGraphAnalyzer для точек интеграции, DependencyAnalyzer для анализа центральности, затем генерация через LLM.

Query -> FeatureDevIntentDetector -> integrate_handlers()
  |                                       |
  |  Фаза 1: Хендлер совпал?     Да -> Структурированный отчёт (без LLM)
  |                               Нет -> Фаза 2: Полный конвейер
  |
  Фаза 2: Доменный плагин -> Запросы CPG -> CallGraphAnalyzer
           -> DependencyAnalyzer -> LLM -> Ответ

Три хендлера

Три хендлера зарегистрированы в HandlerRegistry("feature_dev"), отсортированы по приоритету:

Хендлер Приоритет Интент Назначение
ExtensionPointHandler 5 extension_points Поиск точек расширения/перехвата в CPG по категории, с запасным поиском и ранжированием по релевантности
IntegrationPointsHandler 10 integration_points Поиск точек перехвата, точек входа из доменного плагина, расчёт сложности интеграции
SimilarFeaturesHandler 20 similar_features Поиск похожих шаблонов, анализ зависимостей, рекомендация размещения, классификация типов шаблонов

Все хендлеры наследуют FeatureDevHandler -> BaseHandler и возвращают HandlerResult с полями data, retrieved_functions, evidence и metadata.

Понимание существующего кода

> Найти функции, связанные с обработкой транзакций

╭─────────────── Связанный код ───────────────────────────────╮
│                                                              │
│  Функции транзакций:                                         │
│                                                              │
│  Точки входа:                                                │
│    StartTransaction()      src/backend/access/transam/xact.c │
│    CommitTransaction()     src/backend/access/transam/xact.c │
│    AbortTransaction()      src/backend/access/transam/xact.c │
│                                                              │
│  Вспомогательные функции:                                    │
│    AssignTransactionId()   src/backend/access/transam/xact.c │
│    GetCurrentTransactionId() src/backend/access/transam/xact.c │
│                                                              │
│  Связанные модули:                                           │
│    src/backend/access/heap/  - Операции с кучей              │
│    src/backend/storage/lmgr/ - Менеджер блокировок           │
│                                                              │
╰──────────────────────────────────────────────────────────────╯

Анализ цепочек вызовов

> Показать путь вызова от парсера к исполнителю

╭─────────────── Цепочка вызовов ─────────────────────────────╮
│                                                              │
│  Поток Парсер -> Исполнитель:                                │
│                                                              │
│  1. pg_parse_query()                                         │
│       |                                                      │
│  2. pg_analyze_and_rewrite()                                 │
│       |                                                      │
│  3. pg_plan_queries()                                        │
│       |                                                      │
│  4. PortalRun()                                              │
│       |                                                      │
│  5. ExecutorStart() -> ExecutorRun() -> ExecutorFinish()      │
│       |                                                      │
│  6. ExecProcNode() [диспетчеризация по конкретным узлам]     │
│                                                              │
╰──────────────────────────────────────────────────────────────╯

Интеграция CallGraphAnalyzer

Основной workflow использует CallGraphAnalyzer из src/analysis/ для глубокого анализа точек интеграции:

  • find_all_callers(method, max_depth) — обход графа вызовов вверх для поиска всех транзитивных вызывающих
  • find_all_callees(method, max_depth) — обход графа вызовов вниз для поиска всех транзитивных вызываемых
  • analyze_impact(method) — вычисляет impact_score, transitive_callers, transitive_callees, direct_callers

Методы с большим числом вызывающих (> min_callees) определяются как популярные точки интеграции — хорошие кандидаты для подключения новых функций. Анализ воздействия определяет безопасность: методы с impact_score < 0.5 отмечаются как безопасные для расширения.

Точки интеграции

Поиск точек расширения

> Где я могу добавить новый тип узла?

╭─────────────── Точки расширения ────────────────────────────╮
│                                                              │
│  Добавление нового типа узла исполнителя:                    │
│                                                              │
│  1. Определите структуру узла в:                             │
│     src/include/nodes/execnodes.h                            │
│                                                              │
│  2. Реализуйте операции узла:                                │
│     src/backend/executor/nodeXXX.c                           │
│     - ExecInitXXX()                                          │
│     - ExecXXX()                                              │
│     - ExecEndXXX()                                           │
│                                                              │
│  3. Зарегистрируйте в диспетчере:                            │
│     src/backend/executor/execProcnode.c                      │
│     - ExecInitNode()                                         │
│     - ExecProcNode()                                         │
│                                                              │
╰──────────────────────────────────────────────────────────────╯

ExtensionPointHandler использует определение категории по принципу «наиболее длинное совпадение» по ключевым словам на EN и RU (например, «table access method» -> table_am, «custom scan» -> custom_scan). Категории: aggregate, custom_scan, planner_hooks, executor_hooks, utility_hooks, table_am, index_am, fdw, join_algorithm, authentication.

Точки перехвата и точки входа

IntegrationPointsHandler объединяет три источника данных:

  1. Точки перехвата — функции подсистем из доменного плагина, отфильтрованные по целевому модулю
  2. Точки входа — domain.get_entry_points() для активного домена
  3. Похожие шаблоны — методы, совпадающие с именем функции через запросы ILIKE к CPG

Сложность интеграции рассчитывается по количеству точек перехвата: low / medium / high.

Анализ центральности по посредничеству

Расширение фазы 4A использует DependencyAnalyzer.identify_architectural_chokepoints() для поиска стратегически важных точек интеграции:

  • Методы с betweenness_percentile > betweenness_percentile_high отмечаются как стратегические точки интеграции
  • Они центральны в архитектуре — подходят для функций, затрагивающих несколько подсистем
  • Метаданные включают high_centrality_points, top_centrality_method, max_centrality_percentile

Похожие функции и шаблоны

Классификация шаблонов

SimilarFeaturesHandler классифицирует методы по 5 шаблонам именования:

Шаблон Префиксы
Initialization init_, setup_, create_, new_, alloc_
Handler/callback handle_, process_, on_, exec_, run_
Query/lookup get_, find_, lookup_, fetch_, search_
Validation validate_, check_, verify_, is_, has_
Cleanup free_, destroy_, cleanup_, close_, end_

Рекомендация по размещению

SimilarFeaturesHandler._recommend_placement() рекомендует, куда разместить новый код:

  1. Извлекает ключевые слова из имени функции
  2. Оценивает каждую подсистему по пересечению ключевых слов (с повышением для целевого модуля)
  3. Находит наиболее частый файл среди функций лучшей подсистемы
  4. Определяет ближайший метод (по сходству имён) как точку привязки
  5. Рассчитывает уверенность: overlap / (keywords + 2.0)
> Где разместить новую функцию инвалидации кеша?

╭─────────────── Рекомендуемое размещение ─────────────────────╮
│                                                               │
│  Подсистема: cache manager                                    │
│  Файл: src/backend/utils/cache.c                              │
│  Рядом с методом: cache_lookup() (строка 145)                 │
│  Уверенность: 75%                                             │
│                                                               │
│  Связанные методы в этой области:                             │
│    - cache_insert()                                           │
│    - cache_remove()                                           │
│    - cache_invalidate_all()                                   │
│                                                               │
╰───────────────────────────────────────────────────────────────╯

Примеры шаблонов

> Покажи примеры шаблонов для подсистемы executor

╭─────────────── Примеры шаблонов ─────────────────────────────╮
│                                                               │
│  Примеры из целевой подсистемы:                               │
│                                                               │
│  Метод            | Файл          | Шаблон         | CC      │
│  init_executor()  | execMain.c:42 | Initialization | 3       │
│  exec_scan()      | execScan.c:88 | Handler        | 5       │
│  get_plan_node()  | execUtils.c:15| Query/lookup   | 2       │
│  check_perms()    | execPerms.c:7 | Validation     | 4       │
│  end_executor()   | execMain.c:200| Cleanup        | 1       │
│                                                               │
╰───────────────────────────────────────────────────────────────╯

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

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

S04 полностью доменно-независим — использует get_active_domain() для загрузки доменного плагина, который предоставляет:

  • get_extension_points(category) — функции точек расширения для категории
  • get_extension_categories() — доступные категории с ключевыми словами
  • get_subsystem_functions() — функции, сгруппированные по подсистемам
  • get_entry_points() — имена функций верхнего уровня

При запросе к CPG для поиска совпадающих функций workflow использует 4-уровневую цепочку отката:

  1. Доменный плагин — получить функции из плагина, запрос к CPG по точному имени
  2. Поиск по категории в CPG — вывести английские термины из имени категории, поиск ILIKE
  3. Поиск по ключевым словам в CPG — извлечь ключевые слова из запроса, поиск ILIKE
  4. Запасной поиск перехватчиков — поиск шаблонов *_hook, *Hook*; затем извлечение имён CamelCase/snake_case из запроса

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

# Узнать о точках интеграции
python -m src.cli query "Where to add a new join algorithm?"

# Найти похожие функции
python -m src.cli query "Show similar features to heap_insert"

# Найти точки расширения
python -m src.cli query "Find planner hook injection points"

# Анализ зависимостей
python -m src.cli query "What modules does the buffer manager depend on?"

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

  • «Как работает [feature_name]?»
  • «Какие функции задействованы в [subsystem]?»
  • «Куда разместить новую [функцию] в [модуле]?»
  • «Покажи похожие реализации для [existing_feature]»
  • «Как проходит поток данных для [operation]?»
  • «Найди точки интеграции для [component]»
  • «Покажи примеры шаблонов для [подсистемы]»
  • «Рекомендуй размещение для нового [типа функции]»
  • «Найди точки расширения для [категории]»
  • «Какие точки перехвата есть в [модуле]?»

S04 vs S05 vs S13: S04 направлен на поиск точек интеграции и расширения для добавления новых функций в существующий код. S05 направлен на рефакторинг существующего кода (обнаружение запахов, предложение улучшений). S13 направлен на массовый рефакторинг — координацию масштабных изменений по множеству файлов.