solver-sdk/docs/thinking/streaming-thinking-guide.md

SDK для интеграции с Code Solver Backend API (совместимо с браузером и Node.js), с поддержкой функциональности мышления (Thinking Mode)

# Руководство: Потоковый чат с Thinking через SDK

Это руководство объясняет, как использовать обновленный `solver-sdk` для получения потоковых ответов от языковой модели с поддержкой режима "thinking" через WebSocket. Это позволяет отображать ход мыслей модели и финальный ответ в реальном времени.

## Основной метод: `streamChatWithThinking`

Для потоковой передачи с thinking используйте новый метод `sdk.chat.streamChatWithThinking`.

**Преимущества:**

- **Автоматическое подключение WebSocket:** SDK сам создает и управляет WebSocket соединением.
- **Простая обработка событий:** Вы просто предоставляете callback-функцию для обработки всех событий потока.
- **Полная поддержка Anthropic:** Обрабатываются все актуальные события (`thinking_delta`, `text_delta`, `signature_delta`, `message_delta`, `ping` и т.д.).

## Пример использования

```javascript
const { CodeSolverSDK } = require('solver-sdk'); // Или import { CodeSolverSDK } from 'solver-sdk';

async function runStreamingExample() {
  // 1. Инициализация SDK
  const sdk = new CodeSolverSDK({
    baseURL: 'https://your-backend-url.com', // URL вашего бэкенда
    // apiKey: 'your-api-key' // Если требуется
  });

  // 2. Сообщения для отправки
  const messages = [
    { role: 'user', content: 'Объясни теорию относительности простыми словами.' }
  ];

  // 3. Опции запроса (включаем thinking)
  const options = {
    model: 'claude-3-7-sonnet-20240229', // Или другая модель с поддержкой thinking
    thinking: true, // Обязательно для активации режима
    temperature: 0.7
  };

  // 4. Обработчик событий WebSocket
  const handleEvent = (eventType, data) => {
    console.log(`[EVENT: ${eventType}]`, data); // Логирование всех событий для отладки

    switch(eventType) {
      // Начало потока
      case 'connect':
        console.log(`WebSocket подключен: ${data.socketId}`);
        break;
      case 'message_start':
        console.log(`Начало ответа модели: ${data.model}`);
        // Здесь можно инициализировать UI для отображения ответа
        break;

      // Поток размышлений
      case 'thinking_start':
        console.log('-- Начало размышлений --');
        // Очистить/показать область для размышлений
        break;
      case 'thinking_delta':
        process.stdout.write(data.text); // Выводим текст размышлений по мере поступления
        // Добавить data.text в UI область размышлений
        break;
      case 'signature_delta':
        console.log('[Подпись блока thinking получена]');
        break;

      // Поток основного ответа
      case 'text_delta':
        process.stdout.write(data.text); // Выводим текст ответа по мере поступления
        // Добавить data.text в UI область ответа
        break;

      // Завершение блоков и сообщения
      case 'content_block_stop':
        // Блок (thinking или text) завершен
        break;
      case 'message_delta':
        // Обновление статуса сообщения (например, stop_reason)
        console.log(`Обновление сообщения: ${JSON.stringify(data.delta)}`);
        break;
      case 'message_stop':
        console.log('-- Сообщение завершено --');
        // Показать финальное состояние UI
        break;

      // Служебные события
      case 'ping':
        console.log('[Ping от сервера]');
        break;
      case 'retry':
        console.warn(`Попытка переподключения ${data.retryCount} из-за перегрузки...`);
        break;

      // Ошибки и завершение
      case 'error':
        console.error(`Ошибка WebSocket: ${data.message} (Код: ${data.code})`);
        // Показать сообщение об ошибке в UI
        break;
      case 'disconnect':
        console.log('WebSocket отключен');
        break;
      case 'done':
        console.log('Поток данных завершен.');
        // Можно закрыть соединение или ожидать новых запросов
        break;
        
      case 'unknown_event':
        console.log(`Получено неизвестное событие: ${data.type}`);
        break;
    }
  };

  // 5. Вызов метода и ожидание потока
  try {
    console.log('Отправка запроса...');
    const response = await sdk.chat.streamChatWithThinking(
      messages,
      options,
      handleEvent // Передаем наш обработчик
    );

    console.log(`Запрос успешно отправлен. Используется Socket ID: ${response.socketId}`);
    console.log('Ожидание событий через WebSocket...');
    // В реальном приложении здесь будет основной цикл работы или ожидание

  } catch (error) {
    console.error('Ошибка при отправке запроса:', error);
    // Обработка ошибки инициации запроса
  }
}

// Запуск примера
runStreamingExample();
```

## Ключевые моменты

1.  **Включите `thinking: true`**: Это главный параметр для активации режима потокового мышления.
2.  **Предоставьте обработчик `onEvent`**: Эта функция будет получать все события WebSocket.
3.  **Обрабатывайте нужные события**: Как минимум, вам понадобятся `thinking_delta` (для размышлений) и `text_delta` (для основного ответа), а также `error` и `done`.
4.  **SDK управляет соединением**: Вам не нужно вручную создавать `socketId` или подключаться к WebSocket – SDK сделает это автоматически.

## (Опционально) Использование существующего `socketId`

Если ваш клиент уже управляет WebSocket соединением и имеет `socketId`, вы можете передать его в опциях, чтобы SDK использовал существующее соединение:

```javascript
// Предположим, у вас есть connectResponse от sdk.chat.connectWebSocket()
const existingSocketId = connectResponse.socketId;

const options = {
  model: 'claude-3-7-sonnet-20240229',
  thinking: true,
  socketId: existingSocketId // Передаем существующий ID
};

// SDK не будет создавать новое соединение, а использует указанное
const response = await sdk.chat.streamChatWithThinking(
  messages,
  options,
  handleEvent 
);
```

Это полезно, если вы хотите использовать одно WebSocket соединение для нескольких запросов.