Kuzya 2-0 lost patch

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

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

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

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

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

Версия / ветка	Назначение	Подтверждённое состояние
Legacy Stable	Существующая версия и эталон поведения при переносе	Legacy-код сохранён в репозитории; при проверке ветки `main` и `kuzya-1.0` указывали на коммит `145bc857`
Kuzya 2.0	Новая реализация на aiogram 3	Разрабатывается в `feature/openai-bot-v2`; часть функций перенесена и проверена
Последняя подтверждённая точка 2.0	Перенос команд модерации	Коммит `b5095f4f` от 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.

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

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

Источник: история ветки разработки.

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

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

!свой

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

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

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

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

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

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

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

!предупреждение причина

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

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

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

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

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

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

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

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

Команда	Назначение	Состояние проверки
`!мут 30`	Ограничить отправку сообщений на указанное число минут	Временный мут проверен в тестовом чате
`!размут`	Снять ограничения отправки сообщений	Проверено в тестовом чате
`!бан 60`	Исключить пользователя и запретить возвращение на указанное число минут	Проверен временный бан на одну минуту
`!бан 0`	Постоянный бан	Предусмотрен кодом; отдельный live-тест не зафиксирован

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

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

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

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

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

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

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

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

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

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

b5095f4f — Migrate legacy moderation commands.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Новое предупреждение

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

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

[За мут] [Против]

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

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

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

required_votes = admin_count // 2 + 1

Число администраторов	Необходимо голосов «за»
3	2
4	3
5	3
6	4

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

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

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

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

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

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

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

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

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

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

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

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

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

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

number_of_warnings = 1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Этап	Основная задача	Статус по последней проверке
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

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

chats;
users;
messages;
warnings;
moderation_actions;
admins;
chat_settings.

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

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

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

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

Kuzya 2.2 — RAMBA AI Router

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Kuzya Guardian

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

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

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

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

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

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

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

Shadow Mode

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Итоги дня

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

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

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

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

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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