Проектирование аутентификации OpenRouter и управления моделями

В этом документе описаны цели проектирования процесса аутентификации OpenRouter и связанных с ним изменений в управлении моделями. Документ намеренно фокусируется на продуктовых и архитектурных решениях, а не на истории реализации.

Цели

• Позволить пользователям проходить аутентификацию в OpenRouter как через CLI, так и через /auth.
• Переиспользовать существующий путь провайдера, совместимого с OpenAI, вместо добавления нового типа аутентификации для OpenRouter.
• Обеспечить удобный первый запуск без требования сразу управлять сотнями моделей.
• Сохранить понятный путь к расширенному управлению моделями через /manage-models.

OpenRouter Auth

OpenRouter интегрирован как провайдер, совместимый с OpenAI:

• тип аутентификации: AuthType.USE_OPENAI
• настройки провайдера: modelProviders.openai
• переменная окружения для API-ключа: OPENROUTER_API_KEY
• базовый URL: https://openrouter.ai/api/v1

Это позволяет избежать введения специфичного для OpenRouter AuthType, поскольку путь провайдера моделей в рантайме уже совместим с OpenAI. Такой подход сохраняет согласованность статуса аутентификации, разрешения моделей, выбора провайдера и схемы настроек с существующей абстракцией провайдера.

Пользовательские сценарии выглядят следующим образом:

• qwen auth openrouter --key <key> для автоматизации или прямой настройки API-ключа.
• qwen auth openrouter для OAuth через браузер.
• /auth → API Key → OpenRouter для сценария в TUI.

Браузерный OAuth использует PKCE-поток OpenRouter и записывает полученный API-ключ в настройки перед обновлением статуса аутентификации на AuthType.USE_OPENAI.

Model Management

OpenRouter предоставляет большой динамический каталог моделей. Запись каждой обнаруженной модели в modelProviders.openai загромождает /model и превращает долгосрочное поле настроек в кэш удалённого каталога.

Ключевое архитектурное разделение заключается в следующем:

• Каталог: полный набор моделей, обнаруженных из источника, такого как OpenRouter.
• Включённые модели: меньший набор моделей, которые должны отображаться в /model и сохраняться в пользовательских настройках.

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

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

/manage-models

Расширенное управление моделями должно быть вынесено в отдельную точку входа /manage-models. Этот процесс должен позволять пользователям:

• просматривать обнаруженные модели;
• выполнять поиск по id, отображаемому имени, префиксу провайдера и производным тегам, таким как free или vision;
• видеть, какие модели включены в данный момент;
• включать или отключать модели пакетами.

Параметр источника должен оставаться частью этого дизайна. OpenRouter — лишь первый источник динамического каталога; будущие источники, такие как ModelScope и ModelStudio, должны соответствовать той же структуре. Сложность UI можно снизить, но базовая абстракция источника должна оставаться доступной в качестве точки расширения.

Current Boundary

Это изменение должно реализовать необходимый минимум для удобной настройки аутентификации OpenRouter и моделей:

• Аутентификация через OAuth или по ключу настраивает OpenRouter через существующий путь провайдера, совместимого с OpenAI.
• Начальный набор включённых моделей формируется вручную, вместо того чтобы выгружать полный каталог в настройки.
• Полное хранение каталога, просмотр, фильтрация и пакетное управление переносятся в /manage-models.

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