ййй

2026-03-27 15:51:10 +03:00
parent 15586f9a8c
commit 51378c5d66
1234 changed files with 95644 additions and 543076 deletions
@@ -0,0 +1,235 @@
+Ниже обновленная версия с учетом гибридной модели интент роутера.
+
+---
+
+## 1. Концепция агента
+
+Агент проектируется как intent-driven система для работы с кодом и документацией, где пользовательский запрос сначала нормализуется и интерпретируется, затем по нему извлекается релевантный контекст из многослойного RAG, после чего специализированный task workflow выполняет целевую задачу. Агент не является единым “умным чатом”: логика разделена на маршрутизацию, retrieval и специализированные execution workflows. Проверка evidence, вызовы LLM и правила сборки ответа находятся внутри task workflows и зависят от типа задачи.
+
+---
+
+## 2. Компонентная модель
+
+```mermaid
+flowchart LR
+    IDE[IDE Plugin / Client] --> API[API Layer]
+    API --> IR[IntentRouter V3]
+    IR --> RAG[Retrieval RAG]
+
+    RAG --> TW1[Task Workflow: Documentation Explain]
+    RAG --> TW2[Task Workflow: OpenAPI Generation]
+    RAG --> TW3[Task Workflow: Documentation Generation]
+    RAG --> TWN[Other Specialized Task Workflows]
+
+    TW1 --> OUT[Response / Artifact]
+    TW2 --> OUT
+    TW3 --> OUT
+    TWN --> OUT
+```
+
+---
+
+## 3. Основной flow процесса
+
+### Основной процесс
+
+1. Пользователь отправляет запрос через IDE plugin или другой клиент.
+2. `API Layer` принимает запрос и передает его в агент.
+3. `IntentRouter V3`:
+
+   * нормализует запрос;
+   * детерминированно извлекает ключевые артефакты;
+   * с помощью LLM определяет тип задачи и параметры обработки;
+   * формирует параметры retrieval.
+4. Выполняется извлечение данных из `Retrieval RAG`.
+5. Извлеченный контекст передается в соответствующий `Task Workflow`.
+6. Внутри workflow выполняется:
+
+   * подготовка контекста;
+   * evidence-проверки;
+   * вызовы LLM;
+   * формирование результата.
+7. Результат возвращается пользователю.
+
+### Sequence diagram
+
+```mermaid
+sequenceDiagram
+    participant User as User / IDE Plugin
+    participant API as API Layer
+    participant Router as IntentRouter V3
+    participant RAG as Retrieval RAG
+    participant WF as Task Workflow
+
+    User->>API: request
+    API->>Router: agent call
+    Router->>Router: normalize + extract artifacts
+    Router->>Router: LLM routing (task / intent)
+    Router->>RAG: retrieval request
+    RAG-->>Router: retrieved context
+    Router->>WF: route result + context
+    WF->>WF: evidence logic + LLM calls
+    WF-->>API: final result
+    API-->>User: response
+```
+
+---
+
+## 4. Описание компонентов
+
+### 4.1. IDE Plugin / Client
+
+**Задача**
+Точка входа пользователя в агент.
+
+**Как устроен**
+Любой внешний клиент (IDE plugin, web UI и др.), который отправляет запрос и получает результат.
+
+**Почему так**
+Агент изначально проектируется как backend-система, независимая от интерфейса.
+
+---
+
+### 4.2. API Layer
+
+**Задача**
+Обеспечивает внешний интерфейс взаимодействия с агентом.
+
+**Как устроен**
+Принимает запрос, валидирует его и передает во внутренний pipeline, затем возвращает результат.
+
+**Почему так**
+Позволяет изолировать транспортный слой от логики агента.
+
+---
+
+### 4.3. IntentRouter V3
+
+**Задача**
+Определяет, как должен обрабатываться пользовательский запрос и какой сценарий выполнения применить.
+
+**Как устроен**
+
+Гибридная модель из двух частей:
+
+#### 1. Детерминированный слой
+
+Выполняет:
+
+* нормализацию запроса;
+* извлечение ключевых артефактов:
+
+  * домены;
+  * типы сущностей (API, entity, component и т.д.);
+  * явные ссылки (endpoint, путь, имя);
+* выделение базовых сигналов (например: explain / list / generate).
+
+Этот слой задает **жесткие рамки интерпретации запроса**.
+
+#### 2. LLM-роутинг
+
+Использует:
+
+* нормализованный запрос;
+* извлеченные артефакты;
+* описание доступных типов задач;
+
+и определяет:
+
+* тип задачи;
+* общий сценарий обработки;
+* параметры retrieval;
+* ожидаемую форму ответа.
+
+#### Итог
+
+Router формирует:
+
+* параметры retrieval;
+* тип task workflow;
+* контекст для дальнейшего выполнения.
+
+**Почему решение такое**
+
+Ранее использовался более детерминированный подход с фиксированными сценариями, который хорошо работал в узком наборе задач, но плохо масштабируется. Полностью LLM-based роутинг, наоборот, дает гибкость, но теряет предсказуемость и управляемость.
+
+Поэтому выбран гибридный подход:
+
+* детерминированный слой фиксирует ключевые артефакты и ограничения;
+* LLM выполняет гибкую интерпретацию задачи.
+
+Это позволяет:
+
+* сохранить управляемость и стабильность;
+* избежать взрывного роста количества сценариев;
+* поддерживать сложные и нетиповые запросы.
+
+---
+
+### 4.4. Retrieval RAG
+
+**Задача**
+Извлечь релевантный контекст для выполнения задачи.
+
+**Как устроен**
+Многослойная система хранения знаний (код, документация, факты, связи), из которой извлекается структурированный контекст в зависимости от параметров, заданных роутером.
+
+**Почему так**
+Разные задачи требуют разных типов данных, поэтому используется слойная модель вместо плоского поиска.
+
+---
+
+### 4.5. Task Workflows
+
+**Задача**
+Реализуют прикладную логику выполнения конкретного типа задачи.
+
+**Как устроены**
+Набор специализированных workflows, например:
+
+* объяснение по документации;
+* генерация OpenAPI;
+* генерация документации;
+* другие сценарии.
+
+Внутри workflow находятся:
+
+* обработка контекста;
+* evidence-проверки;
+* вызовы LLM;
+* сборка результата.
+
+**Почему так**
+Логика проверки данных и генерации сильно зависит от задачи, поэтому она инкапсулируется в отдельных workflows, а не в одном универсальном слое.
+
+---
+
+### 4.6. Output / Artifact
+
+**Задача**
+Вернуть результат пользователю.
+
+**Как устроен**
+Может быть:
+
+* текстовый ответ;
+* структурированный список;
+* OpenAPI спецификация;
+* документация;
+* иной артефакт.
+
+**Почему так**
+Агент должен поддерживать не только ответы, но и генерацию инженерных артефактов.
+
+---
+
+## Итог
+
+Обновленная архитектура строится на следующем принципе:
+
+* **детерминированное извлечение ключевых артефактов** задает рамки;
+* **LLM выполняет гибкий роутинг внутри этих рамок**;
+* **retrieval обеспечивает данные**;
+* **task workflows реализуют прикладную логику и контроль качества**.
+
+Это позволяет одновременно сохранить управляемость системы и обеспечить масштабируемость под новые типы задач.