# 🗺️ ДОРОЖНАЯ КАРТА И АРХИТЕКТУРНЫЙ РОАДМАП ПРОЕКТА SCUD ORION AI

## 📌 Зафиксированные вехи и концептуальные архитектурные решения

Схема веток Gitea для ближайшего развития проекта:

main (100% стабильный релиз)
  │
  ├──► feature/tool-registry-db ──────┐ (Создание таблицы tool_action_registry в SQLite)
  │                                   ▼
  ├───────────────────────────────► merge to main
  │
  ├──► feature/interactive-buttons ───┐ (Подключение Да/Нет чипсов на фронтенде)
  │                                   ▼
  ├───────────────────────────────► merge to main
  │
  └──► feature/ephemeral-context ─────┐ (Внедрение флагов is_ephemeral для очистки памяти LLM)
                                      ▼
                                  merge to main




### 1. Архитектура скользящего контекста и отслеживания смены темы (Intent / Topic Drift Tracking)
* **Проблема:** При работе с длинными операциями (редактирование промптов, мастера табелей, снапшотов) оператор может отвлекаться на сторонние вопросы или уточнения. Жесткий сброс сессии уничтожает черновики, а вечное хранение засоряет память LLM.
* **Решение (Сферическое / Фундаментальное):**
  1. **Семантическая оценка моделью:** Модель через системный контекст определяет, относится ли вопрос оператора к активному черновику/инструменту или разговор ушел в сторону (`topic_shift = true`).
  2. **Детерминированный счетчик в бэкенде:** Бэкенд фиксирует шаги отвлечения (`idle_turns`). Пока $N < 3$, оператор может свободно общаться, не теряя висящий контекст.
  3. **Вежливый перехват и выбор (Guard):** На 3-м шаге отвлечения система отвечает на текущий вопрос оператора и мягко напоминает о незавершенной транзакции кнопками `[Применить / Сохранить]` или `[Отменить и сбросить]`.

---

## 🚀 Будущие модули и запланированный функционал (Backlog)

### 2. Интерактивный модуль планирования и дорожных карт (Checklist & Task Planner Engine)
* **Концепция:** Специализированный инструмент для LLM-агента, позволяющий вести динамические проектные чек-листы и планы с интерактивными чекбоксами прямо в диалоге и базе данных.
* **Ключевые возможности:**
  * Составление многоуровневых планов с чекбоксами (`[ ]` / `[x]`).
  * Фиксация промежуточных комментариев и статусов выполнения по каждому пункту.
  * Синхронизация задач плана с SQLite-таблицей `tasks`.
  * Экспорт планов в Markdown/Excel и отображение на дашборде.


### 3. Изолированная среда выполнения и песочница кода (Code Execution Sandbox Engine)
* **Концепция:** Безопасный изолированный Docker-контейнер (или gVisor / Pyodide / nsjail окружение) для динамического выполнения кода, генерируемого моделью в процессе рассуждений и анализа данных.
* **Ключевые возможности:**
  * Запуск сложных вычислений, агрегаций и статистического анализа данных СКУД на лету (Pandas / NumPy).
  * Выполнение тестовых сценариев и валидация скриптов перед их сохранением/применением на проде.
  * Полная изоляция от хост-системы: read-only доступ к копиям данных, ограничение памяти/CPU (cgroups), отсутствие доступа к чувствительным сетевым интерфейсам.
  * Возврат результатов вычислений (stdout, stderr, артефакты, сгенерированные таблицы/графики) обратно в контекст модели.


### 1. Архитектура скользящего контекста и отслеживания смены темы (Intent / Topic Drift Tracking)
* **Статус:** `MVP Реализован и протестирован` (на базе инструментов системного промпта: `db_preview_prompt_merge`, `db_confirm_prompt_preview`, `db_cancel_prompt_preview`).
* **Концептуальное решение:**
  1. **Двухфазное состояние сессии:** Разделение жизненного цикла на фазу черновика (`PROMPT_PREVIEW`) и фазу интерактивного подтверждения/диалога (`PROMPT_FOLLOWUP`).
  2. **Эфемерный буфер:** Промежуточные экраны, подтверждения и тяжелые выводы помечаются `is_ephemeral = 1` и не засоряют постоянную историю диалога.
  3. **Детерминированный счетчик (Topic Drift):** Бэкенд инкрементирует `idle_turns` при отвлечении на сторонние темы. На шаге $N = 3$ срабатывает **Context Guard** с напоминанием и кнопками действий, а при $N > 3$ происходит автоматический сброс сессии и вызов `db_purge_ephemeral_messages`.
  4. **Fast-Path очистка:** Прямой перехват команд завершения (`нет, спасибо`, `закончить настройку`) моментально очищает эфемерный контекст.

---

### 1.1. План масштабирования механизма эфемерного контекста на все инструменты (Rollout Roadmap)

План:

[1. REST API (main.py)] ────► Добавляем POST, PATCH, DELETE для /api/v1/tasks
            │
[2. Agent (agent.py)]   ────► При db_get_tasks отдаем payload {type: "TASK_INTERACTIVE_CARD", tasks: [...]}
            │
[3. UI (chat.js / CSS)] ────► Рендерим карточку с табами [Все] [В работе] [В планах] [Завершенные]

#### Этап 1. Модуль задач и бэклога (`tasks`)
* **Целевые инструменты:** `db_get_tasks`, `db_add_task`, `db_update_task_status`, `db_delete_task`.
* **Задачи реализации:**
  * Перевод вывода объемных плоских списков задач в эфемерный режим (`is_ephemeral = 1`), чтобы история диалога не забивалась длинными перечнями.
  * Реализация состояния сессии `TASKS_FOLLOWUP` после создания/изменения/удаления задачи.
  * Интеграция с Context Guard: напоминание о завершении работы с задачами на 3-м шаге отвлечения.
  * Автоочистка промежуточных диалоговых карточек задач при переключении на аналитику СКУД или общие вопросы.

#### Этап 2. Модуль срезов и архива СКУД (`snapshots`)
* **Целевые инструменты:** `db_get_snapshots`, `db_delete_snapshots`.
* **Задачи реализации:**
  * Маркировка объемных таблиц срезов и логов как эфемерных сообщений.
  * Внедрение интерактивного подтверждения при удалении снапшотов по ID или по дате (`SNAPSHOTS_PREVIEW` / `SNAPSHOTS_FOLLOWUP`).
  * Полная автоочистка временных таблиц срезов из памяти диалога после получения пользователем нужной информации.

#### Этап 3. Модуль базы знаний, правил и аномалий (`kb & anomalies`)
* **Целевые инструменты:** `db_get_rules`, `db_get_anomalies`, `db_get_reference`.
* **Задачи реализации:**
  * Вывод справочников команд, правил арбитража и списков аномалий исключительно во временный слой.
  * Предотвращение «залипания» модели на старых правилах из истории: гарантия того, что LLM всегда запрашивает актуальные правила через Tool Call, а не читает их из контекста предыдущих сообщений.

#### Этап 4. Декларативная унификация в `tool_action_registry`
* **Целевые изменения:**
  * Расширение схемы `tool_action_registry` новыми декларативными полями: `followup_state_type`, `auto_purge_on_exit`, `guard_question_template`.
  * Устранение жестких проверок названий функций в `agent.py`: перевод всей логики жизненного цикла сессий и очистки памяти на декларативные параметры из базы данных SQLite.