Skip to content

Начало работы с codex-bot

Этот гайд поможет вам пройти путь от настройки окружения до создания первой фичи с использованием лучших практик codex-bot.

💎 Философия: Универсальный конструктор

codex-bot — это эволюционирующий конструктор с «батарейками внутри». Он спроектирован как гибкий инструмент, который кратно ускоряет разработку сложных систем, предлагая готовые архитектурные решения для типовых задач.

Фреймворк поддерживает самые разные сценарии использования:

  • Автономный бот: Вся бизнес-логика реализуется непосредственно внутри бота.
  • Умный клиент: Бот выступает в роли интерфейса, который запрашивает данные через API и визуализирует их для пользователя.
  • Событийный шлюз: Прием внешних хуков от вашего бэкенда для мгновенной отправки уведомлений в каналы или личные сообщения.
  • Цифровой ассистент: Сопровождение пользователя по сложным сценариям с сохранением контекста и синхронизацией состояний.

Главная сила codex-bot раскрывается в работе в составе комплексных экосистем (в связке с сайтами, воркерами и API), где он становится надежным мостом между вашим бэкендом и пользователем в Telegram.

🚀 Шаг 1: Подготовка окружения

Для чистоты и порядка всегда используйте виртуальное окружение.

  1. Создайте папку вашего проекта: bash mkdir my_project && cd my_project

  2. Создайте и активируйте виртуальное окружение: bash python -m venv venv # Для Windows: venv\Scripts\activate # Для Linux/macOS: source venv/bin/activate

  3. Установите фреймворк: bash pip install codex-bot

🛠️ Шаг 2: Инициализация проекта

Запустите команду инициализации прямо из корня вашего проекта. CLI развернет необходимую инфраструктуру в текущей папке, а код бота изолирует в директории src/.

codex-bot startproject my_bot

Что произойдет:

  • В корне появятся файлы управления: pyproject.toml, manage.py, .env.
  • В папке src/my_bot/ будет создан скелет кода вашего бота.
  • Если вы запускаете команду в существующем проекте (Django, FastAPI), CLI предложит режим Smart Merge, создав конфиги с суффиксом .bot.

После генерации установите зависимости вашего проекта:

pip install -e .

🧩 Шаг 3: Создание первой фичи

Фичи — это независимые модули вашего бота. Давайте создадим фичу "Профиль":

codex-bot create-feature profile

CLI создаст папку src/my_bot/features/telegram/profile/ с полной структурой: Handlers, Logic, UI. Добавьте её в INSTALLED_FEATURES в файле settings.py.

✍️ Шаг 4: Написание логики (Best Practices)

В logic/orchestrator.py мы рекомендуем использовать встроенные "батарейки": StateManager и Smart Resolver.

async def render_content(self, payload: Any, director: Director) -> ViewResultDTO:
    # 1. Изолированное состояние фичи
    fsm = ProfileStateManager(director.state)

    # 2. Умный запрос данных (авто-навигация от бэкенда)
    raw_data = await director.container.api.get_profile(director.user_id)
    data = await director.resolve(raw_data)

    if isinstance(data, UnifiedViewDTO):
        return data # Редирект на другую сцену

    # 3. Чистый UI слой
    return self.ui.render_main(data)

🏁 Шаг 5: Запуск

Запустите бота через сгенерированный скрипт:

python manage.py run

🔍 Что дальше?

  • Узнайте, как Director управляет переходами.
  • Изучите концепцию Stateless UI в ViewSender.
  • Посмотрите, как работают Redis Streams для фоновых задач.