mirror of
https://gitflic.ru/project/alt-gnome/karkas.git
synced 2024-12-23 16:23:02 +03:00
Рефакторинг файлов README.md и документации
This commit is contained in:
x1z53
parent
04a4ab4868
commit
5f5e851ecd
@ -1,8 +0,0 @@
|
||||
Руководитель проекта:
|
||||
- Семен Фомченков (@Armatik), e-mail: armatik@alt-gnome.ru
|
||||
|
||||
Ведущие разработчики:
|
||||
- Максим Слипенко (@Maks1m_S), e-mail: maxim@slipenko.com
|
||||
|
||||
Участники проекта:
|
||||
- Илья Женецкий (@ilyazheprog)
|
||||
61
README.md
61
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) — блок для создания отчётов об ошибках.
|
||||
|
||||
105
docs/BLOCKS-SPEC.md
Normal file
105
docs/BLOCKS-SPEC.md
Normal 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
49
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 <package_name>` для добавления новых зависимостей.
|
||||
Теперь рабочее окружение настроено!
|
||||
|
||||
## Дополнительная информация
|
||||
|
||||
- Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости;
|
||||
- Poetry автоматически управляет виртуальными окружениями для каждого пакета;
|
||||
- Вы можете использовать команду `poetry add <package_name>` (где `<package_name>` — имя пакета) для добавления новых зависимостей.
|
||||
|
||||
@ -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`. Она позволяет получить модуль или предоставляемые им объекты по его
|
||||
идентификатору.
|
||||
@ -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).
|
||||
|
||||
@ -2,17 +2,16 @@
|
||||
|
||||
|
||||
|
||||
Чат-бот помощник в [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`.
|
||||
|
||||
@ -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 |
|
||||
|
||||
@ -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. Бот сформирует отчёт и отправит его.
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -1,20 +1,26 @@
|
||||
# Модуль Admin
|
||||
# Блок Admin
|
||||
|
||||
Модуль `admin` предоставляет администраторам и модераторам чата инструменты для управления:
|
||||
Данный блок предоставляет администраторам и модераторам чата инструменты для управления.
|
||||
|
||||
## Функциональность
|
||||
|
||||
- Удаление сообщений.
|
||||
- Удаление сообщений;
|
||||
- Получение ID чата.
|
||||
|
||||
## Команды
|
||||
|
||||
- `/rm` - удалить сообщение, на которое отвечает команда.
|
||||
- `/chatID` - получить ID текущего чата.
|
||||
| Команда | Описание |
|
||||
| :-------: | --------------------------------------------------------- |
|
||||
| `/rm` | Удаление сообщения, ответом на которое отправлена команда |
|
||||
| `/chatID` | Получение ID текущего чата |
|
||||
|
||||
## Использование
|
||||
|
||||
1. Ответьте на сообщение, которое нужно удалить.
|
||||
Удаление сообщений:
|
||||
|
||||
1. Ответьте на сообщение, которое нужно удалить;
|
||||
2. Отправьте команду `/rm`.
|
||||
|
||||
Чтобы получить ID чата, отправьте команду `/chatID`.
|
||||
Получение ID чата:
|
||||
|
||||
1. Отправьте команду `/chatID`
|
||||
|
||||
@ -1,17 +1,16 @@
|
||||
# Модуль Command Helper
|
||||
# Блок Command Helper
|
||||
|
||||
Модуль `command_helper` упрощает регистрацию команд бота и управление ими.
|
||||
Данный блок упрощает регистрации команд бота и управления ими.
|
||||
|
||||
## Функциональность
|
||||
|
||||
- Регистрация команд бота.
|
||||
- Регистрация команд бота;
|
||||
- Установка команд для пользователей в зависимости от их роли.
|
||||
|
||||
## Использование
|
||||
|
||||
1. Импортируйте функцию `register_command`.
|
||||
2. Вызовите функцию `register_command`, передав ей название команды, ее описание и роль пользователя,
|
||||
которому доступна эта команда.
|
||||
1. Импортируйте функцию `register_command`;
|
||||
2. Вызовите функцию `register_command`, передав ей название команды, её описание и роль пользователей, которым доступна она будет доступна.
|
||||
|
||||
## Пример
|
||||
|
||||
|
||||
@ -1,18 +1,18 @@
|
||||
# Модуль Config
|
||||
# Блок Config
|
||||
|
||||
Модуль `config` управляет конфигурацией бота.
|
||||
Данный блок позволяет управляет конфигурацией бота.
|
||||
|
||||
## Функциональность
|
||||
|
||||
- Загрузка конфигурации из файла `config.yaml`.
|
||||
- Сохранение конфигурации в файл.
|
||||
- Регистрация параметров конфигурации.
|
||||
- Загрузка конфигурации из файла `config.yaml`;
|
||||
- Сохранение конфигурации в файл;
|
||||
- Регистрация параметров конфигурации;
|
||||
- Получение значений параметров.
|
||||
|
||||
## Использование
|
||||
|
||||
1. Импортируйте объект `config`.
|
||||
2. Вызовите метод `register`, чтобы зарегистрировать параметр конфигурации.
|
||||
1. Импортируйте объект `config`;
|
||||
2. Вызовите метод `register`, чтобы зарегистрировать параметр конфигурации;
|
||||
3. Вызовите метод `get`, чтобы получить значение параметра.
|
||||
|
||||
## Пример
|
||||
|
||||
@ -1,12 +1,14 @@
|
||||
# Модуль Filters
|
||||
# Блок Filters
|
||||
|
||||
Модуль `filters` предоставляет фильтры для aiogram, которые используются для ограничения доступа к командам
|
||||
Данный блок предоставляет фильтры для `aiogram`, которые используются для ограничения доступа к командам
|
||||
и обработчикам событий.
|
||||
|
||||
## Фильтры
|
||||
|
||||
- `ChatModerOrAdminFilter` - пропускает сообщения только от модераторов и администраторов чата.
|
||||
- `ChatNotInApproveFilter` - пропускает сообщения только из чатов, не входящих в список разрешенных.
|
||||
| Фильтр | Описание |
|
||||
| :----------------------: | ---------------------------------------------------------------------- |
|
||||
| `ChatModerOrAdminFilter` | Пропускает сообщения только от модераторов и администраторов чата |
|
||||
| `ChatNotInApproveFilter` | Пропускает сообщения только из чатов, не входящих в список разрешенных |
|
||||
|
||||
## Использование
|
||||
|
||||
|
||||
@ -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 при инициализации.
|
||||
|
||||
@ -1,15 +1,20 @@
|
||||
# Модуль Info
|
||||
# Блок Info
|
||||
|
||||
Модуль `info` предоставляет информацию о пользователях и чатах.
|
||||
Данный блок предоставляет информацию о пользователях и чатах.
|
||||
|
||||
## Команды
|
||||
|
||||
- `/info` - получить информацию о пользователе.
|
||||
- `/chatinfo` - получить информацию о чате.
|
||||
| Команда | Описание |
|
||||
| :---------: | ----------------------------------- |
|
||||
| `/info` | Получение информации о пользователе |
|
||||
| `/chatinfo` | Получение информации о чате |
|
||||
|
||||
## Использование
|
||||
|
||||
Чтобы получить информацию о пользователе, отправьте команду `/info`,
|
||||
ответив на сообщение пользователя или указав его тег.
|
||||
Информация о пользователе:
|
||||
|
||||
Чтобы получить информацию о чате, отправьте команду `/chatinfo`.
|
||||
1. Отправьте команду `/info`, ответив на сообщение пользователя или указав его тег.
|
||||
|
||||
Информация о чате:
|
||||
|
||||
1. Отправьте команду `/chatinfo`.
|
||||
|
||||
@ -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 и префикс.
|
||||
|
||||
## Пример
|
||||
|
||||
|
||||
@ -1,18 +1,18 @@
|
||||
# Модуль Report
|
||||
# Блок Report
|
||||
|
||||
Модуль `report` позволяет пользователям сообщать о спам-сообщениях в чате.
|
||||
Данный блок даёт пользователям возможность сообщать о спам-сообщениях в чате.
|
||||
|
||||
## Команды
|
||||
|
||||
- `/report` - пожаловаться на сообщение как на спам.
|
||||
| Команда | Описание |
|
||||
| :-------: | ------------------------------------------------ |
|
||||
| `/report` | Сообщить администраторам о сообщении как о спаме |
|
||||
|
||||
## Использование
|
||||
|
||||
Чтобы сообщить о сообщении как о спаме, отправьте команду `/report`, ответив на сообщение, которое вы хотите отметить. Модуль уведомит администраторов, которые имеют права модерации.
|
||||
Чтобы указать, что сообщении является спамом, ответьте на него, использовав команду `/report`. Блок уведомит администраторов, которые имеют права модерации.
|
||||
|
||||
### Пример использования
|
||||
|
||||
1. Найдите сообщение, которое вы хотите отметить как спам.
|
||||
2. Ответьте на это сообщение командой `/report`.
|
||||
|
||||
Примечание: Команда `/report` должна быть отправлена в ответ на сообщение, которое вы хотите отметить.
|
||||
1. Найдите сообщение, которое вы хотите отметить как спам;
|
||||
2. Ответьте на это сообщение, указав при этом команду `/report`.
|
||||
|
||||
@ -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. Вызовите методы класса для проверки роли пользователя или получения имени роли.
|
||||
|
||||
## Пример
|
||||
|
||||
@ -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 секунд, его статус в чате меняется на "забанен".
|
||||
|
||||
@ -1,23 +1,7 @@
|
||||
# Karkas Core
|
||||
# Ядро Karkas
|
||||
|
||||
Это ядро Karkas, содержащее базовые компоненты:
|
||||
Ядро Karkas — базовые компоненты платформы «Каркас»: система управления блоками, логирование и утилиты.
|
||||
|
||||
- Система управления модулями.
|
||||
- Логирование.
|
||||
- Утилиты.
|
||||
|
||||
## Система управления модулями
|
||||
|
||||
Система управления модулями отвечает за:
|
||||
|
||||
- Загрузку модулей.
|
||||
- Проверку зависимостей.
|
||||
- Предоставление API для взаимодействия между модулями.
|
||||
|
||||
## Логирование
|
||||
|
||||
Модуль логирования предоставляет функции для записи логов в консоль.
|
||||
|
||||
## Утилиты
|
||||
|
||||
Модуль утилит содержит вспомогательные функции, например, для форматирования текста.
|
||||
- **Система управления блоками** — отвечает за их загрузку, проверку зависимостей и предоставление API для межблочного взаимодействия;
|
||||
- **Блок логирования** — предоставляет функции для записи логов в консоль;
|
||||
- **Блок утилит** — содержит вспомогательные функции, например, для форматирования текста.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user