diff --git a/AUTHORS b/AUTHORS index 99c7efc..39b759d 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,5 +1,5 @@ Руководитель проекта: - - Семён Фомченков (@Armatik), e-mail: armatik@alt-gnome.ru + - Семен Фомченков (@Armatik), e-mail: armatik@alt-gnome.ru Ведущие разработчики: - Максим Слипенко (@Maks1m_S), e-mail: maxim@slipenko.com diff --git a/README.md b/README.md index 6beac59..2de29e9 100644 --- a/README.md +++ b/README.md @@ -2,44 +2,44 @@ ## Что такое «Каркас»? -Каркас — это платформа для разработки модульных Telegram-ботов, которая призвана упростить взаимодействие с чатами. «Каркас» предоставляет возможность расширять функциональность бота с помощью интеграции различных модулей. Код платформы и набор стандартных модулей находятся в этом монорепозитории. +Каркас — это платформа для разработки блочных Telegram-ботов, которая призвана упростить взаимодействие с чатами. «Каркас» предоставляет возможность расширять функциональность бота с помощью интеграции различных блоков. Код платформы и набор стандартных блоков находятся в этом монорепозитории. ## Структура монорепозитория Монорепозиторий Karkas включает в себя: -- **Ядро Karkas (`src/karkas_core`):** Основные компоненты платформы, такие как система управления модулями, логирование и утилиты. -- **Блоки Karkas (`src/karkas_blocks`):** Содержит стандартные и дополнительные модули, которые расширяют функциональность ботов, созданных на платформе «Каркас». +- **Ядро Karkas (`src/karkas_core`):** Основные компоненты платформы, такие как система управления блоками, логирование и утилиты. +- **Блоки Karkas (`src/karkas_blocks`):** Содержит стандартные и дополнительные блоки, которые расширяют функциональность ботов, созданных на платформе «Каркас». - **Бот Gnomик (`src/gnomik`):** Пример реализации бота, созданного на основе платформы «Каркас». -## Модули +## Блоки -Модули Karkas — это независимые компоненты, которые добавляют функциональность бота. +Блоки Karkas — это независимые компоненты, которые добавляют функциональность бота. -### Структура модуля +### Структура блока -Структура модуля представлена [здесь](docs/MODULES-SPEC.md). +Структура блока представлена [здесь](docs/BLOCKS-SPEC.md). -### Стандартные модули +### Стандартные блоки -Стандартные модули предоставляют базовые функции для работы бота +Стандартные блоки предоставляют базовые функции для работы бота -Полный перечень стандартных модулей: +Полный перечень стандартных блоков: -- [`admin`](src/karkas_blocks/karkas_blocks/standard/admin/README.md) — модуль модерирования чата; -- [`roles`](src/karkas_blocks/karkas_blocks/standard/roles/README.md) — модуль управления ролями пользователей; -- [`config`](src/karkas_blocks/karkas_blocks/standard/config/README.md) — модуль управления конфигурацией бота; -- [`database`](src/karkas_blocks/karkas_blocks/standard/database/README.md) — модуль для работы с базой данных; -- [`fsm_database_storage`](src/karkas_blocks/karkas_blocks/standard/fsm_database_storage/README.md) — модуль для хранения состояний FSM в базе данных; -- [`filters`](src/karkas_blocks/karkas_blocks/standard/filters/README.md) — модуль, предоставляющий фильтры для `aiogram`; -- [`message_processing`](src/karkas_blocks/karkas_blocks/standard/message_processing/README.md) — модуль обработки входящих сообщений; -- [`miniapp`](src/karkas_blocks/karkas_blocks/standard/miniapp/README.md) — модуль для реализации веб-интерфейса бота; -- [`command_helper`](src/karkas_blocks/karkas_blocks/standard/command_helper/README.md) — модуль для упрощения регистрации команд бота; -- [`info`](src/karkas_blocks/karkas_blocks/standard/info/README.md) — модуль предоставления информации о пользователях и чатах. +- [`admin`](src/karkas_blocks/karkas_blocks/standard/admin/README.md) — блок модерирования чата; +- [`roles`](src/karkas_blocks/karkas_blocks/standard/roles/README.md) — блок управления ролями пользователей; +- [`config`](src/karkas_blocks/karkas_blocks/standard/config/README.md) — блок управления конфигурацией бота; +- [`database`](src/karkas_blocks/karkas_blocks/standard/database/README.md) — блок для работы с базой данных; +- [`fsm_database_storage`](src/karkas_blocks/karkas_blocks/standard/fsm_database_storage/README.md) — блок для хранения состояний FSM в базе данных; +- [`filters`](src/karkas_blocks/karkas_blocks/standard/filters/README.md) — блок, предоставляющий фильтры для `aiogram`; +- [`message_processing`](src/karkas_blocks/karkas_blocks/standard/message_processing/README.md) — блок обработки входящих сообщений; +- [`miniapp`](src/karkas_blocks/karkas_blocks/standard/miniapp/README.md) — блок для реализации веб-интерфейса бота; +- [`command_helper`](src/karkas_blocks/karkas_blocks/standard/command_helper/README.md) — блок для упрощения регистрации команд бота; +- [`info`](src/karkas_blocks/karkas_blocks/standard/info/README.md) — блок предоставления информации о пользователях и чатах. -### Дополнительные официальные модули +### Дополнительные официальные блоки -Дополнительные официальные модули созданы командой разработки платформы «Каркас» и предоставляют расширенные возможности для бота: +Дополнительные официальные блоки созданы командой разработки платформы «Каркас» и предоставляют расширенные возможности для бота: -- [`yandexgpt`](src/karkas_blocks/karkas_blocks/external/yandexgpt/README.md) — модуль для интеграции с нейросетью YandexGPT; -- [`create_report_apps`](src/karkas_blocks/karkas_blocks/external/create_report_apps/README.md) — модуль для создания отчётов об ошибках. +- [`yandexgpt`](src/karkas_blocks/karkas_blocks/external/yandexgpt/README.md) — блок для интеграции с нейросетью YandexGPT; +- [`create_report_apps`](src/karkas_blocks/karkas_blocks/external/create_report_apps/README.md) — блок для создания отчётов об ошибках. diff --git a/docs/MODULES-SPEC.md b/docs/BLOCKS-SPEC.md similarity index 56% rename from docs/MODULES-SPEC.md rename to docs/BLOCKS-SPEC.md index d8cd5b8..dd99e9d 100644 --- a/docs/MODULES-SPEC.md +++ b/docs/BLOCKS-SPEC.md @@ -1,4 +1,4 @@ -# Спецификация модулей +# Спецификация блоков > **Внимание!** > @@ -6,17 +6,17 @@ > > Могут возникнуть изменения, которые не будут обратно совместимы (breaking changes). -Каждый модуль представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`. +Каждый блок представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`. -## Метаданные модуля (`info.json`) +## Метаданные блока (`info.json`) -Файл `info.json` содержит информацию о модуле в формате JSON. Пример структуры `info.json` приведён ниже: +Файл `info.json` содержит информацию о блоке в формате JSON. Пример структуры `info.json` приведён ниже: ```json { "id": "standard.info", "name": "Info", - "description": "Модуль с информацией", + "description": "Блок с информацией", "author": "Karkas Team", "version": "1.0.0", "privileged": false, @@ -43,22 +43,22 @@ } ``` -| Поле | Описание | -| :-----------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Уникальный идентификатор модуля | -| `name` | Название модуля | -| `description` | Описание функциональности модуля | -| `author` | Автор модуля | -| `version` | Версия модуля в формате [SemVer](https://semver.org/) | -| `privileged` | Является ли модуль привилегированным (булево значение) | -| `dependencies` | Объект, описывающий зависимости модуля от других модулей | -| `dependencies.required` и `dependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — идентификатор модуля, значение — версия или объект `DependencyInfo`. | -| `pythonDependencies` | Объект, описывающий зависимости модуля от внешних Python пакетов. | -| `pythonDependencies.required` и `pythonDependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — название пакета, значение — версия. | +| Поле | Описание | +| :-----------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Уникальный идентификатор блока | +| `name` | Название блока | +| `description` | Описание функциональности блока | +| `author` | Автор блока | +| `version` | Версия блока в формате [SemVer](https://semver.org/) | +| `privileged` | Является ли блок привилегированным (булево значение) | +| `dependencies` | Объект, описывающий зависимости блока от других блоков | +| `dependencies.required` и `dependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — идентификатор блока, значение — версия или объект `DependencyInfo`. | +| `pythonDependencies` | Объект, описывающий зависимости блока от внешних Python пакетов. | +| `pythonDependencies.required` и `pythonDependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — название пакета, значение — версия. | ### DependencyInfo -Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов модуля (`uses`). Если `uses` не указан, то доступ к модулю целиком запрещён. Пример объекта `DependencyInfo`: +Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов блока (`uses`). Если `uses` не указан, то доступ к блоку целиком запрещён. Пример объекта `DependencyInfo`: ```json { @@ -67,39 +67,39 @@ } ``` -| Поле | Описание | -| :-------: | ------------------------------------ | -| `version` | Версия модуля | -| `uses` | Список используемых атрибутов модуля | +| Поле | Описание | +| :-------: | ----------------------------------- | +| `version` | Версия блока | +| `uses` | Список используемых атрибутов блока | -## Режимы работы модулей +## Режимы работы блоков ### Непривилегированный режим (`privileged: false`) -- Модуль выполняется в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений; -- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`, а также несколько стандартных модулей, необходимых для работы; +- Исполнение блока происходит в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений; +- Может импортировать только явно разрешенные блоки, указанные в `pythonDependencies`, а также несколько стандартных блоков, необходимых для работы; - Имеет доступ к пакету `karkas_core.modules_system.public_api` для взаимодействия с ботом. ### Привилегированный режим (`privileged: true`) -- Модуль выполняется без ограничений; +- Блок исполняется без ограничений; - Имеет полный доступ ко всем пакетам, доступным в окружении; -- Должен использоваться с осторожностью и только для модулей, требующих расширенных прав. +- Должен использоваться с осторожностью и только для блоков, требующих расширенных прав. -## Жизненный цикл модуля +## Жизненный цикл блока 1. Загрузка метаданных из `info.json`; 2. Проверка зависимостей: - Проверка всех обязательных зависимостей; - Проверка совместимости версий зависимостей; - Проверка зависимостей Python; -3. Загрузка кода модуля из `__init__.py`; +3. Загрузка кода блока из `__init__.py`; 4. Вызов функции `module_init`, если она есть; -5. После загрузки всех модулей вызывается функция `module_late_init`, если она есть. +5. После загрузки всех блоков вызывается функция `module_late_init`, если она есть. -## Межмодульное взаимодейтвие +## Межблочное взаимодейтвие -Для взаимодействия друг с другом описан [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py), -предоставляемое системой управления модулями. +Для блоков взаимодействия друг с другом описан [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py), +предоставляемое системой управления блоками. -Например, можно использовать функцию `get_module` для получения модуля или предоставляемых им объекты по идентификатору. +Например, можно использовать функцию `get_module` для получения блока или предоставляемых им объекты по идентификатору. diff --git a/src/altlinux/README.md b/src/altlinux/README.md index 1500d10..98cc3e2 100644 --- a/src/altlinux/README.md +++ b/src/altlinux/README.md @@ -6,7 +6,7 @@ ## Функционал -Список модулей, используемых в боте: +Список блоков, используемых в боте: - `report` — вызов администрации чата одной командой; - `welcome` — автоматическая вариативная проверка пользователей на признаки бота или другой рекламной системы; @@ -28,7 +28,7 @@ docker build -t altlinux -f Dockerfile ../.. docker run -v ./config.yaml:/app/config.yaml altlinux ``` -Замените `./config.yaml` на путь к вашему локальному файлу конфигурации. +Замените `./config.yaml` на путь к локальному файлу конфигурации. ### Вручную @@ -50,6 +50,6 @@ python -m altlinux Пример конфигурации бота находится в файле [`config-example.yaml`](./config-example.yaml). -## Модули +## Блоки -Список загружаемых модулей указан в файле [`__main__.py`](./altlinux/__main__.py). +Список загружаемых блоков указан в файле [`__main__.py`](./altlinux/__main__.py). diff --git a/src/karkas_blocks/README.md b/src/karkas_blocks/README.md index caf1698..c4da55a 100644 --- a/src/karkas_blocks/README.md +++ b/src/karkas_blocks/README.md @@ -1,8 +1,10 @@ # Блоки Karkas -Блоки Karkas — это набор «блоков» (модулей) для платформы «Каркас», которые добавляют функциональность ботам. +Блоки Karkas — это набор блоков для платформы «Каркас», которые добавляют функциональность ботам. ## Типы блоков -- **Стандартные (`standard`)** — блоки, содержащие основной функционал: управление пользователями, ролями и настройками; -- **Дополнительные (`external`)** — блоки, созданные командой разработки платформы «Каркас». Предоставляют расширенные возможности: интеграция с нейросетями, внешними сервисами и API. +| Тип | Описание | +| :-------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| Стандартные (`standard`) | Блоки, содержащие основной функционал: управление пользователями, ролями и настройками | +| Дополнительные (`external`) | Блоки, созданные командой разработки платформы «Каркас». Предоставляют расширенные возможности: интеграция с нейросетями, внешними сервисами и API | diff --git a/src/karkas_blocks/karkas_blocks/standard/command_helper/README.md b/src/karkas_blocks/karkas_blocks/standard/command_helper/README.md index 0146b40..f70100a 100644 --- a/src/karkas_blocks/karkas_blocks/standard/command_helper/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/command_helper/README.md @@ -1,6 +1,6 @@ -# Модуль Command Helper +# Блок Command Helper -Данный для упрощения регистрации команд бота и управления ими. +Данный блок упрощает регистрации команд бота и управления ими. ## Функциональность diff --git a/src/karkas_blocks/karkas_blocks/standard/config/README.md b/src/karkas_blocks/karkas_blocks/standard/config/README.md index a13f13f..c7b0c96 100644 --- a/src/karkas_blocks/karkas_blocks/standard/config/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/config/README.md @@ -1,6 +1,6 @@ -# Модуль Config +# Блок Config -Данный модуль позволяет управляет конфигурацией бота. +Данный блок позволяет управляет конфигурацией бота. ## Функциональность diff --git a/src/karkas_blocks/karkas_blocks/standard/filters/README.md b/src/karkas_blocks/karkas_blocks/standard/filters/README.md index 6a27e23..6e3f8a0 100644 --- a/src/karkas_blocks/karkas_blocks/standard/filters/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/filters/README.md @@ -1,12 +1,14 @@ -# Модуль Filters +# Блок Filters -Данный модуль предоставляет фильтры для `aiogram`, которые используются для ограничения доступа к командам +Данный блок предоставляет фильтры для `aiogram`, которые используются для ограничения доступа к командам и обработчикам событий. ## Фильтры -- `ChatModerOrAdminFilter` — пропускает сообщения только от модераторов и администраторов чата; -- `ChatNotInApproveFilter` — пропускает сообщения только из чатов, не входящих в список разрешенных. +| Фильтр | Описание | +| :----------------------: | ---------------------------------------------------------------------- | +| `ChatModerOrAdminFilter` | Пропускает сообщения только от модераторов и администраторов чата | +| `ChatNotInApproveFilter` | Пропускает сообщения только из чатов, не входящих в список разрешенных | ## Использование diff --git a/src/karkas_blocks/karkas_blocks/standard/report/README.md b/src/karkas_blocks/karkas_blocks/standard/report/README.md index 4788f04..703b841 100644 --- a/src/karkas_blocks/karkas_blocks/standard/report/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/report/README.md @@ -1,14 +1,16 @@ -# Модуль Report +# Блок Report -Данный модуль даёт пользователям возможность сообщать о спам-сообщениях в чате. +Данный блок даёт пользователям возможность сообщать о спам-сообщениях в чате. ## Команды -- `/report` — сообщить администраторам о сообщении как о спаме. +| Команда | Описание | +| :-------: | ------------------------------------------------ | +| `/report` | Сообщить администраторам о сообщении как о спаме | ## Использование -Чтобы указать, что сообщении является спамом, ответьте на него, использовав команду `/report`. Модуль уведомит администраторов, которые имеют права модерации. +Чтобы указать, что сообщении является спамом, ответьте на него, использовав команду `/report`. Блок уведомит администраторов, которые имеют права модерации. ### Пример использования diff --git a/src/karkas_blocks/karkas_blocks/standard/welcome/README.md b/src/karkas_blocks/karkas_blocks/standard/welcome/README.md index b4f9ee1..c4da55a 100644 --- a/src/karkas_blocks/karkas_blocks/standard/welcome/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/welcome/README.md @@ -1,22 +1,10 @@ -## Модуль Welcome +# Блоки Karkas -Данный модуль отвечает за верификацию новых участников чата, используя различные методы проверки. Он помогает предотвратить спам и автоматические атаки на чат, поддтверждая «человечность» новых пользователей. +Блоки Karkas — это набор блоков для платформы «Каркас», которые добавляют функциональность ботам. -## Функциональность +## Типы блоков -Модуль поддерживает несколько методов верификации, которые случайным образом применяются к новым участникам чата: - -- `IAmHumanButton` — верификация с помощью кнопки; -- `IAmHumanInput` — верификация с помощью ввода текста; -- `MathButtonsVerification` — верификация решением математической задачи с помощью кнопок; -- `MathInputVerificationMethod` — верификация решением математической задачи с помощью ввода; -- `QuestionButtonsVerification` — Верификация ответом на вопрос с помощью кнопок; -- `QuestionInputVerification` — верификация ответом на вопрос с помощью ввода. - -## Использование - -1. **Обработка новых участников**: когда новый участник присоединяется к чату, выбирается случайный метод верификации и создаётся задача проверки; -2. **Верификация**: - - **Верификация с помощью кнопок**: обработчик ожидает нажатия кнопки от пользователя и проверяет ответ; - - **Верификация с помощью ввода текста**: обработчик проверять введённый текст и проверяет ответ. -3. **Время на проверку**: если новый участник не проходит проверку в течение 30 секунд, его статус в чате меняется на "забанен". +| Тип | Описание | +| :-------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| Стандартные (`standard`) | Блоки, содержащие основной функционал: управление пользователями, ролями и настройками | +| Дополнительные (`external`) | Блоки, созданные командой разработки платформы «Каркас». Предоставляют расширенные возможности: интеграция с нейросетями, внешними сервисами и API | diff --git a/src/karkas_core/README.md b/src/karkas_core/README.md index 07cf930..823d16a 100644 --- a/src/karkas_core/README.md +++ b/src/karkas_core/README.md @@ -1,7 +1,7 @@ # Ядро Karkas -Ядро Karkas — базовые компоненты платформы «Каркас»: система управления модулями, логирование и утилиты. +Ядро Karkas — базовые компоненты платформы «Каркас»: система управления блоками, логирование и утилиты. -- **Система управления модулями** — отвечает за их загрузку, проверку зависимостей и предоставление API для межмодульного взаимодействия; -- **Модуль логирования** — предоставляет функции для записи логов в консоль; -- **Модуль утилит** — содержит вспомогательные функции, например, для форматирования текста. +- **Система управления блоками** — отвечает за их загрузку, проверку зависимостей и предоставление API для межблочного взаимодействия; +- **Блок логирования** — предоставляет функции для записи логов в консоль; +- **Блок утилит** — содержит вспомогательные функции, например, для форматирования текста.