Просмотр кода страницы Kuzya 2-0 lost patch

'''Кузя''' — Telegram-бот для администрирования и сопровождения сообщества. Проект развивается от административного бота к интеллектуальному помощнику, способному поддерживать диалог, находить информацию в истории чата и помогать модераторам.

Основная задача Кузи — автоматизировать рутинные действия и предоставить администрации удобные инструменты управления сообществом. Окончательный контроль остаётся у людей.

'''Текущий этап: Kuzya 2.0 — перенос существующих функций на новую архитектуру. Полный функциональный паритет с Legacy пока не подтверждён.'''

Состояние разработки в статье отражает проверку репозитория и результатов тестирования по состоянию на '''18 сентября 2026 года'''. Наличие кода в репозитории не означает, что все возможности уже развёрнуты и проверены в основном сообществе.

== Репозиторий и версии ==

* [https://gitlab.ramba-art.ru/Gans/noprodaction Репозиторий noProdaction]
* [https://gitlab.ramba-art.ru/Gans/noprodaction/-/tree/feature/openai-bot-v2 Ветка разработки Kuzya 2.0]
* [https://gitlab.ramba-art.ru/Gans/noprodaction/-/commits/feature/openai-bot-v2 История изменений Kuzya 2.0]

{| class="wikitable"
! Версия / ветка
! Назначение
! Подтверждённое состояние
|-
| '''Legacy Stable'''
| Существующая версия и эталон поведения при переносе
| Legacy-код сохранён в репозитории; при проверке ветки <code>main</code> и <code>kuzya-1.0</code> указывали на коммит <code>145bc857</code>
|-
| '''Kuzya 2.0'''
| Новая реализация на aiogram 3
| Разрабатывается в <code>feature/openai-bot-v2</code>; часть функций перенесена и проверена
|-
| '''Последняя подтверждённая точка 2.0'''
| Перенос команд модерации
| Коммит <code>b5095f4f</code> от 3 сентября 2026 года
|}

Главный принцип миграции:

'''Новая версия должна сохранить существующие возможности и архив MySQL. Замена Legacy допускается после проверки функционального паритета.'''

Базовые AI-функции уже присутствуют в ветке 2.0. Их наличие не означает завершения миграции или готовности будущего Guardian.

== Возможности Legacy Stable ==

Legacy служит исходной точкой для переноса следующих возможностей:

* выдача и снятие мута;
* временный и постоянный бан;
* предупреждения с указанием причины;
* хранение истории предупреждений;
* внутренний список администраторов Кузи;
* приветствие новых участников;
* информационные команды;
* вывод правил, ссылок и приглашений;
* информация о поддержке проекта;
* взаимодействие с публикациями Telegram-канала;
* информационные сообщения под новыми видео;
* хранение истории сообщений чата;
* изменение настроек и текстов административными командами;
* базовое взаимодействие с AI.

'''Этот список описывает исходную функциональность проекта, а не подтверждённый полный набор возможностей Kuzya 2.0.'''

== Что уже сделано в Kuzya 2.0 ==

=== Новая основа бота ===

В репозитории зафиксированы:

* создание новой версии на '''aiogram 3''';
* разделение обработчиков и сервисов;
* интеграция OpenAI через прокси;
* AI-ответы в личных сообщениях;
* сохранение истории в совместимом с Legacy формате;
* поддержка диалога через reply;
* перенос информационных команд;
* перенос приветствий;
* перенос внутренних администраторов;
* перенос предупреждений;
* перенос команд модерации.

Наличие базового reply-диалога не означает готовности полноценного контекста сообщества, долговременной памяти или RAG.

=== Контрольные коммиты ===

{| class="wikitable"
! Дата
! Коммит
! Изменение
|-
| 26 августа 2026
| <code>b55de2fa</code>
| Создание бота на aiogram 3
|-
| 26 августа 2026
| <code>38472685</code>
| Рабочая интеграция OpenAI через прокси
|-
| 2 сентября 2026
| <code>aa68090b</code>
| AI-ответы в личных сообщениях
|-
| 2 сентября 2026
| <code>476d2895</code>
| Удаление старого кода из ветки разработки и подготовка Kuzya 2.0
|-
| 2 сентября 2026
| <code>e691eb92</code>
| История в Legacy-БД и диалог через reply
|-
| 2 сентября 2026
| <code>da627b0c</code>
| Перенос информационных команд
|-
| 2 сентября 2026
| <code>346f7b69</code>
| Перенос приветствий
|-
| 3 сентября 2026
| <code>2a9a23ea</code>
| Перенос внутренних администраторов
|-
| 3 сентября 2026
| <code>2ae970c5</code>
| Перенос системы предупреждений
|-
| 3 сентября 2026
| <code>b5095f4f</code>
| Перенос команд модерации
|}

Источник: [https://gitlab.ramba-art.ru/Gans/noprodaction/-/commits/feature/openai-bot-v2 история ветки разработки].

=== Внутренние администраторы ===

Перенесена команда:

<pre>
!свой
</pre>

Команда применяется ответом на сообщение пользователя и добавляет его во внутренний список администраторов Кузи.

Подтверждено тестированием:

* распознавание команды;
* проверка инициатора по внутренней таблице администраторов;
* определение пользователя из reply;
* обнаружение уже зарегистрированного администратора;
* добавление нового администратора в MySQL.

При проверке в тестовом чате количество записей увеличилось с двух до трёх.

'''Внутренний администратор Кузи и администратор Telegram-чата — разные роли.''' Команда <code>!свой</code> управляет внутренним списком и сама по себе не выдаёт административные права Telegram.

=== Предупреждения ===

Перенесена команда:

<pre>
!предупреждение причина
</pre>

Команда применяется ответом на сообщение нарушителя.

Реализована цепочка:

# Проверка прав внутреннего администратора Кузи.
# Определение нарушителя и исходного сообщения.
# Запись предупреждения в MySQL.
# Подсчёт предупреждений пользователя.
# Удаление команды и сообщения-нарушения при наличии необходимых прав.
# Публикация уведомления в чате.

Проверено создание предупреждения с причиной <code>тест</code> и сохранение соответствующей записи в MySQL.

Добавлено создание отсутствующей таблицы предупреждений по совместимой схеме, включая поле <code>message_id</code>.

'''Уведомление в отдельном админ-чате и кнопка мута после предупреждения остаются незавершённой частью переноса.'''

=== Мут, размут и бан ===

В новой версии используются команды без старого суффикса <code>1</code>:

{| class="wikitable"
! Команда
! Назначение
! Состояние проверки
|-
| <code>!мут 30</code>
| Ограничить отправку сообщений на указанное число минут
| Временный мут проверен в тестовом чате
|-
| <code>!размут</code>
| Снять ограничения отправки сообщений
| Проверено в тестовом чате
|-
| <code>!бан 60</code>
| Исключить пользователя и запретить возвращение на указанное число минут
| Проверен временный бан на одну минуту
|-
| <code>!бан 0</code>
| Постоянный бан
| Предусмотрен кодом; отдельный live-тест не зафиксирован
|}

Команды применяются ответом на сообщение пользователя.

Инициатор должен иметь права администратора Telegram-чата. Для <code>!размут</code> также добавлена проверка прав, отсутствовавшая в разобранном Legacy-обработчике.

Результаты тестов мута, размута и временного бана подтверждены сообщениями бота и наблюдением за поведением тестового пользователя.

=== Среда разработки ===

По последним зафиксированным результатам новая версия запускалась в следующей среде:

{| class="wikitable"
! Параметр
! Значение
|-
| Узел / контейнер
| <code>noprodaction-v2</code>
|-
| Proxmox CT
| <code>503</code>
|-
| Каталог проекта
| <code>/opt/bots/noprodaction</code>
|-
| Ветка
| <code>feature/openai-bot-v2</code>
|-
| Сервис
| <code>kuzya.service</code>
|-
| Окружение Python
| <code>.venv</code>
|-
| Чат для проверок
| «Панды»
|}

Эти сведения описывают последнюю подтверждённую конфигурацию. Текущее состояние сервиса проверяется отдельно на сервере.

== Текущая точка остановки ==

'''Последний подтверждённый завершённый блок — перенос команд модерации.'''

Он сохранён в репозитории:

[https://gitlab.ramba-art.ru/Gans/noprodaction/-/commit/b5095f4f92f994d07c151fdedf399e27c556eb74 b5095f4f — Migrate legacy moderation commands].

Следующим обсуждалось восстановление действия '''«Мут на 120 минут»''' после предупреждения.

В ходе обсуждения предложено расширить этот механизм:

* создать отдельный служебный админ-чат;
* привязать его к основному сообществу;
* отправлять туда карточки предупреждений;
* принимать решение о муте голосованием внутренних администраторов.

'''Привязка чатов и коллективное голосование находятся на стадии проектирования. Их реализация в проверенном состоянии репозитория не подтверждена.'''

=== Ближайшие задачи ===

# Проверить актуальное состояние ветки, сервиса и соответствие запущенного кода репозиторию.
# Завершить уведомления о предупреждениях и действие мута на 120 минут.
# Согласовать правила привязки админ-чата и коллективного голосования.
# Составить полный список функций Legacy и проверить каждую в Kuzya 2.0.
# Завершить недостающие функции, включая проверку сценариев публикаций канала и изменения настроек.
# Подтвердить сохранность архива и совместимость работы с MySQL.
# После достижения паритета переходить к следующим этапам дорожной карты.

== Планируемая коллективная модерация ==

=== Привязка админ-чата ===

Для основного сообщества предлагается хранить привязку к отдельному служебному чату.

Пример предполагаемой схемы:

<pre>
Основной чат
     |
     | предупреждение
     v
Привязанный админ-чат
     |
     | карточка нарушения
     v
Голосование администраторов
     |
     v
Исполнение принятого решения
</pre>

В качестве интерфейса обсуждалась двухэтапная привязка:

<pre>
В основном чате:
!кодадминчата

В служебном чате:
!привязать <код>
</pre>

'''Названия команд приведены как предложение и пока не являются документированным рабочим интерфейсом.'''

=== Голосование за мут ===

Предлагаемая карточка:

<pre>
Новое предупреждение

Чат: название сообщества
Пользователь: имя / username
Причина: флуд
Всего предупреждений: 3
Выдал: администратор

Предложение: мут на 120 минут

[За мут] [Против]
</pre>

Предлагаемые правила:

* голосуют внутренние администраторы соответствующего основного чата;
* каждый администратор имеет один голос;
* до завершения голосования голос можно изменить;
* решение принимается при количестве голосов «за» больше половины состава;
* после исполнения решения голосование закрывается;
* обычные команды ручной модерации сохраняются.

Предлагаемая формула большинства:

<pre>
required_votes = admin_count // 2 + 1
</pre>

{| class="wikitable"
! Число администраторов
! Необходимо голосов «за»
|-
| 3
| 2
|-
| 4
| 3
|-
| 5
| 3
|-
| 6
| 4
|}

Перед реализацией необходимо определить:

* окончательный порог голосования;
* срок действия голосования;
* условия закрытия без принятого решения;
* порядок учёта изменений состава администраторов;
* поведение при ручном муте или бане во время голосования;
* защиту от повторного исполнения;
* обработку ошибок Telegram API.

В будущем этот механизм может принимать предложения Guardian. До появления Guardian он должен работать самостоятельно для ручных предупреждений.

== База данных и архив сообщества ==

Кузя использует '''MySQL''' для хранения истории и служебных данных.

По исторической оценке за август 2026 года архив содержал около '''497 000 сообщений'''. Это ориентир за указанный период, а не текущий результат подсчёта строк.

=== История сообщений ===

В Legacy-формате сохраняются, в частности:

* дата и время;
* идентификатор чата;
* Telegram ID пользователя;
* username;
* отображаемое имя;
* текст сообщения;
* Telegram message ID.

При миграции необходимо сохранять существующий архив и связи между записями.

=== Предупреждения ===

Для предупреждений используются отдельные записи, содержащие:

* пользователя;
* идентификатор исходного сообщения;
* причину;
* значение <code>number_of_warnings</code>;
* идентификатор и имя администратора;
* дату и время.

В перенесённой Legacy-логике каждое новое предупреждение создаёт строку со значением:

<pre>
number_of_warnings = 1
</pre>

Общее число предупреждений пользователя определяется суммированием этого поля.

Для связи с исходным сообщением предусмотрено поле <code>message_id</code>. Полноту исторических связей необходимо проверить до использования данных для интеллектуальной модерации.

При сопоставлении сообщений требуется учитывать также чат: одного <code>message_id</code> недостаточно для различения сообщений из разных чатов.

=== Использование архива для AI ===

История предупреждений может стать источником примеров нарушений, но ещё не считается готовым проверенным набором данных.

Перед использованием необходимо:

* проверить наличие исходных сообщений;
* проверить причины и корректность связей;
* восстановить доступный контекст;
* учесть изменения правил сообщества;
* отделить подтверждённые нарушения от спорных случаев;
* добавить примеры сообщений без нарушений.

== Архитектура проекта ==

=== Текущая реализация ===

В разработке используются отдельные обработчики и сервисы. Среди подтверждённых компонентов:

<pre>
main.py
bot/
  handlers/
    common.py
    info.py
    ai.py
    history.py
    admins.py
    moderation.py
  services/
    database.py
</pre>

Схема показывает известные компоненты и не является полным перечнем файлов репозитория.

=== Целевая архитектура ===

В перспективе Кузя объединит три направления:

<pre>
                    КУЗЯ
                      |
        +-------------+-------------+
        |             |             |
        v             v             v
 Telegram Admin   AI Assistant    Guardian
        |             |             |
   mute / ban       диалог       анализ нарушений
   warnings         контекст     предложения
   rules            поиск        антиспам
   channel          RAG          конфликты
        |             |             |
        +-------------+-------------+
                      |
                      v
                 RAMBA AI Router
</pre>

Это целевая схема. Guardian, RAG и подключение Кузи к RAMBA AI Router не относятся к подтверждённым завершённым функциям текущей версии.

== AI: текущая реализация и целевое направление ==

=== Текущая реализация ===

В ветке Kuzya 2.0 зафиксированы интеграция OpenAI через прокси, ответы в личных сообщениях и базовый диалог через reply.

Эти возможности необходимо учитывать при описании текущего состояния: AI уже присутствует, хотя миграция Legacy ещё не завершена.

=== Планируемая интеграция RAMBA AI Router ===

Целевое направление — использование локальной инфраструктуры RAMBA AI.

<pre>
Telegram
    |
    v
  Кузя
    |
    v
RAMBA AI Router
    |
    +--> локальная модель для быстрых ответов
    |
    +--> локальная модель для сложных задач
    |
    +--> специализированная модель
    |
    +--> внешний AI при необходимости
</pre>

Telegram-бот должен обращаться к Router через согласованный интерфейс. Выбор и запуск моделей остаются ответственностью AI-инфраструктуры.

Локальные модели планируются как основа интеллектуальных функций, внешние API — как дополнительный инструмент.

'''Развитие RAMBA AI Router и его памяти является отдельной работой. Готовность функции Router не означает её автоматического подключения к Кузе.'''

== Дорожная карта ==

Номера версий ниже обозначают планируемые этапы развития, а не список выпущенных релизов.

{| class="wikitable"
! Этап
! Основная задача
! Статус по последней проверке
|-
| '''Legacy Stable'''
| Существующая функциональность и эталон миграции
| Исходная версия сохранена
|-
| '''2.0'''
| Новая архитектура и полный перенос существующих функций
| В работе; часть функций перенесена и проверена
|-
| '''2.1'''
| Нормализация MySQL с сохранением архива
| Запланировано
|-
| '''2.2'''
| Интеграция с RAMBA AI Router
| Запланировано; подключение Кузи не подтверждено
|-
| '''2.3'''
| Развитие диалогов и краткосрочного контекста
| Запланировано поверх базовых AI-ответов
|-
| '''2.4'''
| RAG по истории Telegram-чата
| Запланировано
|-
| '''3.0'''
| Основа Kuzya Guardian
| Запланировано
|-
| '''3.1'''
| Shadow Mode и оценка качества
| Запланировано
|-
| '''3.2'''
| Полуавтоматическая модерация
| Запланировано
|-
| '''3.3'''
| Репутация пользователей
| Запланировано
|-
| '''3.4'''
| Анализ развития конфликтов
| Запланировано
|-
| '''4.0'''
| Аналитика сообщества и дайджесты
| Запланировано
|-
| '''4.1'''
| Глубокая интеграция AI с правилами сообщества
| Запланировано
|-
| '''5.0'''
| Интеллектуальный Community Guardian
| Долгосрочная цель
|}

=== Kuzya 2.0 — функциональный паритет ===

Этап считается завершённым после проверки переноса всех необходимых возможностей Legacy.

Критерии готовности:

* административные и информационные команды работают;
* приветствия и сценарии публикаций канала проверены;
* настройки и тексты доступны в предусмотренных сценариях;
* история и предупреждения сохраняются корректно;
* права доступа соответствуют назначению команд;
* архив MySQL сохранён;
* известные различия с Legacy документированы;
* подготовлен порядок переключения и возврата к стабильной версии.

=== Kuzya 2.1 — нормализация MySQL ===

Планируется постепенный переход от таблиц отдельных чатов к общей структуре:

* <code>chats</code>;
* <code>users</code>;
* <code>messages</code>;
* <code>warnings</code>;
* <code>moderation_actions</code>;
* <code>admins</code>;
* <code>chat_settings</code>.

Миграция должна сохранять историю, идентификаторы и связи данных.

Для административных действий планируется учитывать источник решения:

* <code>human</code> — администратор;
* <code>ai</code> — AI;
* <code>rule</code> — автоматическое правило.

Для коллективных решений дополнительно потребуется хранить сведения о голосовании.

=== Kuzya 2.2 — RAMBA AI Router ===

Планируется подключение Кузи к общему AI-бэкенду.

Это позволит:

* менять модели независимо от Telegram-бота;
* использовать одну инфраструктуру для нескольких проектов;
* централизованно управлять маршрутизацией запросов;
* определить условия обращения к внешнему AI.

=== Kuzya 2.3 — контекст диалогов ===

Планируется развитие диалога с учётом:

* текущего вопроса;
* предыдущих реплик;
* цепочки reply;
* принадлежности сообщений к конкретному чату и разговору;
* настроек сообщества;
* доступных правил.

Контекст разных пользователей и чатов должен разделяться в соответствии с назначением диалога.

=== Kuzya 2.4 — RAG по истории ===

История чата не должна целиком передаваться модели при каждом запросе.

Планируемая схема:

<pre>
Архив MySQL
      |
      v
Подготовка и индексация
      |
      v
Поисковый индекс
      |
      v
Поиск подходящих фрагментов
      |
      v
Контекст для ответа AI
</pre>

Конкретный способ поиска и необходимость векторной базы определяются при реализации.

Пример будущего запроса:

<pre>
Кузя, мы раньше обсуждали эту проблему?
</pre>

Бот должен находить связанные обсуждения и, где возможно, показывать ссылки на исходные сообщения.

== Kuzya Guardian ==

'''Kuzya Guardian''' — планируемая система интеллектуальной помощи модераторам.

Она должна анализировать сообщения и контекст, находить возможные нарушения и предлагать действия.

=== Анализ сообщений ===

Предполагаемые категории:

* спам;
* флуд;
* нежелательная реклама;
* оскорбления;
* нарушения правил;
* провокации;
* эскалация конфликтов;
* повторные нарушения.

Планируемая последовательность:

<pre>
Новое сообщение
       |
       v
Проверки по правилам
       |
       v
AI-анализ сообщения и контекста
       |
       v
Оценка и объяснение
       |
       v
Рекомендация или передача модераторам
</pre>

=== Shadow Mode ===

На первом этапе Guardian работает в режиме наблюдения.

'''AI не получает право самостоятельно наказывать пользователей.'''

Он формирует предложения, а администрация подтверждает или отклоняет их.

Пример будущей карточки:

<pre>
Возможное нарушение

Пользователь: @username
Категория: оскорбление
Основание: пояснение с учётом контекста
Предлагаемое действие: предупреждение

[Нарушение] [Не нарушение] [Рассмотреть действие]
</pre>

Решения модераторов сохраняются для оценки качества системы.

=== Данные для оценки качества ===

Для рассмотренного случая планируется сохранять:

* исходное сообщение;
* доступный контекст;
* версию правил;
* оценку и объяснение AI;
* решение модератора;
* причину решения;
* фактически выполненное действие.

Сбор таких примеров не означает автоматического обучения модели. Обучение и изменение логики должны быть отдельными проверяемыми процедурами.

=== Полуавтоматическая модерация ===

Автоматические действия возможны только после оценки качества на реальных примерах.

Для каждой категории необходимо определить:

* допустимые действия;
* условия передачи решения человеку;
* ограничения автоматизации;
* порядок отмены;
* журнал действий;
* критерии отключения при ошибках.

Числовая оценка уверенности модели сама по себе не является достаточным основанием для наказания.

=== Репутация пользователей ===

В перспективе система сможет учитывать:

* предупреждения;
* подтверждённые муты и баны;
* повторяемость нарушений;
* отменённые решения;
* периоды без нарушений.

Репутация рассматривается как дополнительный контекст. Она не должна автоматически превращать любое сообщение пользователя в нарушение.

=== Анализ конфликтов ===

Планируется анализ последовательности сообщений нескольких участников.

Цель — обнаруживать развитие конфликта и предлагать своевременное вмешательство модераторов.

Возможные действия:

* рекомендация прекратить спор;
* уведомление администрации;
* передача контекста на рассмотрение.

== Аналитика сообщества ==

На последующих этапах Кузя сможет формировать:

* статистику сообщений;
* число активных участников;
* сведения о новых участниках;
* статистику предупреждений и других действий;
* основные темы обсуждения;
* ежедневные дайджесты.

Пример будущего дайджеста:

<pre>
Итоги дня

Основные обсуждения:
...

Полезные ссылки:
...

Модерация:
...

Вопросы, требующие внимания администрации:
...
</pre>

При формировании отчётов необходимо различать фактическую статистику из БД и выводы AI.

== Знание правил сообщества ==

Планируется включение действующих правил конкретного чата в контекст ответов.

Пример:

<pre>
Кузя, можно здесь публиковать ссылку на YouTube?
</pre>

Ответ должен опираться на правила выбранного сообщества.

Для объяснения модерации желательно указывать:

* применённый пункт правил;
* основание решения;
* источник решения — человек, правило или AI;
* возможность пересмотра администрацией.

== Разделение Кузи и RAMBA Bot ==

Кузя специализируется на Telegram-сообществе:

* участники;
* правила;
* диалоги;
* история;
* модерация;
* аналитика.

Управление серверами и инфраструктурой относится к отдельному '''RAMBA Bot'''.

Целевая схема:

<pre>
Кузя                         RAMBA Bot
 |                               |
 | сообщество                    | инфраструктура
 |                               |
 +---------------+---------------+
                 |
                 v
           RAMBA AI Router
</pre>

Общий AI-бэкенд не означает общие права доступа или смешивание контекста двух ботов.

== Принципы проекта ==

# '''Сохранять существующие функции.''' Завершить и проверить перенос Legacy перед заменой стабильной версии.
# '''Сохранять архив.''' Не терять историю MySQL, предупреждения и связи между данными.
# '''Разделять готовое и запланированное.''' Документировать реализацию, тестирование и развёртывание отдельно.
# '''Сохранять контроль администрации.''' Решения должны быть объяснимыми и доступными для пересмотра.
# '''Вводить автоматизацию постепенно.''' Сначала наблюдение и оценка качества, затем ограниченные действия.
# '''Развивать локальный AI как целевую основу.''' Подключение Router проводить отдельным проверяемым этапом.
# '''Сохранять специализацию Кузи.''' Инфраструктурные задачи выносить в RAMBA Bot.
# '''Фиксировать рабочие этапы.''' Сохранять изменения в Git и обновлять документацию по подтверждённым результатам.

== Конечная цель ==

Кузя должен стать помощником сообщества, который:

* выполняет административные команды;
* помогает участникам;
* находит накопленные знания;
* поддерживает содержательный диалог;
* предлагает модераторам обоснованные решения;
* формирует полезные отчёты;
* оставляет окончательный контроль за администрацией.

'''Ближайшая практическая цель — завершить Kuzya 2.0, подтвердить паритет с Legacy и сохранить существующий архив.'''

[[Категория:RAMBA]]
[[Категория:RAMBA AI]]
[[Категория:Telegram]]
[[Категория:Боты]]