Мы не будем писать «игрушечного» бота в одном файле index.js. Большинство туториалов учат вас писать код, который невозможно поддерживать, как только у бота появляется больше 100 пользователей или сложная логика диалога.

Сегодня мы развернем профессиональный скелет приложения. Наша цель — создать среду, в которой разработка бизнес-логики (подключение ИИ) будет изолирована от инфраструктурного шума.

Почему именно этот стек?

Runtime: Node.js + TypeScript. Асинхронная природа Node.js идеально подходит для I/O операций (сетевые запросы к Telegram и OpenAI). TypeScript — это не опция, а необходимость. Без строгой типизации вы утонете в объектах context и структурах API Telegram.
Framework: grammY. Многие привыкли к Telegraf, но grammY — это «фреймворк нового поколения». Он на 100% покрывает Telegram Bot API, имеет лучшую поддержку TypeScript из коробки и работает быстрее.
Package Manager: pnpm. Экономит место на диске и быстрее устанавливает зависимости, чем npm.
Containerization: Docker. Мы сразу пакуем бота в контейнер. Это гарантирует, что он будет работать одинаково и на вашем MacBook, и на дешевом VPS.

Шаг 1. Инициализация и структура

Создайте папку проекта и инициализируйте его.

mkdir ai-bot-course
cd ai-bot-course
pnpm init

Установим основные зависимости. Нам понадобятся сам фреймворк, переменные окружения и инструменты разработки.

pnpm add grammy dotenv
pnpm add -D typescript tsx @types/node

Правильная структура папок:

Корень зла плохих ботов — отсутствие структуры. Сделаем сразу чисто:

.
├── src
│   ├── bot.ts          # Точка входа (entry point)
│   ├── config.ts       # Валидация env-переменных
│   ├── handlers        # Обработчики команд (/start, text)
│   └── services        # Логика общения с AI (будет позже)
├── .env                # Секреты (токен, ключи)
├── Dockerfile
├── docker-compose.yml
└── tsconfig.json

Создадим tsconfig.json. Нам нужен строгий режим (strict: true), чтобы TS бил нас по рукам за any.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Шаг 2. Конфигурация и безопасность

Никогда не пишите process.env.BOT_TOKEN прямо в коде бота. Если переменной нет, бот должен упасть сразу при старте, а не в момент работы.

Создайте файл .env:

BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
NODE_ENV=development

Создайте файл src/config.ts для централизованного управления конфигом:

import dotenv from 'dotenv';

dotenv.config();

if (!process.env.BOT_TOKEN) {
  throw new Error('BOT_TOKEN must be provided!');
}

export const config = {
  BOT_TOKEN: process.env.BOT_TOKEN,
  IS_DEV: process.env.NODE_ENV === 'development',
};

Шаг 3. Точка входа (Entry Point)

Напишем базового бота в src/bot.ts. Обратите внимание: мы добавляем обработку ошибок (bot.catch). Бот в продакшене не должен падать, если Telegram API вернул 403 ошибку (например, пользователь заблокировал бота).

import { Bot, Context, GrammyError, HttpError } from 'grammy';
import { config } from './config';

// Создаем инстанс бота
const bot = new Bot(config.BOT_TOKEN);

// Простой обработчик команды /start
bot.command('start', async (ctx) => {
  await ctx.reply('Привет! Я готов стать твоим ИИ-ассистентом. 🚀');
});

// Обработчик ошибок
bot.catch((err) => {
  const ctx = err.ctx;
  console.error(`Error while handling update ${ctx.update.update_id}:`);
  const e = err.error;

  if (e instanceof GrammyError) {
    console.error('Error in request:', e.description);
  } else if (e instanceof HttpError) {
    console.error('Could not contact Telegram:', e);
  } else {
    console.error('Unknown error:', e);
  }
});

// Запуск
console.log('Bot is starting...');
bot.start();

Для удобного запуска добавьте скрипт в package.json:

"scripts": {
  "dev": "tsx watch src/bot.ts",
  "build": "tsc",
  "start": "node dist/bot.js"
}

Команда dev запустит бота в режиме hot-reload: он будет перезагружаться сам при изменении кода.

Шаг 4. Docker-first подход

Мы не будем запускать бота через npm start на сервере. Мы упакуем его в контейнер.

Создайте Dockerfile. Используем мультистейдж сборку, чтобы финальный образ был легким (без TS исходников, только JS).

Dockerfile

# Stage 1: Build
FROM node:18-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml* ./
# Устанавливаем pnpm
RUN npm install -g pnpm
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build

# Stage 2: Run
FROM node:18-alpine
WORKDIR /app
COPY package.json pnpm-lock.yaml* ./
RUN npm install -g pnpm
# Ставим только production зависимости
RUN pnpm install --prod --frozen-lockfile
COPY --from=builder /app/dist ./dist

CMD ["node", "dist/bot.js"]

И файл оркестрации docker-compose.yml. Он пригодится нам в следующих уроках, когда мы добавим базу данных PostgreSQL.

version: '3.8'

services:
  bot:
    build: .
    restart: always
    env_file: .env
    # В будущем здесь добавится depends_on: - db

Шаг 5. Выбор модели (LLM)

Перед тем как писать код интеграции (в следующих уроках), вам нужно определиться с провайдером. Для разработки бота у вас есть два пути:

OpenAI (GPT-4o / GPT-3.5-turbo): Золотой стандарт. Лучшее понимание инструкций.12
- Плюс: Простота API.34
- Минус: Сложности с оплатой из РФ и необходимость VPN/Proxy для запросов с российских серверов.56
Anthropic (Claude 3.5 Sonnet): Более «человечный» стиль общения, лучше пишет код.78
- Минус:9 Те же сложности с доступом.10
Local / Open Source (через Qubu): Есл11и вы используете экосистему Qubu, вы можете арендовать GPU и запустить Llama 3 или DeepSeek через vLLM. Это дает API, совместимый с OpenAI, но без риска блокировок.

Рекомендация для курса: Мы будем писать код, совместимый с интерфейсом OpenAI SDK. Это позволит вам переключаться между GPT-4, DeepSeek или локальной моделью, просто меняя BASE_URL в конфиге.

Добавьте в .env заготовку:

AI_PROVIDER=openai # или deepseek / qubu
AI_API_KEY=sk-...
AI_BASE_URL=https://api.openai.com/v1 # Можно поменять на прокси

Задание

Зайдите в @BotFather в Telegram, создайте нового бота и получите токен.
Склонируйте структуру проекта, которую мы разобрали.
Запустите бота локально через pnpm dev. Убедитесь, что он отвечает на /start.
Запустите бота через Docker: docker-compose up --build.

Результат: У вас должен быть запущенный контейнер, который пишет в логи Bot is starting... и реагирует на сообщения в Telegram.

Краткие итоги

Мы настроили TypeScript + grammY — это стандарт для сложных ботов.
Мы изолировали конфигурацию в .env — безопасность превыше всего.
Мы подготовили Dockerfile — бот готов к деплою на любой сервер прямо сейчас.
В следующем уроке мы подключим к этому каркасу «память» (PostgreSQL + Prisma), чтобы бот мог запоминать пользователей.