feat(llm): переход на реляционные узлы промпта, db_cli context и очистка от регулярок
This commit is contained in:
@@ -0,0 +1,37 @@
|
||||
# 📋 История изменений (CHANGELOG)
|
||||
|
||||
Все ключевые изменения архитектуры, инструментов и модулей проекта SCUD Orion AI фиксируются в данном файле.
|
||||
|
||||
---
|
||||
|
||||
## [2026-08-17] — Внедрение CLI-инспекции контекста и переход на нативный Function Calling
|
||||
|
||||
### ✨ Добавлено
|
||||
* **`scripts/db_cli.py`**: Добавлена команда `context` для инспекции истории сообщений `chat_messages` по сессиям с визуальным отображением флагов `[ЭФЕМЕРНОЕ]`.
|
||||
* **`ROADMAP.md`**: Сформирована актуальная дорожная карта с планом отказа от регулярных выражений в пользу нативного Function Calling.
|
||||
|
||||
### 🔧 Изменено
|
||||
* **`modules/web_api/llm/db_tools.py`**: Удалены устаревшие неиспользуемые функции и заглушки счетчиков простоя.
|
||||
* **`modules/web_api/static/js/chat/core.js`**: Внедрена поддержка вызова инлайн-редактора черновика промпта прямо из окна диалога.
|
||||
|
||||
---
|
||||
|
||||
## [2026-08-15] — Реляционная архитектура системного промпта
|
||||
|
||||
### ✨ Добавлено
|
||||
* **`system_prompt_nodes`**: Создана таблица реляционных узлов промпта с индексацией по разделам и пунктам (`section_id`, `item_id`).
|
||||
* **`db_prompt_node_edit`**: Добавлен инструмент точечного добавления, изменения и удаления пунктов системного промпта.
|
||||
* **Инлайн-редактор**: Добавлен визуальный diff-просмотр изменений с подсветкой и кнопкой `[✏️ Редактировать]`.
|
||||
|
||||
### 🔧 Изменено
|
||||
* **`modules/web_api/llm/agent.py`**: Генерация активного системного промпта переведена на динамическую сборку из реляционных узлов SQLite.
|
||||
* **`modules/web_api/llm/core/fast_path.py`**: Обработка кнопок «Подтвердить» и «Отменить» переведена на атомарную запись узлов в базу данных.
|
||||
|
||||
---
|
||||
|
||||
## [2026-08-10] — Механизм эфемерных сообщений и очистки диалога
|
||||
|
||||
### ✨ Добавлено
|
||||
* **Эфемерные сообщения (`is_ephemeral`)**: Маркировка временных сервисных ответов и черновиков.
|
||||
* **`db_purge_ephemeral_messages`**: Механизм физической зачистки временных записей из SQLite при завершении операций.
|
||||
* **Интерактивные виджеты**: Поддержка карточек задач (`TASK_INTERACTIVE_CARD`) с кнопками быстрого действия.
|
||||
@@ -0,0 +1,185 @@
|
||||
# **PROJECT BRAIN: SCUD Orion AI & Context API (Master Technical & Architectural Manifesto)**
|
||||
|
||||
**Версия документа:** 5.0 (Ultimate Developer & LLM Context Engine)
|
||||
**Назначение:** Исчерпывающий контекстный дамп проекта для немедленного продолжения разработки в любой передовой LLM без потери исторического контекста, с полным пониманием бизнес-логики, схем баз данных, подводных камней и нерешенных задач.
|
||||
|
||||
## ---
|
||||
|
||||
**1\. Архитектурный паспорт и инфраструктурный профиль**
|
||||
|
||||
| Компонент | Параметры и стек |
|
||||
| :---- | :---- |
|
||||
| **Среда и ОС** | Linux Docker Home (Debian/Ubuntu), Python 3.11/3.12 в виртуальном окружении venv, Git/Gitea. Разработка ведется через VS Code Remote-SSH. |
|
||||
| **Локальная СУБД проекта** | SQLite (data/scud\_orion\_ai.db), режим PRAGMA journal\_mode \= WAL, PRAGMA synchronous \= NORMAL, PRAGMA foreign\_keys \= ON. |
|
||||
| **СКУД Источник (MSSQL)** | MS SQL Server 172.16.31.221\\SQL (база Orion-14.01.21-1), драйвер ODBC Driver 18 for SQL Server (TrustServerCertificate=yes, Encrypt=no). Доступ через pyodbc. |
|
||||
| **1С:ЗУП 3.1 Источник (MSSQL)** | MS SQL Server ACCOUNT-01 (база ZUP30, пользователь scud\_reader). Прямое чтение таблиц dbo.\_Reference299 (сотрудники) и dbo.\_InfoRg16921 (состояния отсутствий). Резервная Samba-шара: /mnt/scud\_share. |
|
||||
| **Локальный контур LLM** | Ollama на http://192.168.11.3:11434 (GPU NVIDIA RTX 5070 Ti 16GB). Модель qwen2.5:14b (основной агент, Function Calling, анализ аномалий), qwen2.5vl:7b-q8\_0 (OCR документов/картинок). |
|
||||
| **Web API & Фронтенд** | FastAPI (Uvicorn), JWT (HS256, 30 дней), Passlib (bcrypt). Фронтенд: Single Page Application (HTML5, Tailwind CSS, Vanilla JS) с Generative UI виджетами. |
|
||||
|
||||
## ---
|
||||
|
||||
**2\. Энциклопедия подводных камней, инцидентов и принятых инженерных решений**
|
||||
|
||||
### **2.1. Галлюцинации LLM и переход к парадигме Python-Driven Diff**
|
||||
|
||||
> * **Проблема:** Попытка передать списки в 300 ФИО напрямую в промпт модели с командой «сравни списки» приводила к потере контекста, выдуманным опечаткам (*«ЛЕНМОРНИИПРОЕКТ ОЭС Варламова Мария»*) и плейсхолдерам ('Васильев Л.И.', ...).
|
||||
> * **Решение:** Утверждена строгая гибридная схема:
|
||||
1. **Детерминированный слой (Python / Pandas / SQL):** читает файлы, нормализует строки, агрегирует совмещения и мгновенно находит 95%+ точных соответствий.
|
||||
2. **Интеллектуальный слой (Qwen 2.5:14b):** вызывается *только на спорный несовпавший остаток* (1–5 записей) в виде строгого JSON-интерфейса Entity Resolution.
|
||||
|
||||
### **2.2. Символьная нормализация и кадровые совмещения (Кейс Балаевой О.Г.)**
|
||||
|
||||
> * **Проблема символов:** Латинские омоглифы (буквы клавиатуры a, c, e, o, p, x, y вместо русских), разделители 1С в скобках ((осн.), (совм.), (внешн.)), неразрывные пробелы \\xa0, буква ё и случайный ввод цифры 0 вместо буквы О.
|
||||
> * **Решение (normalize\_fio):** Очистка скобок через регулярное выражение re.sub(r'\\(.\*?\\)', '', fio), замена латиницы через str.maketrans('aceopxyABCEHKMOPTX', 'асеорхуАВСЕНКМОРТХ'), замена ё-\>е и удаление лишних пробелов.
|
||||
> * **Коллизия 270 vs 271:** В СКУД 270 физических лиц (один пропуск на человека), в 1С — 271 строка. Сотрудник **Балаева Ольга Геннадьевна** числится на двух ставках в разных отделах (*Руководитель управления персоналом* и *Руководитель режимно-секретного отдела*).
|
||||
> * **Решение:** Внедрена группировка датафрейма 1С по fio\_clean с агрегацией должностей и подразделений через разделитель " / ".
|
||||
|
||||
### **2.3. Защита от коллизий полных тёзок и ложных связок однофамильцев (Кейс Семеновых)**
|
||||
|
||||
> * **Инцидент:** Неограниченная строгими правилами LLM связала двух разных сотрудниц — *«Семенову Юлию Борисовну»* (работает) и *«Семенову Дину Дмитриевну»* (в отпуске), посчитав разные имена опечаткой из\-за одинаковой фамилии. В результате Юлии Борисовне ошибочно был приписан статус отпуска.
|
||||
> * **Двухконтурный барьер:**
|
||||
1. **В промпте:** Запрет объединения однофамильцев с разными именами/отчествами.
|
||||
2. **В Python:** Проверка совпадения первых букв имени и отчества. При несовпадении сопоставление ИИ аннулируется с логированием ⚠️ \[Блокировка фейка\].
|
||||
|
||||
### **2.4. Вынесение исключений в exceptions.json и синонимы отделов**
|
||||
|
||||
> * Служебный персонал (отдел «ЭТО», уборщики производственных и служебных помещений, клинеры, дворники, гардеробщики) вынесен в exceptions.json.
|
||||
> * Для сопоставления кратких аббревиатур СКУД и полных названий отделов 1С (*«ОВК» ⟷ «Отдел внутреннего контроля»*) создана таблица department\_synonyms с автоматическим самообучением при работе человека (Human-in-the-Loop).
|
||||
|
||||
### **2.5. Разгадка феномена «исчезающих неизвестных» и аппаратный сбой СКУД 04.08.2026**
|
||||
|
||||
> * **Аномалия:** Утром 04.08.2026 на главном КПП зависли контроллеры входа. У 119 сотрудников не записалось утреннее событие (time\_in \= 'Нет входа'). Из них 57 человек были в отпусках/командировках по 1С. Оставшиеся 74 человека были на работе без утренней отметки. Однако вечерняя сводка показала всего 4–7 «неизвестных».
|
||||
> * **Причина:** Скрипт агрегации видел дневные перемещения (обед, внутренние двери, туалет, вечерний выход) и автоматически проставлял Статус \= 'Присутствовал' и is\_present \= 1, несмотря на то, что колонка Начало\_дня оставалась 'Нет входа'. В итоге 70 человек тихо ушли в «Итого на работе», а системный сбой оборудования был замаскирован.
|
||||
> * **Архитектурный фикс:**
|
||||
1. Введена колонка **first\_activity («Первая активность»)** — вычисление MIN(TimeVal) AS FirstRawEvent по таблице pLogData без учета направления двери.
|
||||
2. Если time\_in \== 'Нет входа', но first\_activity \!= '—', записи ставится anomaly\_flag \= 'ANOMALY\_NO\_IN\_HAS\_ACTIVITY', а is\_present принудительно сбрасывается в 0\.
|
||||
3. Внедрен модуль analyze\_scud\_mass\_failure\_ai(): если доля таких аномалий превышает 5% смены (\>10 чел.), ИИ генерирует системный алерт о массовом сбое контроллеров КПП.
|
||||
> * **Кейс Равина В.Э.:** Главный специалист официально находился в основном отпуске по 1С, утреннего входа на КПП не было, но зафиксирована активность в 14:11:06 и вечерний выход в 17:18:38. Система зарегистрировала истинную кадровую аномалию (физическое присутствие при официальном отпуске).
|
||||
|
||||
### **2.6. Система сквозных датированных снапшотов (срезов)**
|
||||
|
||||
> * **Формат ID:** \[Y\]YYYYMMDD-NNN (например, Y20260804-001 для вчерашнего зафиксированного вечернего среза на 22:00 и 20260805-002 для дневного).
|
||||
> * **Оптимизация:** Функция has\_yesterday\_final\_snapshot() проверяет наличие вчерашнего среза в SQLite: если он есть, повторный тяжелый запрос к MS SQL Орион пропускается.
|
||||
> * **CLI-управление:** Поддержка запуска отчетов по любому историческому снапшоту через ключ \--snapshot \[ID\] и пропуск выгрузки через \--skip-export.
|
||||
|
||||
### **2.7. Web API, Generative UI и управление жизненным циклом сессий (Topic Drift & Ephemeral Buffer)**
|
||||
|
||||
> * **Проблема засорения контекста LLM:** Вывод объемных списков задач, системных промптов и таблиц срезов забивал окно диалога, вызывая галлюцинации и «залипание» модели на старых данных.
|
||||
> * **Решение:**
|
||||
* В chat\_messages введен флаг is\_ephemeral \= 1 для временных сообщений.
|
||||
* Двухфазные сессии (PROMPT\_PREVIEW → PROMPT\_FOLLOWUP) и детерминированный счетчик idle\_turns.
|
||||
* **Context Guard:** На 3-м шаге отвлечения оператора на сторонние темы система отвечает на вопрос и выводит интерактивное напоминание с кнопками \[Завершить настройку\] / \[Показать промпт\]. При idle\_turns \> 3 происходит автоочистка сессии вызовом db\_purge\_ephemeral\_messages().
|
||||
* **Fast-Path:** Прямой перехват команд подтверждения («да», «подтверждаю») и выхода («нет, спасибо») без обращения к LLM (ответ за 0.05 сек).
|
||||
* **Декларативный реестр (tool\_action\_registry):** Хранение шаблонов ответов, кнопок и настроек эфемерности в SQLite.
|
||||
> * **Generative UI (Задачи):** Инструмент db\_get\_tasks возвращает TASK\_INTERACTIVE\_CARD, рендерящий на клиенте живой виджет задач с табами (Все / В работе / В планах / Завершенные), чекбоксами и inline-созданием задач через REST API.
|
||||
|
||||
## ---
|
||||
|
||||
**3\. Полная схема базы данных SQLite (data/scud\_orion\_ai.db)**
|
||||
|
||||
| Таблица | Назначение и бизнес-логика | Структура полей |
|
||||
| :---- | :---- | :---- |
|
||||
| **scud\_logs** | Логи проходов СКУД, расчетное время в здании и снапшоты. | id INTEGER PK AUTOINCREMENT, log\_date TEXT, fio TEXT, fio\_clean TEXT, department TEXT, position TEXT, time\_in TEXT, first\_activity TEXT DEFAULT '—', time\_out TEXT, time\_in\_building TEXT, is\_present INTEGER, anomaly\_flag TEXT DEFAULT 'NONE', snapshot\_time TEXT, snapshot\_id TEXT, created\_at TIMESTAMP |
|
||||
| **zup\_staff** | Штатное расписание 1С:ЗУП на даты срезов. | id INTEGER PK AUTOINCREMENT, snapshot\_date TEXT, fio TEXT, fio\_clean TEXT, department TEXT, position TEXT, created\_at TIMESTAMP |
|
||||
| **zup\_absences** | Документы отклонений 1С (отпуска, больничные, командировки, декреты). | id INTEGER PK AUTOINCREMENT, absence\_date TEXT, fio TEXT, fio\_clean TEXT, absence\_type TEXT, created\_at TIMESTAMP |
|
||||
| **anomalies\_history** | Журнал выявленных кадровых и аппаратных аномалий. | id INTEGER PK AUTOINCREMENT, anomaly\_date TEXT, fio TEXT, anomaly\_type TEXT, details TEXT, human\_status TEXT DEFAULT 'Pending', created\_at TIMESTAMP |
|
||||
| **ai\_knowledge\_base** | Глобальные правила арбитража и приоритеты компании для ИИ. | id INTEGER PK AUTOINCREMENT, rule\_text TEXT UNIQUE, added\_by TEXT DEFAULT 'Human', created\_at TIMESTAMP |
|
||||
| **system\_prompts** | Версионные системные промпты агента (активный по is\_active=1). | id INTEGER PK AUTOINCREMENT, name TEXT, prompt\_text TEXT, is\_active INTEGER DEFAULT 1, updated\_at TIMESTAMP |
|
||||
| **tool\_action\_registry** | Декларативный реестр шаблонов, кнопок и настроек эфемерности инструментов. | id INTEGER PK AUTOINCREMENT, tool\_name TEXT UNIQUE, category TEXT, bypass\_llm INTEGER, success\_template TEXT, follow\_up\_question TEXT, action\_type TEXT, buttons\_json TEXT, is\_active INTEGER, is\_ephemeral INTEGER, updated\_at TIMESTAMP |
|
||||
| **session\_states** | Активные состояния сессий, черновики и счетчик idle\_turns. | session\_id TEXT PRIMARY KEY, state\_type TEXT, pending\_data TEXT, updated\_at TIMESTAMP |
|
||||
| **chat\_messages** | История диалогов с поддержкой разделения на постоянные и эфемерные сообщения. | id INTEGER PK AUTOINCREMENT, session\_id TEXT, role TEXT, content TEXT, is\_ephemeral INTEGER DEFAULT 0, created\_at TIMESTAMP |
|
||||
| **tasks** | Реестр задач операторов с привязкой к user\_id. | id INTEGER PK AUTOINCREMENT, task\_id TEXT, module TEXT, title TEXT, priority TEXT, status TEXT, due\_date TEXT, user\_id INTEGER, created\_at TIMESTAMP |
|
||||
| **users** | Учетные записи операторов (хэши паролей bcrypt, права администратора). | id INTEGER PK AUTOINCREMENT, username TEXT UNIQUE, password\_hash TEXT, is\_admin INTEGER, full\_name TEXT, created\_at TIMESTAMP |
|
||||
| **department\_synonyms** | База соответствия аббревиатур СКУД полным названиям отделов 1С. | id INTEGER PK AUTOINCREMENT, short\_name TEXT UNIQUE, full\_name TEXT, created\_at TIMESTAMP |
|
||||
| **system\_reference** | Справочник команд и примеров промптов для операторов. | id INTEGER PK AUTOINCREMENT, category TEXT, title TEXT, example\_prompt TEXT, description TEXT |
|
||||
|
||||
## ---
|
||||
|
||||
**4\. Архитектурная структура каталогов**
|
||||
|
||||
scud\_ai/
|
||||
├── config.py \# Конфигурация: пути, расчет дат, URL Ollama, параметры MS SQL
|
||||
├── exceptions.json \# Декларативные фильтры исключений (ОВК, уборщики, подрядчики)
|
||||
├── main\_etl.py \# Оркестратор ETL: экспорт СКУД/1С \-\> SQLite \-\> Excel/MD отчеты
|
||||
├── project\_code\_snapshot.md \# Полный монолитный исходный код всех файлов репозитория
|
||||
├── core/
|
||||
│ └── database.py \# Драйвер SQLite (WAL), функции сохранения/загрузки срезов
|
||||
├── services/
|
||||
│ ├── scud\_export.py \# Прямой SQL-экспорт из MS SQL «Орион Pro»
|
||||
│ ├── zup\_extractor.py \# Прямой SQL-экспорт из MS SQL 1С:ЗУП 3.1
|
||||
│ ├── data\_loader.py \# Загрузка данных, нормализация ФИО, расчет первой активности
|
||||
│ ├── data\_validator.py \# Проверка свежести и наличия файлов за Вчера и Сегодня
|
||||
│ ├── excel\_exporter.py \# Генерация сводки и детального отчета в Excel (openpyxl)
|
||||
│ ├── text\_reporter.py \# Построение итогового Markdown-отчета через Qwen 2.5
|
||||
│ ├── ai\_verifier.py \# Модули ИИ-аудита, Fuzzy Matching и детекции сбоев СКУД
|
||||
│ ├── feedback\_loop.py \# Интерактивный консольный модуль Human-in-the-Loop
|
||||
│ ├── knowledge\_base.py \# Интерфейс работы с базой знаний правил
|
||||
│ └── share\_copier.py \# Резервное скачивание файлов 1С с шары /mnt/scud\_share
|
||||
├── scripts/
|
||||
│ ├── db\_cli.py \# CLI-утилита управления БД, снапшотами, дампами и сессиями
|
||||
│ ├── fix\_snapshots.py \# Скрипт переиндексации и нормализации снапшотов
|
||||
│ ├── init\_tool\_registry.py \# Инициализация декларативного реестра инструментов
|
||||
│ └── diagnostics/
|
||||
│ ├── inspect\_db.py \# Диагностика структуры таблиц и количества записей
|
||||
│ ├── inspect\_ephemeral.py \# Анализ распределения постоянных и эфемерных сообщений
|
||||
│ ├── inspect\_files.py \# Аудит файлов и размеров на диске
|
||||
│ └── show\_tree.py \# Вывод дерева каталогов
|
||||
├── modules/web\_api/
|
||||
│ ├── main.py \# Точка входа FastAPI приложения, роутеры и раздача статики
|
||||
│ ├── routers/ (admin, auth, chat, tasks) \# REST эндпоинты
|
||||
│ ├── llm/
|
||||
│ │ ├── agent.py \# Координатор диалога, Tool Calls и Topic Drift Guard
|
||||
│ │ ├── schemas.py \# Описание JSON-схем инструментов для Ollama
|
||||
│ │ ├── file\_parser.py \# Мультимодальный парсер файлов (PDF, PNG, XLSX, TXT)
|
||||
│ │ ├── db\_tools.py \# Фасадные вызовы функций БД для агента
|
||||
│ │ ├── core/ (calendar\_utils, fast\_path, ollama\_client, prompt\_merger, tool\_injector)
|
||||
│ │ └── db/ (connection, db\_chat, db\_prompts, db\_snapshots, db\_tasks)
|
||||
│ └── static/ (index.html, css/styles.css, js/app.js, js/auth.js, js/chat.js, js/tasks.js)
|
||||
└── docs/
|
||||
└── development\_roadmap.md \# Стратегическая дорожная карта и архитектурный бэклог
|
||||
|
||||
## ---
|
||||
|
||||
**5\. Справочник команд CLI (HOWTO)**
|
||||
|
||||
### **ETL Пайплайн (main\_etl.py):**
|
||||
|
||||
> * python main\_etl.py — стандартный дневной запуск (экспорт из MS SQL, сохранение снапшота, генерация отчетов).
|
||||
> * python main\_etl.py \--skip-export — построение отчетов по последнему имеющемуся снапшоту из SQLite без повторного запроса к MS SQL.
|
||||
> * python main\_etl.py \--snapshot 20260805-001 — точный расчет отчетов по указанному составному ID снапшота.
|
||||
> * python main\_etl.py \-d — запуск в режиме расширенной отладки (DEBUG).
|
||||
|
||||
### **CLI базы данных (scripts/db\_cli.py):**
|
||||
|
||||
> * python scripts/db\_cli.py stats — статистика по количеству строк во всех таблицах БД.
|
||||
> * python scripts/db\_cli.py snapshots \[ДД.ММ.ГГГГ\] — просмотр реестра снапшотов с сортировкой по времени создания (свежие сверху).
|
||||
> * python scripts/db\_cli.py scud \[ДД.ММ.ГГГГ\] \[--snapshot ID\] \[--export-xlsx NAME\] — инспекция логов СКУД и экспорт в Excel.
|
||||
> * python scripts/db\_cli.py absences \[ДД.ММ.ГГГГ\] — список кадровых отклонений из 1С:ЗУП.
|
||||
> * python scripts/db\_cli.py anomalies — история выявленных аномалий.
|
||||
> * python scripts/db\_cli.py rules — правила базы знаний компании.
|
||||
> * python scripts/db\_cli.py prompts — системные промпты из system\_prompts.
|
||||
> * python scripts/db\_cli.py tools — декларативный реестр действий инструментов и кнопок.
|
||||
> * python scripts/db\_cli.py sessions — активные сессионные стейты и висящие черновики.
|
||||
> * python scripts/db\_cli.py snapshot del \[ID\] — удаление конкретного снапшота по ID.
|
||||
> * python scripts/db\_cli.py snapshot del \--day \[ДД.ММ.ГГГГ\] — удаление всех снапшотов за день.
|
||||
> * python scripts/db\_cli.py dump \[backup.xlsx\] — полный дамп всех таблиц базы данных в многостраничный Excel.
|
||||
|
||||
## ---
|
||||
|
||||
**6\. Стратегическая дорожная карта и нерешенные задачи (Roadmap & Backlog)**
|
||||
|
||||
> 1. **Масштабирование механизма эфемерного контекста на все инструменты (Rollout Roadmap):**
|
||||
* **Снапшоты (snapshots):** Перевод вывода объемных таблиц срезов в эфемерный режим (is\_ephemeral \= 1), внедрение интерактивного подтверждения при удалении снапшотов по ID/дате через состояния SNAPSHOTS\_PREVIEW / SNAPSHOTS\_FOLLOWUP.
|
||||
* **База знаний и аномалии (kb & anomalies):** Вывод справочников команд, правил арбитража и списков аномалий исключительно во временный слой для исключения «залипания» модели на устаревших правилах из истории сообщений.
|
||||
* **Декларативная унификация в tool\_action\_registry:** Расширение схемы таблицы полями followup\_state\_type, auto\_purge\_on\_exit, guard\_question\_template для устранения хардкода имен функций в agent.py.
|
||||
> 2. **Модуль анализа внутридневных перемещений («Контроль перекуров»):**
|
||||
* Анализ интервалов между событиями OUT (выход) и IN (возврат) по журналу pLogData.
|
||||
* Подсчет суммарного времени нахождения вне рабочего места в течение смены с отсечением технологической нормы (30–40 минут).
|
||||
* Вывод аналитического блока и злостных нарушителей в отдельный лист Excel-отчета и итоговую Markdown-сводку.
|
||||
> 3. **Интерактивный Task Planner & Roadmap Engine:**
|
||||
* Специализированный инструмент для ведения динамических проектных планов и чек-листов с чекбоксами (\[ \] / \[x\]) прямо в диалоге с синхронизацией в таблицу tasks.
|
||||
> 4. **Изолированная среда исполнения кода (Code Execution Sandbox):**
|
||||
* Безопасный изолированный Docker/gVisor контейнер для динамического выполнения генерируемого моделью Python/Pandas кода на лету с возвратом stdout/stderr и графиков в контекст.
|
||||
> 5. **Автоматизация расписания срезов и Telegram-алерты:**
|
||||
* Автозапуск выгрузок в 12:00, 17:00 и 19:00 через systemd-таймеры с фиксацией snapshot\_time.
|
||||
* Отправка мгновенных алертов о массовых сбоях турникетов (\>5%) и критических кадровых конфликтах дежурному системному администратору в Telegram.
|
||||
@@ -0,0 +1,61 @@
|
||||
# 🗺️ ДОРОЖНАЯ КАРТА И АРХИТЕКТУРНЫЙ РОАДМАП ПРОЕКТА SCUD ORION AI
|
||||
|
||||
## 📌 Зафиксированные вехи и концептуальные архитектурные решения
|
||||
|
||||
Схема веток Gitea для развития проекта:
|
||||
|
||||
main (100% стабильный релиз)
|
||||
│
|
||||
├──► feature/prompt-relational-nodes ──┐ (Перевод системного промпта на реляционные узлы в SQLite)
|
||||
│ ▼
|
||||
├──────────────────────────────────► merge to main
|
||||
│
|
||||
├──► feature/native-function-calling ──┐ (Отказ от регулярных выражений tool_injector.py в пользу нативного FC)
|
||||
│ ▼
|
||||
├──────────────────────────────────► merge to main
|
||||
│
|
||||
└──► feature/ephemeral-context ────────┐ (Интеллектуальный жизненный цикл эфемерных сообщений)
|
||||
▼
|
||||
merge to main
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Текущий активный спринт: Нативный Function Calling и реляционный редактор промпта
|
||||
|
||||
### 1. Архитектура чистого диалогового агента без регулярных выражений
|
||||
* **Концепция:** Полный отказ от жестких эвристик и регулярных выражений в `tool_injector.py`. Все решения о намерениях оператора, вызове инструментов и переключении тем принимает языковая модель через семантический контекст.
|
||||
* **Ключевые этапы реализации:**
|
||||
* **Этап 1 (Санитарная очистка):** Превращение `tool_injector.py` в простой фильтр мусорных тегов без инжекции и перехватов команд.
|
||||
* **Этап 2 (Семантическое управление сессией):** Инструктаж модели в `role: system` о поведении в состоянии `PROMPT_PREVIEW` (оценка подтверждения, отмены, правок или смены темы диалога).
|
||||
* **Этап 3 (Жизненный цикл контекста):** Модель видит временные сообщения (`is_ephemeral = 1`) только во время активной ветки; при фиксации решения (`fast_path.py`) контекст очищается через `db_purge_ephemeral_messages`.
|
||||
* **Этап 4 (Гибридный UI):** Поддержка как диалоговых правок, так и прямого инлайн-редактирования через форму `[✏️ Редактировать]` в окне чата.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Масштабирование эфемерного контекста и сервисные инструменты
|
||||
|
||||
### 2. Модуль инспекции контекста и базы данных (`db_cli.py`)
|
||||
* **Статус:** `Реализовано`.
|
||||
* Добавлена команда `context [session_id] [--limit N]` для просмотра сырой таблицы сообщений `chat_messages` с пометками об эфемерности.
|
||||
|
||||
### 3. Модуль задач и бэклога (`tasks`)
|
||||
* **Целевые инструменты:** `db_get_tasks`, `db_add_task`, `db_update_task_status`, `db_delete_task`.
|
||||
* Вывод интерактивных карточек задач с фильтрами без засорения постоянной истории диалога.
|
||||
|
||||
### 4. Модуль срезов и архива СКУД (`snapshots`)
|
||||
* **Целевые инструменты:** `db_get_snapshots`, `db_delete_snapshots`.
|
||||
* Интерактивное подтверждение удаления срезов и автоматическая очистка таблиц срезов из контекста.
|
||||
|
||||
### 5. Модуль базы знаний, правил и аномалий (`kb & anomalies`)
|
||||
* **Целевые инструменты:** `db_get_rules`, `db_get_anomalies`, `db_get_reference`.
|
||||
* Изоляция нормативных справочников от постоянной истории диалога для предотвращения залипания LLM.
|
||||
|
||||
---
|
||||
|
||||
## 🔮 Долгосрочный бэклог (Future Modules)
|
||||
|
||||
### 6. Интерактивный модуль планирования (Checklist & Task Planner Engine)
|
||||
* Динамические проектные чек-листы с синхронизацией в таблицу `tasks`.
|
||||
|
||||
### 7. Изолированная песочница кода (Code Execution Sandbox Engine)
|
||||
* Запуск динамических Python/Pandas вычислений в изолированном Docker/gVisor контуре.
|
||||
+223
@@ -0,0 +1,223 @@
|
||||
# **SCUD Orion AI — Полная энциклопедическая хроника, архитектурный паспорт, разбор всех инцидентов и технический контекст проекта**
|
||||
|
||||
**Версия документа:** 4.0 (Исчерпывающий монолитный контекстный паспорт для новой сессии)
|
||||
**Стек технологий и инфраструктура:** Python 3.11+, FastAPI (Uvicorn), SQLite (WAL mode, PRAGMA synchronous=NORMAL, внешние ключи ON), Ollama REST API (Qwen 2.5:14b — основной текстовый агент и классификатор, Qwen 2.5-VL:7b-q8\_0 / Qwen 3-VL:8b — OCR и зрение), MS SQL Server 2019/2022 (СКУД «Орион Pro» ЗАО НВП «Болид», 1С:ЗУП 3.1 через pyodbc / ODBC Driver 18), сетевая Samba-шара (/mnt/scud\_share), Git/Gitea, HTML5 / Vanilla JS / Tailwind CSS.
|
||||
|
||||
## ---
|
||||
|
||||
**1\. Исходный бизнес-контекст, роли систем и фундаментальные задачи**
|
||||
|
||||
Проект решает комплексную проблему контроллинга трудовой дисциплины, автоматического сопоставления кадровых фактов и защиты от рассинхронизации мастер-данных на предприятии со штатом \~270–276 сотрудников.
|
||||
|
||||
### **Источники первичных данных:**
|
||||
|
||||
> * **СКУД «Орион Pro» (Болид):** База данных MS SQL Server (SERVER: 172.16.31.221\\SQL, DB: Orion-14.01.21-1). Основные таблицы:
|
||||
* pLogData — журнал всех сырых физических транзакций турникетов, калиток и внутренних дверей. Ключевые поля: TimeVal (время сервера), DeviceTime (время контроллера), HozOrgan / Hrk (ID сотрудника), Event (код события: 26, 28, 32 — вход; 27, 29, 33 — выход; 54, 55, 64, 65 — внутренние считыватели), Mode (направление: 1 — IN, 2 — OUT), ReaderIndex, DoorIndex.
|
||||
* pList — реестр физических лиц и пропусков (ФИО, табельный номер, статус архива).
|
||||
* PDivision, PPost — справочники подразделений и должностей СКУД.
|
||||
> * **1С:ЗУП 3.1 (Кадры):** База данных MS SQL Server (SERVER: ACCOUNT-01, DB: ZUP30).
|
||||
* dbo.\_Reference299 — эталонный справочник сотрудников.
|
||||
* dbo.\_InfoRg16921 — периодический регистр сведений состояний сотрудников (отпуска основные, больничные, командировки, декретные отпуска, отпуска без сохранения оплаты).
|
||||
* Файловые выгрузки с сетевой шары /mnt/scud\_share: файлы Штат\_ДД\_ММ\_ГГГГ.xlsx (шапка 7–8 строк) и Отсутствия\_ДД\_ММ\_ГГГГ.xlsx (шапка 3–4 строки).
|
||||
> * **Реестры статических исключений:** static\_reason\_workers.csv (реестр удаленщиков и постоянных разъездных сотрудников), exceptions.json (декларативный фильтр обслуживающего персонала и спец-отделов).
|
||||
|
||||
## ---
|
||||
|
||||
**2\. Подробнейшая пошаговая хронология разработки, эволюция идей и разбор ошибок**
|
||||
|
||||
### **Фаза 1: Первые эксперименты с LLM, выявление галлюцинаций и гибридная парадигма**
|
||||
|
||||
> * **Попытка передачи сырых списков в чат:** Первоначальная попытка скормить модели Qwen 2.5:14b список из сотен ФИО с инструкцией *«запомни список 1С»* показала, что у LLM нет постоянной памяти между сессиями. Модель теряла контекст, путала фамилии и выдавала ответы с троеточиями ('Васильев Л.И.', ...) или придумывала несуществующие строки (*«ЛЕНМОРНИИПРОЕКТ ОЭС Варламова Мария»*).
|
||||
> * **Ошибки openpyxl vs pandas:** Первая генерация кода моделью использовала библиотеку openpyxl с построчным перебором ячеек, жестко зашитыми опечатками (поиск слова 'фиио') и падением по FileNotFoundError.
|
||||
> * **Переход к детерминированному пайплайну:** Принято ключевое архитектурное решение — **LLM не считает математику и не фильтрует 300 строк текста**. Всю механическую работу (ETL, слияние, фильтрацию) выполняет быстрый детерминированный Python (pandas, SQL), а локальная LLM выступает исключительно в роли «умного ревизора» на этапе сопоставления сомнительного несовпавшего остатка (Diff).
|
||||
|
||||
### **Фаза 2: Нормализация ФИО, кодировки и коллизия совместителей (Кейс Балаевой О.Г.)**
|
||||
|
||||
> * **Символьные ловушки:**
|
||||
* Латинские буквы-двойники (омоглифы a, c, e, o, p, x, y, случайно набранные в английской раскладке).
|
||||
* Служебные суффиксы в скобках, добавляемые 1С ((осн.), (совм.), (внешн.)).
|
||||
* Буквы ё/е, двойные пробелы, неразрывные пробелы \\xa0 и случайный ввод цифры 0 вместо буквы О.
|
||||
> * **Функция normalize\_fio():** Разработан строгий конвейер очистки:
|
||||
> `def normalize_fio(fio):`
|
||||
> `if not fio or not isinstance(fio, str): return ""`
|
||||
> `fio_clean = re.sub(r'\(.*?\)', '', fio) # Удаление скобок`
|
||||
> `fio_clean = fio_clean.replace('\xa0', ' ')`
|
||||
> `trans = str.maketrans('aceopxyABCEHKMOPTX', 'асеорхуАВСЕНКМОРТХ')`
|
||||
> `fio_clean = fio_clean.translate(trans)`
|
||||
> `fio_clean = fio_clean.replace('ё', 'е').replace('Ё', 'Е')`
|
||||
> `return " ".join(fio_clean.strip().split()).title()`
|
||||
> * **Коллизия 270 vs 271:** В СКУД числилось 270 уникальных человек, а в 1С — 271 строка. Ручной разбор показал, что **Балаева Ольга Геннадьевна** занимает две ставки в 1С (*Руководитель управления персоналом* и *Руководитель режимно-секретного отдела*) при одном физическом пропуске в СКУД.
|
||||
> * **Решение:** Внедрена обязательная группировка штата 1С по fio\_clean с объединением должностей и подразделений через " / ".
|
||||
|
||||
### **Фаза 3: Защита Entity Resolution от однофамильцев (Инцидент с Семеновыми)**
|
||||
|
||||
> * **Сбой модели:** При передаче несовпавших ФИО в Qwen 2.5 модель ошибочно сопоставила *«Семенову Юлию Борисовну»* (которая была на работе) с *«Семеновой Диной Дмитриевной»* (находившейся в отпуске), посчитав это опечаткой в имени из\-за одинаковой фамилии. В результате Юлия Борисовна получила статус нарушителя («в отпуске, но пришла»).
|
||||
> * **Двухконтурная защита:**
|
||||
1. В системный промпт ИИ зашито категорическое правило: однофамильцы с разными именами/отчествами — строго разные люди, объединение запрещено.
|
||||
2. В Python встроен дублирующий барьер: если фамилии совпадают, но инициалы/первые буквы имен различаются, связь ИИ принудительно аннулируется с логированием ⚠️ \[Блокировка фейка\].
|
||||
|
||||
### **Фаза 4: Декларативные исключения и синонимы отделов**
|
||||
|
||||
> * **Переход к exceptions.json:** Исключение клининга, дворников, гардеробщиков и хозяйственного персонала отдела «ЭТО» вынесено из кода в конфигурационный файл exceptions.json (поддержка списков departments, positions, fio, position\_keywords).
|
||||
> * **База синонимов отделов (department\_synonyms):** Для сопоставления сокращений СКУД с длинными названиями 1С (например, *«ОВК» ⟷ «Отдел внутреннего контроля»*) создана таблица SQLite, автоматически обучаемая при подтверждениях оператора.
|
||||
|
||||
### **Фаза 5: Аппаратный сбой СКУД 04.08.2026, разгадка «исчезающих неизвестных» и Первая активность**
|
||||
|
||||
> * **Анатомия сбоя:** Утром 04.08.2026 зависли регистраторы входа на главном КПП. У 119 сотрудников не записалось событие входа (time\_in \= 'Нет входа'). Из них 57 человек были официально закрыты документами 1С (отпуска, командировки). Оставшиеся \~74 человека реально пришли на работу, но утренней отметки не имели. Однако вечером сводка выдала всего 4–7 «неизвестных».
|
||||
> * **Вскрытие механизма ошибки:** Было обнаружено, что скрипт агрегации видел дневные перемещения сотрудников (выходы на обед, считыватели туалетов, внутренние двери) и автоматически выставлял Статус \= 'Присутствовал' и is\_present \= 1\. Из-за этого люди попадали в категорию «Итого на работе», а массовый аппаратный сбой скрывался.
|
||||
> * **Внедрение «Первой активности»:**
|
||||
1. В базу данных и выгрузки Excel добавлена колонка **first\_activity («Первая активность»)** — минимальное время любого события дня в здании (MIN(TimeVal) AS FirstRawEvent без учета направления двери).
|
||||
2. Если time\_in \== 'Нет входа', но first\_activity \!= '—', записи присваивается anomaly\_flag \= 'ANOMALY\_NO\_IN\_HAS\_ACTIVITY', а is\_present принудительно сбрасывается в 0\.
|
||||
3. Внедрен модуль analyze\_scud\_mass\_failure\_ai(): при превышении порога в 5% смены (\>10 человек) ИИ поднимает тревогу о массовом сбое контроллеров КПП.
|
||||
> * **Кейс Равина В.Э.:** Сотрудник находился в официальном отпуске, утреннего входа не имел, но пришел после обеда (первая активность 14:11:06, выход 17:18:38). Система корректно зафиксировала истинную кадровую аномалию (физическое присутствие при официальном отпуске).
|
||||
|
||||
### **Фаза 6: Архитектурная миграция под Gitea и система срезов (снапшотов)**
|
||||
|
||||
> * **Безопасный рефакторинг:** Монолит разделен на слои (core/, services/, scripts/, modules/web\_api/) через git mv с сохранением истории коммитов в ветке refactor/modular-structure.
|
||||
> * **Формат ID снапшота:** Введена схема \[Y\]YYYYMMDD-NNN (например, Y20260804-001 для вчерашнего зафиксированного вечернего среза на 22:00 и 20260805-002 для дневного).
|
||||
> * **Оптимизация экспорта:** Если в SQLite уже зафиксирован вчерашний срез с префиксом Y, повторный тяжелый SQL-запрос к СКУД Орион не выполняется (функция has\_yesterday\_final\_snapshot).
|
||||
> * **Инспекция и CLI:** Написан инструмент scripts/db\_cli.py с командами stats, snapshots, scud, absences, anomalies, rules, prompts, tools, sessions, dump, snapshot del.
|
||||
|
||||
### **Фаза 7: Web API, Generative UI, управление памятью LLM и Topic Drift Guard**
|
||||
|
||||
> * **FastAPI & Безопасность:** Развернут Web API с JWT-авторизацией (bcrypt), изолированными задачами пользователей (tasks с привязкой к user\_id), гостевым режимом и ролевой моделью.
|
||||
> * **Проблема деградации контекста LLM:** Вывод объемных списков задач, текстов системных промптов и таблиц снапшотов засорял контекстное окно чата, приводя к галлюцинациям и «залипанию» модели на старых правилах.
|
||||
> * **Решение проблемы памяти (Topic Drift & Ephemeral Context):**
|
||||
* В таблицу chat\_messages добавлен флаг is\_ephemeral \= 1 для временных сообщений.
|
||||
* Введены двухфазные сессии (PROMPT\_PREVIEW → PROMPT\_FOLLOWUP) и детерминированный счетчик отвлечений idle\_turns.
|
||||
* **Context Guard:** На 3-м шаге отвлечения оператора на сторонние темы система отвечает на вопрос и выводит интерактивное напоминание с кнопками \[Завершить настройку\] / \[Показать промпт\]. При idle\_turns \> 3 происходит автоочистка сессии вызовом db\_purge\_ephemeral\_messages().
|
||||
* **Fast-Path:** Прямой перехват команд подтверждения («да», «подтверждаю», «сохранить») и выхода («нет, спасибо», «закончить настройку») без обращения к LLM (ответ за 0.05 сек).
|
||||
* **Декларативный реестр действий (tool\_action\_registry):** Хранение шаблонов ответов, типов кнопок и признаков эфемерности в SQLite.
|
||||
> * **Generative UI (Интерактивные карточки задач):** Инструмент db\_get\_tasks возвращает полезную нагрузку TASK\_INTERACTIVE\_CARD. Фронтенд рендерит живой виджет с табами (Все / В работе / В планах / Завершенные), чекбоксами и inline-созданием задач через REST API без вызова LLM.
|
||||
|
||||
## ---
|
||||
|
||||
**3\. Полная схема базы данных SQLite (data/scud\_orion\_ai.db)**
|
||||
|
||||
| Таблица | Назначение и бизнес-логика | Полная структура колонок |
|
||||
| :---- | :---- | :---- |
|
||||
| **scud\_logs** | Хранение логов проходов СКУД, расчетного времени и снапшотов. | id (PK), log\_date, fio, fio\_clean, department, position, time\_in, first\_activity, time\_out, time\_in\_building, is\_present, anomaly\_flag, snapshot\_time, snapshot\_id, created\_at |
|
||||
| **zup\_staff** | Штатное расписание 1С:ЗУП на даты срезов. | id (PK), snapshot\_date, fio, fio\_clean, department, position, created\_at |
|
||||
| **zup\_absences** | Официальные кадровые отклонения 1С (отпуска, больничные, командировки, декреты). | id (PK), absence\_date, fio, fio\_clean, absence\_type, created\_at |
|
||||
| **anomalies\_history** | Журнал выявленных кадровых и аппаратных аномалий. | id (PK), anomaly\_date, fio, anomaly\_type, details, human\_status, created\_at |
|
||||
| **ai\_knowledge\_base** | Глобальные правила арбитража и приоритеты компании для ИИ. | id (PK), rule\_text, added\_by, created\_at |
|
||||
| **system\_prompts** | Версионные системные промпты агента (активный промпт по is\_active=1). | id (PK), name, prompt\_text, is\_active, updated\_at |
|
||||
| **tool\_action\_registry** | Декларативный реестр шаблонов, кнопок и настроек эфемерности инструментов. | id (PK), tool\_name, category, bypass\_llm, success\_template, follow\_up\_question, action\_type, buttons\_json, is\_active, is\_ephemeral, updated\_at |
|
||||
| **session\_states** | Активные состояния сессий, черновики и счетчик idle\_turns. | session\_id (PK), state\_type, pending\_data, updated\_at |
|
||||
| **chat\_messages** | История диалогов с поддержкой разделения на постоянные и эфемерные сообщения. | id (PK), session\_id, role, content, is\_ephemeral, created\_at |
|
||||
| **tasks** | Реестр задач пользователей с привязкой к user\_id. | id (PK), task\_id, module, title, priority, status, due\_date, user\_id, created\_at |
|
||||
| **users** | Учетные записи операторов (хэши паролей bcrypt, права администратора). | id (PK), username, password\_hash, is\_admin, full\_name, created\_at |
|
||||
| **department\_synonyms** | База знаний соответствия аббревиатур СКУД полным названиям отделов 1С. | id (PK), short\_name, full\_name, created\_at |
|
||||
| **system\_reference** | Справочник команд и примеров промптов для операторов. | id (PK), category, title, example\_prompt, description |
|
||||
|
||||
## ---
|
||||
|
||||
**4\. Актуальная архитектура каталогов и назначение файлов**
|
||||
|
||||
`scud_ai/`
|
||||
`├── config.py # Конфигурация: пути, расчет дат, URL Ollama, параметры MS SQL`
|
||||
`├── exceptions.json # Декларативные фильтры исключений (ОВК, уборщики, подрядчики)`
|
||||
`├── main_etl.py # Оркестратор ETL: экспорт СКУД/1С -> SQLite -> Excel/MD отчеты`
|
||||
`├── project_code_snapshot.md # Полный исходный код всех файлов репозитория`
|
||||
`├── core/`
|
||||
`│ └── database.py # Драйвер SQLite (WAL), функции сохранения/загрузки срезов`
|
||||
`├── services/`
|
||||
`│ ├── scud_export.py # Прямой SQL-экспорт из MS SQL «Орион Pro»`
|
||||
`│ ├── zup_extractor.py # Прямой SQL-экспорт из MS SQL 1С:ЗУП 3.1`
|
||||
`│ ├── data_loader.py # Загрузка данных, нормализация ФИО, расчет первой активности`
|
||||
`│ ├── data_validator.py # Проверка свежести и наличия файлов за Вчера и Сегодня`
|
||||
`│ ├── excel_exporter.py # Генерация сводки и детального отчета в Excel (openpyxl)`
|
||||
`│ ├── text_reporter.py # Построение итогового Markdown-отчета через Qwen 2.5`
|
||||
`│ ├── ai_verifier.py # Модули ИИ-аудита, Fuzzy Matching и детекции сбоев СКУД`
|
||||
`│ ├── feedback_loop.py # Интерактивный консольный модуль Human-in-the-Loop`
|
||||
`│ ├── knowledge_base.py # Интерфейс работы с базой знаний правил`
|
||||
`│ └── share_copier.py # Резервное скачивание файлов 1С с шары /mnt/scud_share`
|
||||
`├── scripts/`
|
||||
`│ ├── db_cli.py # CLI-утилита управления БД, снапшотами, дампами и сессиями`
|
||||
`│ ├── fix_snapshots.py # Скрипт переиндексации и нормализации снапшотов`
|
||||
`│ ├── init_tool_registry.py # Инициализация декларативного реестра инструментов`
|
||||
`│ └── diagnostics/`
|
||||
`│ ├── inspect_db.py # Диагностика структуры таблиц и количества записей`
|
||||
`│ ├── inspect_ephemeral.py # Анализ распределения постоянных и эфемерных сообщений`
|
||||
`│ ├── inspect_files.py # Аудит файлов и размеров на диске`
|
||||
`│ └── show_tree.py # Вывод дерева каталогов`
|
||||
`├── modules/web_api/`
|
||||
`│ ├── main.py # Точка входа FastAPI приложения, роутеры и раздача статики`
|
||||
`│ ├── routers/`
|
||||
`│ │ ├── admin.py # Управление пользователями`
|
||||
`│ │ ├── auth.py # JWT аутентификация и смена паролей`
|
||||
`│ │ ├── chat.py # Эндпоинты диалогов (авторизованный и гостевой)`
|
||||
`│ │ └── tasks.py # REST API управления задачами`
|
||||
`│ ├── llm/`
|
||||
`│ │ ├── agent.py # Координатор диалога, Tool Calls и Topic Drift Guard`
|
||||
`│ │ ├── schemas.py # Описание JSON-схем инструментов для Ollama`
|
||||
`│ │ ├── file_parser.py # Мультимодальный парсер файлов (PDF, PNG, XLSX, TXT)`
|
||||
`│ │ ├── db_tools.py # Фасадные вызовы функций БД для агента`
|
||||
`│ │ ├── core/`
|
||||
`│ │ │ ├── calendar_utils.py # Формирование системного контекста дат и дней недели`
|
||||
`│ │ │ ├── fast_path.py # Быстрый перехват команд подтверждения/отмены (0.05 с)`
|
||||
`│ │ │ ├── ollama_client.py # HTTP-клиент взаимодействия с Ollama API`
|
||||
`│ │ │ ├── prompt_merger.py # Парсинг и слияние правок системного промпта`
|
||||
`│ │ │ └── tool_injector.py # Очистка сырых тегов и артефактов Tool Calls`
|
||||
`│ │ └── db/`
|
||||
`│ │ ├── connection.py # Подключение к scud_orion_ai.db`
|
||||
`│ │ ├── db_chat.py # Сохранение истории и очистка эфемерных сообщений`
|
||||
`│ │ ├── db_prompts.py # Системные промпты, стейты и реестр действий`
|
||||
`│ │ ├── db_snapshots.py # Выборка и удаление снапшотов`
|
||||
`│ │ └── db_tasks.py # CRUD операции с задачами пользователей`
|
||||
`│ └── static/`
|
||||
`│ ├── index.html # SPA разметка (модалки, чат, боковая панель задач)`
|
||||
`│ ├── css/styles.css # Стили и мобильные оптимизации`
|
||||
`│ └── js/`
|
||||
`│ ├── app.js # Инициализация приложения`
|
||||
`│ ├── auth.js # Логика входа, смены паролей и администрирования`
|
||||
`│ ├── chat.js # Обработка сообщений, Drag&Drop, виджет задач и кнопки`
|
||||
`│ └── tasks.js # Управление боковой панелью задач (Drawer)`
|
||||
`└── docs/`
|
||||
`└── development_roadmap.md # Стратегическая дорожная карта и архитектурный бэклог`
|
||||
|
||||
## ---
|
||||
|
||||
**5\. Справочник команд командной строки (CLI Reference)**
|
||||
|
||||
### **Главный конвейер контроллинга (main\_etl.py)**
|
||||
|
||||
> * python main\_etl.py — стандартный дневной запуск: экспорт свежих данных СКУД и 1С, сохранение снапшота в SQLite, генерация Excel и Markdown отчетов.
|
||||
> * python main\_etl.py \--skip-export — построение отчетов по последнему имеющемуся снапшоту из SQLite без повторного запроса к MS SQL.
|
||||
> * python main\_etl.py \--snapshot 20260805-001 — точный расчет отчетов по указанному составному ID снапшота.
|
||||
> * python main\_etl.py \-d — запуск в режиме расширенной отладки (DEBUG).
|
||||
|
||||
### **CLI-утилита управления SQLite базой данных (scripts/db\_cli.py)**
|
||||
|
||||
> * python scripts/db\_cli.py stats — общая статистика количества записей по всем таблицам БД.
|
||||
> * python scripts/db\_cli.py snapshots \[ДД.ММ.ГГГГ\] — просмотр реестра снапшотов с сортировкой по времени создания (самые свежие сверху).
|
||||
> * python scripts/db\_cli.py scud \[ДД.ММ.ГГГГ\] \[--snapshot ID\] \[--export-xlsx NAME\] — просмотр логов СКУД и опциональный экспорт в Excel.
|
||||
> * python scripts/db\_cli.py absences \[ДД.ММ.ГГГГ\] — список кадровых отклонений из 1С:ЗУП.
|
||||
> * python scripts/db\_cli.py anomalies — история выявленных аномалий.
|
||||
> * python scripts/db\_cli.py rules — правила базы знаний компании.
|
||||
> * python scripts/db\_cli.py prompts — просмотр системных промптов из таблицы system\_prompts.
|
||||
> * python scripts/db\_cli.py tools — вывод декларативного реестра действий инструментов и шаблонов кнопок.
|
||||
> * python scripts/db\_cli.py sessions — просмотр активных сессионных стейтов и висящих черновиков.
|
||||
> * python scripts/db\_cli.py snapshot del \[ID\] — удаление конкретного снапшота по ID.
|
||||
> * python scripts/db\_cli.py snapshot del \--day \[ДД.ММ.ГГГГ\] — удаление всех снапшотов за выбранный день.
|
||||
> * python scripts/db\_cli.py dump \[backup.xlsx\] — полный дамп всех таблиц базы данных в многостраничный Excel-файл.
|
||||
|
||||
## ---
|
||||
|
||||
**6\. Стратегическая дорожная карта развития (Roadmap & Backlog)**
|
||||
|
||||
> 1. **Масштабирование механизма эфемерного контекста на все инструменты (Rollout Roadmap):**
|
||||
* **Снапшоты (snapshots):** Перевод вывода объемных таблиц срезов в эфемерный режим (is\_ephemeral \= 1), внедрение интерактивного подтверждения при удалении снапшотов по ID/дате через состояния SNAPSHOTS\_PREVIEW / SNAPSHOTS\_FOLLOWUP.
|
||||
* **База знаний и аномалии (kb & anomalies):** Вывод справочников команд, правил арбитража и списков аномалий исключительно во временный слой для исключения «залипания» модели на устаревших правилах из истории сообщений.
|
||||
* **Декларативная унификация в tool\_action\_registry:** Расширение схемы таблицы полями followup\_state\_type, auto\_purge\_on\_exit, guard\_question\_template для устранения хардкода имен функций в agent.py.
|
||||
> 2. **Модуль анализа внутридневных перемещений («Контроль перекуров»):**
|
||||
* Анализ интервалов между событиями OUT (выход) и IN (возврат) по журналу pLogData.
|
||||
* Подсчет суммарного времени нахождения вне рабочего места в течение смены с отсечением технологической нормы (30–40 минут).
|
||||
* Вывод аналитического блока и злостных нарушителей в отдельный лист Excel-отчета и итоговую Markdown-сводку.
|
||||
> 3. **Интерактивный Task Planner & Roadmap Engine:**
|
||||
* Специализированный инструмент для ведения динамических проектных планов и чек-листов с чекбоксами (\[ \] / \[x\]) прямо в диалоге с синхронизацией в таблицу tasks.
|
||||
> 4. **Изолированная среда исполнения кода (Code Execution Sandbox):**
|
||||
* Безопасный изолированный Docker/gVisor контейнер для динамического выполнения генерируемого моделью Python/Pandas кода на лету с возвратом stdout/stderr и графиков в контекст.
|
||||
> 5. **Автоматизация расписания срезов и Telegram-алерты:**
|
||||
* Автозапуск выгрузок в 12:00, 17:00 и 19:00 через systemd-таймеры с фиксацией snapshot\_time.
|
||||
* Отправка мгновенных алертов о массовых сбоях турникетов (\>5%) и критических кадровых конфликтах дежурному системному администратору в Telegram.
|
||||
@@ -47,4 +47,51 @@ main (100% стабильный релиз)
|
||||
* Запуск сложных вычислений, агрегаций и статистического анализа данных СКУД на лету (Pandas / NumPy).
|
||||
* Выполнение тестовых сценариев и валидация скриптов перед их сохранением/применением на проде.
|
||||
* Полная изоляция от хост-системы: read-only доступ к копиям данных, ограничение памяти/CPU (cgroups), отсутствие доступа к чувствительным сетевым интерфейсам.
|
||||
* Возврат результатов вычислений (stdout, stderr, артефакты, сгенерированные таблицы/графики) обратно в контекст модели.
|
||||
* Возврат результатов вычислений (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.
|
||||
@@ -0,0 +1,33 @@
|
||||
# План реализации
|
||||
|
||||
## 1. Очистка от регулярок и костылей (`tool_injector.py`)
|
||||
- [ ] Полностью удалить принудительные перехваты текста регулярными выражениями для команд добавления, редактирования и удаления пунктов.
|
||||
- [ ] Оставить в модуле только базовую санитарную очистку сырых тегов (`<tool_call>`).
|
||||
|
||||
---
|
||||
|
||||
## 2. Настройка контекста и инструкций сессии (`agent.py`)
|
||||
- [ ] Передать управление диалогом языковой модели через системный блок `role: "system"`.
|
||||
- [ ] При активном состоянии `PROMPT_PREVIEW` передавать модели инструкцию:
|
||||
- **Подтверждение / отмена / корректировка:** продолжать работу с превью и вызывать соответствующие инструменты.
|
||||
- **Смена темы:** вежливо напомнить об открытом изменении и запросить решение.
|
||||
- [ ] Обеспечить видимость эфемерных сообщений (`is_ephemeral = 1`) для модели во время активной работы с превью.
|
||||
|
||||
---
|
||||
|
||||
## 3. Очистка эфемерных сообщений при завершении (`fast_path.py`)
|
||||
- [ ] Настроить удаление временных сообщений превью (`db_purge_ephemeral_messages`) строго в момент нажатия кнопок **«Подтвердить»** или **«Отменить»**.
|
||||
- [ ] Сбрасывать состояние сессии в базе данных после фиксации решения.
|
||||
|
||||
---
|
||||
|
||||
## 4. Инлайн-редактор в окне диалога (`core.js`)
|
||||
- [ ] Проверить работу блока ручного редактирования (`inline-prompt-editor-container`) с кнопками **«Сохранить правки»** и **«Свернуть»**.
|
||||
- [ ] Обеспечить сохранение черновика через API (`/api/v1/chat/draft`) и отображение обновленного текста перед подтверждением.
|
||||
|
||||
---
|
||||
|
||||
## 5. Тестирование и валидация
|
||||
- [ ] **Нативные вызовы:** проверить добавление, редактирование и удаление пунктов через нативные вызовы модели.
|
||||
- [ ] **Контекстные сценарии:** проверить поведение модели при смене темы диалога оператором.
|
||||
- [ ] **UI и очистка:** проверить ручное редактирование через кнопку в окне чата и последующую очистку контекста.
|
||||
Reference in New Issue
Block a user