0
0
mirror of https://gitflic.ru/project/maks1ms/ocab.git synced 2024-12-24 00:33:05 +03:00

улучшена документация

This commit is contained in:
Maxim Slipenko 2024-07-31 19:24:27 +03:00
parent ffa5af740e
commit 63b321a500
16 changed files with 376 additions and 17 deletions

View File

@ -9,7 +9,7 @@
## Метаинформация о модуле (info.json)
Этот файл содержит метаинформацию о модуле в формате JSON. Пример структуры info.json приведён ниже:
Этот файл содержит метаинформацию о модуле в формате JSON. Пример структуры info.json приведен ниже:
```json
{
@ -20,8 +20,26 @@
"version": "1.0.0",
"privileged": false,
"dependencies": {
"required": {
"standard.roles": "^1.0.0",
"standard.database": "^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": "*"
}
}
}
```
@ -30,31 +48,60 @@
- `name`: Название модуля.
- `description`: Описание функциональности модуля.
- `author`: Автор модуля.
- `version`: Версия модуля.
- `version`: Версия модуля в формате [SemVer](https://semver.org/).
- `privileged`: Булево значение, указывающее, является ли модуль привилегированным.
- `dependencies`: Объект, описывающий зависимости модуля от других модулей с указанием версии.
- `dependencies`: Объект, описывающий зависимости модуля от других **OCAB** модулей.
- `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 (это накладывает ряд ограничений);
- Может использовать только определенный набор разрешенных пакетов
**Непривилегированный режим** (`privileged: false`):
- Модуль выполняется в доверенной среде на основе RestrictedPython (это накладывает ряд ограничений).
- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`,
а также несколько стандартных модулей, необходимых для работы.
- Имеет доступ к пакету `ocab_core.modules_system.public_api` для взаимодействия с ботом.
Привилегированный режим (`privileged: true`):
**Привилегированный режим** (`privileged: true`):
- Модуль выполняется без ограничений.
- Имеет полный доступ ко всем пакетам.
- Имеет полный доступ ко всем пакетам, доступным в окружении.
- Должен использоваться с осторожностью и только для модулей, требующих расширенных прав.
## Жизненный цикл модуля
1. Загрузка метаданных из `info.json`
2. Проверка зависимостей
3. Загрузка кода модуля из `__init__.py`
4. Вызов функции `module_init` (если она есть)
1. Загрузка метаданных из `info.json`.
2. Проверка зависимостей:
- Проверяется наличие всех обязательных зависимостей.
- Проверяется совместимость версий зависимостей.
- Проверяется наличие Python зависимостей.
3. Загрузка кода модуля из `__init__.py`.
4. Вызов функции `module_init` (если она есть).
5. После загрузки всех модулей вызывается функция `module_late_init` (если она есть).
## Взаимодействие между модулями
Модули могут взаимодействовать друг с другом через [API](../src/ocab_core/modules_system/public_api/__init__.py), предоставляемое системой управления модулями.
Модули могут взаимодействовать друг с другом через [API](../src/ocab_core/ocab_core/modules_system/public_api/__init__.py),
предоставляемое системой управления модулями.
Например, есть функция `get_module`. Она позволяет получить модуль или предоставляемые им объекты по его идентификатору.
Например, есть функция `get_module`. Она позволяет получить модуль или предоставляемые им объекты по его
идентификатору.

View File

@ -1 +1,37 @@
# Гномик
# Gnomик
![Логотип](./docs/gnomik.jpg)
Чат-бот помощник в [ALT Gnome Chat](https://t.me/alt_gnome_chat).
ALT Regular Gnome Community - открытое сообщество пользователей операционной системы ALT Regular Gnome.
- [Канал](https://t.me/alt_gnome)
- [Wiki](https://alt-gnome.wiki)
## Описание
Gnomик - это чат-бот, разработанный на платформе Open Chat AI Bot (OCAB) для Telegram. Он предоставляет различные функции и возможности, помогающие пользователям операционной системы ALT Regular Gnome.
## Функционал
<!--
TODO: описать функционал
-->
## Запуск
Запуск бота осуществляется с помощью команды:
```bash
python -m gnomik
```
## Конфигурация
Конфигурация бота находится в файле `config.yaml`.
## Модули
Список загружаемых модулей указан в файле `__main__.py`.

BIN
src/gnomik/docs/gnomik.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 61 KiB

View File

@ -1 +1,23 @@
# OCAB Core
Это ядро OCAB, содержащее базовые компоненты:
- Система управления модулями.
- Логирование.
- Утилиты.
## Система управления модулями
Система управления модулями отвечает за:
- Загрузку модулей.
- Проверку зависимостей.
- Предоставление API для взаимодействия между модулями.
## Логирование
Модуль логирования предоставляет функции для записи логов в консоль.
## Утилиты
Модуль утилит содержит вспомогательные функции, например, для форматирования текста.

View File

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

View File

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

View File

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

View File

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

View File

@ -0,0 +1,24 @@
# Модуль Command Helper
Модуль `command_helper` упрощает регистрацию команд бота и управление ими.
## Функциональность
- Регистрация команд бота.
- Установка команд для пользователей в зависимости от их роли.
## Использование
1. Импортируйте функцию `register_command`.
2. Вызовите функцию `register_command`, передав ей название команды, ее описание и роль пользователя,
которому доступна эта команда.
## Пример
```python
from ocab_core.modules_system.public_api import get_module
register_command = get_module("standard.command_helper", "register_command")
register_command("my_command", "Описание моей команды", role="ADMIN")
```

View File

@ -0,0 +1,28 @@
# Модуль Config
Модуль `config` управляет конфигурацией бота.
## Функциональность
- Загрузка конфигурации из файла `config.yaml`.
- Сохранение конфигурации в файл.
- Регистрация параметров конфигурации.
- Получение значений параметров.
## Использование
1. Импортируйте объект `config`.
2. Вызовите метод `register`, чтобы зарегистрировать параметр конфигурации.
3. Вызовите метод `get`, чтобы получить значение параметра.
## Пример
```python
from ocab_core.modules_system.public_api import get_module
config = get_module("standard.config", "config")
config.register("my_parameter", "string", default_value="default")
value = config.get("my_parameter")
```

View File

@ -0,0 +1,29 @@
# Модуль Filters
Модуль `filters` предоставляет фильтры для aiogram, которые используются для ограничения доступа к командам
и обработчикам событий.
## Фильтры
- `ChatModerOrAdminFilter` - пропускает сообщения только от модераторов и администраторов чата.
- `ChatNotInApproveFilter` - пропускает сообщения только из чатов, не входящих в список разрешенных.
## Использование
Фильтры можно использовать в декораторах `@router.message` и `@router.callback_query`.
## Пример
```python
from aiogram import Router
from ocab_core.modules_system.public_api import get_module
ChatModerOrAdminFilter = get_module("standard.filters", "ChatModerOrAdminFilter")
router = Router()
@router.message(ChatModerOrAdminFilter())
async def admin_command(message: Message):
# Обработка команды, доступной только администраторам и модераторам.
pass
```

View File

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

View File

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

View File

@ -0,0 +1,14 @@
# Модуль Message Processing
Модуль `message_processing` обрабатывает все входящие сообщения.
## Функциональность
- Проверка чата и пользователя на наличие в базе данных.
- Обновление информации о чате и пользователе.
- Добавление статистики сообщений.
- Передача сообщения модулю `yandexgpt`, если оно соответствует условиям.
## Использование
Модуль автоматически обрабатывает все входящие сообщения.

View File

@ -0,0 +1,23 @@
# Модуль Miniapp
Модуль `miniapp` реализует веб-интерфейс для бота, доступный через Telegram Mini Apps.
## Функциональность
- Регистрация страниц веб-интерфейса.
- Авторизация пользователей через Telegram.
## Использование
1. Импортируйте функцию `register_page`.
2. Вызовите функцию `register_page`, передав ей название страницы, ее путь, blueprint Dash и префикс.
## Пример
```python
from ocab_core.modules_system.public_api import get_module
register_page = get_module("standard.miniapp", "register_page")
register_page("Моя страница", "/my_page", my_blueprint, prefix="my_page")
```

View File

@ -0,0 +1,36 @@
# Модуль Roles
Модуль `roles` управляет ролями пользователей.
## Роли
- `USER` - обычный пользователь.
- `MODERATOR` - модератор.
- `ADMIN` - администратор.
- `BOT` - бот.
## Функциональность
- Проверка роли пользователя.
- Получение имени роли по ID.
- Получение ID роли по имени.
## Использование
1. Импортируйте класс `Roles`.
2. Создайте экземпляр класса.
3. Вызовите методы класса для проверки роли пользователя или получения имени роли.
## Пример
```python
from ocab_core.modules_system.public_api import get_module
Roles = get_module("standard.roles", "Roles")
roles = Roles()
is_admin = await roles.check_admin_permission(user_id)
role_name = await roles.get_role_name(role_id)
```