78 lines
11 KiB
Markdown
78 lines
11 KiB
Markdown
# 📋 ТЕХНИЧЕСКОЕ ЗАДАНИЕ: ИНТЕГРАЦИЯ MIXED-INITIATIVE LLM-АГЕНТА
|
||
**Ветка:** `027-dataset-llm-orchestration`
|
||
**Контекст:** Архитектура автоматического ревью датасетов (US1) и подготовки к запуску (US3) реализована отлично. Требуется переработать процесс "Clarification" (US2) из жесткого модального опросника в полноценный контекстно-зависимый диалог с LLM-агентом (Смешанная инициатива / Mixed-Initiative), а также закрыть архитектурные риски (PII, Concurrency).
|
||
|
||
Тебе необходимо выполнить задачу в два этапа.
|
||
|
||
---
|
||
|
||
## ЭТАП 1: Обновление спецификаций (Директория `specs/027-dataset-llm-orchestration/`)
|
||
|
||
Твоя первая задача — актуализировать проектную документацию, чтобы она отражала новую парадигму взаимодействия пользователя и агента, а также закрывала дыры в безопасности.
|
||
|
||
**1. Обновить `ux_reference.md`:**
|
||
* **Отказ от модалок:** Заменить концепцию `ClarificationDialog` на интеграцию диалога в выдвижную правую панель `AssistantChatPanel`.
|
||
* **Mixed-Initiative:** Описать, что диалог может быть инициирован как системой (очередь `Clarification Queue`), так и пользователем (свободные вопросы агенту по контексту датасета, например: *"Почему этот фильтр помечен как partial?"*).
|
||
* **Inline-взаимодействие (Context Actions):** Дописать появление микро-кнопок `[✨ Спросить ИИ]` / `[✨ Улучшить]` рядом с неразрешенными фильтрами (`unresolved`), предупреждениями валидации и полем Бизнес-summary в основном Workspace.
|
||
* **Визуальный фокус:** Зафиксировать правило: когда агент задает вопрос по конкретному фильтру/полю в чате, карточка этого элемента в центральной колонке UI подсвечивается (highlight/glow).
|
||
* **Confirmation Cards:** Описать интерактивные виджеты внутри ленты чата для опасных операций (например, подтверждение запуска датасета в SQL Lab), опирающиеся на `AssistantConfirmationRecord`.
|
||
|
||
**2. Обновить `spec.md` (Functional Requirements):**
|
||
* Добавить **FR-045**: Система должна позволять пользователю задавать свободные вопросы по контексту загруженного датасета (профиль, фильтры, маппинги, SQL).
|
||
* Добавить **FR-046**: Агент должен уметь принимать команды на естественном языке для изменения состояния сессии (например: *"Одобри все маппинги"*, *"Сгенерируй превью SQL"*).
|
||
* Изменить **FR-013**: Уточняющие вопросы должны задаваться не в изолированном окне, а в контексте глобального чата ассистента.
|
||
|
||
**3. Обновить `contracts/api.yaml` и `data-model.md`:**
|
||
* **Связь чата и сессии:** В `AssistantMessageRequest` добавить опциональное поле `dataset_review_session_id: string`.
|
||
* **Оптимистичные блокировки:** В сущность `DatasetReviewSession` (и DTO `SessionDetail`) добавить поле `version: integer` для предотвращения состояния гонки (Race Condition) при совместном редактировании сессии коллабораторами (пользователь + агент).
|
||
* **PII Masking:** В `data-model.md` для `ImportedFilter` явно указать требование маскирования чувствительных данных (`raw_value`) перед отправкой контекста в LLM.
|
||
|
||
**4. Обновить `contracts/modules.md`:**
|
||
* В `DatasetReviewOrchestrator` добавить связь `@RELATION: [EXPOSES_STATE_TO] -> [AssistantApi]`.
|
||
* В описание `ClarificationEngine` добавить, что он маршрутизирует свои запросы через `AssistantChatPanel`.
|
||
|
||
---
|
||
|
||
## ЭТАП 2: Реализация доработок в кодовой базе (Frontend & Backend)
|
||
|
||
На основе обновленных спеков реализуй архитектурные и UI/UX изменения в коде.
|
||
|
||
### 🛠️ 2.1 Backend: Архитектура, Безопасность и Инструменты Агента
|
||
1. **PII Data Masking:**
|
||
* Где: `backend/src/core/utils/superset_context_extractor.py` или слой подготовки промпта.
|
||
* Что: Реализовать фильтрацию/маскирование значений фильтров (например, email, SSN), извлеченных из Superset, *до* того, как они попадут в контекст LLM. Агенту нужны только ключи и структура для маппинга, а не сырые PII-данные.
|
||
2. **Optimistic Locking (Борьба с Race Conditions):**
|
||
* Где: `backend/src/services/dataset_review/repositories/session_repository.py`.
|
||
* Что: Реализовать проверку поля `version` при сохранении `DatasetReviewSession`. В случае конфликта (кто-то другой, включая агента, уже изменил сессию) выбрасывать `StaleDataError` -> HTTP 409 Conflict.
|
||
3. **Интеграция контекста датасета в Ассистента:**
|
||
* Где: `backend/src/api/routes/assistant.py` (`_plan_intent_with_llm`, `_build_tool_catalog`).
|
||
* Что: Если в запросе передан `dataset_review_session_id`, подгружать `DatasetProfile`, `ImportedFilters` и `ValidationFindings` в системный промпт (System Prompt) ассистента, чтобы он мог отвечать на вопросы по датасету.
|
||
4. **Новые Tools (Интенты) для Агента:**
|
||
* Где: `backend/src/api/routes/assistant.py` -> `_dispatch_intent`.
|
||
* Что: Научить агента вызывать методы `DatasetReviewOrchestrator`. Добавить инструменты: `APPROVE_MAPPINGS` (одобрить ворнинги), `SET_FIELD_SEMANTICS` (переписать описание колонки), `GENERATE_SQL_PREVIEW` (триггер компиляции).
|
||
5. **Garbage Collection сессий:**
|
||
* Где: `backend/src/core/task_manager/cleanup.py` (или аналог).
|
||
* Что: Написать scheduled-таску для жесткого удаления (hard delete) брошенных/архивированных сессий обзора (например, старше 30 дней), чтобы БД не переполнялась снепшотами SQL и графами контекста.
|
||
|
||
### 🎨 2.2 Frontend: Реактивный Workspace и Чат
|
||
1. **Интеграция AssistantChatPanel (Slide-out Drawer):**
|
||
* Где: `frontend/src/routes/datasets/review/[id]/+page.svelte` (`DatasetReviewWorkspace`).
|
||
* Что: Внедрить вызов боковой панели ассистента `AssistantChatPanel`. Убедиться, что при её открытии контент Workspace сдвигается или корректно перекрывается, не теряя контекста SQL-превью и фильтров. Удалить старый `ClarificationDialog` (модалку).
|
||
2. **Контекстные кнопки (Inline Triggers ✨):**
|
||
* Что: В компоненты `ValidationFindingsPanel.svelte`, `ExecutionMappingReview.svelte` и карточки фильтров добавить микро-кнопки `[✨ Спросить ИИ]`.
|
||
* Действие: По клику открывать `assistantChat` store и отправлять предзаполненный скрытый контекстный промпт (например, *"Объясни проблему с фильтром X и предложи решение"*).
|
||
3. **Визуальная синхронизация (State Reactivity):**
|
||
* Что: Когда агент через чат задает вопрос по `field_id` или `filter_id` (Clarification Queue), соответствующий элемент в Workspace должен получать CSS-класс подсветки (glow/highlight).
|
||
* Как: Связать `ClarificationStateResult` из стора сессии с рендером строк в `SemanticLayerReview.svelte` и списках фильтров.
|
||
4. **Confirmation Cards в ленте чата:**
|
||
* Где: `frontend/src/lib/components/assistant/AssistantChatPanel.svelte`.
|
||
* Что: Для команд, требующих `AssistantConfirmationRecord` (например, запуск в SQL Lab), рендерить внутри чата специальный виджет: *"Вы уверены, что хотите запустить этот контекст? [Отменить][Запустить]"*.
|
||
5. **Debounce для SQL Preview:**
|
||
* Где: `frontend/src/lib/components/dataset-review/CompiledSQLPreview.svelte`.
|
||
* Что: Предотвратить спам запросами к Superset API. Если пользователь или агент быстро меняют маппинги, статус превью становится `stale`. Запрос на перегенерацию должен отправляться либо по явной кнопке, либо с debounce-задержкой 2-3 секунды после окончания потока изменений.
|
||
|
||
### ⚙️ Правила выполнения для Агента:
|
||
1. **Не ломать инварианты:** Сохранить принцип **WYSIWWR (What You See Is What Will Run)**. LLM *никогда* не должна генерировать финальный SQL-код сама. LLM собирает параметры, а SQL компилирует только Superset (`SupersetCompilationAdapter`).
|
||
2. **Семантическое логирование:** Любые изменения состояния сессий на бэкенде оборачивать в `belief_scope` (`logger.reason()`, `logger.reflect()`), как указано в системных контрактах.
|
||
3. По завершении этапа 1, дождись утверждения (или переходи к Этапу 2 автономно, если находишься в режиме Auto-Execute), строго следуя обновленным контрактам `api.yaml`.
|