mirror of
https://gitflic.ru/project/alt-gnome/karkas.git
synced 2024-12-23 16:23:02 +03:00
Дополнительный рефакторинг документации
This commit is contained in:
x1z53
parent
eac32d5215
commit
e97e0604b8
2
AUTHORS
2
AUTHORS
@ -1,5 +1,5 @@
|
||||
Руководитель проекта:
|
||||
- Семён Фомченков (@Armatik), e-mail: armatik@alt-gnome.ru
|
||||
- Семен Фомченков (@Armatik), e-mail: armatik@alt-gnome.ru
|
||||
|
||||
Ведущие разработчики:
|
||||
- Максим Слипенко (@Maks1m_S), e-mail: maxim@slipenko.com
|
||||
|
||||
48
README.md
48
README.md
@ -2,44 +2,44 @@
|
||||
|
||||
## Что такое «Каркас»?
|
||||
|
||||
Каркас — это платформа для разработки модульных Telegram-ботов, которая призвана упростить взаимодействие с чатами. «Каркас» предоставляет возможность расширять функциональность бота с помощью интеграции различных модулей. Код платформы и набор стандартных модулей находятся в этом монорепозитории.
|
||||
Каркас — это платформа для разработки блочных Telegram-ботов, которая призвана упростить взаимодействие с чатами. «Каркас» предоставляет возможность расширять функциональность бота с помощью интеграции различных блоков. Код платформы и набор стандартных блоков находятся в этом монорепозитории.
|
||||
|
||||
## Структура монорепозитория
|
||||
|
||||
Монорепозиторий Karkas включает в себя:
|
||||
|
||||
- **Ядро Karkas (`src/karkas_core`):** Основные компоненты платформы, такие как система управления модулями, логирование и утилиты.
|
||||
- **Блоки Karkas (`src/karkas_blocks`):** Содержит стандартные и дополнительные модули, которые расширяют функциональность ботов, созданных на платформе «Каркас».
|
||||
- **Ядро Karkas (`src/karkas_core`):** Основные компоненты платформы, такие как система управления блоками, логирование и утилиты.
|
||||
- **Блоки Karkas (`src/karkas_blocks`):** Содержит стандартные и дополнительные блоки, которые расширяют функциональность ботов, созданных на платформе «Каркас».
|
||||
- **Бот Gnomик (`src/gnomik`):** Пример реализации бота, созданного на основе платформы «Каркас».
|
||||
|
||||
## Модули
|
||||
## Блоки
|
||||
|
||||
Модули Karkas — это независимые компоненты, которые добавляют функциональность бота.
|
||||
Блоки Karkas — это независимые компоненты, которые добавляют функциональность бота.
|
||||
|
||||
### Структура модуля
|
||||
### Структура блока
|
||||
|
||||
Структура модуля представлена [здесь](docs/MODULES-SPEC.md).
|
||||
Структура блока представлена [здесь](docs/BLOCKS-SPEC.md).
|
||||
|
||||
### Стандартные модули
|
||||
### Стандартные блоки
|
||||
|
||||
Стандартные модули предоставляют базовые функции для работы бота
|
||||
Стандартные блоки предоставляют базовые функции для работы бота
|
||||
|
||||
Полный перечень стандартных модулей:
|
||||
Полный перечень стандартных блоков:
|
||||
|
||||
- [`admin`](src/karkas_blocks/karkas_blocks/standard/admin/README.md) — модуль модерирования чата;
|
||||
- [`roles`](src/karkas_blocks/karkas_blocks/standard/roles/README.md) — модуль управления ролями пользователей;
|
||||
- [`config`](src/karkas_blocks/karkas_blocks/standard/config/README.md) — модуль управления конфигурацией бота;
|
||||
- [`database`](src/karkas_blocks/karkas_blocks/standard/database/README.md) — модуль для работы с базой данных;
|
||||
- [`fsm_database_storage`](src/karkas_blocks/karkas_blocks/standard/fsm_database_storage/README.md) — модуль для хранения состояний FSM в базе данных;
|
||||
- [`filters`](src/karkas_blocks/karkas_blocks/standard/filters/README.md) — модуль, предоставляющий фильтры для `aiogram`;
|
||||
- [`message_processing`](src/karkas_blocks/karkas_blocks/standard/message_processing/README.md) — модуль обработки входящих сообщений;
|
||||
- [`miniapp`](src/karkas_blocks/karkas_blocks/standard/miniapp/README.md) — модуль для реализации веб-интерфейса бота;
|
||||
- [`command_helper`](src/karkas_blocks/karkas_blocks/standard/command_helper/README.md) — модуль для упрощения регистрации команд бота;
|
||||
- [`info`](src/karkas_blocks/karkas_blocks/standard/info/README.md) — модуль предоставления информации о пользователях и чатах.
|
||||
- [`admin`](src/karkas_blocks/karkas_blocks/standard/admin/README.md) — блок модерирования чата;
|
||||
- [`roles`](src/karkas_blocks/karkas_blocks/standard/roles/README.md) — блок управления ролями пользователей;
|
||||
- [`config`](src/karkas_blocks/karkas_blocks/standard/config/README.md) — блок управления конфигурацией бота;
|
||||
- [`database`](src/karkas_blocks/karkas_blocks/standard/database/README.md) — блок для работы с базой данных;
|
||||
- [`fsm_database_storage`](src/karkas_blocks/karkas_blocks/standard/fsm_database_storage/README.md) — блок для хранения состояний FSM в базе данных;
|
||||
- [`filters`](src/karkas_blocks/karkas_blocks/standard/filters/README.md) — блок, предоставляющий фильтры для `aiogram`;
|
||||
- [`message_processing`](src/karkas_blocks/karkas_blocks/standard/message_processing/README.md) — блок обработки входящих сообщений;
|
||||
- [`miniapp`](src/karkas_blocks/karkas_blocks/standard/miniapp/README.md) — блок для реализации веб-интерфейса бота;
|
||||
- [`command_helper`](src/karkas_blocks/karkas_blocks/standard/command_helper/README.md) — блок для упрощения регистрации команд бота;
|
||||
- [`info`](src/karkas_blocks/karkas_blocks/standard/info/README.md) — блок предоставления информации о пользователях и чатах.
|
||||
|
||||
### Дополнительные официальные модули
|
||||
### Дополнительные официальные блоки
|
||||
|
||||
Дополнительные официальные модули созданы командой разработки платформы «Каркас» и предоставляют расширенные возможности для бота:
|
||||
Дополнительные официальные блоки созданы командой разработки платформы «Каркас» и предоставляют расширенные возможности для бота:
|
||||
|
||||
- [`yandexgpt`](src/karkas_blocks/karkas_blocks/external/yandexgpt/README.md) — модуль для интеграции с нейросетью YandexGPT;
|
||||
- [`create_report_apps`](src/karkas_blocks/karkas_blocks/external/create_report_apps/README.md) — модуль для создания отчётов об ошибках.
|
||||
- [`yandexgpt`](src/karkas_blocks/karkas_blocks/external/yandexgpt/README.md) — блок для интеграции с нейросетью YandexGPT;
|
||||
- [`create_report_apps`](src/karkas_blocks/karkas_blocks/external/create_report_apps/README.md) — блок для создания отчётов об ошибках.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Спецификация модулей
|
||||
# Спецификация блоков
|
||||
|
||||
> **Внимание!**
|
||||
>
|
||||
@ -6,17 +6,17 @@
|
||||
>
|
||||
> Могут возникнуть изменения, которые не будут обратно совместимы (breaking changes).
|
||||
|
||||
Каждый модуль представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`.
|
||||
Каждый блок представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`.
|
||||
|
||||
## Метаданные модуля (`info.json`)
|
||||
## Метаданные блока (`info.json`)
|
||||
|
||||
Файл `info.json` содержит информацию о модуле в формате JSON. Пример структуры `info.json` приведён ниже:
|
||||
Файл `info.json` содержит информацию о блоке в формате JSON. Пример структуры `info.json` приведён ниже:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "standard.info",
|
||||
"name": "Info",
|
||||
"description": "Модуль с информацией",
|
||||
"description": "Блок с информацией",
|
||||
"author": "Karkas Team",
|
||||
"version": "1.0.0",
|
||||
"privileged": false,
|
||||
@ -43,22 +43,22 @@
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Описание |
|
||||
| :-----------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Уникальный идентификатор модуля |
|
||||
| `name` | Название модуля |
|
||||
| `description` | Описание функциональности модуля |
|
||||
| `author` | Автор модуля |
|
||||
| `version` | Версия модуля в формате [SemVer](https://semver.org/) |
|
||||
| `privileged` | Является ли модуль привилегированным (булево значение) |
|
||||
| `dependencies` | Объект, описывающий зависимости модуля от других модулей |
|
||||
| `dependencies.required` и `dependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — идентификатор модуля, значение — версия или объект `DependencyInfo`. |
|
||||
| `pythonDependencies` | Объект, описывающий зависимости модуля от внешних Python пакетов. |
|
||||
| `pythonDependencies.required` и `pythonDependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — название пакета, значение — версия. |
|
||||
| Поле | Описание |
|
||||
| :-----------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Уникальный идентификатор блока |
|
||||
| `name` | Название блока |
|
||||
| `description` | Описание функциональности блока |
|
||||
| `author` | Автор блока |
|
||||
| `version` | Версия блока в формате [SemVer](https://semver.org/) |
|
||||
| `privileged` | Является ли блок привилегированным (булево значение) |
|
||||
| `dependencies` | Объект, описывающий зависимости блока от других блоков |
|
||||
| `dependencies.required` и `dependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — идентификатор блока, значение — версия или объект `DependencyInfo`. |
|
||||
| `pythonDependencies` | Объект, описывающий зависимости блока от внешних Python пакетов. |
|
||||
| `pythonDependencies.required` и `pythonDependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — название пакета, значение — версия. |
|
||||
|
||||
### DependencyInfo
|
||||
|
||||
Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов модуля (`uses`). Если `uses` не указан, то доступ к модулю целиком запрещён. Пример объекта `DependencyInfo`:
|
||||
Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов блока (`uses`). Если `uses` не указан, то доступ к блоку целиком запрещён. Пример объекта `DependencyInfo`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -67,39 +67,39 @@
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Описание |
|
||||
| :-------: | ------------------------------------ |
|
||||
| `version` | Версия модуля |
|
||||
| `uses` | Список используемых атрибутов модуля |
|
||||
| Поле | Описание |
|
||||
| :-------: | ----------------------------------- |
|
||||
| `version` | Версия блока |
|
||||
| `uses` | Список используемых атрибутов блока |
|
||||
|
||||
## Режимы работы модулей
|
||||
## Режимы работы блоков
|
||||
|
||||
### Непривилегированный режим (`privileged: false`)
|
||||
|
||||
- Модуль выполняется в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений;
|
||||
- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`, а также несколько стандартных модулей, необходимых для работы;
|
||||
- Исполнение блока происходит в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений;
|
||||
- Может импортировать только явно разрешенные блоки, указанные в `pythonDependencies`, а также несколько стандартных блоков, необходимых для работы;
|
||||
- Имеет доступ к пакету `karkas_core.modules_system.public_api` для взаимодействия с ботом.
|
||||
|
||||
### Привилегированный режим (`privileged: true`)
|
||||
|
||||
- Модуль выполняется без ограничений;
|
||||
- Блок исполняется без ограничений;
|
||||
- Имеет полный доступ ко всем пакетам, доступным в окружении;
|
||||
- Должен использоваться с осторожностью и только для модулей, требующих расширенных прав.
|
||||
- Должен использоваться с осторожностью и только для блоков, требующих расширенных прав.
|
||||
|
||||
## Жизненный цикл модуля
|
||||
## Жизненный цикл блока
|
||||
|
||||
1. Загрузка метаданных из `info.json`;
|
||||
2. Проверка зависимостей:
|
||||
- Проверка всех обязательных зависимостей;
|
||||
- Проверка совместимости версий зависимостей;
|
||||
- Проверка зависимостей Python;
|
||||
3. Загрузка кода модуля из `__init__.py`;
|
||||
3. Загрузка кода блока из `__init__.py`;
|
||||
4. Вызов функции `module_init`, если она есть;
|
||||
5. После загрузки всех модулей вызывается функция `module_late_init`, если она есть.
|
||||
5. После загрузки всех блоков вызывается функция `module_late_init`, если она есть.
|
||||
|
||||
## Межмодульное взаимодейтвие
|
||||
## Межблочное взаимодейтвие
|
||||
|
||||
Для взаимодействия друг с другом описан [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py),
|
||||
предоставляемое системой управления модулями.
|
||||
Для блоков взаимодействия друг с другом описан [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py),
|
||||
предоставляемое системой управления блоками.
|
||||
|
||||
Например, можно использовать функцию `get_module` для получения модуля или предоставляемых им объекты по идентификатору.
|
||||
Например, можно использовать функцию `get_module` для получения блока или предоставляемых им объекты по идентификатору.
|
||||
@ -6,7 +6,7 @@
|
||||
|
||||
## Функционал
|
||||
|
||||
Список модулей, используемых в боте:
|
||||
Список блоков, используемых в боте:
|
||||
|
||||
- `report` — вызов администрации чата одной командой;
|
||||
- `welcome` — автоматическая вариативная проверка пользователей на признаки бота или другой рекламной системы;
|
||||
@ -28,7 +28,7 @@ docker build -t altlinux -f Dockerfile ../..
|
||||
docker run -v ./config.yaml:/app/config.yaml altlinux
|
||||
```
|
||||
|
||||
Замените `./config.yaml` на путь к вашему локальному файлу конфигурации.
|
||||
Замените `./config.yaml` на путь к локальному файлу конфигурации.
|
||||
|
||||
### Вручную
|
||||
|
||||
@ -50,6 +50,6 @@ python -m altlinux
|
||||
|
||||
Пример конфигурации бота находится в файле [`config-example.yaml`](./config-example.yaml).
|
||||
|
||||
## Модули
|
||||
## Блоки
|
||||
|
||||
Список загружаемых модулей указан в файле [`__main__.py`](./altlinux/__main__.py).
|
||||
Список загружаемых блоков указан в файле [`__main__.py`](./altlinux/__main__.py).
|
||||
|
||||
@ -1,8 +1,10 @@
|
||||
# Блоки Karkas
|
||||
|
||||
Блоки Karkas — это набор «блоков» (модулей) для платформы «Каркас», которые добавляют функциональность ботам.
|
||||
Блоки Karkas — это набор блоков для платформы «Каркас», которые добавляют функциональность ботам.
|
||||
|
||||
## Типы блоков
|
||||
|
||||
- **Стандартные (`standard`)** — блоки, содержащие основной функционал: управление пользователями, ролями и настройками;
|
||||
- **Дополнительные (`external`)** — блоки, созданные командой разработки платформы «Каркас». Предоставляют расширенные возможности: интеграция с нейросетями, внешними сервисами и API.
|
||||
| Тип | Описание |
|
||||
| :-------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Стандартные (`standard`) | Блоки, содержащие основной функционал: управление пользователями, ролями и настройками |
|
||||
| Дополнительные (`external`) | Блоки, созданные командой разработки платформы «Каркас». Предоставляют расширенные возможности: интеграция с нейросетями, внешними сервисами и API |
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Модуль Command Helper
|
||||
# Блок Command Helper
|
||||
|
||||
Данный для упрощения регистрации команд бота и управления ими.
|
||||
Данный блок упрощает регистрации команд бота и управления ими.
|
||||
|
||||
## Функциональность
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Модуль Config
|
||||
# Блок Config
|
||||
|
||||
Данный модуль позволяет управляет конфигурацией бота.
|
||||
Данный блок позволяет управляет конфигурацией бота.
|
||||
|
||||
## Функциональность
|
||||
|
||||
|
||||
@ -1,12 +1,14 @@
|
||||
# Модуль Filters
|
||||
# Блок Filters
|
||||
|
||||
Данный модуль предоставляет фильтры для `aiogram`, которые используются для ограничения доступа к командам
|
||||
Данный блок предоставляет фильтры для `aiogram`, которые используются для ограничения доступа к командам
|
||||
и обработчикам событий.
|
||||
|
||||
## Фильтры
|
||||
|
||||
- `ChatModerOrAdminFilter` — пропускает сообщения только от модераторов и администраторов чата;
|
||||
- `ChatNotInApproveFilter` — пропускает сообщения только из чатов, не входящих в список разрешенных.
|
||||
| Фильтр | Описание |
|
||||
| :----------------------: | ---------------------------------------------------------------------- |
|
||||
| `ChatModerOrAdminFilter` | Пропускает сообщения только от модераторов и администраторов чата |
|
||||
| `ChatNotInApproveFilter` | Пропускает сообщения только из чатов, не входящих в список разрешенных |
|
||||
|
||||
## Использование
|
||||
|
||||
|
||||
@ -1,14 +1,16 @@
|
||||
# Модуль Report
|
||||
# Блок Report
|
||||
|
||||
Данный модуль даёт пользователям возможность сообщать о спам-сообщениях в чате.
|
||||
Данный блок даёт пользователям возможность сообщать о спам-сообщениях в чате.
|
||||
|
||||
## Команды
|
||||
|
||||
- `/report` — сообщить администраторам о сообщении как о спаме.
|
||||
| Команда | Описание |
|
||||
| :-------: | ------------------------------------------------ |
|
||||
| `/report` | Сообщить администраторам о сообщении как о спаме |
|
||||
|
||||
## Использование
|
||||
|
||||
Чтобы указать, что сообщении является спамом, ответьте на него, использовав команду `/report`. Модуль уведомит администраторов, которые имеют права модерации.
|
||||
Чтобы указать, что сообщении является спамом, ответьте на него, использовав команду `/report`. Блок уведомит администраторов, которые имеют права модерации.
|
||||
|
||||
### Пример использования
|
||||
|
||||
|
||||
@ -1,22 +1,10 @@
|
||||
## Модуль Welcome
|
||||
# Блоки Karkas
|
||||
|
||||
Данный модуль отвечает за верификацию новых участников чата, используя различные методы проверки. Он помогает предотвратить спам и автоматические атаки на чат, поддтверждая «человечность» новых пользователей.
|
||||
Блоки Karkas — это набор блоков для платформы «Каркас», которые добавляют функциональность ботам.
|
||||
|
||||
## Функциональность
|
||||
## Типы блоков
|
||||
|
||||
Модуль поддерживает несколько методов верификации, которые случайным образом применяются к новым участникам чата:
|
||||
|
||||
- `IAmHumanButton` — верификация с помощью кнопки;
|
||||
- `IAmHumanInput` — верификация с помощью ввода текста;
|
||||
- `MathButtonsVerification` — верификация решением математической задачи с помощью кнопок;
|
||||
- `MathInputVerificationMethod` — верификация решением математической задачи с помощью ввода;
|
||||
- `QuestionButtonsVerification` — Верификация ответом на вопрос с помощью кнопок;
|
||||
- `QuestionInputVerification` — верификация ответом на вопрос с помощью ввода.
|
||||
|
||||
## Использование
|
||||
|
||||
1. **Обработка новых участников**: когда новый участник присоединяется к чату, выбирается случайный метод верификации и создаётся задача проверки;
|
||||
2. **Верификация**:
|
||||
- **Верификация с помощью кнопок**: обработчик ожидает нажатия кнопки от пользователя и проверяет ответ;
|
||||
- **Верификация с помощью ввода текста**: обработчик проверять введённый текст и проверяет ответ.
|
||||
3. **Время на проверку**: если новый участник не проходит проверку в течение 30 секунд, его статус в чате меняется на "забанен".
|
||||
| Тип | Описание |
|
||||
| :-------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Стандартные (`standard`) | Блоки, содержащие основной функционал: управление пользователями, ролями и настройками |
|
||||
| Дополнительные (`external`) | Блоки, созданные командой разработки платформы «Каркас». Предоставляют расширенные возможности: интеграция с нейросетями, внешними сервисами и API |
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
# Ядро Karkas
|
||||
|
||||
Ядро Karkas — базовые компоненты платформы «Каркас»: система управления модулями, логирование и утилиты.
|
||||
Ядро Karkas — базовые компоненты платформы «Каркас»: система управления блоками, логирование и утилиты.
|
||||
|
||||
- **Система управления модулями** — отвечает за их загрузку, проверку зависимостей и предоставление API для межмодульного взаимодействия;
|
||||
- **Модуль логирования** — предоставляет функции для записи логов в консоль;
|
||||
- **Модуль утилит** — содержит вспомогательные функции, например, для форматирования текста.
|
||||
- **Система управления блоками** — отвечает за их загрузку, проверку зависимостей и предоставление API для межблочного взаимодействия;
|
||||
- **Блок логирования** — предоставляет функции для записи логов в консоль;
|
||||
- **Блок утилит** — содержит вспомогательные функции, например, для форматирования текста.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user