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

обновил документацию

This commit is contained in:
Maxim Slipenko 2024-07-31 20:01:32 +03:00
parent 63b321a500
commit 9fa23f18b9
5 changed files with 111 additions and 99 deletions

View File

@ -1,60 +1,44 @@
# OpenChatAiBot V2 # OCAB - Open Chat Ai Bot
## Что такое OCAB? ## Что такое OCAB?
OCAB - это бот для Telegram, который призван помочь во взаимодействии с чатом. OCAB - это платформа для разработки модульных Telegram-ботов, которая призвана упростить взаимодействие с чатами.
Бот поддерживает интеграцию модулей для расширения функционала. OCAB предоставляет возможность расширять функциональность бота с помощью интеграции различных модулей.
Фактически бот является платформой для запуска созданных для него модулей. Код платформы и набор стандартных модулей находятся в этом монорепозитории.
Модули могут взаимодействовать друг с другом или быть полностью независимыми.
## Что такое модуль? ## Структура монорепозитория
Модуль - это директория, которая содержит в себе код модуля и его конфигурацию. Монорепозиторий OCAB включает в себя:
* **Ядро OCAB (src/ocab_core):** Содержит основные компоненты платформы, такие как система управления модулями,
логирование и утилиты.
* **Модули OCAB (src/ocab_modules):** Содержит стандартные и дополнительные модули, которые расширяют
функциональность ботов OCAB.
* **Пример бота (src/gnomik):** Пример реализации бота на платформе OCAB.
## Модули
Модули OCAB - это независимые компоненты, которые добавляют функциональность к боту.
### Структура модуля ### Структура модуля
*Будет дополнено после закрытия [issue #17](https://gitflic.ru/project/armatik/ocab/issue/17).* Структура модуля представлена [здесь](docs/MODULES-SPEC.md).
## Стандартные модули ### Стандартные модули
В стандартный состав бота входят следующие модули: Стандартные модули предоставляют базовые функции для работы бота:
* [admin](src/ocab_modules/ocab_modules/standard/admin/README.md) - модуль для модерирования чата.
* [roles](src/ocab_modules/ocab_modules/standard/roles/README.md) - модуль ролей пользователей.
* [config](src/ocab_modules/ocab_modules/standard/config/README.md) - модуль управления конфигурацией бота.
* [database](src/ocab_modules/ocab_modules/standard/database/README.md) - модуль для работы с базой данных.
* [fsm_database_storage](src/ocab_modules/ocab_modules/standard/fsm_database_storage/README.md) - модуль для хранения состояний FSM в базе данных.
* [filters](src/ocab_modules/ocab_modules/standard/filters/README.md) - модуль, предоставляющий фильтры для aiogram.
* [message_processing](src/ocab_modules/ocab_modules/standard/message_processing/README.md) - модуль обработки входящих сообщений.
* [miniapp](src/ocab_modules/ocab_modules/standard/miniapp/README.md) - модуль для реализации веб-интерфейса бота.
* [command_helper](src/ocab_modules/ocab_modules/standard/command_helper/README.md) - модуль для упрощения регистрации команд бота.
* [info](src/ocab_modules/ocab_modules/standard/info/README.md) - модуль предоставления информации о пользователях и чатах.
* `admin` - модуль для модерирования чата. Позволяет удалять сообщения, банить пользователей и т.д. ### Дополнительные официальные модули
* `reputation` - модуль репутации пользователей. Позволяет оценивать ответы пользователей и накапливать репутацию.
* `welcome` - модуль приветствия новых пользователей. Позволяет приветствовать новых пользователей в чате, а также
проверять пользователя капчей для предотвращения спама.
* `roles` - модуль ролей. Позволяет назначать пользователям роли и ограничивать доступ к командам бота по ролям.
Является важной частью системы прав доступа и модуля `admin`.
## Дополнительные официальные модули Дополнительные официальные модули разработаны командой OCAB и предоставляют расширенные возможности для бота:
* [yandexgpt](src/ocab_modules/ocab_modules/external/yandexgpt/README.md) - модуль для интеграции с нейросетью YandexGPT.
* `yandexgpt` - модуль для генерации ответов на основе нейросети GPT-3.5. Позволяет боту отвечать на сообщения * [create_report_apps](src/ocab_modules/ocab_modules/external/create_report_apps/README.md) - модуль для создания отчетов об ошибках.
пользователей, используя нейросеть. Ключевой особенностью является построение линии контекста для нейросети,
которая позволяет боту отвечать на вопросы, используя контекст предыдущих сообщений. Для этого используется
модуль база данных хранящий историю сообщений.
<!--
* `bugzilla` - модуль для интеграции с BugZilla. Позволяет получать уведомления о новых багах в BugZilla, отслеживать их
статус, формировать стандартизированные сообщения для корректного описания багов. В будущем планируется интеграция с
API BugZilla для возможности создания багов из чата.
* `alt_packages` - модуль для интеграции с AltLinux Packages. Позволяет получать уведомления о новых пакетах в репозитории
AltLinux, поиска пакетов по названию, получения истории изменений, команды для установки пакета из репозитория и
прочей информации о пакете.
* `notes` - модуль заметок. Позволяет сохранять заметки для пользователей и чатов. Заметки являются ссылками на
сообщения в чате.
-->
Список модулей будет пополняться. Идеи для модулей можно оставлять в [issues](https://gitflic.ru/project/armatik/ocab/issue/create).
## Установка бота
### Docker
### Вручную
## Технологический стек
* Python 3.11.6 или выше - основной язык программирования.
* SQLite 3 - база данных для хранения информации о чате и пользователях.
* [Poetry](https://gitflic.ru/project/armatik/ocab/blob?file=how-to%20install%20deps.md&branch=OCAB-V2) - менеджер зависимостей.
* aiogram 3 - библиотека для работы с Telegram API.
* peewee - ORM для работы с базой данных.

39
docs/DEV.md Normal file
View File

@ -0,0 +1,39 @@
## Настройка рабочего окружения
Данная инструкция поможет вам настроить рабочее окружение для разработки OCAB.
### Предварительные требования
* **Python 3.12:** OCAB требует Python 3.12.
* **VSCode:** Рекомендуется использовать VSCode для разработки.
* **Git:** У вас должен быть установлен Git для клонирования репозитория.
### Шаги
1. **Клонируйте репозиторий:**
```bash
git clone https://gitflic.ru/project/armatik/ocab.git
```
2. **Откройте проект в VSCode:**
* Откройте папку `ocab` в VSCode.
* VSCode автоматически предложит открыть проект как workspace, используя файл `ocab.code-workspace`.
Нажмите "Открыть Workspace", чтобы принять предложение.
3. **Настройте Poetry:**
* Установите Poetry, следуя инструкциям на официальном сайте: [https://python-poetry.org/docs/](https://python-poetry.org/docs/).
* **Для каждого пакета:**
* Перейдите в папку пакета (например, `src/ocab_core`).
* Выполните команду `poetry install`, чтобы установить зависимости пакета.
* Poetry создаст виртуальное окружение внутри папки пакета (`.venv`).
4. **Активируйте виртуальное окружение:**
* Выполните команду `poetry shell` в папке пакета, чтобы активировать виртуальное окружение.
Теперь ваше рабочее окружение настроено, и вы можете начать.
### Дополнительная информация
* Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости.
* Poetry автоматически управляет виртуальными окружениями для каждого пакета.
* Вы можете использовать команду `poetry add <package_name>` для добавления новых зависимостей.

View File

@ -1,47 +0,0 @@
## Poetry
### Установка с официального сайта
```shell
curl -sSL https://install.python-poetry.org | python3 -
```
### Установка с PyPi
```shell
python3 -m pip install poetry
```
Доп информация:https://www.8host.com/blog/ustanovka-menedzhera-zavisimostej-poetry/
## Зависимости
### Добавление зависимости
```shell
poetry add NAME
```
`NAME` - название зависимости.
### Установка зависимостей
```shell
poetry install
```
### Обновление зависимостей
```shell
poetry update
```
## Виртуальное окружение
### Создание/активация
```shell
poetry shell
```
### Настройка
Хранить окружение внутри проекта
```shell
poetry config virtualenvs.in-project true
```

View File

@ -22,8 +22,26 @@ 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` на пути к вашим локальным файлам конфигурации и паки для базы данных.
### Вручную
1. Активируйте виртуальное окружение Gnomика:
```bash
poetry shell
```
2. Запустите бота:
```bash ```bash
python -m gnomik python -m gnomik
``` ```

View File

@ -0,0 +1,18 @@
core:
mode: WEBHOOK
token: xxx
webhook:
public_url: xxx
filters:
approved_chat_id: -4128011756 | -4128011756
default_chat_tag: '@alt_gnome_chat'
miniapp:
public_url: xxx
yandexgpt:
catalogid: xxx
inword: помогите | не работает
prompt: Ты чат-бот ...
startword: Бот| Бот, | бот | бот,
token: xxx
token_for_answer: 2000
token_for_request: 8000