96 lines
4.4 KiB
Markdown
96 lines
4.4 KiB
Markdown
# BotPages
|
||
|
||
BotPages — кроссплатформенный фреймворк для создания диалоговых ботов с системой страниц (page‑based conversational framework).
|
||
|
||
Цели проекта:
|
||
- Простая модель страниц и навигации.
|
||
- Портируемость между мессенджерами через адаптеры.
|
||
- Поддержка middleware и декларативной системы команд.
|
||
- Минимум boilerplate и удобный developer experience.
|
||
|
||
Структура репозитория
|
||
|
||
- `BotPages.Core` — ядро фреймворка: навигация, страницы, маршрутизация, реестр команд, middleware, абстракции адаптеров и хранилища состояния.
|
||
- `BotPages.Telegram` — адаптер для Telegram Bot API (реализация `IMessangerAdapterSetup`/`IMessengerAdapter`).
|
||
- `Demo` — пример приложения с несколькими страницами и конфигурацией адаптера.
|
||
- `BotPages` — мета‑проект для упаковки библиотек.
|
||
- `docs/` — внутренняя документация проекта (Quickstart, API reference и т.д.).
|
||
|
||
Требования
|
||
|
||
- .NET 8 SDK
|
||
- C# 12
|
||
|
||
Быстрый старт (локально)
|
||
|
||
1. Клонируйте репозиторий:
|
||
|
||
```bash
|
||
git clone https://git.frigat.duckdns.org/FrigaT/BotPages.git
|
||
cd BotPages
|
||
```
|
||
|
||
2. Соберите решения:
|
||
|
||
```bash
|
||
dotnet build
|
||
```
|
||
|
||
3. Запуск демо (Telegram):
|
||
|
||
- Установите переменную окружения `TELEGRAM_TOKEN` с токеном бота.
|
||
|
||
```bash
|
||
setx TELEGRAM_TOKEN "<token>" # Windows
|
||
export TELEGRAM_TOKEN="<token>" # Linux/macOS
|
||
```
|
||
|
||
- Запустите demo:
|
||
|
||
```bash
|
||
dotnet run --project Demo
|
||
```
|
||
|
||
Основные концепции
|
||
|
||
- `BotPagesApp` — точка конфигурации приложения: регистрация адаптеров, middleware, маршрутов и команд, запуск.
|
||
- `Page`, `StatefulPage`, `SingletonPage` — модели страниц с жизненным циклом (`OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError`).
|
||
- `NavigationService` — управление переходами между страницами и определение текущей страницы по сессии.
|
||
- `CommandsRegistry` — шаблоны команд вида `/cmd {arg} {opt?}` с поддержкой именованных и опциональных аргументов.
|
||
- `IPageMiddleware` — middleware-конвейер, выполняющийся для каждого апдейта.
|
||
- `IMessangerAdapterSetup` / `IMessengerAdapter` — интерфейсы, позволяющие подключать новые мессенджеры.
|
||
|
||
Документация
|
||
|
||
Полная внутренняя документация находится в `docs/`:
|
||
- `docs/GETTING_STARTED.md` — быстрый старт и примеры конфигурации.
|
||
- `docs/API_REFERENCE.md` — краткий reference публичных API.
|
||
- `docs/PROJECT_DOCUMENTATION.md` — обзор архитектуры и компонентов.
|
||
|
||
XML‑документация генерируется при сборке (опция `GenerateDocumentationFile` в `.csproj`), её можно использовать для генерации HTML‑референса (docfx, MkDocs и т.п.).
|
||
|
||
Примеры использования
|
||
|
||
```csharp
|
||
var app = new BotPagesApp(stateStorage, logger)
|
||
.AddAdapter("telegram", new TelegramAdapterSetup(token))
|
||
.AddDefaultPage<WelcomePage>()
|
||
.MapCommand<WelcomePage>("/start")
|
||
.AddMiddleware(new LoggingMiddleware(logger));
|
||
|
||
await app.Build(CancellationToken.None);
|
||
```
|
||
|
||
Вклад и тестирование
|
||
|
||
- Принимам пулл‑реквесты. Описание PR должно содержать цель и краткое описание изменения.
|
||
- Следуйте единому стилю кода и включённым nullable-аннотациям.
|
||
|
||
Лицензия
|
||
|
||
Проект распространяется под лицензией MIT. Смотрите файл `LICENSE`.
|
||
|
||
Контакты
|
||
|
||
Автор: FrigaT
|
||
Репозиторий: https://git.frigat.duckdns.org/FrigaT/BotPages |