Композитные рабочие процессы

Композитные рабочие процессы

Руководство по архитектуре и использованию композиции и оркестрации сценариев.

Содержание

Обзор

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

Ключевые преимущества

  • Комплексный анализ: Объединение проверок безопасности, производительности и качества
  • Дедупликация: Автоматическое объединение и дедупликация находок
  • Разрешение конфликтов: Разрешение противоречивых рекомендаций
  • Оценка приоритетов: Ранжирование находок по комбинированным метрикам
  • Единая точка входа: Одна команда для полного анализа

Архитектура

┌─────────────────────────────────────────────────────────────────────────────┐
│                    АРХИТЕКТУРА КОМПОЗИТНОГО РАБОЧЕГО ПРОЦЕССА                │
│                                                                              │
│  Запрос пользователя: "Оптимизировать src/"                                  │
│        │                                                                     │
│        ▼                                                                     │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │                    ОРКЕСТРАТОР (S18 или S19)                            │ │
│  │                                                                          │ │
│  │  ┌─────────────────────────────────────────────────────────────────┐   │ │
│  │  │                   ВЫЗЫВАТЕЛЬ СЦЕНАРИЕВ                           │   │ │
│  │  │                                                                   │   │ │
│  │  │  Параллельное выполнение:                                         │   │ │
│  │  │  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐                    │   │ │
│  │  │  │ S02 │  │ S05 │  │ S06 │  │ S11 │  │ S12 │                    │   │ │
│  │  │  │Безоп│  │Рефак│  │Произ│  │Архит│  │Долг │                    │   │ │
│  │  │  └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘                    │   │ │
│  │  │     │        │       │        │        │                         │   │ │
│  │  │     └────────┴───────┴────────┴────────┘                         │   │ │
│  │  │                      │                                            │   │ │
│  │  │              Результаты подсценариев                              │   │ │
│  │  └──────────────────────┼───────────────────────────────────────────┘   │ │
│  │                         │                                                │ │
│  │  ┌──────────────────────▼───────────────────────────────────────────┐   │ │
│  │  │                ОБЪЕДИНИТЕЛЬ РЕЗУЛЬТАТОВ                           │   │ │
│  │  │                                                                   │   │ │
│  │  │  Стратегия: union | intersection | weighted | consensus          │   │ │
│  │  │  - Дедупликация (порог схожести: 0.8)                             │   │ │
│  │  │  - Отслеживание источников                                        │   │ │
│  │  │  - Сохранение метаданных                                          │   │ │
│  │  └──────────────────────┼───────────────────────────────────────────┘   │ │
│  │                         │                                                │ │
│  │  ┌──────────────────────▼───────────────────────────────────────────┐   │ │
│  │  │                 РАЗРЕШИТЕЛЬ КОНФЛИКТОВ                            │   │ │
│  │  │                                                                   │   │ │
│  │  │  Режим: priority_based | security_first | interactive            │   │ │
│  │  │  - Обнаружение противоречивых рекомендаций                        │   │ │
│  │  │  - Применение правил разрешения                                   │   │ │
│  │  │  - Логирование решений                                            │   │ │
│  │  └──────────────────────┼───────────────────────────────────────────┘   │ │
│  │                         │                                                │ │
│  │  ┌──────────────────────▼───────────────────────────────────────────┐   │ │
│  │  │                КАЛЬКУЛЯТОР ПРИОРИТЕТОВ                            │   │ │
│  │  │                                                                   │   │ │
│  │  │  Алгоритм: weighted_sum | risk_based | custom                     │   │ │
│  │  │  Веса: серьёзность(0.3) × влияние(0.25) × roi(0.2)                │   │ │
│  │  │        × уверенность(0.15) × консенсус(0.1)                       │   │ │
│  │  └──────────────────────┼───────────────────────────────────────────┘   │ │
│  │                         │                                                │ │
│  └─────────────────────────┼────────────────────────────────────────────────┘ │
│                            │                                                  │
│                            ▼                                                  │
│                  УНИФИЦИРОВАННЫЕ НАХОДКИ                                      │
│                  (отсортированы по приоритету)                                │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

S18 как оркестратор

Сценарий 18 (Оптимизация кода) оркестрирует несколько сценариев анализа для комплексного улучшения кода:

Подсценарии

Сценарий Название Вес Вклад
S02 Аудит безопасности 1.5 Уязвимости безопасности
S05 Рефакторинг 1.0 Запахи кода, мёртвый код
S06 Производительность 1.2 Узкие места производительности
S11 Архитектура 1.1 Нарушения архитектуры
S12 Технический долг 0.9 Элементы технического долга

Поток выполнения

Запрос оптимизации S18
        │
        ├─→ S02: Анализ безопасности
        ├─→ S05: Анализ рефакторинга
        ├─→ S06: Анализ производительности
        ├─→ S11: Анализ архитектуры
        └─→ S12: Анализ технического долга
                │
                ▼
        Объединение находок (взвешенное)
                │
                ▼
        Разрешение конфликтов
                │
                ▼
        Расчёт приоритетов
                │
                ▼
        Унифицированный отчёт об оптимизации

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

# CLI
codegraph composition run "Оптимизировать src/core/" -o s18

# TUI
/select 18
> Проанализировать src/core/ для комплексной оптимизации

Вывод

╭─────────────── Результаты композитной оптимизации ──────────╮
│                                                                │
│  Вызванные подсценарии: S02, S05, S06, S11, S12                │
│  Находок до объединения: 87                                    │
│  Находок после объединения: 52                                 │
│  Удалено дубликатов: 35                                        │
│  Разрешено конфликтов: 3                                       │
│  Время выполнения: 4.2с                                        │
│                                                                │
│  Топ находок:                                                  │
│                                                                │
│  1. [Критическое] Уязвимость SQL-инъекции                      │
│     Источник: S02 (Безопасность)                               │
│     Оценка приоритета: 0.95                                    │
│                                                                │
│  2. [Высокое] Узкое место производительности в цикле           │
│     Источник: S06 (Производительность)                         │
│     Оценка приоритета: 0.87                                    │
│                                                                │
│  3. [Высокое] Нарушение слоя архитектуры                       │
│     Источник: S11 (Архитектура)                                │
│     Оценка приоритета: 0.82                                    │
│                                                                │
╰────────────────────────────────────────────────────────────────╯

S19 как оркестратор

Сценарий 19 (Проверка стандартов) оркестрирует проверку соответствия с правилами на основе документов:

Подсценарии

Сценарий Название Вклад
S08 Соответствие Правила соответствия стандартам
S17 Редактирование файлов Применение исправлений

Обогащение документами

S19 обогащает находки ссылками из документов стандартов:

Документ стандартов
        │
        ▼
    Извлечение правил
        │
        ├─→ S08: Анализ соответствия
        │         │
        │         ▼
        │   Найденные нарушения
        │         │
        │         ▼
        └─→ Обогащение документами
                  │
                  ▼
        Нарушения со ссылками

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

# CLI
codegraph composition run "Проверить на соответствие стандартам OWASP" -o s19

# С пользовательским документом стандартов
codegraph composition run "Проверить по company_standards.yaml" -o s19

Компоненты композиции

ScenarioInvoker

Вызывает подсценарии с параллельным или последовательным выполнением:

from src.workflow.composition import ScenarioInvoker

invoker = ScenarioInvoker()

# Параллельное выполнение (по умолчанию)
results = invoker.invoke_parallel(
    scenarios=["scenario_02", "scenario_06", "scenario_11"],
    state=state,
    timeout=30.0,
)

# Последовательное выполнение
results = invoker.invoke_sequential(
    scenarios=["scenario_02", "scenario_06"],
    state=state,
)

ResultMerger

Объединяет находки с настраиваемыми стратегиями:

from src.workflow.composition import ResultMerger, MergeStrategy

merger = ResultMerger()

# Объединение со стратегией union (включить все)
result = merger.merge(
    scenario_results={"s02": findings_s02, "s06": findings_s06},
    strategy=MergeStrategy.UNION,
)

# Объединение со взвешенной стратегией
result = merger.merge(
    scenario_results=all_findings,
    strategy=MergeStrategy.WEIGHTED,
)

Стратегии объединения

Стратегия Описание Вариант использования
union Включить все находки Комплексный анализ
intersection Только находки из 2+ сценариев Только высокая уверенность
weighted Взвешивать по приоритету сценария Приоритизированный анализ
consensus Находки с согласием Консервативный подход

ConflictResolver

Разрешает противоречивые рекомендации:

from src.workflow.composition import ConflictResolver

resolver = ConflictResolver()

# Разрешение конфликтов
resolved_findings, resolution_log = resolver.resolve_conflicts(
    findings=unified_findings,
    mode="priority_based",
)

Типы конфликтов

Тип Описание Разрешение
Одно место Несколько находок для одного кода Оставить с высшим приоритетом
Противоречие Противоречивые рекомендации Применить правила разрешения
Перекрытие Частично перекрывающиеся находки Объединить или выбрать

PriorityCalculator

Вычисляет комбинированные оценки приоритетов:

from src.workflow.composition import PriorityCalculator

calculator = PriorityCalculator()

# Вычислить и отсортировать по приоритету
prioritized = calculator.sort_by_priority(findings)

# Получить разбивку приоритета
breakdown = calculator.get_priority_breakdown(finding)

Веса приоритетов

Фактор Вес Описание
severity 0.30 Уровень серьёзности находки
impact 0.25 Оценка потенциального влияния
roi 0.20 Возврат инвестиций
confidence 0.15 Уверенность обнаружения
consensus 0.10 Согласие между сценариями

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

Настройка композиции в config.yaml:

composition:
  enabled: true

  orchestrators:
    scenario_18:
      sub_scenarios:
        - scenario_02  # Безопасность
        - scenario_05  # Рефакторинг
        - scenario_06  # Производительность
        - scenario_11  # Архитектура
        - scenario_12  # Технический долг
      parallel_execution: true
      timeout_seconds: 60
      enabled: true

    scenario_19:
      sub_scenarios:
        - scenario_08  # Соответствие
        - scenario_17  # Редактирование файлов
      parallel_execution: false
      timeout_seconds: 30
      enabled: true

  merging:
    strategy: weighted  # union, intersection, weighted, consensus
    deduplication_threshold: 0.8
    max_findings: 100
    preserve_sources: true

  priority:
    algorithm: weighted_sum  # weighted_sum, risk_based, custom
    weights:
      severity: 0.30
      impact: 0.25
      roi: 0.20
      confidence: 0.15
      consensus: 0.10

  conflicts:
    resolution_mode: priority_based  # priority_based, security_first, interactive
    security_priority_boost: 1.5
    compliance_priority_boost: 1.3
    log_resolutions: true

API-эндпоинты

POST /api/v1/composition/query

Выполнить композитный рабочий процесс:

POST /api/v1/composition/query
Content-Type: application/json
Authorization: Bearer <token>

{
  "query": "Оптимизировать src/core/",
  "orchestrator": "scenario_18",
  "context": {
    "language": "ru",
    "file_paths": ["src/core/"]
  },
  "parallel": true,
  "merge_strategy": "weighted"
}

Ответ:

{
  "session_id": "sess_abc123",
  "answer": "Найдено 52 возможности для оптимизации...",
  "unified_findings": [...],
  "priority_scores": {...},
  "sub_scenario_results": {...},
  "conflicts_resolved": 3,
  "execution_time_ms": 4234.5,
  "metadata": {...}
}

POST /api/v1/composition/apply

Применить ожидающую правку из сессии:

POST /api/v1/composition/apply
Content-Type: application/json
Authorization: Bearer <token>

{
  "session_id": "sess_abc123",
  "finding_id": "find_xyz789",
  "preview": true
}

GET /api/v1/composition/conflicts/{session_id}

Получить информацию о конфликтах для сессии:

GET /api/v1/composition/conflicts/sess_abc123
Authorization: Bearer <token>

GET /api/v1/composition/session/{session_id}

Получить полное состояние сессии:

GET /api/v1/composition/session/sess_abc123
Authorization: Bearer <token>

GET /api/v1/composition/config

Получить конфигурацию композиции:

GET /api/v1/composition/config
Authorization: Bearer <token>

Команды CLI

# Запустить композитный рабочий процесс
codegraph composition run "<запрос>" -o s18|s19

# Запустить с конкретными подсценариями
codegraph composition run "Анализировать src/" -o s18 -s scenario_02 -s scenario_06

# Запустить со стратегией объединения
codegraph composition run "Оптимизировать код" -o s18 --merge-strategy weighted

# Применить ожидающую правку
codegraph composition apply <finding_id> -s <session_id>

# Предпросмотр правки перед применением
codegraph composition apply <finding_id> -s <session_id> --preview

# Просмотреть конфликты
codegraph composition conflicts -s <session_id>

# Просмотреть конфигурацию
codegraph composition config

# Список доступных сценариев
codegraph composition scenarios

Лучшие практики

1. Выбор правильного оркестратора

  • S18 для оптимизации: Когда нужны улучшения производительности, безопасности и качества
  • S19 для соответствия: Когда нужна проверка стандартов со ссылками

2. Настройка стратегии объединения

# Для комплексного анализа (включить всё)
merging:
  strategy: union

# Только для находок с высокой уверенностью
merging:
  strategy: intersection

# Для приоритизированного анализа
merging:
  strategy: weighted

3. Обработка конфликтов

Включите логирование конфликтов для понимания решений по разрешению:

conflicts:
  log_resolutions: true

4. Оптимизация производительности

Для больших кодовых баз используйте параллельное выполнение с таймаутом:

orchestrators:
  scenario_18:
    parallel_execution: true
    timeout_seconds: 120

5. Настройка весов приоритетов

Настройте веса в соответствии с приоритетами вашей команды:

priority:
  weights:
    severity: 0.40  # Приоритет серьёзности
    impact: 0.20
    roi: 0.20
    confidence: 0.10
    consensus: 0.10

Связанная документация