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

VibeOS уже может взаимодействовать с любым OpenAI-совместимым эндпоинтом через путь пользовательского провайдера. Не добавляйте встроенного провайдера, если только вы не хотите обеспечить первоклассный пользовательский опыт для этого сервиса:

аутентификация или обновление токена, специфичные для провайдера
курируемый каталог моделей
пункты меню настройки / vibeos model
псевдонимы провайдера для синтаксиса provider:model
форма API, отличная от OpenAI, требующая адаптера

Если провайдер — это просто «ещё один OpenAI-совместимый базовый URL и API-ключ», именованного пользовательского провайдера может быть достаточно.

Модель мышления

Встроенный провайдер должен быть согласован на нескольких уровнях:

vibeos_cli/auth.py определяет, как находятся учётные данные.
vibeos_cli/runtime_provider.py преобразует это в данные времени выполнения:
- provider
- api_mode
- base_url
- api_key
- source
run_agent.py использует api_mode, чтобы решить, как создавать и отправлять запросы.
vibeos_cli/models.py и vibeos_cli/main.py обеспечивают отображение провайдера в CLI. (vibeos_cli/setup.py автоматически делегирует полномочия main.py — изменений там не требуется.)
agent/auxiliary_client.py и agent/model_metadata.py обеспечивают работу вспомогательных задач и бюджетирования токенов.

Важная абстракция — это api_mode.

Большинство провайдеров используют chat_completions.
Codex использует codex_responses.
Anthropic использует anthropic_messages.
Новый протокол, отличный от OpenAI, обычно означает добавление нового адаптера и новой ветки api_mode.

Сначала выберите путь реализации

Путь A — OpenAI-совместимый провайдер

Используйте этот путь, когда провайдер принимает стандартные запросы в стиле chat-completions.

Типичная работа:

добавить метаданные аутентификации
добавить каталог моделей / псевдонимы
добавить разрешение на этапе выполнения
добавить привязку к меню CLI
добавить значения по умолчанию для вспомогательных моделей
добавить тесты и пользовательскую документацию

Обычно вам не нужен новый адаптер или новый api_mode.

Путь B — Нативный провайдер

Используйте этот путь, когда провайдер не ведёт себя как OpenAI chat completions.

Примеры, существующие в репозитории на данный момент:

codex_responses
anthropic_messages

Этот путь включает всё из Пути A, а также:

адаптер провайдера в agent/
ветки в run_agent.py для построения запросов, отправки, извлечения использования, обработки прерываний и нормализации ответов
тесты адаптера

Контрольный список файлов

Обязательно для каждого встроенного провайдера

vibeos_cli/auth.py
vibeos_cli/models.py
vibeos_cli/runtime_provider.py
vibeos_cli/main.py
agent/auxiliary_client.py
agent/model_metadata.py
тесты
пользовательская документация в website/docs/

подсказка

vibeos_cli/setup.py не требует изменений. Мастер настройки делегирует выбор провайдера/модели функции select_provider_and_model() в main.py — любой провайдер, добавленный туда, автоматически доступен в vibeos setup.

Дополнительно для нативных / не-OpenAI провайдеров

agent/<provider>_adapter.py
run_agent.py
pyproject.toml, если требуется SDK провайдера

Быстрый путь: Простые провайдеры с API-ключом

Если ваш провайдер — это просто OpenAI-совместимый эндпоинт, который аутентифицируется с помощью одного API-ключа, вам не нужно трогать auth.py, runtime_provider.py, main.py или любые другие файлы из полного контрольного списка ниже.

Всё, что вам нужно:

Директория плагина в plugins/model-providers/<your-provider>/, содержащая:
- __init__.py — вызывает register_provider(profile) на уровне модуля
- plugin.yaml — манифест (name, kind: model-provider, version, description)
Вот и всё. Плагины провайдеров автоматически загружаются при первом вызове get_provider_profile() или list_providers() — как встроенные плагины (из этого репозитория), так и пользовательские плагины из $VIBEOS_HOME/plugins/model-providers/.

Когда вы добавляете плагин и он вызывает register_provider(), автоматически настраивается следующее:

Запись PROVIDER_REGISTRY в auth.py (разрешение учётных данных, поиск переменных окружения)
api_mode устанавливается в chat_completions
base_url берётся из конфигурации или объявленной переменной окружения
env_vars проверяются в порядке приоритета для API-ключа
Список fallback_models регистрируется для провайдера
Флаг CLI --provider принимает идентификатор провайдера
Меню vibeos model включает провайдера
Мастер vibeos setup автоматически делегирует полномочия main.py
Синтаксис псевдонима provider:model работает
Разрешитель времени выполнения возвращает правильные base_url и api_key
Флаг CLI --provider <name>` принимает идентификатор провайдера
Активация резервной модели может корректно переключиться на провайдера

Пользовательские плагины в $VIBEOS_HOME/plugins/model-providers/<name>/ переопределяют встроенные плагины с тем же именем (последний записавший побеждает в register_provider()) — таким образом, сторонние разработчики могут модифицировать или заменять любой встроенный профиль без редактирования репозитория.

Смотрите plugins/model-providers/nvidia/ или plugins/model-providers/gmi/ в качестве шаблона, а также полное Руководство по плагинам провайдеров моделей для справки по полям, идиомам хуков и сквозным примерам.

Полный путь: OAuth и сложные провайдеры

Используйте полный контрольный список ниже, когда вашему провайдеру требуется что-либо из следующего:

OAuth или обновление токена (Nous Portal, Codex, Qwen Portal, Copilot)
Форма API, отличная от OpenAI, требующая нового адаптера (Anthropic Messages, Codex Responses)
Пользовательское обнаружение эндпоинта или зондирование нескольких регионов (z.ai, Kimi)
Курируемый статический каталог моделей или динамическая загрузка /models
Специфичные для провайдера пункты меню vibeos model с особыми потоками аутентификации

Шаг 1: Выберите один канонический идентификатор провайдера

Выберите один идентификатор провайдера и используйте его везде.

Примеры из репозитория:

openai-codex
kimi-coding
minimax-cn

Этот же идентификатор должен появиться в:

PROVIDER_REGISTRY в vibeos_cli/auth.py
_PROVIDER_LABELS в vibeos_cli/models.py
_PROVIDER_ALIASES как в vibeos_cli/auth.py, так и в vibeos_cli/models.py
вариантах CLI --provider в vibeos_cli/main.py
ветках настройки / выбора модели
значениях по умолчанию для вспомогательных моделей
тестах

Если идентификатор различается между этими файлами, провайдер будет казаться наполовину подключённым: аутентификация может работать, в то время как /model, настройка или разрешение времени выполнения молча его пропускают.

Шаг 2: Добавьте метаданные аутентификации в `vibeos_cli/auth.py`

Для провайдеров с API-ключом добавьте запись ProviderConfig в PROVIDER_REGISTRY с:

id
name
auth_type="api_key"
inference_base_url
api_key_env_vars
опционально base_url_env_var

Также добавьте псевдонимы в _PROVIDER_ALIASES.

Используйте существующих провайдеров в качестве шаблонов:

простой путь с API-ключом: Z.AI, MiniMax
путь с API-ключом и обнаружением эндпоинта: Kimi, Z.AI
нативное разрешение токена: Anthropic
путь OAuth / хранилище аутентификации: Nous, OpenAI Codex

Вопросы, на которые нужно ответить здесь:

Какие переменные окружения должна проверять VibeOS и в каком порядке приоритета?
Нужны ли провайдеру переопределения базового URL?
Нужно ли ему зондирование эндпоинта или обновление токена?
Что должно говорить сообщение об ошибке аутентификации, когда учётные данные отсутствуют?

Если провайдеру нужно нечто большее, чем «найти API-ключ», добавьте выделенный разрешитель учётных данных вместо того, чтобы втискивать логику в несвязанные ветки.

Шаг 3: Добавьте каталог моделей и псевдонимы в `vibeos_cli/models.py`

Обновите каталог провайдера, чтобы провайдер работал в меню и в синтаксисе provider:model.

Типичные правки:

_PROVIDER_MODELS
_PROVIDER_LABELS
_PROVIDER_ALIASES
порядок отображения провайдера внутри list_available_providers()
provider_model_ids(), если провайдер поддерживает динамическую загрузку /models

Если провайдер предоставляет динамический список моделей, отдавайте ему предпочтение и сохраняйте _PROVIDER_MODELS в качестве статического запасного варианта.

Этот файл также отвечает за то, чтобы такие вводы работали:

anthropic:claude-sonnet-4-6
kimi:model-name

Если псевдонимы здесь отсутствуют, провайдер может аутентифицироваться правильно, но всё равно выдавать ошибку при разборе /model.

Шаг 4: Разрешите данные времени выполнения в `vibeos_cli/runtime_provider.py`

resolve_runtime_provider() — это общий путь, используемый CLI, шлюзом, cron, ACP и клиентами-помощниками.

Добавьте ветку, которая возвращает словарь как минимум с:

{
    "provider": "your-provider",
    "api_mode": "chat_completions",  # или ваш нативный режим
    "base_url": "https://...",
    "api_key": "...",
    "source": "env|portal|auth-store|explicit",
    "requested_provider": requested_provider,
}

Если провайдер совместим с OpenAI, api_mode обычно должен оставаться chat_completions.

Будьте осторожны с приоритетом API-ключа. VibeOS уже содержит логику, чтобы избежать утечки ключа OpenRouter на несвязанные эндпоинты. Новый провайдер должен быть столь же явным в отношении того, какой ключ идёт к какому базовому URL.

Шаг 5: Подключите CLI в `vibeos_cli/main.py`

Провайдер не будет обнаружен, пока не появится в интерактивном потоке vibeos model.

Обновите следующее в vibeos_cli/main.py:

словарь provider_labels
список providers в select_provider_and_model()
диспетчеризацию провайдера (if selected_provider == ...)
варианты аргумента --provider
варианты входа/выхода, если провайдер поддерживает эти потоки
функцию _model_flow_<provider>() или повторно используйте _model_flow_api_key_provider(), если она подходит

подсказка

vibeos_cli/setup.py не требует изменений — он вызывает select_provider_and_model() из main.py, поэтому ваш новый провайдер автоматически появляется как в vibeos model, так и в vibeos setup.

Шаг 6: Обеспечьте работу вспомогательных вызовов

Здесь важны два файла:

`agent/auxiliary_client.py`

Добавьте дешёвую / быструю вспомогательную модель по умолчанию в _API_KEY_PROVIDER_AUX_MODELS, если это прямой провайдер с API-ключом.

Вспомогательные задачи включают в себя такие вещи, как:

суммаризация изображений
суммаризация извлечённых веб-данных
суммаризация сжатия контекста
суммаризация поиска по сессии
сброс памяти

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

`agent/model_metadata.py`

Добавьте длины контекста для моделей провайдера, чтобы бюджетирование токенов, пороги сжатия и лимиты оставались адекватными.

Шаг 7: Если провайдер нативный, добавьте адаптер и поддержку в `run_agent.py`

Если провайдер не является простым chat completions, изолируйте специфичную для провайдера логику в agent/<provider>_adapter.py.

Сосредоточьте run_agent.py на оркестровке. Он должен вызывать вспомогательные функции адаптера, а не создавать полезные нагрузки провайдера вручную по всему файлу.

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

Новый файл адаптера

Типичные обязанности:

создать SDK / HTTP-клиент
разрешить токены
преобразовать сообщения разговора в стиле OpenAI в формат запроса провайдера
преобразовать схемы инструментов, если необходимо
нормализовать ответы провайдера обратно в то, что ожидает run_agent.py
извлечь данные об использовании и причине завершения

`run_agent.py`

Найдите api_mode и проверьте каждую точку переключения. Как минимум, убедитесь:

__init__ выбирает новый api_mode
создание клиента работает для провайдера
_build_api_kwargs() знает, как форматировать запросы
_interruptible_api_call() отправляет запрос к правильному вызову клиента
пути прерывания / перестроения клиента работают
проверка ответа принимает формат провайдера
извлечение причины завершения корректно
извлечение использования токенов корректно
активация резервной модели может корректно переключиться на нового провайдера
пути генерации суммаризации и сброса памяти всё ещё работают

Также найдите self.client. в run_agent.py. Любой путь кода, который предполагает существование стандартного клиента OpenAI, может сломаться, когда нативный провайдер использует другой объект клиента или self.client = None.

Кэширование подсказок и поля запроса, специфичные для провайдера

Кэширование подсказок и специфичные для провайдера настройки легко регрессируют.

Примеры, уже существующие в репозитории:

Anthropic имеет нативный путь кэширования подсказок
OpenRouter получает поля маршрутизации провайдера
не каждый провайдер должен получать все опции на стороне запроса

Когда вы добавляете нативного провайдера, перепроверьте, что VibeOS отправляет только те поля, которые этот провайдер действительно понимает.

Шаг 8: Тесты

Как минимум, затроньте тесты, которые защищают подключение провайдера.

Обычные места:

tests/vibeos_cli/test_runtime_provider_resolution.py
tests/cli/test_cli_provider_resolution.py
tests/vibeos_cli/test_model_switch_custom_providers.py (и соседние tests/vibeos_cli/test_model_switch_*.py)
tests/vibeos_cli/test_setup_model_provider.py
tests/run_agent/test_provider_parity.py
tests/run_agent/test_run_agent.py
tests/test_<provider>_adapter.py для нативного провайдера

Для примеров, ориентированных только на документацию, точный набор файлов может отличаться. Суть в том, чтобы охватить:

разрешение аутентификации
меню CLI / выбор провайдера
разрешение провайдера во время выполнения
путь выполнения агента
разбор provider:model
любое специфичное для адаптера преобразование сообщений

Запускайте тесты с отключённым xdist:

source venv/bin/activate
python -m pytest tests/vibeos_cli/test_runtime_provider_resolution.py tests/cli/test_cli_provider_resolution.py tests/vibeos_cli/test_setup_model_provider.py tests/run_agent/test_provider_parity.py -n0 -q

Для более глубоких изменений запустите полный набор тестов перед отправкой:

source venv/bin/activate
python -m pytest tests/ -n0 -q

Шаг 9: Живая проверка

После тестов проведите реальную дымовую проверку.

source venv/bin/activate
python -m vibeos_cli.main chat -q "Say hello" --provider your-provider --model your-model

Также протестируйте интерактивные потоки, если вы изменили меню:

source venv/bin/activate
python -m vibeos_cli.main model
python -m vibeos_cli.main setup

Для нативных провайдеров также проверьте хотя бы один вызов инструмента, а не только ответ в виде простого текста.

Шаг 10: Обновите пользовательскую документацию

Если провайдер предназначен для поставки как первоклассный вариант, обновите также пользовательскую документацию:

website/docs/getting-started/quickstart.md
website/docs/user-guide/configuration.md
website/docs/reference/environment-variables.md

Разработчик может идеально подключить провайдера и всё равно оставить пользователей неспособными обнаружить необходимые переменные окружения или поток настройки.

Контрольный список для OpenAI-совместимого провайдера

Используйте это, если провайдер является стандартным chat completions.

ProviderConfig добавлен в vibeos_cli/auth.py
псевдонимы добавлены в vibeos_cli/auth.py и vibeos_cli/models.py
каталог моделей добавлен в vibeos_cli/models.py
ветка времени выполнения добавлена в vibeos_cli/runtime_provider.py
привязка CLI добавлена в vibeos_cli/main.py (setup.py наследует автоматически)
вспомогательная модель добавлена в agent/auxiliary_client.py
длины контекста добавлены в agent/model_metadata.py
тесты времени выполнения / CLI обновлены
пользовательская документация обновлена

Контрольный список для нативного провайдера

Используйте это, когда провайдеру нужен новый путь протокола.

всё из контрольного списка OpenAI-совместимого провайдера
адаптер добавлен в agent/<provider>_adapter.py
новый api_mode поддерживается в run_agent.py
путь прерывания / перестроения работает
извлечение использования и причины завершения работает
путь резервного копирования работает
тесты адаптера добавлены
живая дымовая проверка пройдена

Распространённые ошибки

1. Добавление провайдера в аутентификацию, но не в разбор моделей

Это приводит к тому, что учётные данные разрешаются правильно, в то время как вводы /model и provider:model завершаются ошибкой.

2. Забывание, что `config["model"]` может быть строкой или словарём

Большая часть кода выбора провайдера должна нормализовать обе формы.

3. Предположение, что встроенный провайдер обязателен

Если сервис просто совместим с OpenAI, пользовательский провайдер может уже решить проблему пользователя с меньшими затратами на обслуживание.

4. Забывание вспомогательных путей

Основной путь чата может работать, в то время как суммаризация, сброс памяти или помощники по работе с изображениями выходят из строя, потому что маршрутизация вспомогательных средств никогда не обновлялась.

5. Ветки нативного провайдера, спрятанные в `run_agent.py`

Ищите api_mode и self.client.. Не предполагайте, что очевидный путь запроса — единственный.

6. Отправка настроек, предназначенных только для OpenRouter, другим провайдерам

Такие поля, как маршрутизация провайдера, принадлежат только тем провайдерам, которые их поддерживают.

7. Обновление `vibeos model`, но не `vibeos setup`

Оба потока должны знать о провайдере.

Хорошие цели для поиска при реализации

Если вы ищете все места, которых касается провайдер, найдите эти символы:

PROVIDER_REGISTRY
_PROVIDER_ALIASES
_PROVIDER_MODELS
resolve_runtime_provider
_model_flow_
select_provider_and_model
api_mode
_API_KEY_PROVIDER_AUX_MODELS
self.client.

Модель мышления​

Сначала выберите путь реализации​

Путь A — OpenAI-совместимый провайдер​

Путь B — Нативный провайдер​

Контрольный список файлов​

Обязательно для каждого встроенного провайдера​

Дополнительно для нативных / не-OpenAI провайдеров​

Быстрый путь: Простые провайдеры с API-ключом​

Полный путь: OAuth и сложные провайдеры​

Шаг 1: Выберите один канонический идентификатор провайдера​

Шаг 2: Добавьте метаданные аутентификации в vibeos_cli/auth.py​

Шаг 3: Добавьте каталог моделей и псевдонимы в vibeos_cli/models.py​

Шаг 4: Разрешите данные времени выполнения в vibeos_cli/runtime_provider.py​

Шаг 5: Подключите CLI в vibeos_cli/main.py​

Шаг 6: Обеспечьте работу вспомогательных вызовов​

agent/auxiliary_client.py​

agent/model_metadata.py​

Шаг 7: Если провайдер нативный, добавьте адаптер и поддержку в run_agent.py​

Новый файл адаптера​

run_agent.py​

Кэширование подсказок и поля запроса, специфичные для провайдера​

Шаг 8: Тесты​

Шаг 9: Живая проверка​

Шаг 10: Обновите пользовательскую документацию​

Контрольный список для OpenAI-совместимого провайдера​

Контрольный список для нативного провайдера​

Распространённые ошибки​

1. Добавление провайдера в аутентификацию, но не в разбор моделей​

2. Забывание, что config["model"] может быть строкой или словарём​

3. Предположение, что встроенный провайдер обязателен​

4. Забывание вспомогательных путей​

5. Ветки нативного провайдера, спрятанные в run_agent.py​

6. Отправка настроек, предназначенных только для OpenRouter, другим провайдерам​

7. Обновление vibeos model, но не vibeos setup​

Хорошие цели для поиска при реализации​

Связанная документация​