Playground Studio (Русский)

Обзор

Playground Studio превращает /dashboard/playground из простого редактора на базе Monaco в полнофункциональное рабочее пространство для тестирования. Оно заменяет устаревший page.tsx оболочкой PlaygroundStudio, которая отображает четыре вкладки и общую панель конфигурации.

┌ Playground ──────────────────────────────────────────────────────────┐
│ [💬 Чат] [⚖ Сравнение] [{} API] [🔧 Сборка]  142↑ 38↓ · $0.002 </>│
├──────────────────────────────────────────┬───────────────────────────┤
│  {содержимое активной вкладки}           │ ─ Конфигурация            │
│                                          │ Эндпоинт  [чат ∨]         │
│                                          │ Модель    [gpt-5.4 ∨]     │
│                                          │ Система   [текстовое поле]│
│                                          │ Темп.     ▕▕▔▔ 0.7        │
│                                          │ Пресеты [▾ загрузить][сохранить]│
│                                          │ [✨ Улучшить промпт]       │
└──────────────────────────────────────────┴───────────────────────────┘

---

Вкладки

Вкладка чата

Расширяет ChatPlayground.tsx, превращая его в рабочее пространство для многоходового взаимодействия с потоковой передачей:

• Полноценный рендеринг Markdown с помощью MarkdownMessage.tsx (блоки кода, таблицы, списки, ссылки).
• Системный промпт берётся из общей панели конфигурации.
• Количество токенов и стоимость для каждого сообщения (токены промпта + токены завершения).
• Повторная генерация последнего ответа.
• Отправляет запросы в POST /v1/chat/completions с потоковой передачей SSE.

Вкладка сравнения

Ключевое преимущество прокси: запуск одного промпта параллельно для 4 моделей.

• До 4 столбцов, каждый из которых независимо получает потоковые данные из /v1/chat/completions.
• Кнопка + Добавить модель (сочетание клавиш Cmd+K) для добавления столбцов.
• Запустить все ▶ запускает все потоки одновременно с помощью Promise.all и отдельного AbortController для каждого столбца.
• Глобальная команда Отменить все прерывает каждый выполняющийся поток.
• Компонент ProviderMetrics в каждом столбце показывает TTFT, TPS, количество токенов и расчётную стоимость в реальном времени.
• Метрики помечены как «оценка на стороне клиента» (D12) — измерение начинается с первого фрагмента SSE.

Вкладка API

Полностью сохраняет исходный редактор Monaco для опытных пользователей (D14):

• 10 эндпоинтов: завершения чата, завершения, эмбеддинги, изображения, аудио, речь, транскрипции, модерация, переранжирование, поиск.
• Загрузка мультимодальных файлов.
• Потоковая передача SSE с выводом в реальном времени.
• Обёрнут в ApiTab.tsx (ленивая загрузка, ssr: false).

Вкладка сборки

Интерфейс для инструментов/вызова функций и структурированного вывода:

• ToolsBuilder.tsx — добавление, редактирование и удаление tools[] с редактором схемы JSON для каждого инструмента. Проверяет параметры с помощью ToolDefinitionSchema (Zod).
• StructuredOutputEditor.tsx — переключатель режима JSON и редактор схемы JSON. Проверяет ответ на соответствие схеме с помощью StructuredOutputSchema (Zod).
• Отправляет запрос в /v1/chat/completions с tools[] и/или response_format.

---

Панель конфигурации (общая)

StudioConfigPane.tsx — всегда видима, можно свернуть.

Поле	Компонент	Примечания
Эндпоинт	<select>	10 вариантов, соответствующих PlaygroundEndpoint
Модель	<input>	произвольный текст, например openai/gpt-4o
Системный промпт	<textarea>	передаётся во все вкладки
Параметры	ParamSliders	temperature, max_tokens, top_p, presence/frequency penalty, seed, stop
Пресеты	PresetPicker	загрузка/сохранение именованных снимков конфигурации (хранятся в БД)
Улучшение промпта	ImprovePromptButton	открывает модальное окно с предупреждением о квоте, вызывает /api/playground/improve-prompt

Состояние поднято в PlaygroundStudio.tsx и передаётся во все вкладки. При переключении вкладок состояние конфигурации сохраняется.

---

Верхняя панель

StudioTopBar.tsx:

• Переключатель вкладок (role=“tablist”).
• TokenCostCounter — отображение количества токенов (↑/↓) и оценочной стоимости в реальном времени.
• Кнопка экспорта кода (</>) — открывает ExportCodeModal.

---

Модальное окно экспорта кода

ExportCodeModal.tsx использует codeExport.ts для генерации фрагментов curl / Python / TypeScript из текущего PlaygroundState. В качестве заполнителя API-ключа всегда используется $OMNIROUTE_API_KEY (D11).

---

Улучшение промпта

ImprovePromptButton.tsx → useImprovePrompt.ts → POST /api/playground/improve-prompt:

1. Модальное окно предупреждает: «будет израсходована квота».
2. После подтверждения отправляет { system, prompt, model, tone } в маршрут.
3. Маршрут внутренне вызывает /v1/chat/completions с promptImprover.META_SYSTEM_PROMPT.
4. Возвращает { improvedSystem?, improvedPrompt?, tokensIn, tokensOut }.
5. Интерфейс обновляет системный промпт панели конфигурации и пользовательский промпт вкладки чата.

---

Пресеты

PresetPicker.tsx → usePresets.ts → /api/playground/presets/*:

• Хранятся в таблице SQLite playground_presets (миграция 084_playground_presets.sql).
• Каждый пресет содержит: name, endpoint, model, system, params_json, created_at.
• CRUD: список через GET, создание через POST, GET /:id, PUT /:id, DELETE /:id.

---

Метрики потоковой передачи

useStreamMetrics.ts + streamMetrics.ts (чистая функция):

• start() — записывает время начала запроса.
• onFirstChunk() — записывает TTFT.
• onChunk(n) — накапливает количество токенов завершения.
• finish(usage?) — вычисляет итоговые метрики: ttftMs, totalMs, tps, tokensIn, tokensOut, costUsd.
• Цены берутся из статической таблицы в src/lib/playground/types.ts (помечены как «оценочные» — D13).

---

Серверные маршруты

Метод	Путь	Обработчик
POST	/api/playground/improve-prompt	Проверяет ImprovePromptRequestSchema с помощью Zod; вызывает /v1/chat/completions с метапромптом
GET	/api/playground/presets	Возвращает { presets: PlaygroundPresetListItem[] }
POST	/api/playground/presets	Создаёт пресет; проверяет PlaygroundPresetCreateSchema
GET	/api/playground/presets/:id	Возвращает один пресет или 404
PUT	/api/playground/presets/:id	Частичное обновление
DELETE	/api/playground/presets/:id	204

Аутентификация: необязательная (REQUIRE_API_KEY). Ошибки формируются через buildErrorBody() (жёсткое правило №12).

---

Ключевые файлы

Путь	Назначение
src/app/(dashboard)/dashboard/playground/PlaygroundStudio.tsx	Компонент-оболочка, управление вкладками
src/app/(dashboard)/dashboard/playground/components/StudioTopBar.tsx	Вкладки + счётчик + кнопка экспорта
src/app/(dashboard)/dashboard/playground/components/StudioConfigPane.tsx	Общая панель конфигурации
src/app/(dashboard)/dashboard/playground/components/tabs/ChatTab.tsx	Рабочая область чата
src/app/(dashboard)/dashboard/playground/components/tabs/CompareTab.tsx	Сравнение нескольких моделей
src/app/(dashboard)/dashboard/playground/components/tabs/ApiTab.tsx	Редактор Monaco (сохранён)
src/app/(dashboard)/dashboard/playground/components/tabs/BuildTab.tsx	Инструменты + структурированный вывод
src/app/(dashboard)/dashboard/playground/components/ExportCodeModal.tsx	Модальное окно экспорта кода
src/app/(dashboard)/dashboard/playground/components/CompareColumn.tsx	Отдельный столбец сравнения
src/app/(dashboard)/dashboard/playground/components/ProviderMetrics.tsx	Отображение TTFT/TPS
src/app/(dashboard)/dashboard/playground/hooks/useStreamMetrics.ts	Клиентский хук метрик
src/app/(dashboard)/dashboard/playground/hooks/usePresets.ts	Хук CRUD для пресетов
src/app/(dashboard)/dashboard/playground/hooks/useImprovePrompt.ts	Хук улучшения промпта
src/lib/playground/codeExport.ts	Генератор curl/Python/TS (общий с Search Tools)
src/lib/playground/promptImprover.ts	Конструктор метапромпта
src/lib/playground/streamMetrics.ts	Чистое вычисление метрик
src/lib/db/playgroundPresets.ts	Модуль БД (CRUD)
src/app/api/playground/improve-prompt/route.ts	REST-маршрут улучшения промпта
src/app/api/playground/presets/route.ts	Получение списка и создание пресетов
src/app/api/playground/presets/[id]/route.ts	Получение/обновление/удаление пресетов
src/lib/db/migrations/084_playground_presets.sql	Миграция БД

---

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

Симптом	Причина	Решение
Редактор Monaco не отображается на вкладке API	Monaco загружен через SSR	Убедитесь, что ApiTab использует dynamic(..., { ssr: false })
Сравниваемые потоки запускаются последовательно	Неправильное использование Promise.all	Запуски всех потоков должны быть инициированы одним вызовом Promise.all
В метриках TTFT отображается null	Обработчик первого фрагмента не подключен	Проверьте, что useStreamMetrics.onFirstChunk() вызывается в цикле чтения SSE
Предустановка не сохраняется	Миграция БД не выполнена	Выполните npm run db:migrate или перезапустите сервер (миграция запускается автоматически при старте)
Функция улучшения промпта возвращает 502	Модель не указана в Config	Перед улучшением пользователь должен ввести имя модели на панели Config
В экспортированном коде отображается MISSING_API_KEY	Заполнитель не вставлен	codeExport.ts всегда использует API_KEY_PLACEHOLDER = "$OMNIROUTE_API_KEY"

---

Ссылки

• Основной план: _tasks/features-v3.8.6/refactorpages/_orchestration/master-plan-group-C.md
• План функции: _tasks/features-v3.8.6/refactorpages/17-playground-studio-redesign.plan.md
• Экспорт кода: src/lib/playground/codeExport.ts
• Улучшение промптов: src/lib/playground/promptImprover.ts
• Search Tools Studio: docs/frameworks/SEARCH_TOOLS_STUDIO.md

---

Исходный код OmniRoute (a58000c7685f)