Photon iMessage

Подключите VibeOS к iMessage через Photon — управляемый сервис, который берёт на себя выделение номеров Apple и уровень защиты от злоупотреблений, так что вам не нужно запускать собственное Mac-реле.

Бесплатный тариф использует общий пул iMessage-линий Photon — разные получатели могут видеть разные номера отправителя, но каждый диалог остаётся стабильным. Платный тариф Business даёт каждому пользователю один и тот же выделенный номер; плагин поддерживает оба варианта, и бесплатный тариф рекомендуется в качестве отправной точки.

Бесплатный старт

Общий пул линий Photon бесплатен. Для отправки первого iMessage из VibeOS не требуется подписка — нужен только номер телефона, который мы привяжем к вашей учётной записи.

Архитектура

Photon — это канал с постоянным соединением, как Discord или Slack — никаких вебхуков, публичных URL или секретов подписи.

SDK spectrum-ts поддерживает долгоживущий gRPC-поток к Photon в обоих направлениях. Поскольку SDK написан только на TypeScript, VibeOS запускает его в небольшом управляемом Node-сайдкаре и общается с ним через loopback:

• Входящие — сайдкар потребляет gRPC-поток app.messages SDK и пересылает каждое сообщение в Python-адаптер через loopback GET /inbound (NDJSON). Адаптер дедуплицирует и отправляет его агенту, автоматически переподключаясь при обрыве потока.
• Исходящие — ответы отправляются через loopback POST к сайдкару, который вызывает space.send(...) в SDK.

Python-плагин автоматически запускает, контролирует и останавливает сайдкар.

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

• Учётная запись Photon — зарегистрируйтесь на app.photon.codes
• Node.js 18.17 или новее в PATH (node --version)
• Номер телефона, способный принимать iMessage (используется для привязки учётной записи)

Вот и всё — никаких публичных URL или туннелей настраивать не нужно.

Первоначальная настройка

Запустите мастер единого шлюза и выберите Photon iMessage:

vibeos gateway setup

…или запустите настройку Photon напрямую (мастер вызывает тот же процесс):

# Вход через код устройства + проект + пользователь + зависимости сайдкара, всё в одном
vibeos photon setup --phone +15551234567

Настройка выполняется в следующем порядке:

1. Вход через устройство (client_id=photon-cli) — открывает https://app.photon.codes/ для подтверждения и сохраняет bearer-токен.
2. Находит или создаёт проект VibeOS в вашей учётной записи.
3. Включает Spectrum, считывает идентификатор Spectrum проекта и обновляет секрет проекта.
4. Регистрирует ваш номер телефона как пользователя Spectrum — пропускается, если пользователь с таким номером уже существует, так что повторный запуск безопасен.
5. Выводит назначенную iMessage-линию — номер, на который нужно писать, чтобы связаться с агентом.
6. Запускает npm install в каталоге сайдкара плагина.

Учётные данные времени выполнения записываются в ~/.vibeos/.env (PHOTON_PROJECT_ID = идентификатор проекта Spectrum, PHOTON_PROJECT_SECRET), туда же, где каждый другой канал хранит свой токен. Метаданные управления (токен устройства, идентификатор проекта в панели) хранятся в ~/.vibeos/auth.json в credential_pool.photon / credential_pool.photon_project.

Авторизация пользователей

Photon использует ту же модель авторизации, что и все остальные каналы VibeOS. Выберите один подход:

Сопряжение через DM (по умолчанию). Когда неизвестный номер отправляет сообщение на вашу Photon-линию, VibeOS отвечает кодом сопряжения. Подтвердите его с помощью:

vibeos pairing approve photon <CODE>

Используйте vibeos pairing list, чтобы просмотреть ожидающие коды и подтверждённых пользователей.

Предварительная авторизация конкретных номеров (в ~/.vibeos/.env):

PHOTON_ALLOWED_USERS=+15551234567,+15559876543

Открытый доступ (только для разработки, в ~/.vibeos/.env):

PHOTON_ALLOW_ALL_USERS=true

Когда установлен PHOTON_ALLOWED_USERS, неизвестные отправители игнорируются без предложения кода сопряжения (белый список сигнализирует, что вы намеренно ограничили доступ).

Требование упоминаний в групповых чатах

По умолчанию VibeOS отвечает на каждое авторизованное личное сообщение и групповое сообщение. Чтобы сделать групповые чаты опциональными, включите шлюз упоминаний (личные сообщения всё равно работают всегда):

gateway:
  platforms:
    photon:
      enabled: true
      require_mention: true

С require_mention: true сообщения в групповых чатах игнорируются, если они не соответствуют шаблону слова-активатора. По умолчанию совпадают VibeOS и варианты @VibeOS agent. Для пользовательского имени агента задайте regex-шаблоны:

gateway:
  platforms:
    photon:
      require_mention: true
      mention_patterns:
        - '(?<![\w@])@?amos\b[,:\-]?'

Оба ключа также принимают переменные окружения (PHOTON_REQUIRE_MENTION, PHOTON_MENTION_PATTERNS). Это та же модель шлюза упоминаний, что используется в канале iMessage BlueBubbles.

Запуск шлюза

vibeos gateway start

Вы увидите что-то вроде:

[photon] connected — sidecar on 127.0.0.1:8789, streaming inbound over gRPC

Отправьте iMessage на ваш назначенный номер, и VibeOS ответит.

Статус и устранение неполадок

vibeos photon status

Выводит сохранённые учётные данные, состояние сайдкара, ваш зарегистрированный номер и назначенную iMessage-линию, которую использует VibeOS. Когда токен Photon и проект в панели доступны, status обновляет недостающие строки номеров из панели без выделения новых линий.

Photon iMessage status
──────────────────────
  device token        : ✓ stored
  dashboard project   : 3c90c3cc-0d44-4b50-...
  spectrum project id : sp-...
  project secret      : ✓ stored
  my number           : +15551234567
  assigned number     : +16282679185
  node binary         : /usr/bin/node
  sidecar deps        : ✓ installed

Частые проблемы:

• sidecar deps : ✗ run vibeos photon install-sidecar — Node установлен, но spectrum-ts нет. Выполните предложенную команду.
• device token : ✗ missing — запустите vibeos photon setup для входа.
• No iMessage line assigned yet — Spectrum включён, но линия не выделена; повторно запустите vibeos photon setup или проверьте панель.
• Сайдкар не запускается — убедитесь, что node --version 18.17+ и что vibeos photon install-sidecar завершился без ошибок.

Текущие ограничения

• Входящие вложения — только метаданные. Входящие события содержат имя файла + MIME-тип; агент видит маркер, но пока не может прочитать байты. SDK предоставляет байты вложений через content.read(), так что это будет доработано в сайдкаре.
• Исходящие вложения поддерживаются. VibeOS отправляет изображения, голосовые заметки, видео и документы через конструкторы контента attachment() / voice() библиотеки spectrum-ts через endpoint /send-attachment сайдкара. Подписи приходят отдельным iMessage-пузырём после медиа.
• Бесплатные квоты Photon: 5 000 сообщений на сервер в день, 50 инициаций новых диалогов на общую линию в день. Увеличение доступно — напишите на help@photon.codes.

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

Переменная	По умолчанию	Примечания
PHOTON_PROJECT_ID	из .env	Идентификатор проекта Spectrum (projectId в SDK); устанавливается при настройке
PHOTON_PROJECT_SECRET	из .env	Секрет проекта; устанавливается при настройке
PHOTON_SIDECAR_PORT	8789	Loopback-порт для управления сайдкаром и входящего канала
PHOTON_SIDECAR_AUTOSTART	true	Запускает ли адаптер сайдкар
PHOTON_NODE_BIN	which node	Переопределить путь к бинарнику Node
PHOTON_HOME_CHANNEL	(не задано)	Идентификатор пространства по умолчанию для cron/уведомлений
PHOTON_HOME_CHANNEL_NAME	(не задано)	Человеческое название домашнего канала
PHOTON_ALLOWED_USERS	(не задано)	Белый список номеров в формате E.164 через запятую
PHOTON_ALLOW_ALL_USERS	false	Только для разработки — принимать любого отправителя
PHOTON_REQUIRE_MENTION	false	Требовать слово-активатор перед ответом в группах
PHOTON_MENTION_PATTERNS	Слова-активаторы VibeOS	JSON-список / через запятую / через новую строку regex-шаблонов для групповых упоминаний
PHOTON_DASHBOARD_HOST	app.photon.codes	Переопределить хост панели / входа через устройство
PHOTON_SPECTRUM_HOST	spectrum.photon.codes	Переопределить хост API Spectrum