mirror of
https://gitflic.ru/project/maks1ms/ocab.git
synced 2024-12-24 00:33:05 +03:00
обновил документацию
This commit is contained in:
parent
63b321a500
commit
9fa23f18b9
80
README.md
80
README.md
@ -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
39
docs/DEV.md
Normal 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>` для добавления новых зависимостей.
|
||||||
@ -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
|
|
||||||
```
|
|
||||||
@ -22,11 +22,29 @@ TODO: описать функционал
|
|||||||
|
|
||||||
## Запуск
|
## Запуск
|
||||||
|
|
||||||
Запуск бота осуществляется с помощью команды:
|
### Docker
|
||||||
|
|
||||||
```bash
|
1. Соберите Docker-образ:
|
||||||
python -m gnomik
|
```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
|
||||||
|
python -m gnomik
|
||||||
|
```
|
||||||
|
|
||||||
## Конфигурация
|
## Конфигурация
|
||||||
|
|
||||||
|
|||||||
18
src/gnomik/config-example.yaml
Normal file
18
src/gnomik/config-example.yaml
Normal 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
|
||||||
Loading…
Reference in New Issue
Block a user