Рефакторинг файлов README.md и документации

2024-12-24 08:34:42 +03:00 · 2024-08-24 15:34:13 +03:00 · 2024-08-24 15:34:13 +03:00 · eac32d5215
commit eac32d5215
parent 805bbcd8f9
12 changed files with 164 additions and 185 deletions
--- a/2
+++ b/2
@ -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
--- a/README.md
+++ b/README.md
@ -1,23 +1,20 @@
-# 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 — это независимые компоненты, которые добавляют функциональность бота.

 ### Структура модуля

@ -25,20 +22,24 @@ Karkas предоставляет возможность расширять фу

 ### Стандартные модули

-Стандартные модули предоставляют базовые функции для работы бота:
-* [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) — модуль предоставления информации о пользователях и чатах.

 ### Дополнительные официальные модули

-Дополнительные официальные модули разработаны командой 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) - модуль для создания отчетов об ошибках.
+Дополнительные официальные модули созданы командой разработки платформы «Каркас» и предоставляют расширенные возможности для бота:
+
+- [`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) — модуль для создания отчётов об ошибках.
--- a/docs/DEV.md
+++ b/docs/DEV.md
@ -1,39 +1,34 @@
-## Настройка рабочего окружения
+# Настройка рабочего окружения

 Данная инструкция поможет вам настроить рабочее окружение для разработки Karkas.

-### Предварительные требования
+## Предварительные требования

-* **Python 3.12:** Karkas требует Python 3.12.
-* **VSCode:** Рекомендуется использовать VSCode для разработки.
-* **Git:**  У вас должен быть установлен Git для клонирования репозитория.
+- **Python** — платформа «Каркас» требует интерпретатор языка Python версии 3.12;
+- **VSCode** — рекомендованная среда разработки;
+- **Git** — инструмент контроля версий, необходим клонирования репозиториянео.

-### Шаги
+## Шаги

-1. **Клонируйте репозиторий:**
-   ```bash
-   git clone https://gitflic.ru/project/alt-gnome/karkas.git
-   ```
+1. Клонируйте репозиторий с помощью утилиты `git`:

-2. **Откройте проект в VSCode:**
-   * Откройте папку `karkas` в VSCode.
-   * VSCode автоматически предложит открыть проект как workspace, используя файл `karkas.code-workspace`.
-     Нажмите "Открыть Workspace", чтобы принять предложение.
+```shell
+git clone https://gitflic.ru/project/alt-gnome/karkas.git
+```

-3. **Настройте Poetry:**
-   * Установите Poetry, следуя инструкциям на официальном сайте: [https://python-poetry.org/docs/](https://python-poetry.org/docs/).
-   * **Для каждого пакета:**
-     * Перейдите в папку пакета (например, `src/karkas_core`).
-     * Выполните команду `poetry install`, чтобы установить зависимости пакета.
-     * Poetry создаст виртуальное окружение внутри папки пакета (`.venv`).
+2. Откройте папку `karkas` в VSCode. Среда разработки автоматически предложит открыть проект как Workspace, используя файл `karkas.code-workspace`. Нажмите `Открыть Workspace`, чтобы принять предложение;

-4. **Активируйте виртуальное окружение:**
-   * Выполните команду `poetry shell` в папке пакета, чтобы активировать виртуальное окружение.
+3. Установите инструмент Poetry, следуя инструкциям из [официальной документации](https://python-poetry.org/docs/). Для каждого пакета выполните следующую последовательность действий:

-Теперь ваше рабочее окружение настроено, и вы можете начать.
+   - Перейдите в папку пакета (например, `src/karkas_core`);
+   - Выполните команду `poetry install`, чтобы установить зависимости пакета. После этого будет создано виртуальное окружене (`.venv`);

-### Дополнительная информация
+4. Выполните команду `poetry shell` в папке пакета, над которым будут производится работы, чтобы активировать виртуальное окружение.

-* Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости.
-* Poetry автоматически управляет виртуальными окружениями для каждого пакета.
-* Вы можете использовать команду `poetry add <package_name>` для добавления новых зависимостей.
+Теперь рабочее окружение настроено!
+
+## Дополнительная информация
+
+- Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости;
+- Poetry автоматически управляет виртуальными окружениями для каждого пакета;
+- Вы можете использовать команду `poetry add <package_name>` (где `<package_name>` — имя пакета) для добавления новых зависимостей.
--- a/docs/MODULES-SPEC.md
+++ b/docs/MODULES-SPEC.md
@ -2,14 +2,15 @@

 > **Внимание!**
 >
-> Данная спецификация еще не закончена и активно разрабатывается.
-> Могут быть значительные изменения (breaking changes).
+> Данная спецификация ещё не закончена и активно разрабатывается.
+>
+> Могут возникнуть изменения, которые не будут обратно совместимы (breaking changes).

-Каждый модуль представлен в виде папки, содержащей два обязательных файла: info.json и `__init__.py`.
+Каждый модуль представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`.

-## Метаинформация о модуле (info.json)
+## Метаданные модуля (`info.json`)

-Этот файл содержит метаинформацию о модуле в формате JSON. Пример структуры info.json приведен ниже:
+Файл `info.json` содержит информацию о модуле в формате JSON. Пример структуры `info.json` приведён ниже:

 ```json
 {
@ -24,9 +25,7 @@
      "standard.roles": "^1.0.0",
      "standard.database": {
        "version": "^1.0.0",
-        "uses": [
-          "db_api"
-        ]
+        "uses": ["db_api"]
      }
    },
    "optional": {
@ -44,64 +43,63 @@
 }
 ```

- `id`: Уникальный идентификатор модуля.
- `name`: Название модуля.
- `description`: Описание функциональности модуля.
- `author`: Автор модуля.
- `version`: Версия модуля в формате [SemVer](https://semver.org/).
- `privileged`: Булево значение, указывающее, является ли модуль привилегированным.
- `dependencies`: Объект, описывающий зависимости модуля от других **Karkas** модулей.
-    - `required`: Обязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`.
-    - `optional`: Необязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`.
- `pythonDependencies`: Объект, описывающий зависимости модуля от внешних Python пакетов.
-    - `required`: Обязательные зависимости. Ключ - название пакета, значение - версия.
-    - `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` позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов модуля (`uses`). Если `uses` не указан, то доступ к модулю целиком запрещён. Пример объекта `DependencyInfo`:

 ```json
 {
  "version": "^1.0.0",
-  "uses": [
-    "db_api"
-  ]
+  "uses": ["db_api"]
 }
 ```

- `version`: Версия модуля.
- `uses`: Список разрешенных атрибутов модуля.
+|   Поле    | Описание                             |
+| :-------: | ------------------------------------ |
+| `version` | Версия модуля                        |
+|  `uses`   | Список используемых атрибутов модуля |

-## Режимы выполнения модулей
+## Режимы работы модулей

-**Непривилегированный режим** (`privileged: false`):
- Модуль выполняется в доверенной среде на основе RestrictedPython (это накладывает ряд ограничений).
- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`,
-  а также несколько стандартных модулей, необходимых для работы.
+### Непривилегированный режим (`privileged: false`)
+
+- Модуль выполняется в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений;
+- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`, а также несколько стандартных модулей, необходимых для работы;
 - Имеет доступ к пакету `karkas_core.modules_system.public_api` для взаимодействия с ботом.

-**Привилегированный режим** (`privileged: true`):
- Модуль выполняется без ограничений.
- Имеет полный доступ ко всем пакетам, доступным в окружении.
+### Привилегированный режим (`privileged: true`)
+
+- Модуль выполняется без ограничений;
+- Имеет полный доступ ко всем пакетам, доступным в окружении;
 - Должен использоваться с осторожностью и только для модулей, требующих расширенных прав.

 ## Жизненный цикл модуля

-1. Загрузка метаданных из `info.json`.
+1. Загрузка метаданных из `info.json`;
 2. Проверка зависимостей:
-    - Проверяется наличие всех обязательных зависимостей.
-    - Проверяется совместимость версий зависимостей.
-    - Проверяется наличие Python зависимостей.
-3. Загрузка кода модуля из `__init__.py`.
-4. Вызов функции `module_init` (если она есть).
-5. После загрузки всех модулей вызывается функция `module_late_init` (если она есть).
+   - Проверка всех обязательных зависимостей;
+   - Проверка совместимости версий зависимостей;
+   - Проверка зависимостей Python;
+3. Загрузка кода модуля из `__init__.py`;
+4. Вызов функции `module_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` для получения модуля или предоставляемых им объекты по идентификатору.
--- a/src/altlinux/README.md
+++ b/src/altlinux/README.md
@ -2,47 +2,54 @@

 ## Описание

-Подготовленная версия Karkas для интеграции в чат [Альт Линукс](https://t.me/alt_linux)
+Бот, созданный на основе платформы «Каркас» и подготовленный для интеграции в чат [Альт Линукс](https://t.me/alt_linux)

 ## Функционал
-Список OCAB-модулей используемых в боте:

-* report - Вызов администрации чата одной командой
-* welcome - Автоматическая вариативная проверка пользователей на признаки бота или другой автоматической рекламной системы
-* help - Получение справки о боте
+Список модулей, используемых в боте:
+
+- `report` — вызов администрации чата одной командой;
+- `welcome` — автоматическая вариативная проверка пользователей на признаки бота или другой рекламной системы;
+- `help` — получение справки о боте.

 ## Запуск

-### Docker
+### Через Docker образ
+
+1. Соберите Docker образ:
+
+```shell
+docker build -t altlinux -f Dockerfile ../..
+```

-1. Соберите Docker-образ:
-    ```bash
-    docker build -t altlinux -f Dockerfile ../..
-    ```
 2. Запустите контейнер:
-    ```bash
-    docker run -v ./config.yaml:/app/config.yaml altlinux
-    ```

-    Замените `./config.yaml` на путь к вашему локальному файлу конфигурации.
+```shell
+docker run -v ./config.yaml:/app/config.yaml altlinux
+```
+
+Замените `./config.yaml` на путь к вашему локальному файлу конфигурации.

 ### Вручную

 1. Активируйте виртуальное окружение:
-    ```bash
-    poetry shell
-    ```
+
+```shell
+poetry shell
+```
+
 2. Запустите бота:
-    ```bash
-    python -m altlinux
-    ```
+
+```shell
+python -m altlinux
+```

 ## Конфигурация

 Конфигурация хранится в файле `config.yaml`.

-Пример конфигурации бота находится в файле `config-example.yaml`.
+Пример конфигурации бота находится в файле [`config-example.yaml`](./config-example.yaml).

 ## Модули

-Список загружаемых модулей указан в файле `__main__.py`.
+Список загружаемых модулей указан в файле [`__main__.py`](./altlinux/__main__.py).
--- a/src/karkas_blocks/README.md
+++ b/src/karkas_blocks/README.md
@ -1,12 +1,8 @@
-# Karkas Blocks
+# Блоки Karkas

-Karkas Blocks содержит набор модулей для платформы Open Chat AI Bot (Karkas).
+Блоки Karkas — это набор «блоков» (модулей) для платформы «Каркас», которые добавляют функциональность ботам.

-## Описание
+## Типы блоков

-Karkas - это платформа для создания чат-ботов Telegram. Модули - это расширения, которые добавляют функциональность ботам Karkas.
-
-## Типы модулей
-
-* **Стандартные модули (standard.*):** Предоставляют основные функции, такие как управление пользователями, ролями и настройками.
-* **Дополнительные официальные модули (external.*):** Разработаны командой Karkas и предоставляют расширенные возможности, такие как интеграция с нейросетями, внешними сервисами и API.
+- **Стандартные (`standard`)** — блоки, содержащие основной функционал: управление пользователями, ролями и настройками;
+- **Дополнительные (`external`)** — блоки, созданные командой разработки платформы «Каркас». Предоставляют расширенные возможности: интеграция с нейросетями, внешними сервисами и API.
--- a/src/karkas_blocks/karkas_blocks/standard/command_helper/README.md
+++ b/src/karkas_blocks/karkas_blocks/standard/command_helper/README.md
@ -1,17 +1,16 @@
 # Модуль Command Helper

-Модуль `command_helper` упрощает регистрацию команд бота и управление ими.
+Данный для упрощения регистрации команд бота и управления ими.

 ## Функциональность

- Регистрация команд бота.
+- Регистрация команд бота;
 - Установка команд для пользователей в зависимости от их роли.

 ## Использование

-1. Импортируйте функцию `register_command`.
-2. Вызовите функцию `register_command`, передав ей название команды, ее описание и роль пользователя,
-   которому доступна эта команда.
+1. Импортируйте функцию `register_command`;
+2. Вызовите функцию `register_command`, передав ей название команды, её описание и роль пользователей, которым доступна она будет доступна.

 ## Пример

--- a/src/karkas_blocks/karkas_blocks/standard/config/README.md
+++ b/src/karkas_blocks/karkas_blocks/standard/config/README.md
@ -1,18 +1,18 @@
 # Модуль Config

-Модуль `config` управляет конфигурацией бота.
+Данный модуль позволяет управляет конфигурацией бота.

 ## Функциональность

- Загрузка конфигурации из файла `config.yaml`.
- Сохранение конфигурации в файл.
- Регистрация параметров конфигурации.
+- Загрузка конфигурации из файла `config.yaml`;
+- Сохранение конфигурации в файл;
+- Регистрация параметров конфигурации;
 - Получение значений параметров.

 ## Использование

-1. Импортируйте объект `config`.
-2. Вызовите метод `register`, чтобы зарегистрировать параметр конфигурации.
+1. Импортируйте объект `config`;
+2. Вызовите метод `register`, чтобы зарегистрировать параметр конфигурации;
 3. Вызовите метод `get`, чтобы получить значение параметра.

 ## Пример
--- a/src/karkas_blocks/karkas_blocks/standard/filters/README.md
+++ b/src/karkas_blocks/karkas_blocks/standard/filters/README.md
@ -1,12 +1,12 @@
 # Модуль Filters

-Модуль `filters` предоставляет фильтры для aiogram, которые используются для ограничения доступа к командам
+Данный модуль предоставляет фильтры для `aiogram`, которые используются для ограничения доступа к командам
 и обработчикам событий.

 ## Фильтры

- `ChatModerOrAdminFilter` - пропускает сообщения только от модераторов и администраторов чата.
- `ChatNotInApproveFilter` - пропускает сообщения только из чатов, не входящих в список разрешенных.
+- `ChatModerOrAdminFilter` — пропускает сообщения только от модераторов и администраторов чата;
+- `ChatNotInApproveFilter` — пропускает сообщения только из чатов, не входящих в список разрешенных.

 ## Использование

--- a/src/karkas_blocks/karkas_blocks/standard/report/README.md
+++ b/src/karkas_blocks/karkas_blocks/standard/report/README.md
@ -1,18 +1,16 @@
 # Модуль Report

-Модуль `report` позволяет пользователям сообщать о спам-сообщениях в чате.
+Данный модуль даёт пользователям возможность сообщать о спам-сообщениях в чате.

 ## Команды

- `/report` - пожаловаться на сообщение как на спам.
+- `/report` — сообщить администраторам о сообщении как о спаме.

 ## Использование

-Чтобы сообщить о сообщении как о спаме, отправьте команду `/report`, ответив на сообщение, которое вы хотите отметить. Модуль уведомит администраторов, которые имеют права модерации.
+Чтобы указать, что сообщении является спамом, ответьте на него, использовав команду `/report`. Модуль уведомит администраторов, которые имеют права модерации.

 ### Пример использования

-1. Найдите сообщение, которое вы хотите отметить как спам.
-2. Ответьте на это сообщение командой `/report`.
-
-Примечание: Команда `/report` должна быть отправлена в ответ на сообщение, которое вы хотите отметить.
+1. Найдите сообщение, которое вы хотите отметить как спам;
+2. Ответьте на это сообщение, указав при этом команду `/report`.
--- a/src/karkas_blocks/karkas_blocks/standard/welcome/README.md
+++ b/src/karkas_blocks/karkas_blocks/standard/welcome/README.md
@ -1,21 +1,22 @@
 ## Модуль Welcome

-Модуль `welcome` отвечает за верификацию новых участников чата, используя различные методы проверки. Он помогает предотвратить спам и автоматические атаки на чат, обеспечивая, что новые участники подтверждают свою человеческую природу перед получением доступа.
+Данный модуль отвечает за верификацию новых участников чата, используя различные методы проверки. Он помогает предотвратить спам и автоматические атаки на чат, поддтверждая «человечность» новых пользователей.

-## Команды и Методы
+## Функциональность

 Модуль поддерживает несколько методов верификации, которые случайным образом применяются к новым участникам чата:

- **IAmHumanButton** - Верификация с помощью кнопки.
- **IAmHumanInput** - Верификация с помощью ввода текста.
- **MathButtonsVerification** - Верификация решением математической задачи с помощью кнопок.
- **MathInputVerificationMethod** - Верификация решением математической задачи с помощью ввода.
- **QuestionButtonsVerification** - Верификация ответом на вопрос с помощью кнопок.
- **QuestionInputVerification** - Верификация ответом на вопрос с помощью ввода.
+- `IAmHumanButton` — верификация с помощью кнопки;
+- `IAmHumanInput` — верификация с помощью ввода текста;
+- `MathButtonsVerification` — верификация решением математической задачи с помощью кнопок;
+- `MathInputVerificationMethod` — верификация решением математической задачи с помощью ввода;
+- `QuestionButtonsVerification` — Верификация ответом на вопрос с помощью кнопок;
+- `QuestionInputVerification` — верификация ответом на вопрос с помощью ввода.

-## Как это работает
+## Использование

-1. **Обработка новых участников**: Когда новый участник присоединяется к чату, выбирается случайный метод верификации, и создается задача проверки.
-2. **Тайм-аут проверки**: Если новый участник не проходит проверку в течение 30 секунд, его статус в чате меняется на "забанен".
-3. **Верификация по кнопкам**: Если верификация осуществляется с помощью кнопок, обработчик будет ожидать нажатие кнопки от пользователя и проверит правильность ответа.
-4. **Верификация по вводу**: Если верификация осуществляется путем ввода текста, обработчик будет проверять введенный текст и действовать в зависимости от результата проверки.
+1. **Обработка новых участников**: когда новый участник присоединяется к чату, выбирается случайный метод верификации и создаётся задача проверки;
+2. **Верификация**:
+   - **Верификация с помощью кнопок**: обработчик ожидает нажатия кнопки от пользователя и проверяет ответ;
+   - **Верификация с помощью ввода текста**: обработчик проверять введённый текст и проверяет ответ.
+3. **Время на проверку**: если новый участник не проходит проверку в течение 30 секунд, его статус в чате меняется на "забанен".
--- a/src/karkas_core/README.md
+++ b/src/karkas_core/README.md
@ -1,23 +1,7 @@
-# Karkas Core
+# Ядро Karkas

-Это ядро Karkas, содержащее базовые компоненты:
+Ядро Karkas — базовые компоненты платформы «Каркас»: система управления модулями, логирование и утилиты.

- Система управления модулями.
- Логирование.
- Утилиты.
-
-## Система управления модулями
-
-Система управления модулями отвечает за:
-
- Загрузку модулей.
- Проверку зависимостей.
- Предоставление API для взаимодействия между модулями.
-
-## Логирование
-
-Модуль логирования предоставляет функции для записи логов в консоль.
-
-## Утилиты
-
-Модуль утилит содержит вспомогательные функции, например, для форматирования текста.
+- **Система управления модулями** — отвечает за их загрузку, проверку зависимостей и предоставление API для межмодульного взаимодействия;
+- **Модуль логирования** — предоставляет функции для записи логов в консоль;
+- **Модуль утилит** — содержит вспомогательные функции, например, для форматирования текста.