Композитные рабочие процессы¶
Руководство по архитектуре и использованию композиции и оркестрации сценариев.
Содержание¶
- Обзор
- Архитектура
- S18 как оркестратор
- S19 как оркестратор
- Компоненты композиции
- Конфигурация
- API-эндпоинты
- Команды CLI
- Лучшие практики
Обзор¶
Композитные рабочие процессы позволяют сценариям действовать как оркестраторы, вызывающие несколько подсценариев для комплексного анализа. Это обеспечивает сложный многогранный анализ кода без необходимости запускать сценарии по отдельности.
Ключевые преимущества¶
- Комплексный анализ: Объединение проверок безопасности, производительности и качества
- Дедупликация: Автоматическое объединение и дедупликация находок
- Разрешение конфликтов: Разрешение противоречивых рекомендаций
- Оценка приоритетов: Ранжирование находок по комбинированным метрикам
- Единая точка входа: Одна команда для полного анализа
Архитектура¶
┌─────────────────────────────────────────────────────────────────────────────┐
│ АРХИТЕКТУРА КОМПОЗИТНОГО РАБОЧЕГО ПРОЦЕССА │
│ │
│ Запрос пользователя: "Оптимизировать 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