mirrors/karkas
0
0
Fork 0
mirror of https://gitflic.ru/project/alt-gnome/karkas.git synced 2024-12-23 16:23:02 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merged with main

Browse Source
This commit is contained in:
Давид Султаниязов 2024-08-26 11:26:57 +03:00
commit 6d421ee9b5
21 changed files with 349 additions and 346 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
CONTRIBUTORS
View File

@ -1,8 +0,0 @@
Руководитель проекта:
- Семен Фомченков (@Armatik), e-mail: armatik@alt-gnome.ru
Ведущие разработчики:
- Максим Слипенко (@Maks1m_S), e-mail: maxim@slipenko.com
Участники проекта:
- Илья Женецкий (@ilyazheprog)

61
README.md
View File

@ -1,44 +1,45 @@
# Karkas # Каркас
## Что такое Karkas? ## Что такое «Каркас»?
Karkas - это платформа для разработки модульных Telegram-ботов, которая призвана упростить взаимодействие с чатами. Каркас — это платформа для разработки блочных Telegram-ботов, которая призвана упростить взаимодействие с чатами. «Каркас» предоставляет возможность расширять функциональность бота с помощью интеграции различных блоков. Код платформы и набор стандартных блоков находятся в этом монорепозитории.
Karkas предоставляет возможность расширять функциональность бота с помощью интеграции различных модулей.
Код платформы и набор стандартных модулей находятся в этом монорепозитории.
## Структура монорепозитория ## Структура монорепозитория
Монорепозиторий Karkas включает в себя: Монорепозиторий 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) — блок для создания отчётов об ошибках.

105
docs/BLOCKS-SPEC.md Normal file
View File

@ -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` для получения блока или предоставляемых им объекты по идентификатору.

49
docs/DEV.md
View File

@ -1,39 +1,34 @@
## Настройка рабочего окружения # Настройка рабочего окружения
Данная инструкция поможет вам настроить рабочее окружение для разработки Karkas. Данная инструкция поможет вам настроить рабочее окружение для разработки Karkas.
### Предварительные требования ## Предварительные требования
* **Python 3.12:** Karkas требует Python 3.12. - **Python** — платформа «Каркас» требует интерпретатор языка Python версии 3.12;
* **VSCode:** Рекомендуется использовать VSCode для разработки. - **VSCode** — рекомендованная среда разработки;
* **Git:** У вас должен быть установлен Git для клонирования репозитория. - **Git** — инструмент контроля версий, необходим клонирования репозиториянео.
### Шаги ## Шаги
1. **Клонируйте репозиторий:** 1. Клонируйте репозиторий с помощью утилиты `git`:
```bash
git clone https://gitflic.ru/project/alt-gnome/karkas.git
```
2. **Откройте проект в VSCode:** ```shell
* Откройте папку `karkas` в VSCode. git clone https://gitflic.ru/project/alt-gnome/karkas.git
* VSCode автоматически предложит открыть проект как workspace, используя файл `karkas.code-workspace`. ```
Нажмите "Открыть Workspace", чтобы принять предложение.
3. **Настройте Poetry:** 2. Откройте папку `karkas` в VSCode. Среда разработки автоматически предложит открыть проект как Workspace, используя файл `karkas.code-workspace`. Нажмите `Открыть Workspace`, чтобы принять предложение;
* Установите Poetry, следуя инструкциям на официальном сайте: [https://python-poetry.org/docs/](https://python-poetry.org/docs/).
* **Для каждого пакета:**
* Перейдите в папку пакета (например, `src/karkas_core`).
* Выполните команду `poetry install`, чтобы установить зависимости пакета.
* Poetry создаст виртуальное окружение внутри папки пакета (`.venv`).
4. **Активируйте виртуальное окружение:** 3. Установите инструмент Poetry, следуя инструкциям из [официальной документации](https://python-poetry.org/docs/). Для каждого пакета выполните следующую последовательность действий:
* Выполните команду `poetry shell` в папке пакета, чтобы активировать виртуальное окружение.
Теперь ваше рабочее окружение настроено, и вы можете начать. - Перейдите в папку пакета (например, `src/karkas_core`);
- Выполните команду `poetry install`, чтобы установить зависимости пакета. После этого будет создано виртуальное окружене (`.venv`);
### Дополнительная информация 4. Выполните команду `poetry shell` в папке пакета, над которым будут производится работы, чтобы активировать виртуальное окружение.
* Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости. Теперь рабочее окружение настроено!
* Poetry автоматически управляет виртуальными окружениями для каждого пакета.
* Вы можете использовать команду `poetry add <package_name>` для добавления новых зависимостей. ## Дополнительная информация
- Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости;
- Poetry автоматически управляет виртуальными окружениями для каждого пакета;
- Вы можете использовать команду `poetry add <package_name>` (где `<package_name>` — имя пакета) для добавления новых зависимостей.

107
docs/MODULES-SPEC.md
View File

@ -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`. Она позволяет получить модуль или предоставляемые им объекты по его
идентификатору.

57
src/altlinux/README.md
View File

@ -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. Запустите контейнер: 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ика: 1. Активируйте виртуальное окружение:
```bash
poetry shell ```shell
``` poetry shell
```
2. Запустите бота: 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).

57
src/gnomik/README.md
View File

@ -2,17 +2,16 @@
![Логотип](./docs/gnomik.jpg) ![Логотип](./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 Gnome — открытое сообщество пользователей операционной системы ALT Regular Gnome. Платформы ALT Gnome:
ALT Regular Gnome Community - открытое сообщество пользователей операционной системы ALT Regular Gnome. >
> - [Wiki](https://alt-gnome.wiki)
- [Канал](https://t.me/alt_gnome) > - [Telegram-канал](https://t.me/alt_gnome)
- [Wiki](https://alt-gnome.wiki) > - [Вконтакте](https://vk.com/alt_gnome)
> - [Rutube](https://rutube.ru/channel/32425669/)
## Описание > - [Платформа](https://plvideo.ru/@alt_gnome)
> - [Boosty](https://boosty.to/alt_gnome)
Gnomик - это чат-бот для Telegram, разработанный на платформе Karkas. Он предоставляет различные функции и возможности, помогающие пользователям операционной системы ALT Regular Gnome.
## Функционал ## Функционал
@ -25,31 +24,37 @@ TODO: описать функционал
### Docker ### Docker
1. Соберите 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ика: 1. Активируйте виртуальное окружение Gnomика:
```bash
poetry shell ```shell
``` poetry shell
```
2. Запустите бота: 2. Запустите бота:
```bash
python -m gnomik ```shell
``` python -m gnomik
```
## Конфигурация ## Конфигурация
Конфигурация бота находится в файле `config.yaml`. Конфигурация бота находится в файле `config.yaml`.
## Модули ## Блоки
Список загружаемых модулей указан в файле `__main__.py`. Список загружаемых блоков указан в файле `__main__.py`.

16
src/karkas_blocks/README.md
View File

@ -1,12 +1,10 @@
# Karkas Blocks # Блоки Karkas
Karkas Blocks содержит набор модулей для платформы Open Chat AI Bot (Karkas). Блоки Karkas — это набор блоков для платформы «Каркас», которые добавляют функциональность ботам.
## Описание ## Типы блоков
Karkas - это платформа для создания чат-ботов Telegram. Модули - это расширения, которые добавляют функциональность ботам Karkas. | Тип | Описание |
| :-------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
## Типы модулей | Стандартные (`standard`) | Блоки, содержащие основной функционал: управление пользователями, ролями и настройками |
| Дополнительные (`external`) | Блоки, созданные командой разработки платформы «Каркас». Предоставляют расширенные возможности: интеграция с нейросетями, внешними сервисами и API |
* **Стандартные модули (standard.*):** Предоставляют основные функции, такие как управление пользователями, ролями и настройками.
* **Дополнительные официальные модули (external.*):** Разработаны командой Karkas и предоставляют расширенные возможности, такие как интеграция с нейросетями, внешними сервисами и API.

20
src/karkas_blocks/karkas_blocks/external/create_report_apps/README.md vendored
View File

@ -1,19 +1,21 @@
# Модуль Create Report Apps # Блок Create Report Apps
Модуль `create_report_apps` предназначен для помощи пользователям в создании отчетов об ошибках в приложениях. Данный блок предназначен для помощи пользователям в создании отчётов об ошибках в приложениях.
## Функциональность ## Функциональность
- Задает пользователю ряд вопросов, необходимых для составления отчета. - Задаёт пользователю ряд вопросов, необходимых для составления отчёта;
- Собирает информацию о системе пользователя. - Собирает информацию о системе пользователя;
- Формирует отчет в текстовом формате. - Формирует отчёт в текстовом формате.
## Команды ## Команды
- `/create_report_apps` - запустить процесс создания отчета. | Команда | Описание |
| :-------------------: | --------------- |
| `/create_report_apps` | Создание отчёта |
## Использование ## Использование
1. Отправьте команду `/create_report_apps` боту в личных сообщениях или в групповом чате. 1. Отправьте команду `/create_report_apps` боту личным сообщением или в групповом чате;
2. Ответьте на вопросы бота. 2. Ответьте на вопросы бота;
3. Бот сформирует отчет и отправит его вам. 3. Бот сформирует отчёт и отправит его.

24
src/karkas_blocks/karkas_blocks/external/yandexgpt/README.md vendored
View File

@ -1,22 +1,24 @@
# Модуль YandexGPT # Блок YandexGPT
Модуль `yandexgpt` интегрирует в бота OCAB нейросеть YandexGPT. Данный блок интегрирует в бота нейросеть YandexGPT.
## Функциональность ## Функциональность
- Позволяет боту отвечать на сообщения пользователей, используя YandexGPT. - Позволяет боту отвечать на сообщения пользователей, используя YandexGPT;
- Строит линию контекста для нейросети, используя историю сообщений. - Строит линию контекста для нейросети, используя историю сообщений.
## Конфигурация ## Конфигурация
- `yandexgpt::token` - API-ключ для доступа к YandexGPT. | Параметр | Описание |
- `yandexgpt::catalogid` - идентификатор каталога YandexGPT. | :--------------------: | --------------------------------------------------------------- |
- `yandexgpt::prompt` - системная подсказка для YandexGPT. | `yandexgpt::token` | API-ключ для доступа к YandexGPT |
- `yandexgpt::startword` - слова, с которых должно начинаться сообщение, чтобы бот ответил. | `yandexgpt::catalogid` | Идентификатор каталога YandexGPT |
- `yandexgpt::inword` - слова, которые должны быть в сообщении, чтобы бот ответил. | `yandexgpt::prompt` | Системная подсказка для YandexGPT |
| `yandexgpt::startword` | Слова, с которых должно начинаться сообщение, чтобы бот ответил |
| `yandexgpt::inword` | Слова, которые должны быть в сообщении, чтобы бот ответил |
## Использование ## Использование
1. Настройте конфигурационные параметры модуля. 1. Настройте конфигурационные параметры блока;
2. Отправьте боту сообщение, которое соответствует условиям, указанным в параметрах `startword` и `inword`. 2. Отправьте боту сообщение, начинающееся со слов или содержащее слова, указанные в параметрах `startword` и `inword` соответственно;
3. Бот ответит на сообщение, используя YandexGPT. 3. Бот ответит на сообщение, генерируя текст с помощью YandexGPT.

20
src/karkas_blocks/karkas_blocks/standard/admin/README.md
View File

@ -1,20 +1,26 @@
# Модуль Admin # Блок Admin
Модуль `admin` предоставляет администраторам и модераторам чата инструменты для управления: Данный блок предоставляет администраторам и модераторам чата инструменты для управления.
## Функциональность ## Функциональность
- Удаление сообщений. - Удаление сообщений;
- Получение ID чата. - Получение ID чата.
## Команды ## Команды
- `/rm` - удалить сообщение, на которое отвечает команда. | Команда | Описание |
- `/chatID` - получить ID текущего чата. | :-------: | --------------------------------------------------------- |
| `/rm` | Удаление сообщения, ответом на которое отправлена команда |
| `/chatID` | Получение ID текущего чата |
## Использование ## Использование
1. Ответьте на сообщение, которое нужно удалить. Удаление сообщений:
1. Ответьте на сообщение, которое нужно удалить;
2. Отправьте команду `/rm`. 2. Отправьте команду `/rm`.
Чтобы получить ID чата, отправьте команду `/chatID`. Получение ID чата:
1. Отправьте команду `/chatID`

11
src/karkas_blocks/karkas_blocks/standard/command_helper/README.md
View File

@ -1,17 +1,16 @@
# Модуль Command Helper # Блок Command Helper
Модуль `command_helper` упрощает регистрацию команд бота и управление ими. Данный блок упрощает регистрации команд бота и управления ими.
## Функциональность ## Функциональность
- Регистрация команд бота. - Регистрация команд бота;
- Установка команд для пользователей в зависимости от их роли. - Установка команд для пользователей в зависимости от их роли.
## Использование ## Использование
1. Импортируйте функцию `register_command`. 1. Импортируйте функцию `register_command`;
2. Вызовите функцию `register_command`, передав ей название команды, ее описание и роль пользователя, 2. Вызовите функцию `register_command`, передав ей название команды, её описание и роль пользователей, которым доступна она будет доступна.
которому доступна эта команда.
## Пример ## Пример

14
src/karkas_blocks/karkas_blocks/standard/config/README.md
View File

@ -1,18 +1,18 @@
# Модуль Config # Блок Config
Модуль `config` управляет конфигурацией бота. Данный блок позволяет управляет конфигурацией бота.
## Функциональность ## Функциональность
- Загрузка конфигурации из файла `config.yaml`. - Загрузка конфигурации из файла `config.yaml`;
- Сохранение конфигурации в файл. - Сохранение конфигурации в файл;
- Регистрация параметров конфигурации. - Регистрация параметров конфигурации;
- Получение значений параметров. - Получение значений параметров.
## Использование ## Использование
1. Импортируйте объект `config`. 1. Импортируйте объект `config`;
2. Вызовите метод `register`, чтобы зарегистрировать параметр конфигурации. 2. Вызовите метод `register`, чтобы зарегистрировать параметр конфигурации;
3. Вызовите метод `get`, чтобы получить значение параметра. 3. Вызовите метод `get`, чтобы получить значение параметра.
## Пример ## Пример

10
src/karkas_blocks/karkas_blocks/standard/filters/README.md
View File

@ -1,12 +1,14 @@
# Модуль Filters # Блок Filters
Модуль `filters` предоставляет фильтры для aiogram, которые используются для ограничения доступа к командам Данный блок предоставляет фильтры для `aiogram`, которые используются для ограничения доступа к командам
и обработчикам событий. и обработчикам событий.
## Фильтры ## Фильтры
- `ChatModerOrAdminFilter` - пропускает сообщения только от модераторов и администраторов чата. | Фильтр | Описание |
- `ChatNotInApproveFilter` - пропускает сообщения только из чатов, не входящих в список разрешенных. | :----------------------: | ---------------------------------------------------------------------- |
| `ChatModerOrAdminFilter` | Пропускает сообщения только от модераторов и администраторов чата |
| `ChatNotInApproveFilter` | Пропускает сообщения только из чатов, не входящих в список разрешенных |
## Использование ## Использование

10
src/karkas_blocks/karkas_blocks/standard/fsm_database_storage/README.md
View File

@ -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 при инициализации. Блок автоматически регистрирует хранилище состояний FSM при инициализации.

19
src/karkas_blocks/karkas_blocks/standard/info/README.md
View File

@ -1,15 +1,20 @@
# Модуль Info # Блок Info
Модуль `info` предоставляет информацию о пользователях и чатах. Данный блок предоставляет информацию о пользователях и чатах.
## Команды ## Команды
- `/info` - получить информацию о пользователе. | Команда | Описание |
- `/chatinfo` - получить информацию о чате. | :---------: | ----------------------------------- |
| `/info` | Получение информации о пользователе |
| `/chatinfo` | Получение информации о чате |
## Использование ## Использование
Чтобы получить информацию о пользователе, отправьте команду `/info`, Информация о пользователе:
ответив на сообщение пользователя или указав его тег.
Чтобы получить информацию о чате, отправьте команду `/chatinfo`. 1. Отправьте команду `/info`, ответив на сообщение пользователя или указав его тег.
Информация о чате:
1. Отправьте команду `/chatinfo`.

10
src/karkas_blocks/karkas_blocks/standard/miniapp/README.md
View File

@ -1,16 +1,16 @@
# Модуль Miniapp # Блок Miniapp
Модуль `miniapp` реализует веб-интерфейс для бота, доступный через Telegram Mini Apps. Данный блок реализует веб-интерфейс для бота, доступный через Telegram Mini Apps.
## Функциональность ## Функциональность
- Регистрация страниц веб-интерфейса. - Регистрация страниц веб-интерфейса;
- Авторизация пользователей через Telegram. - Авторизация пользователей через Telegram.
## Использование ## Использование
1. Импортируйте функцию `register_page`. 1. Импортируйте функцию `register_page`;
2. Вызовите функцию `register_page`, передав ей название страницы, ее путь, blueprint Dash и префикс. 2. Вызовите функцию `register_page`, передав ей название страницы, её путь, blueprint Dash и префикс.
## Пример ## Пример

16
src/karkas_blocks/karkas_blocks/standard/report/README.md
View File

@ -1,18 +1,18 @@
# Модуль Report # Блок Report
Модуль `report` позволяет пользователям сообщать о спам-сообщениях в чате. Данный блок даёт пользователям возможность сообщать о спам-сообщениях в чате.
## Команды ## Команды
- `/report` - пожаловаться на сообщение как на спам. | Команда | Описание |
| :-------: | ------------------------------------------------ |
| `/report` | Сообщить администраторам о сообщении как о спаме |
## Использование ## Использование
Чтобы сообщить о сообщении как о спаме, отправьте команду `/report`, ответив на сообщение, которое вы хотите отметить. Модуль уведомит администраторов, которые имеют права модерации. Чтобы указать, что сообщении является спамом, ответьте на него, использовав команду `/report`. Блок уведомит администраторов, которые имеют права модерации.
### Пример использования ### Пример использования
1. Найдите сообщение, которое вы хотите отметить как спам. 1. Найдите сообщение, которое вы хотите отметить как спам;
2. Ответьте на это сообщение командой `/report`. 2. Ответьте на это сообщение, указав при этом команду `/report`.
Примечание: Команда `/report` должна быть отправлена в ответ на сообщение, которое вы хотите отметить.

22
src/karkas_blocks/karkas_blocks/standard/roles/README.md
View File

@ -1,24 +1,26 @@
# Модуль Roles # Блок Roles
Модуль `roles` управляет ролями пользователей. Данный блок управляет ролями пользователей.
## Роли ## Роли
- `USER` - обычный пользователь. | Роль | Описание |
- `MODERATOR` - модератор. | :---------: | -------------------- |
- `ADMIN` - администратор. | `USER` | Обычный пользователь |
- `BOT` - бот. | `MODERATOR` | Модератор |
| `ADMIN` | Администратор |
| `BOT` | Бот |
## Функциональность ## Функциональность
- Проверка роли пользователя. - Проверка роли пользователя;
- Получение имени роли по ID. - Получение имени роли по ID;
- Получение ID роли по имени. - Получение ID роли по имени.
## Использование ## Использование
1. Импортируйте класс `Roles`. 1. Импортируйте класс `Roles`;
2. Создайте экземпляр класса. 2. Создайте экземпляр класса;
3. Вызовите методы класса для проверки роли пользователя или получения имени роли. 3. Вызовите методы класса для проверки роли пользователя или получения имени роли.
## Пример ## Пример

33
src/karkas_blocks/karkas_blocks/standard/welcome/README.md
View File

@ -1,21 +1,24 @@
## Модуль Welcome ## Блок Welcome
Модуль `welcome` отвечает за верификацию новых участников чата, используя различные методы проверки. Он помогает предотвратить спам и автоматические атаки на чат, обеспечивая, что новые участники подтверждают свою человеческую природу перед получением доступа. Данный блок отвечает за верификацию новых участников чата, используя различные методы проверки. Он помогает предотвратить спам и автоматические атаки на чат, поддтверждая «человечность» новых пользователей.
## Команды и Методы ## Функциональность
Модуль поддерживает несколько методов верификации, которые случайным образом применяются к новым участникам чата: Блок поддерживает несколько методов верификации, которые случайным образом применяются к новым участникам чата:
- **IAmHumanButton** - Верификация с помощью кнопки. | Метод | Описание |
- **IAmHumanInput** - Верификация с помощью ввода текста. | :---------------------------: | ----------------------------------------------------------- |
- **MathButtonsVerification** - Верификация решением математической задачи с помощью кнопок. | `IAmHumanButton` | Верификация с помощью кнопки |
- **MathInputVerificationMethod** - Верификация решением математической задачи с помощью ввода. | `IAmHumanInput` | Верификация с помощью ввода текста |
- **QuestionButtonsVerification** - Верификация ответом на вопрос с помощью кнопок. | `MathButtonsVerification` | Верификация решением математической задачи с помощью кнопок |
- **QuestionInputVerification** - Верификация ответом на вопрос с помощью ввода. | `MathInputVerificationMethod` | Верификация решением математической задачи с помощью ввода |
| `QuestionButtonsVerification` | верификация ответом на вопрос с помощью кнопок |
| `QuestionInputVerification` | Верификация ответом на вопрос с помощью ввода |
## Как это работает ## Использование
1. **Обработка новых участников**: Когда новый участник присоединяется к чату, выбирается случайный метод верификации, и создается задача проверки. 1. **Обработка новых участников**: когда новый участник присоединяется к чату, выбирается случайный метод верификации и создаётся задача проверки;
2. **Тайм-аут проверки**: Если новый участник не проходит проверку в течение 30 секунд, его статус в чате меняется на "забанен". 2. **Верификация**:
3. **Верификация по кнопкам**: Если верификация осуществляется с помощью кнопок, обработчик будет ожидать нажатие кнопки от пользователя и проверит правильность ответа. - **Верификация с помощью кнопок**: обработчик ожидает нажатия кнопки от пользователя и проверяет ответ;
4. **Верификация по вводу**: Если верификация осуществляется путем ввода текста, обработчик будет проверять введенный текст и действовать в зависимости от результата проверки. - **Верификация с помощью ввода текста**: обработчик проверять введённый текст и проверяет ответ.
3. **Время на проверку**: если новый участник не проходит проверку в течение 30 секунд, его статус в чате меняется на "забанен".

26
src/karkas_core/README.md
View File

@ -1,23 +1,7 @@
# Karkas Core # Ядро Karkas
Это ядро Karkas, содержащее базовые компоненты: Ядро Karkas — базовые компоненты платформы «Каркас»: система управления блоками, логирование и утилиты.
- Система управления модулями. - **Система управления блоками** — отвечает за их загрузку, проверку зависимостей и предоставление API для межблочного взаимодействия;
- Логирование. - **Блок логирования** — предоставляет функции для записи логов в консоль;
- Утилиты. - **Блок утилит** — содержит вспомогательные функции, например, для форматирования текста.
## Система управления модулями
Система управления модулями отвечает за:
- Загрузку модулей.
- Проверку зависимостей.
- Предоставление API для взаимодействия между модулями.
## Логирование
Модуль логирования предоставляет функции для записи логов в консоль.
## Утилиты
Модуль утилит содержит вспомогательные функции, например, для форматирования текста.