mirror of
https://gitflic.ru/project/maks1ms/ocab.git
synced 2024-12-23 16:23:01 +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 - это бот для 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`.
|
||||
### Дополнительные официальные модули
|
||||
|
||||
## Дополнительные официальные модули
|
||||
|
||||
* `yandexgpt` - модуль для генерации ответов на основе нейросети GPT-3.5. Позволяет боту отвечать на сообщения
|
||||
пользователей, используя нейросеть. Ключевой особенностью является построение линии контекста для нейросети,
|
||||
которая позволяет боту отвечать на вопросы, используя контекст предыдущих сообщений. Для этого используется
|
||||
модуль база данных хранящий историю сообщений.
|
||||
<!--
|
||||
* `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 для работы с базой данных.
|
||||
Дополнительные официальные модули разработаны командой OCAB и предоставляют расширенные возможности для бота:
|
||||
* [yandexgpt](src/ocab_modules/ocab_modules/external/yandexgpt/README.md) - модуль для интеграции с нейросетью YandexGPT.
|
||||
* [create_report_apps](src/ocab_modules/ocab_modules/external/create_report_apps/README.md) - модуль для создания отчетов об ошибках.
|
||||
|
||||
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
|
||||
python -m gnomik
|
||||
```
|
||||
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
|
||||
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