Перейти к основному содержимому

Настройка Raft

VibeOS подключается к Raft как внешний агент через локальный мост wake-channel. Адаптер запускает loopback HTTP-эндпоинт, который получает от моста пустые wake-подсказки, а затем внедряет их в конвейер сессии шлюза VibeOS. Агент читает и отправляет сообщения через CLI Raft — адаптер никогда не касается тел сообщений или курсоров доставки.

Разделение обязанностей
  • Мост отвечает за: потребление wake-подсказок, дедупликацию, backoff, переподключение, доставку хотя бы один раз и ведение журнала подтверждений.
  • Адаптер VibeOS отвечает за: локальный wake-эндпоинт и внедрение короткого уведомления в контекст агента.
  • Агент отвечает за: получение сообщений (raft message check), ответы (raft message send) и все остальные взаимодействия с Raft через CLI.

Адаптер не хранит учётные данные Raft — только общий токен для каждой сессии, используемый для аутентификации между мостом и эндпоинтом на localhost.

Предварительные требования​

  • Рабочее пространство Raft, в котором можно создать внешнего агента
  • CLI Raft, установленный и авторизованный под профилем этого внешнего агента
  • aiohttp — пакет Python (входит в состав расширений VibeOS [all])

В Raft откройте меню агентов, создайте внешнего агента и следуйте инструкциям на карточке настройки, чтобы установить CLI Raft и войти в профиль агента. После создания агента Raft покажет руководство по настройке VibeOS с переменными окружения и конфигурацией, необходимыми для запуска шлюза.

Настройка​

Добавьте в ~/.vibeos/.env:

RAFT_PROFILE=your-agent-profile

Всё — адаптер автоматически включается, когда установлена переменная RAFT_PROFILE. Он генерирует токен моста для каждой сессии, выбирает эфемерный порт и автоматически запускает дочерний процесс моста при старте шлюза.

Как это работает​

Сервер Raft → Мост (wake-подсказки SSE) → POST /wake → Адаптер VibeOS → Контекст агента
Агент → raft message check → Сервер Raft (тела сообщений)
Агент → raft message send → Сервер Raft (ответы)
  1. Сервер Raft отправляет wake-подсказки процессу моста через SSE.
  2. Мост пересылает каждую подсказку как POST /wake на loopback-эндпоинт адаптера.
  3. Адаптер проверяет токен моста, убеждается, что полезная нагрузка не содержит содержимого, и внедряет wake-уведомление в сессию VibeOS.
  4. Агент видит wake-уведомление и использует CLI Raft для чтения сообщений и ответов.

Wake-полезные нагрузки по контракту не содержат содержимого — они передают метаданные (ID события, ID сообщения, временные метки), но никогда не содержат тел сообщений, названий каналов или идентификаторов отправителей. Адаптер отклоняет любую полезную нагрузку, содержащую поля, похожие на содержимое (text, body, content, messages и т.д.).

Мост​

Адаптер автоматически запускает raft agent bridge как дочерний процесс, передавая URL эндпоинта и токен. Мост подключается к серверу Raft, используя настроенный профиль, и начинает пересылать wake-подсказки. Он завершается при остановке шлюза.

Переменные окружения​

ПеременнаяОписаниеПо умолчанию
RAFT_PROFILEСлаг профиля агента Raft — автоматически включает адаптер при установке(обязательно)