Skip to main content
Omniflow расширяется двумя способами, и только двумя. Конфигурация дотягивается до точек входа, которых сопровождающие никогда не увидят: сервер моделей на вашем железе, поставщик идентичности, сервер MCP. Всё остальное — вклад в этот репозиторий, отрецензированный и вкомпилированный. Плагинного рантайма нет, ABI нет, и загрузить сторонний код в работающий процесс невозможно. Эта страница — контракт, который к этому прилагается: на что можно опираться и ожидать, что оно продолжит работать, что будет меняться под вами и как новый адаптер попадает внутрь.

​
Что публично

Эти поверхности покрыты семантическим версионированием и политикой устаревания на той же странице. Ломающее изменение любой из них — это мажорная версия и запись в CHANGELOG.md, а не молчаливая смена поведения.

​
Что внутреннее

Опираться на любое из этого можно — это ваша установка, — но обещаний совместимости здесь нет, и уведомление об устаревании не полагается.
  • /v1/panel и /v1/account. Они существуют, чтобы обслуживать две панели, и меняются вместе с экранами. Они привязаны к сессии с CSRF, так что скрипту с ними в любом случае неудобно. Используйте /v1/admin.
  • Схема базы данных. Миграции только вперёд, а таблицы перестраиваются, когда этого требует функция. Читайте с реплики, если необходимо; писать — только через API. Прямая запись обходит идемпотентность, аудит и правила «только-для-добавления», которые и делают финансовые записи достоверными.
  • Пакеты Go. Каждый пакет лежит под internal/, поэтому компилятор гарантирует, что ничто вне этого модуля их не импортирует. Это намеренно: так сопровождающие свободны менять внутренности, а «расширение» никогда не превращается в «кто-то зависит от сигнатуры этой функции».
  • Каталоги сообщений, внутренности компонентов и сгенерированные клиенты. Они перегенерируются.
  • Схема River и полезная нагрузка заданий. Аргументы задания — деталь реализации того процесса, который его ставит.

​
Расширение без правки кода

Четыре точки интеграции принимают выбранную вами точку входа, и вклад в репозиторий не нужен. Именно поэтому плагинного рантайма нет, а не «он ещё не готов»: то, что людям действительно хочется подключить, — это внешние сервисы, а внешнему сервису нужны URL и учётные данные, а не механизм загрузки кода. Ещё три — это конфигурация уже вкомпилированных адаптеров: платёжные провайдеры, шлюз цифровых товаров и подключение к Remnawave. Вы выбираете, какие включены, с какими учётными данными и какими возможностями, но не то, на каком протоколе они говорят.

​
Добавление адаптера

Платёжный провайдер, шлюз цифровых товаров или провайдер моделей, говорящий на четвёртой форме, — это вклад в репозиторий. Интерфейсы намеренно небольшие, и адаптер, остающийся внутри них, — это ограниченное ревью. Платёжный адаптер реализует шесть методов — Name, Capabilities, Create, Poll, Refund и VerifyWebhook — и объявляет, что он на самом деле умеет, через Capabilities, а не через флаг в конфигурации. Три необязательных интерфейса подхватываются, если реализованы: списание с сохранённого метода без присутствия клиента, восстановление намерения, чья ссылка потеряна, и объявление поддерживаемых валют. Адаптер, который не объявляет валюты, принимает ту, что несёт заказ. На чём ревью будет настаивать в любом случае:
  • Идемпотентность — забота адаптера тоже. Каждый изменяющий вызов несёт ключ идемпотентности, и повторный вызов не должен подвинуть деньги дважды. Адаптер, который не может его соблюсти, обязан об этом сказать, и конвейер трактует неоднозначный исход как случай для человека, а не повторяет попытку, — ровно так сегодня и поступает шлюз цифровых товаров.
  • Возможности объявляются, а не предполагаются. Кнопка возврата у провайдера, который не умеет возвращать, — это будущее обращение в поддержку.
  • Проверка вебхука выполняется раньше всего остального, по сырому телу, с ограничением размера, и неуспешная проверка всё равно записывается.
  • Ни один секрет не попадает в лог, в ошибку, показанную браузеру, или в набор диагностики. Текст ошибки провайдера может вернуть запрос обратно — поэтому адаптеры моделей возвращают статус и ничего больше.
  • Вместе с ним поставляются тесты путей отказа и идемпотентности, а также фикстуры воспроизведения для форм вебхуков.
Сначала откройте предложение функции — см. SUPPORT.md, — потому что вопрос, стоит ли нести этого провайдера, относится к сопровождению, а не к качеству кода. ROADMAP.md прямо говорит, что дополнительные платёжные провайдеры добавляются, когда об этом просит оператор, а не ради их количества.

​
Что намеренно нерасширяемо

  • Нет плагинного рантайма. Нет хоста WASM, нет динамической загрузки и нет точки расширения, выполняющей сторонний код в процессе Omniflow. Песочница возможностей — кандидат после 1.0, и ей нужен проект безопасности, а не библиотека.
  • Нет второго места, решающего, что позволено роли. Каталог прав доступа и сопоставление ролей вкомпилированы в internal/rbac, поэтому ни файл конфигурации, ни строка в базе, ни интеграция не могут расширить доступ.
  • Никаких записей в хранилище Remnawave и никакого управления Xray — ничем, включая адаптер. См. запись 0004.
  • Ни AI, ни MCP не могут обойти RBAC, подтверждение, идемпотентность или журнал аудита. Инструмент сопоставлен с правом доступа, которое у оператора уже есть, а значимое изменение требует человека.

​
Смежное

Интеграция с API

Bearer-токен, ключи идемпотентности, курсоры, ответы об ошибках и известные пробелы контракта.

Совместимость и обновления

Матрица версий, окно обновления и политика устаревания, на которую опирается эта страница.

Процесс выпуска

Как изменение становится версией и что публикует выпуск.

Архитектурные решения

Записи, ограничивающие то, чем расширению позволено быть.