scud_ai/docs/development_roadmap.md

🗺️ ДОРОЖНАЯ КАРТА И АРХИТЕКТУРНЫЙ РОАДМАП ПРОЕКТА 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.