From 5f5e851ecd3a18a91d3493889dc66bcf6180d159 Mon Sep 17 00:00:00 2001 From: x1z53 Date: Sun, 25 Aug 2024 14:52:07 +0300 Subject: [PATCH] =?UTF-8?q?=D0=A0=D0=B5=D1=84=D0=B0=D0=BA=D1=82=D0=BE?= =?UTF-8?q?=D1=80=D0=B8=D0=BD=D0=B3=20=D1=84=D0=B0=D0=B9=D0=BB=D0=BE=D0=B2?= =?UTF-8?q?=20`README.md`=20=D0=B8=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5?= =?UTF-8?q?=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTORS | 8 -- README.md | 61 +++++----- docs/BLOCKS-SPEC.md | 105 +++++++++++++++++ docs/DEV.md | 49 ++++---- docs/MODULES-SPEC.md | 107 ------------------ src/altlinux/README.md | 57 ++++++---- src/gnomik/README.md | 57 +++++----- src/karkas_blocks/README.md | 16 ++- .../external/create_report_apps/README.md | 20 ++-- .../external/yandexgpt/README.md | 24 ++-- .../karkas_blocks/standard/admin/README.md | 20 ++-- .../standard/command_helper/README.md | 11 +- .../karkas_blocks/standard/config/README.md | 14 +-- .../karkas_blocks/standard/filters/README.md | 10 +- .../standard/fsm_database_storage/README.md | 10 +- .../karkas_blocks/standard/info/README.md | 19 ++-- .../karkas_blocks/standard/miniapp/README.md | 10 +- .../karkas_blocks/standard/report/README.md | 16 +-- .../karkas_blocks/standard/roles/README.md | 22 ++-- .../karkas_blocks/standard/welcome/README.md | 33 +++--- src/karkas_core/README.md | 26 +---- 21 files changed, 349 insertions(+), 346 deletions(-) delete mode 100644 CONTRIBUTORS create mode 100644 docs/BLOCKS-SPEC.md delete mode 100644 docs/MODULES-SPEC.md diff --git a/CONTRIBUTORS b/CONTRIBUTORS deleted file mode 100644 index 39b759d..0000000 --- a/CONTRIBUTORS +++ /dev/null @@ -1,8 +0,0 @@ -Руководитель проекта: - - Семен Фомченков (@Armatik), e-mail: armatik@alt-gnome.ru - -Ведущие разработчики: - - Максим Слипенко (@Maks1m_S), e-mail: maxim@slipenko.com - -Участники проекта: - - Илья Женецкий (@ilyazheprog) diff --git a/README.md b/README.md index ffa7e91..2de29e9 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,45 @@ -# Karkas +# Каркас -## Что такое Karkas? +## Что такое «Каркас»? -Karkas - это платформа для разработки модульных Telegram-ботов, которая призвана упростить взаимодействие с чатами. -Karkas предоставляет возможность расширять функциональность бота с помощью интеграции различных модулей. -Код платформы и набор стандартных модулей находятся в этом монорепозитории. +Каркас — это платформа для разработки блочных Telegram-ботов, которая призвана упростить взаимодействие с чатами. «Каркас» предоставляет возможность расширять функциональность бота с помощью интеграции различных блоков. Код платформы и набор стандартных блоков находятся в этом монорепозитории. ## Структура монорепозитория Монорепозиторий Karkas включает в себя: -* **Ядро Karkas (src/karkas_core):** Содержит основные компоненты платформы, такие как система управления модулями, - логирование и утилиты. -* **Модули Karkas (src/karkas_blocks):** Содержит стандартные и дополнительные модули, которые расширяют - функциональность ботов Karkas. -* **Пример бота (src/gnomik):** Пример реализации бота на платформе Karkas. -## Модули +- **Ядро 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) - модуль предоставления информации о пользователях и чатах. +### Стандартные блоки -### Дополнительные официальные модули +Стандартные блоки предоставляют базовые функции для работы бота -Дополнительные официальные модули разработаны командой Karkas и предоставляют расширенные возможности для бота: -* [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) - модуль для создания отчетов об ошибках. +Полный перечень стандартных блоков: + +- [`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) — блок для создания отчётов об ошибках. diff --git a/docs/BLOCKS-SPEC.md b/docs/BLOCKS-SPEC.md new file mode 100644 index 0000000..dd99e9d --- /dev/null +++ b/docs/BLOCKS-SPEC.md @@ -0,0 +1,105 @@ +# Спецификация блоков + +> **Внимание!** +> +> Данная спецификация ещё не закончена и активно разрабатывается. +> +> Могут возникнуть изменения, которые не будут обратно совместимы (breaking changes). + +Каждый блок представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`. + +## Метаданные блока (`info.json`) + +Файл `info.json` содержит информацию о блоке в формате JSON. Пример структуры `info.json` приведён ниже: + +```json +{ + "id": "standard.info", + "name": "Info", + "description": "Блок с информацией", + "author": "Karkas Team", + "version": "1.0.0", + "privileged": false, + "dependencies": { + "required": { + "standard.roles": "^1.0.0", + "standard.database": { + "version": "^1.0.0", + "uses": ["db_api"] + } + }, + "optional": { + "external.yandexgpt": "*" + } + }, + "pythonDependencies": { + "required": { + "some_package": "^1.2.3" + }, + "optional": { + "another_package": "*" + } + } +} +``` + +| Поле | Описание | +| :-----------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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`: + +```json +{ + "version": "^1.0.0", + "uses": ["db_api"] +} +``` + +| Поле | Описание | +| :-------: | ----------------------------------- | +| `version` | Версия блока | +| `uses` | Список используемых атрибутов блока | + +## Режимы работы блоков + +### Непривилегированный режим (`privileged: false`) + +- Исполнение блока происходит в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений; +- Может импортировать только явно разрешенные блоки, указанные в `pythonDependencies`, а также несколько стандартных блоков, необходимых для работы; +- Имеет доступ к пакету `karkas_core.modules_system.public_api` для взаимодействия с ботом. + +### Привилегированный режим (`privileged: true`) + +- Блок исполняется без ограничений; +- Имеет полный доступ ко всем пакетам, доступным в окружении; +- Должен использоваться с осторожностью и только для блоков, требующих расширенных прав. + +## Жизненный цикл блока + +1. Загрузка метаданных из `info.json`; +2. Проверка зависимостей: + - Проверка всех обязательных зависимостей; + - Проверка совместимости версий зависимостей; + - Проверка зависимостей Python; +3. Загрузка кода блока из `__init__.py`; +4. Вызов функции `module_init`, если она есть; +5. После загрузки всех блоков вызывается функция `module_late_init`, если она есть. + +## Межблочное взаимодейтвие + +Для блоков взаимодействия друг с другом описан [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py), +предоставляемое системой управления блоками. + +Например, можно использовать функцию `get_module` для получения блока или предоставляемых им объекты по идентификатору. diff --git a/docs/DEV.md b/docs/DEV.md index 9db59a5..37f92d2 100644 --- a/docs/DEV.md +++ b/docs/DEV.md @@ -1,39 +1,34 @@ -## Настройка рабочего окружения +# Настройка рабочего окружения Данная инструкция поможет вам настроить рабочее окружение для разработки Karkas. -### Предварительные требования +## Предварительные требования -* **Python 3.12:** Karkas требует Python 3.12. -* **VSCode:** Рекомендуется использовать VSCode для разработки. -* **Git:** У вас должен быть установлен Git для клонирования репозитория. +- **Python** — платформа «Каркас» требует интерпретатор языка Python версии 3.12; +- **VSCode** — рекомендованная среда разработки; +- **Git** — инструмент контроля версий, необходим клонирования репозиториянео. -### Шаги +## Шаги -1. **Клонируйте репозиторий:** - ```bash - git clone https://gitflic.ru/project/alt-gnome/karkas.git - ``` +1. Клонируйте репозиторий с помощью утилиты `git`: -2. **Откройте проект в VSCode:** - * Откройте папку `karkas` в VSCode. - * VSCode автоматически предложит открыть проект как workspace, используя файл `karkas.code-workspace`. - Нажмите "Открыть Workspace", чтобы принять предложение. +```shell +git clone https://gitflic.ru/project/alt-gnome/karkas.git +``` -3. **Настройте Poetry:** - * Установите Poetry, следуя инструкциям на официальном сайте: [https://python-poetry.org/docs/](https://python-poetry.org/docs/). - * **Для каждого пакета:** - * Перейдите в папку пакета (например, `src/karkas_core`). - * Выполните команду `poetry install`, чтобы установить зависимости пакета. - * Poetry создаст виртуальное окружение внутри папки пакета (`.venv`). +2. Откройте папку `karkas` в VSCode. Среда разработки автоматически предложит открыть проект как Workspace, используя файл `karkas.code-workspace`. Нажмите `Открыть Workspace`, чтобы принять предложение; -4. **Активируйте виртуальное окружение:** - * Выполните команду `poetry shell` в папке пакета, чтобы активировать виртуальное окружение. +3. Установите инструмент Poetry, следуя инструкциям из [официальной документации](https://python-poetry.org/docs/). Для каждого пакета выполните следующую последовательность действий: -Теперь ваше рабочее окружение настроено, и вы можете начать. + - Перейдите в папку пакета (например, `src/karkas_core`); + - Выполните команду `poetry install`, чтобы установить зависимости пакета. После этого будет создано виртуальное окружене (`.venv`); -### Дополнительная информация +4. Выполните команду `poetry shell` в папке пакета, над которым будут производится работы, чтобы активировать виртуальное окружение. -* Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости. -* Poetry автоматически управляет виртуальными окружениями для каждого пакета. -* Вы можете использовать команду `poetry add ` для добавления новых зависимостей. +Теперь рабочее окружение настроено! + +## Дополнительная информация + +- Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости; +- Poetry автоматически управляет виртуальными окружениями для каждого пакета; +- Вы можете использовать команду `poetry add ` (где `` — имя пакета) для добавления новых зависимостей. diff --git a/docs/MODULES-SPEC.md b/docs/MODULES-SPEC.md deleted file mode 100644 index 3445dd3..0000000 --- a/docs/MODULES-SPEC.md +++ /dev/null @@ -1,107 +0,0 @@ -# Спецификация модулей - -> **Внимание!** -> -> Данная спецификация еще не закончена и активно разрабатывается. -> Могут быть значительные изменения (breaking changes). - -Каждый модуль представлен в виде папки, содержащей два обязательных файла: info.json и `__init__.py`. - -## Метаинформация о модуле (info.json) - -Этот файл содержит метаинформацию о модуле в формате JSON. Пример структуры info.json приведен ниже: - -```json -{ - "id": "standard.info", - "name": "Info", - "description": "Модуль с информацией", - "author": "Karkas Team", - "version": "1.0.0", - "privileged": false, - "dependencies": { - "required": { - "standard.roles": "^1.0.0", - "standard.database": { - "version": "^1.0.0", - "uses": [ - "db_api" - ] - } - }, - "optional": { - "external.yandexgpt": "*" - } - }, - "pythonDependencies": { - "required": { - "some_package": "^1.2.3" - }, - "optional": { - "another_package": "*" - } - } -} -``` - -- `id`: Уникальный идентификатор модуля. -- `name`: Название модуля. -- `description`: Описание функциональности модуля. -- `author`: Автор модуля. -- `version`: Версия модуля в формате [SemVer](https://semver.org/). -- `privileged`: Булево значение, указывающее, является ли модуль привилегированным. -- `dependencies`: Объект, описывающий зависимости модуля от других **Karkas** модулей. - - `required`: Обязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`. - - `optional`: Необязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`. -- `pythonDependencies`: Объект, описывающий зависимости модуля от внешних Python пакетов. - - `required`: Обязательные зависимости. Ключ - название пакета, значение - версия. - - `optional`: Необязательные зависимости. Ключ - название пакета, значение - версия. - -### DependencyInfo - -Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список разрешенных к использованию -атрибутов модуля (`uses`). Если `uses` не указан, то доступ к модулю целиком запрещен. - -```json -{ - "version": "^1.0.0", - "uses": [ - "db_api" - ] -} -``` - -- `version`: Версия модуля. -- `uses`: Список разрешенных атрибутов модуля. - -## Режимы выполнения модулей - -**Непривилегированный режим** (`privileged: false`): -- Модуль выполняется в доверенной среде на основе RestrictedPython (это накладывает ряд ограничений). -- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`, - а также несколько стандартных модулей, необходимых для работы. -- Имеет доступ к пакету `karkas_core.modules_system.public_api` для взаимодействия с ботом. - -**Привилегированный режим** (`privileged: true`): -- Модуль выполняется без ограничений. -- Имеет полный доступ ко всем пакетам, доступным в окружении. -- Должен использоваться с осторожностью и только для модулей, требующих расширенных прав. - -## Жизненный цикл модуля - -1. Загрузка метаданных из `info.json`. -2. Проверка зависимостей: - - Проверяется наличие всех обязательных зависимостей. - - Проверяется совместимость версий зависимостей. - - Проверяется наличие Python зависимостей. -3. Загрузка кода модуля из `__init__.py`. -4. Вызов функции `module_init` (если она есть). -5. После загрузки всех модулей вызывается функция `module_late_init` (если она есть). - -## Взаимодействие между модулями - -Модули могут взаимодействовать друг с другом через [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py), -предоставляемое системой управления модулями. - -Например, есть функция `get_module`. Она позволяет получить модуль или предоставляемые им объекты по его -идентификатору. diff --git a/src/altlinux/README.md b/src/altlinux/README.md index 8bee95a..98cc3e2 100644 --- a/src/altlinux/README.md +++ b/src/altlinux/README.md @@ -2,45 +2,54 @@ ## Описание -Подготовленная версия Karkas Lite для интеграции в чат [Альт Линукс](https://t.me/alt_linux) +Бот, созданный на основе платформы «Каркас» и подготовленный для интеграции в чат [Альт Линукс](https://t.me/alt_linux) ## Функционал -Список OCAB-модулей используемых в боте: -* report - Вызов администрации чата одной командой -* welcome - Автоматическая вариативная проверка пользователей на признаки бота или другой автоматической рекламной системы -* help - Получение информации об Karkas Lite +Список блоков, используемых в боте: + +- `report` — вызов администрации чата одной командой; +- `welcome` — автоматическая вариативная проверка пользователей на признаки бота или другой рекламной системы; +- `help` — получение справки о боте. ## Запуск -### Docker +### Через Docker образ + +1. Соберите Docker образ: + +```shell +docker build -t altlinux -f Dockerfile ../.. +``` -1. Соберите Docker-образ: - ```bash - docker build -t gnomik . - ``` 2. Запустите контейнер: - ```bash - docker run -p 9000:9000 -v ./config.yaml:/app/config.yaml -v ./database:/app/database gnomik - ``` - Замените `./config.yaml` и `./database` на пути к вашим локальным файлам конфигурации и паки для базы данных. +```shell +docker run -v ./config.yaml:/app/config.yaml altlinux +``` + +Замените `./config.yaml` на путь к локальному файлу конфигурации. ### Вручную -1. Активируйте виртуальное окружение Gnomика: - ```bash - poetry shell - ``` +1. Активируйте виртуальное окружение: + +```shell +poetry shell +``` + 2. Запустите бота: - ```bash - python -m gnomik - ``` + +```shell +python -m altlinux +``` ## Конфигурация -Конфигурация бота находится в файле `config.yaml`. +Конфигурация хранится в файле `config.yaml`. -## Модули +Пример конфигурации бота находится в файле [`config-example.yaml`](./config-example.yaml). -Список загружаемых модулей указан в файле `__main__.py`. +## Блоки + +Список загружаемых блоков указан в файле [`__main__.py`](./altlinux/__main__.py). diff --git a/src/gnomik/README.md b/src/gnomik/README.md index 91b66de..5881925 100644 --- a/src/gnomik/README.md +++ b/src/gnomik/README.md @@ -2,17 +2,16 @@ ![Логотип](./docs/gnomik.jpg) -Чат-бот помощник в [ALT Gnome Chat](https://t.me/alt_gnome_chat). +Gnomик — это чат-бот для [ALT Gnome Chat](https://t.me/alt_gnome_chat), созданный на основе платформы «Каркас». Он предоставляет различные функции и возможности, помогающие членам сообщества ALT Gnome. - -ALT Regular Gnome Community - открытое сообщество пользователей операционной системы ALT Regular Gnome. - -- [Канал](https://t.me/alt_gnome) -- [Wiki](https://alt-gnome.wiki) - -## Описание - -Gnomик - это чат-бот для Telegram, разработанный на платформе Karkas. Он предоставляет различные функции и возможности, помогающие пользователям операционной системы ALT Regular Gnome. +> ALT Gnome — открытое сообщество пользователей операционной системы ALT Regular Gnome. Платформы ALT Gnome: +> +> - [Wiki](https://alt-gnome.wiki) +> - [Telegram-канал](https://t.me/alt_gnome) +> - [Вконтакте](https://vk.com/alt_gnome) +> - [Rutube](https://rutube.ru/channel/32425669/) +> - [Платформа](https://plvideo.ru/@alt_gnome) +> - [Boosty](https://boosty.to/alt_gnome) ## Функционал @@ -25,31 +24,37 @@ TODO: описать функционал ### Docker 1. Соберите Docker-образ: - ```bash - docker build -t gnomik . - ``` -2. Запустите контейнер: - ```bash - docker run -p 9000:9000 -v ./config.yaml:/app/config.yaml -v ./database:/app/database gnomik - ``` - Замените `./config.yaml` и `./database` на пути к вашим локальным файлам конфигурации и паки для базы данных. +```shell +docker build -t gnomik . +``` + +2. Запустите контейнер: + +```shell +docker run -p 9000:9000 -v ./config.yaml:/app/config.yaml -v ./database:/app/database gnomik +``` + +Замените `./config.yaml` и `./database` на пути к локальным файлам конфигурации и пакам для базы данных. ### Вручную 1. Активируйте виртуальное окружение Gnomика: - ```bash - poetry shell - ``` + +```shell +poetry shell +``` + 2. Запустите бота: - ```bash - python -m gnomik - ``` + +```shell +python -m gnomik +``` ## Конфигурация Конфигурация бота находится в файле `config.yaml`. -## Модули +## Блоки -Список загружаемых модулей указан в файле `__main__.py`. +Список загружаемых блоков указан в файле `__main__.py`. diff --git a/src/karkas_blocks/README.md b/src/karkas_blocks/README.md index a9de353..c4da55a 100644 --- a/src/karkas_blocks/README.md +++ b/src/karkas_blocks/README.md @@ -1,12 +1,10 @@ -# Karkas Blocks +# Блоки Karkas -Karkas Blocks содержит набор модулей для платформы Open Chat AI Bot (Karkas). +Блоки Karkas — это набор блоков для платформы «Каркас», которые добавляют функциональность ботам. -## Описание +## Типы блоков -Karkas - это платформа для создания чат-ботов Telegram. Модули - это расширения, которые добавляют функциональность ботам Karkas. - -## Типы модулей - -* **Стандартные модули (standard.*):** Предоставляют основные функции, такие как управление пользователями, ролями и настройками. -* **Дополнительные официальные модули (external.*):** Разработаны командой Karkas и предоставляют расширенные возможности, такие как интеграция с нейросетями, внешними сервисами и API. +| Тип | Описание | +| :-------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| Стандартные (`standard`) | Блоки, содержащие основной функционал: управление пользователями, ролями и настройками | +| Дополнительные (`external`) | Блоки, созданные командой разработки платформы «Каркас». Предоставляют расширенные возможности: интеграция с нейросетями, внешними сервисами и API | diff --git a/src/karkas_blocks/karkas_blocks/external/create_report_apps/README.md b/src/karkas_blocks/karkas_blocks/external/create_report_apps/README.md index 695b347..132e486 100644 --- a/src/karkas_blocks/karkas_blocks/external/create_report_apps/README.md +++ b/src/karkas_blocks/karkas_blocks/external/create_report_apps/README.md @@ -1,19 +1,21 @@ -# Модуль Create Report Apps +# Блок Create Report Apps -Модуль `create_report_apps` предназначен для помощи пользователям в создании отчетов об ошибках в приложениях. +Данный блок предназначен для помощи пользователям в создании отчётов об ошибках в приложениях. ## Функциональность -- Задает пользователю ряд вопросов, необходимых для составления отчета. -- Собирает информацию о системе пользователя. -- Формирует отчет в текстовом формате. +- Задаёт пользователю ряд вопросов, необходимых для составления отчёта; +- Собирает информацию о системе пользователя; +- Формирует отчёт в текстовом формате. ## Команды -- `/create_report_apps` - запустить процесс создания отчета. +| Команда | Описание | +| :-------------------: | --------------- | +| `/create_report_apps` | Создание отчёта | ## Использование -1. Отправьте команду `/create_report_apps` боту в личных сообщениях или в групповом чате. -2. Ответьте на вопросы бота. -3. Бот сформирует отчет и отправит его вам. +1. Отправьте команду `/create_report_apps` боту личным сообщением или в групповом чате; +2. Ответьте на вопросы бота; +3. Бот сформирует отчёт и отправит его. diff --git a/src/karkas_blocks/karkas_blocks/external/yandexgpt/README.md b/src/karkas_blocks/karkas_blocks/external/yandexgpt/README.md index 8816567..eeeb205 100644 --- a/src/karkas_blocks/karkas_blocks/external/yandexgpt/README.md +++ b/src/karkas_blocks/karkas_blocks/external/yandexgpt/README.md @@ -1,22 +1,24 @@ -# Модуль YandexGPT +# Блок YandexGPT -Модуль `yandexgpt` интегрирует в бота OCAB нейросеть YandexGPT. +Данный блок интегрирует в бота нейросеть YandexGPT. ## Функциональность -- Позволяет боту отвечать на сообщения пользователей, используя YandexGPT. +- Позволяет боту отвечать на сообщения пользователей, используя YandexGPT; - Строит линию контекста для нейросети, используя историю сообщений. ## Конфигурация -- `yandexgpt::token` - API-ключ для доступа к YandexGPT. -- `yandexgpt::catalogid` - идентификатор каталога YandexGPT. -- `yandexgpt::prompt` - системная подсказка для YandexGPT. -- `yandexgpt::startword` - слова, с которых должно начинаться сообщение, чтобы бот ответил. -- `yandexgpt::inword` - слова, которые должны быть в сообщении, чтобы бот ответил. +| Параметр | Описание | +| :--------------------: | --------------------------------------------------------------- | +| `yandexgpt::token` | API-ключ для доступа к YandexGPT | +| `yandexgpt::catalogid` | Идентификатор каталога YandexGPT | +| `yandexgpt::prompt` | Системная подсказка для YandexGPT | +| `yandexgpt::startword` | Слова, с которых должно начинаться сообщение, чтобы бот ответил | +| `yandexgpt::inword` | Слова, которые должны быть в сообщении, чтобы бот ответил | ## Использование -1. Настройте конфигурационные параметры модуля. -2. Отправьте боту сообщение, которое соответствует условиям, указанным в параметрах `startword` и `inword`. -3. Бот ответит на сообщение, используя YandexGPT. +1. Настройте конфигурационные параметры блока; +2. Отправьте боту сообщение, начинающееся со слов или содержащее слова, указанные в параметрах `startword` и `inword` соответственно; +3. Бот ответит на сообщение, генерируя текст с помощью YandexGPT. diff --git a/src/karkas_blocks/karkas_blocks/standard/admin/README.md b/src/karkas_blocks/karkas_blocks/standard/admin/README.md index bb00f2a..415abee 100644 --- a/src/karkas_blocks/karkas_blocks/standard/admin/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/admin/README.md @@ -1,20 +1,26 @@ -# Модуль Admin +# Блок Admin -Модуль `admin` предоставляет администраторам и модераторам чата инструменты для управления: +Данный блок предоставляет администраторам и модераторам чата инструменты для управления. ## Функциональность -- Удаление сообщений. +- Удаление сообщений; - Получение ID чата. ## Команды -- `/rm` - удалить сообщение, на которое отвечает команда. -- `/chatID` - получить ID текущего чата. +| Команда | Описание | +| :-------: | --------------------------------------------------------- | +| `/rm` | Удаление сообщения, ответом на которое отправлена команда | +| `/chatID` | Получение ID текущего чата | ## Использование -1. Ответьте на сообщение, которое нужно удалить. +Удаление сообщений: + +1. Ответьте на сообщение, которое нужно удалить; 2. Отправьте команду `/rm`. -Чтобы получить ID чата, отправьте команду `/chatID`. +Получение ID чата: + +1. Отправьте команду `/chatID` 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 97a614f..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,17 +1,16 @@ -# Модуль Command Helper +# Блок Command Helper -Модуль `command_helper` упрощает регистрацию команд бота и управление ими. +Данный блок упрощает регистрации команд бота и управления ими. ## Функциональность -- Регистрация команд бота. +- Регистрация команд бота; - Установка команд для пользователей в зависимости от их роли. ## Использование -1. Импортируйте функцию `register_command`. -2. Вызовите функцию `register_command`, передав ей название команды, ее описание и роль пользователя, - которому доступна эта команда. +1. Импортируйте функцию `register_command`; +2. Вызовите функцию `register_command`, передав ей название команды, её описание и роль пользователей, которым доступна она будет доступна. ## Пример diff --git a/src/karkas_blocks/karkas_blocks/standard/config/README.md b/src/karkas_blocks/karkas_blocks/standard/config/README.md index 9094efe..c7b0c96 100644 --- a/src/karkas_blocks/karkas_blocks/standard/config/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/config/README.md @@ -1,18 +1,18 @@ -# Модуль Config +# Блок Config -Модуль `config` управляет конфигурацией бота. +Данный блок позволяет управляет конфигурацией бота. ## Функциональность -- Загрузка конфигурации из файла `config.yaml`. -- Сохранение конфигурации в файл. -- Регистрация параметров конфигурации. +- Загрузка конфигурации из файла `config.yaml`; +- Сохранение конфигурации в файл; +- Регистрация параметров конфигурации; - Получение значений параметров. ## Использование -1. Импортируйте объект `config`. -2. Вызовите метод `register`, чтобы зарегистрировать параметр конфигурации. +1. Импортируйте объект `config`; +2. Вызовите метод `register`, чтобы зарегистрировать параметр конфигурации; 3. Вызовите метод `get`, чтобы получить значение параметра. ## Пример diff --git a/src/karkas_blocks/karkas_blocks/standard/filters/README.md b/src/karkas_blocks/karkas_blocks/standard/filters/README.md index 1cc0a49..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 -Модуль `filters` предоставляет фильтры для aiogram, которые используются для ограничения доступа к командам +Данный блок предоставляет фильтры для `aiogram`, которые используются для ограничения доступа к командам и обработчикам событий. ## Фильтры -- `ChatModerOrAdminFilter` - пропускает сообщения только от модераторов и администраторов чата. -- `ChatNotInApproveFilter` - пропускает сообщения только из чатов, не входящих в список разрешенных. +| Фильтр | Описание | +| :----------------------: | ---------------------------------------------------------------------- | +| `ChatModerOrAdminFilter` | Пропускает сообщения только от модераторов и администраторов чата | +| `ChatNotInApproveFilter` | Пропускает сообщения только из чатов, не входящих в список разрешенных | ## Использование diff --git a/src/karkas_blocks/karkas_blocks/standard/fsm_database_storage/README.md b/src/karkas_blocks/karkas_blocks/standard/fsm_database_storage/README.md index 9a39102..49f3672 100644 --- a/src/karkas_blocks/karkas_blocks/standard/fsm_database_storage/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/fsm_database_storage/README.md @@ -1,13 +1,13 @@ -# Модуль FSM Database Storage +# Блок FSM Database Storage -Модуль `fsm_database_storage` реализует хранение состояний FSM (Finite State Machine) в базе данных. +Данный блок реализует хранение состояний FSM (Finite State Machine) в базе данных. ## Функциональность -- Сохранение состояния FSM в базу данных. -- Получение состояния FSM из базы данных. +- Сохранение состояния FSM в базу данных; +- Получение состояния FSM из базы данных; - Обновление данных состояния FSM. ## Использование -Модуль автоматически регистрирует хранилище состояний FSM при инициализации. +Блок автоматически регистрирует хранилище состояний FSM при инициализации. diff --git a/src/karkas_blocks/karkas_blocks/standard/info/README.md b/src/karkas_blocks/karkas_blocks/standard/info/README.md index 3f0597a..ae51526 100644 --- a/src/karkas_blocks/karkas_blocks/standard/info/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/info/README.md @@ -1,15 +1,20 @@ -# Модуль Info +# Блок Info -Модуль `info` предоставляет информацию о пользователях и чатах. +Данный блок предоставляет информацию о пользователях и чатах. ## Команды -- `/info` - получить информацию о пользователе. -- `/chatinfo` - получить информацию о чате. +| Команда | Описание | +| :---------: | ----------------------------------- | +| `/info` | Получение информации о пользователе | +| `/chatinfo` | Получение информации о чате | ## Использование -Чтобы получить информацию о пользователе, отправьте команду `/info`, -ответив на сообщение пользователя или указав его тег. +Информация о пользователе: -Чтобы получить информацию о чате, отправьте команду `/chatinfo`. +1. Отправьте команду `/info`, ответив на сообщение пользователя или указав его тег. + +Информация о чате: + +1. Отправьте команду `/chatinfo`. diff --git a/src/karkas_blocks/karkas_blocks/standard/miniapp/README.md b/src/karkas_blocks/karkas_blocks/standard/miniapp/README.md index 0fd1008..71632fe 100644 --- a/src/karkas_blocks/karkas_blocks/standard/miniapp/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/miniapp/README.md @@ -1,16 +1,16 @@ -# Модуль Miniapp +# Блок Miniapp -Модуль `miniapp` реализует веб-интерфейс для бота, доступный через Telegram Mini Apps. +Данный блок реализует веб-интерфейс для бота, доступный через Telegram Mini Apps. ## Функциональность -- Регистрация страниц веб-интерфейса. +- Регистрация страниц веб-интерфейса; - Авторизация пользователей через Telegram. ## Использование -1. Импортируйте функцию `register_page`. -2. Вызовите функцию `register_page`, передав ей название страницы, ее путь, blueprint Dash и префикс. +1. Импортируйте функцию `register_page`; +2. Вызовите функцию `register_page`, передав ей название страницы, её путь, blueprint Dash и префикс. ## Пример diff --git a/src/karkas_blocks/karkas_blocks/standard/report/README.md b/src/karkas_blocks/karkas_blocks/standard/report/README.md index 164d17d..703b841 100644 --- a/src/karkas_blocks/karkas_blocks/standard/report/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/report/README.md @@ -1,18 +1,18 @@ -# Модуль Report +# Блок Report -Модуль `report` позволяет пользователям сообщать о спам-сообщениях в чате. +Данный блок даёт пользователям возможность сообщать о спам-сообщениях в чате. ## Команды -- `/report` - пожаловаться на сообщение как на спам. +| Команда | Описание | +| :-------: | ------------------------------------------------ | +| `/report` | Сообщить администраторам о сообщении как о спаме | ## Использование -Чтобы сообщить о сообщении как о спаме, отправьте команду `/report`, ответив на сообщение, которое вы хотите отметить. Модуль уведомит администраторов, которые имеют права модерации. +Чтобы указать, что сообщении является спамом, ответьте на него, использовав команду `/report`. Блок уведомит администраторов, которые имеют права модерации. ### Пример использования -1. Найдите сообщение, которое вы хотите отметить как спам. -2. Ответьте на это сообщение командой `/report`. - -Примечание: Команда `/report` должна быть отправлена в ответ на сообщение, которое вы хотите отметить. +1. Найдите сообщение, которое вы хотите отметить как спам; +2. Ответьте на это сообщение, указав при этом команду `/report`. diff --git a/src/karkas_blocks/karkas_blocks/standard/roles/README.md b/src/karkas_blocks/karkas_blocks/standard/roles/README.md index 3311af7..3f9c21c 100644 --- a/src/karkas_blocks/karkas_blocks/standard/roles/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/roles/README.md @@ -1,24 +1,26 @@ -# Модуль Roles +# Блок Roles -Модуль `roles` управляет ролями пользователей. +Данный блок управляет ролями пользователей. ## Роли -- `USER` - обычный пользователь. -- `MODERATOR` - модератор. -- `ADMIN` - администратор. -- `BOT` - бот. +| Роль | Описание | +| :---------: | -------------------- | +| `USER` | Обычный пользователь | +| `MODERATOR` | Модератор | +| `ADMIN` | Администратор | +| `BOT` | Бот | ## Функциональность -- Проверка роли пользователя. -- Получение имени роли по ID. +- Проверка роли пользователя; +- Получение имени роли по ID; - Получение ID роли по имени. ## Использование -1. Импортируйте класс `Roles`. -2. Создайте экземпляр класса. +1. Импортируйте класс `Roles`; +2. Создайте экземпляр класса; 3. Вызовите методы класса для проверки роли пользователя или получения имени роли. ## Пример diff --git a/src/karkas_blocks/karkas_blocks/standard/welcome/README.md b/src/karkas_blocks/karkas_blocks/standard/welcome/README.md index 612300c..8a59c1d 100644 --- a/src/karkas_blocks/karkas_blocks/standard/welcome/README.md +++ b/src/karkas_blocks/karkas_blocks/standard/welcome/README.md @@ -1,21 +1,24 @@ -## Модуль Welcome +## Блок Welcome -Модуль `welcome` отвечает за верификацию новых участников чата, используя различные методы проверки. Он помогает предотвратить спам и автоматические атаки на чат, обеспечивая, что новые участники подтверждают свою человеческую природу перед получением доступа. +Данный блок отвечает за верификацию новых участников чата, используя различные методы проверки. Он помогает предотвратить спам и автоматические атаки на чат, поддтверждая «человечность» новых пользователей. -## Команды и Методы +## Функциональность -Модуль поддерживает несколько методов верификации, которые случайным образом применяются к новым участникам чата: +Блок поддерживает несколько методов верификации, которые случайным образом применяются к новым участникам чата: -- **IAmHumanButton** - Верификация с помощью кнопки. -- **IAmHumanInput** - Верификация с помощью ввода текста. -- **MathButtonsVerification** - Верификация решением математической задачи с помощью кнопок. -- **MathInputVerificationMethod** - Верификация решением математической задачи с помощью ввода. -- **QuestionButtonsVerification** - Верификация ответом на вопрос с помощью кнопок. -- **QuestionInputVerification** - Верификация ответом на вопрос с помощью ввода. +| Метод | Описание | +| :---------------------------: | ----------------------------------------------------------- | +| `IAmHumanButton` | Верификация с помощью кнопки | +| `IAmHumanInput` | Верификация с помощью ввода текста | +| `MathButtonsVerification` | Верификация решением математической задачи с помощью кнопок | +| `MathInputVerificationMethod` | Верификация решением математической задачи с помощью ввода | +| `QuestionButtonsVerification` | верификация ответом на вопрос с помощью кнопок | +| `QuestionInputVerification` | Верификация ответом на вопрос с помощью ввода | -## Как это работает +## Использование -1. **Обработка новых участников**: Когда новый участник присоединяется к чату, выбирается случайный метод верификации, и создается задача проверки. -2. **Тайм-аут проверки**: Если новый участник не проходит проверку в течение 30 секунд, его статус в чате меняется на "забанен". -3. **Верификация по кнопкам**: Если верификация осуществляется с помощью кнопок, обработчик будет ожидать нажатие кнопки от пользователя и проверит правильность ответа. -4. **Верификация по вводу**: Если верификация осуществляется путем ввода текста, обработчик будет проверять введенный текст и действовать в зависимости от результата проверки. +1. **Обработка новых участников**: когда новый участник присоединяется к чату, выбирается случайный метод верификации и создаётся задача проверки; +2. **Верификация**: + - **Верификация с помощью кнопок**: обработчик ожидает нажатия кнопки от пользователя и проверяет ответ; + - **Верификация с помощью ввода текста**: обработчик проверять введённый текст и проверяет ответ. +3. **Время на проверку**: если новый участник не проходит проверку в течение 30 секунд, его статус в чате меняется на "забанен". diff --git a/src/karkas_core/README.md b/src/karkas_core/README.md index 0737215..823d16a 100644 --- a/src/karkas_core/README.md +++ b/src/karkas_core/README.md @@ -1,23 +1,7 @@ -# Karkas Core +# Ядро Karkas -Это ядро Karkas, содержащее базовые компоненты: +Ядро Karkas — базовые компоненты платформы «Каркас»: система управления блоками, логирование и утилиты. -- Система управления модулями. -- Логирование. -- Утилиты. - -## Система управления модулями - -Система управления модулями отвечает за: - -- Загрузку модулей. -- Проверку зависимостей. -- Предоставление API для взаимодействия между модулями. - -## Логирование - -Модуль логирования предоставляет функции для записи логов в консоль. - -## Утилиты - -Модуль утилит содержит вспомогательные функции, например, для форматирования текста. +- **Система управления блоками** — отвечает за их загрузку, проверку зависимостей и предоставление API для межблочного взаимодействия; +- **Блок логирования** — предоставляет функции для записи логов в консоль; +- **Блок утилит** — содержит вспомогательные функции, например, для форматирования текста.