Урок 1. Как устроен HAPI#

Зачем это нужно#

В первом уровне вы научились запускать HAPI и работать с ним. Теперь давайте разберёмся, как он устроен внутри. Это поможет вам понимать, что происходит «под капотом», быстрее находить проблемы и настраивать систему под себя.

Четыре главных компонента#

HAPI состоит из четырёх частей, которые работают вместе, как команда:

┌──────────────────────────────────────────────────┐
│            Ваш компьютер                         │
│                                                  │
│   CLI ◄──────► Hub ◄──────► Web App              │
│  (агент)      (сервер)      (браузер)            │
│                  │                               │
└──────────────────┼───────────────────────────────┘
                   │
              Relay (туннель)
                   │
              📱 Телефон

Давайте разберём каждый из них.

1. CLI — обёртка вокруг AI-агента#

CLI (от английского Command Line Interface — интерфейс командной строки) — это программа, которую вы запускаете в терминале командой hapi.

Что она делает:

Запускает AI-агента (Claude Code, Codex, Gemini или OpenCode) — это тот самый «умный помощник», который пишет код
Соединяется с Hub — чтобы вы могли управлять сессией удалённо
Передаёт сообщения между вами и агентом
Отправляет запросы на разрешения — когда агент хочет что-то сделать (например, отредактировать файл), он сначала спрашивает вас

Пример запуска:

hapi              # Запустить сессию с Claude Code
hapi codex        # Запустить сессию с OpenAI Codex
hapi gemini       # Запустить сессию с Google Gemini

💡 Простая аналогия: CLI — это как водитель автомобиля. Он управляет AI-агентом и общается с диспетчером (Hub).

2. Hub — центральный сервер#

Hub (от английского hub — центр, узел) — это «диспетчерская» HAPI. Он работает на вашем компьютере и координирует всё остальное.

Что он делает:

Хранит данные в базе SQLite (все сессии, сообщения, разрешения)
Раздаёт веб-интерфейс — ту самую страницу, которую вы открываете в браузере
Связывает CLI и веб-приложение в реальном времени
Отправляет уведомления в Telegram

Технологии связи Hub:

Связь	Технология	Что это
Hub ↔ CLI	Socket.IO	Двусторонняя связь в реальном времени (как чат)
Hub ↔ Браузер	REST + SSE	REST — для действий (отправить сообщение), SSE — для мгновенных обновлений

REST — способ общения программ через интернет (как отправка писем). SSE (Server-Sent Events) — технология, при которой сервер сам отправляет обновления в браузер (как радиотрансляция). Socket.IO — технология двусторонней связи в реальном времени (как телефонный звонок).

Запуск Hub:

hapi hub           # Локальный режим
hapi hub --relay   # С доступом через интернет

3. Web App — интерфейс в браузере#

Web App — это React-приложение (PWA), которое открывается в браузере вашего телефона или компьютера.

PWA (Progressive Web App) — сайт, который можно «установить» на телефон как обычное приложение. Он работает даже без постоянного интернета.

Что вы можете делать в Web App:

📋 Смотреть список сессий — все активные и прошлые
💬 Отправлять сообщения агенту — как в обычном чате
✅ Одобрять или отклонять действия — когда агент просит разрешение
📁 Просматривать файлы проекта — и видеть изменения в коде
🚀 Запускать новые сессии — прямо с телефона

4. Relay — туннель для удалённого доступа#

Relay (от английского relay — реле, ретранслятор) — это сервис, который позволяет подключаться к вашему Hub через интернет, даже если ваш компьютер находится за роутером или файрволом.

Файрвол (firewall) — защитная стена, которая блокирует нежелательные подключения к вашему компьютеру из интернета. NAT — технология в роутере, которая «прячет» ваш компьютер от внешнего мира.

Когда вы запускаете hapi hub --relay, происходит следующее:

Hub подключается к серверу Relay
Relay создаёт публичный адрес (URL) для вашего Hub
Вы получаете QR-код, который можно отсканировать телефоном
Телефон подключается к Hub через Relay

Шифрование: WireGuard + TLS#

HAPI серьёзно относится к безопасности. Весь трафик через Relay защищён двойным шифрованием:

WireGuard — это VPN-протокол (технология создания защищённого «тоннеля» между двумя устройствами). Он шифрует данные так, что никто между вами и вашим компьютером не может их прочитать.
TLS (Transport Layer Security) — тот же тип шифрования, который используется на сайтах с «замочком» (https://). Это второй слой защиты.

💡 Простая аналогия: Представьте, что вы отправляете письмо. WireGuard — это сейф, в который вы кладёте письмо. TLS — это бронированный фургон, который перевозит сейф. Даже если кто-то перехватит фургон, он не сможет добраться до содержимого письма.

Ваш телефон → [TLS шифрование] → [WireGuard тоннель] → Relay → Hub на компьютере

Как всё работает вместе#

Сценарий: вы отправляете сообщение с телефона#

1. Вы пишете сообщение в Web App на телефоне
         │
2. Сообщение через Relay попадает в Hub
         │
3. Hub передаёт сообщение в CLI через Socket.IO
         │
4. CLI передаёт сообщение AI-агенту
         │
5. Агент обрабатывает запрос и отвечает
         │
6. Ответ идёт обратно: CLI → Hub → SSE → Web App
         │
7. Вы видите ответ на экране телефона

Сценарий: агент просит разрешение#

1. AI-агент хочет отредактировать файл
         │
2. CLI отправляет запрос на разрешение в Hub
         │
3. Hub сохраняет запрос и уведомляет вас (SSE + Telegram)
         │
4. Вы получаете уведомление на телефоне
         │
5. Вы нажимаете «Одобрить» в Web App
         │
6. Hub передаёт решение в CLI → агент продолжает работу

Переключение между локальным и удалённым режимом#

Одна из главных «фишек» HAPI — возможность переключаться между терминалом и телефоном без потери сессии.

Направление	Как это работает
Терминал → Телефон	Отправьте сообщение с телефона — терминал автоматически перейдёт в режим ожидания
Телефон → Терминал	Нажмите двойной пробел в терминале — мгновенно вернёте локальное управление

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

Итоги урока#

CLI — запускает и управляет AI-агентом на вашем компьютере
Hub — центральный сервер, который связывает все части вместе и хранит данные
Web App — интерфейс в браузере для управления с любого устройства
Relay — безопасный туннель для доступа через интернет
Трафик защищён двойным шифрованием: WireGuard + TLS
Вы можете свободно переключаться между терминалом и телефоном, не теряя сессию