Files
scud_context_api/docs/planning/architectural_plan.md

4.9 KiB
Raw Permalink Blame History

🏛️ Архитектурный план: Двухуровневая очистка контекста и управление чатами

🎯 Концептуальная суть

  • Для пользователя (UI): Полноценный, наглядный интерфейс с интерактивными превью, карточками и кнопками действий.
  • Для нейросети (LLM): Идеально «стерильное» окно контекста, очищенное от тяжелых временных черновиков (is_ephemeral = 0), что исключает галлюцинации и принуждает модель использовать функции SQLite (Single Source of Truth).
  • Событийно-счетчиковая очистка: Временные данные хранятся ровно столько, сколько нужно для завершения задачи или уточняющих вопросов, после чего безопасно зачищаются.

📋 Пошаговый план реализации (Step-by-Step)

Шаг 1. Модификация схемы Базы Данных (SQLite)

  • Добавление флага эфемеральности в таблицу chat_messages:
ALTER TABLE chat_messages ADD COLUMN is_ephemeral INTEGER DEFAULT 0;
  • is_ephemeral = 0 — постоянные сообщения (вопросы, итоговые отклики, фиксированные задачи).
  • is_ephemeral = 1 — временные рабочие выводы инструментов (превью системного промпта, промежуточные срезы/снапшоты, черновики).

Шаг 2. Разделение каналов истории и задел под изолированные сессии (Multi-Chat)

  • Канал UI (Пользователь): Функция выгрузки истории для веб-интерфейса отдаёт все сообщения (is_ephemeral = 0 и 1), обеспечивая прозрачность работы.
  • Канал LLM (Оллама API): В функцию db_get_chat_history передается жесткий фильтр:
SELECT role, content 
FROM chat_messages 
WHERE session_id = ? AND is_ephemeral = 0 
ORDER BY id DESC 
LIMIT 12;
  • Изолированные чаты (Перспектива):
    • Создание сущности чатов (chat_id / session_id).
    • У каждого чата свой изолированный контекст.
    • Ручное удаление чата физически очищает все связанные записи в chat_messages и session_states.

Шаг 3. Интеллектуальный TTL-счетчик временного контекста (Auto-TTL)

  • Временный контекст (is_ephemeral = 1) НЕ сбрасывается мгновенно, если пользователь задает уточняющие вопросы в рамках той же темы.
  • Вводится счетчик сопутствующих сообщений (например, N = 3..5 сообщений).
  • Если оператор задает N сообщений подряд, не относящихся к активному инструменту, или переключается на другой инструмент — временный контекст автоматически зачищается/деактивируется.

Шаг 4. UX-завершение транзакции (Кнопки «Да / Нет»)

  1. После выполнения операции (например, успешной перезаписи системного промпта) ассистент отдает флаг transaction_completed: true.
  2. На фронтенде выезжает блок подтверждения результатов:

    «Желаемый результат получен?»
    [ 👍 Да, закрыть ] [ 👎 Нет, продолжить ]

  3. Клик «Да»: Отправляет триггер на сервер $ ightarrow$ бэкенд выполняет:
    DELETE FROM chat_messages WHERE session_id = ? AND is_ephemeral = 1;
    
    и очищает session_states.
  4. Клик «Нет»: Оставляет промежуточный контекст активным для продолжения редактирования.

🧹 Подготовка к старту

  1. Предварительная зачистка кода от старых регулярных выражений и системных костылей в llm/agent.py и llm/core/tool_injector.py.
  2. Выполнение scripts/clear_history.py для старта с чистого листа.