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

src/karkas_blocks/README.md

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

src/karkas_blocks/karkas_blocks/external/create_report_apps/README.md

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

src/karkas_blocks/karkas_blocks/external/yandexgpt/README.md

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

src/karkas_blocks/karkas_blocks/standard/admin/README.md

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

src/karkas_blocks/karkas_blocks/standard/command_helper/README.md

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

src/karkas_blocks/karkas_blocks/standard/config/README.md

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

src/karkas_blocks/karkas_blocks/standard/filters/README.md

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

src/karkas_blocks/karkas_blocks/standard/fsm_database_storage/README.md

@@ -1,13 +1,13 @@
-# Модуль FSM Database Storage
+# Блок FSM Database Storage
 
-Модуль `fsm_database_storage` реализует хранение состояний FSM (Finite State Machine) в базе данных.
+Данный блок реализует хранение состояний FSM (Finite State Machine) в базе данных.
 
 ## Функциональность
 
-- Сохранение состояния FSM в базу данных.
-- Получение состояния FSM из базы данных.
+- Сохранение состояния FSM в базу данных;
+- Получение состояния FSM из базы данных;
 - Обновление данных состояния FSM.
 
 ## Использование
 
-Модуль автоматически регистрирует хранилище состояний FSM при инициализации.
+Блок автоматически регистрирует хранилище состояний FSM при инициализации.

src/karkas_blocks/karkas_blocks/standard/info/README.md

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

src/karkas_blocks/karkas_blocks/standard/miniapp/README.md

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

src/karkas_blocks/karkas_blocks/standard/report/README.md

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

src/karkas_blocks/karkas_blocks/standard/roles/README.md

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

src/karkas_blocks/karkas_blocks/standard/welcome/README.md

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