solver-sdk 1.7.4 → 1.7.5

package/docs/WEBSOCKET.md

@@ -1,24 +1,10 @@
 # Работа с WebSocket соединениями
 
-В этом разделе описаны возможности SDK для работы с WebSocket соединениями, методы управления сессиями рассуждений, диагностика соединений и дополнительные возможности для обеспечения стабильной работы.
-
-## Содержание
-
-- [Основы работы с WebSocket](#основы-работы-с-websocket)
-- [Высокоуровневый API (версия 1.7.2)](#высокоуровневый-api-версия-172)
-- [Потоковая передача мышления](#потоковая-передача-мышления)
-- [Управление сессиями рассуждений](#управление-сессиями-рассуждений)
-- [Диагностика соединений](#диагностика-соединений)
-- [Механизм переподключения](#механизм-переподключения)
-- [Сохранение и восстановление сессий](#сохранение-и-восстановление-сессий)
-- [Проверка здоровья соединений](#проверка-здоровья-соединений)
-- [Работа с ping/pong](#работа-с-pingpong)
-- [Примеры использования](#примеры-использования)
-- [Справочник всех событий WebSocket](#справочник-всех-событий-websocket)
+В этом разделе описаны методы SDK для работы с WebSocket соединениями и потоковой передачей данных.
 
 ## Основы работы с WebSocket
 
-SDK предоставляет низкоуровневый WebSocket клиент (`CodeSolverWebSocketClient`), который используется для связи с различными пространствами имен сервера:
+SDK предоставляет высокоуровневое API для работы с WebSocket, интегрированное в основные классы:
 
 ```javascript
 const { CodeSolverSDK } = require('solver-sdk');
@@ -34,24 +20,20 @@ const wsClient = sdk.getWebSocketClient();
 // Подключение к пространству имен рассуждений
 await wsClient.connectToReasoning('reasoning-id');
 
-// Проверка состояния подключения
-const isConnected = wsClient.isConnectedToReasoning();
-console.log('Подключено к рассуждениям:', isConnected);
-
 // Подписка на события
-wsClient.on('thinking_delta', (data) => {
-  console.log('Получен фрагмент мышления:', data.text);
+wsClient.on('content_block_delta', (data) => {
+  if (data.delta?.type === 'thinking_delta') {
+    console.log('Фрагмент мышления:', data.delta.thinking);
+  }
 });
 
 // Отключение
 wsClient.disconnect(WebSocketNamespace.REASONING);
 ```
 
-## Высокоуровневый API (версия 1.7.2)
+## Модули с поддержкой WebSocket
 
-Начиная с версии 1.7.2, SDK предоставляет высокоуровневый API для работы с WebSocket, интегрированный непосредственно в основные классы API:
-
-### Работа с чатом и рассуждениями
+### Чат и рассуждения
 
 ```javascript
 // Подключение WebSocket для чата
@@ -62,15 +44,17 @@ sdk.chat.on('message_start', (data) => {
   console.log('Начало сообщения:', data);
 });
 
-sdk.chat.on('thinking_delta', (data) => {
-  console.log('Фрагмент мышления:', data.text);
+sdk.chat.on('content_block_delta', (data) => {
+  if (data.delta?.type === 'thinking_delta') {
+    console.log('Фрагмент мышления:', data.delta.thinking);
+  }
 });
 
 // Отключение 
 await sdk.chat.disconnectWebSocket();
 ```
 
-### Работа с зависимостями
+### Зависимости
 
 ```javascript
 // Подключение к пространству имен зависимостей
@@ -85,7 +69,7 @@ sdk.dependencies.on('dependency_update', (data) => {
 await sdk.dependencies.disconnectWebSocket();
 ```
 
-### Работа с проектами и индексацией
+### Проекты и индексация
 
 ```javascript
 // Подключение к пространству имен проектов
@@ -100,32 +84,38 @@ sdk.projects.on('indexing_progress', (data) => {
 await sdk.projects.disconnectWebSocket();
 ```
 
+## Поддерживаемые события
+
+Основные события, на которые можно подписаться:
+
+| Событие | Описание | Примечание |
+|---------|----------|------------|
+| `message_start` | Начало сообщения | { id, model, type } |
+| `content_block_start` | Начало блока контента | { content_block: { type }, index } |
+| `content_block_delta` | Дельта блока контента | См. документацию для типов дельт |
+| `content_block_stop` | Конец блока контента | { content_block: { type }, index } |
+| `message_stop` | Конец сообщения | { id, type, stop_reason } |
+| `error` | Ошибка | { message, code, ... } |
+
 ## Потоковая передача мышления
 
-В версии 1.7.2 добавлена полная поддержка потоковой передачи мышления через метод `streamChatWithThinking`:
+Самый простой способ получать мышление — использовать метод `streamChatWithThinking`:
 
 ```javascript
 // Обработчик событий
 const handleEvent = (eventType, data) => {
-  switch(eventType) {
-    case 'thinking_delta':
-      console.log('Мышление:', data.text);
-      break;
-    case 'text_delta':
-      console.log('Ответ:', data.text);
-      break;
-    case 'message_start':
-      console.log('Начало сообщения');
-      break;
-    case 'message_stop':
-      console.log('Завершение ответа');
-      break;
+  if (eventType === 'content_block_delta' && data.delta?.type === 'thinking_delta') {
+    console.log('Мышление:', data.delta.thinking);
+  } else if (eventType === 'content_block_delta' && data.delta?.type === 'text_delta') {
+    console.log('Ответ:', data.delta.text);
+  } else if (eventType === 'message_stop') {
+    console.log('Завершение ответа');
   }
 };
 
 // Отправка запроса с потоковым мышлением
 const messages = [
-  { role: 'user', content: 'Как работает квантовый компьютер?' }
+  { role: 'user', content: 'Объясни квантовую механику' }
 ];
 
 const options = {
@@ -141,368 +131,39 @@ const response = await sdk.chat.streamChatWithThinking(
 );
 ```
 
-### Поддерживаемые события мышления
-
-SDK поддерживает следующие ключевые события:
-
-| Событие | Описание | Данные |
-|---------|----------|--------|
-| `message_start` | Начало сообщения | `{ model: string, type: string }` |
-| `content_block_start` | Начало блока контента | `{ index: number, type: string }` |
-| `thinking_delta` | Фрагмент мышления | `{ text: string, index: number }` |
-| `text_delta` | Фрагмент ответа | `{ text: string, index: number }` |
-| `content_block_stop` | Завершение блока контента | `{ index: number, type: string }` |
-| `message_stop` | Завершение сообщения | `{ type: string }` |
-
-## Управление сессиями рассуждений
-
-SDK версии 1.7.0+ предоставляет расширенные возможности для управления сессиями рассуждений:
-
-### Установка активной сессии рассуждения
-
-```javascript
-// Простая установка активного ID рассуждения
-wsClient.setActiveReasoningId('reasoning-id');
-
-// Расширенный вариант с дополнительными возможностями
-await wsClient.setActiveReasoningIdAsync(
-  'reasoning-id', // ID рассуждения (можно передать null для создания нового)
-  true,           // waitForJoin: ждать результата присоединения
-  true            // createIfNotExists: создать новое, если не существует
-);
-```
-
-### Создание нового рассуждения
-
-```javascript
-// Создание нового рассуждения и получение его ID
-const newReasoningId = await wsClient.createNewReasoning();
-console.log('Создано новое рассуждение:', newReasoningId);
-```
-
-### Проверка существования рассуждения
-
-```javascript
-// Проверка существования рассуждения на сервере
-const exists = await wsClient.checkReasoningExists('reasoning-id');
-if (exists) {
-  console.log('Рассуждение существует');
-} else {
-  console.log('Рассуждение не найдено');
-}
-```
-
-### Получение статуса рассуждения
+## Обработка ошибок
 
 ```javascript
-// Получение детальной информации о сессии рассуждения
-const status = await wsClient.getReasoningStatus('reasoning-id');
-console.log('Статус:', status.exists, status.isActive);
-console.log('Метаданные:', status.metadata);
-```
-
-### Присоединение к сессии рассуждения
-
-```javascript
-// Явное присоединение к существующей сессии
-const joined = await wsClient.joinReasoning(
-  'reasoning-id',
-  true // setActive: установить как активное рассуждение
-);
-
-if (joined) {
-  console.log('Успешно присоединились к рассуждению');
-} else {
-  console.log('Не удалось присоединиться к рассуждению');
-}
-```
-
-## Диагностика соединений
-
-SDK предоставляет методы для диагностики состояния соединений и получения подробной информации о них:
-
-```javascript
-// Диагностика конкретного соединения
-const diagnostics = wsClient.diagnoseConnection(WebSocketNamespace.REASONING);
-console.log('Диагностика соединения:', diagnostics);
-
-// Диагностика всех активных соединений
-const allDiagnostics = wsClient.diagnoseAllConnections();
-console.log('Все соединения:', allDiagnostics);
-```
-
-Результат диагностики содержит следующую информацию:
-
-```typescript
-interface ConnectionDiagnostics {
-  namespace: WebSocketNamespace;  // Пространство имен
-  isConnected: boolean;          // Активно ли соединение
-  socketId: string | null;       // ID сокета
-  lastActivity: number;          // Время последней активности
-  rtt: {                         // Round Trip Time (задержка)
-    current: number;             // Текущая задержка
-    min: number;                 // Минимальная задержка
-    max: number;                 // Максимальная задержка
-    avg: number;                 // Средняя задержка
-  };
-  pingSent: number;              // Отправлено ping-сообщений
-  pongReceived: number;          // Получено pong-ответов
-  missedPongs: number;           // Пропущено pong-ответов
-  timeoutCount: number;          // Количество таймаутов
-  reconnectAttempts: number;     // Количество попыток переподключения
-  lastConnectTime: number;       // Время последнего подключения
-  sessionRecovery: {             // Информация о восстановлении сессии
-    hasSessionToken: boolean;    // Наличие токена сессии
-    tokenLength: number;         // Длина токена сессии
-    wasRecovered: boolean;       // Было ли восстановлено из сессии
-  };
-}
-```
-
-## Механизм переподключения
-
-SDK реализует интеллектуальный механизм переподключения с экспоненциальной задержкой и случайным фактором (jitter) для предотвращения штормов переподключений:
-
-```javascript
-// Настройка параметров переподключения при создании SDK
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.example.com',
-  apiKey: 'your-api-key',
-  websocket: {
-    reconnect: true,               // Включить автоматическое переподключение
-    reconnectStrategy: 'exponential', // 'linear' или 'exponential'
-    retryDelay: 1000,                // Базовая задержка в миллисекундах
-    maxRetryDelay: 30000,            // Максимальная задержка
-    reconnectAttempts: 5             // Максимальное количество попыток
+try {
+  await sdk.chat.streamChatWithThinking(
+    messages,
+    options,
+    handleEvent
+  );
+} catch (error) {
+  if (error.code === 'CONNECTION_ERROR') {
+    console.error('Ошибка подключения:', error.message);
+  } else {
+    console.error('Произошла ошибка:', error.message);
   }
-});
-
-// Принудительное переподключение к пространству имен
-await wsClient.reconnectNamespace(
-  WebSocketNamespace.REASONING,
-  true // immediate: переподключиться немедленно, без задержки
-);
+}
 ```
 
-## Сохранение и восстановление сессий
-
-SDK поддерживает механизм сохранения и восстановления токенов сессий для непрерывной работы при переподключениях:
+## Настройка WebSocket
 
 ```javascript
-// Явное сохранение токена сессии
-wsClient.saveSessionToken(WebSocketNamespace.REASONING, 'session-token');
-
-// Получение сохраненного токена
-const token = wsClient.getSessionToken(WebSocketNamespace.REASONING);
-
-// Очистка токена сессии
-wsClient.clearSessionToken(WebSocketNamespace.REASONING);
-
-// Включение/отключение сохранения сессий при создании SDK
+// Настройка параметров WebSocket при создании SDK
 const sdk = new CodeSolverSDK({
   baseURL: 'https://api.example.com',
   apiKey: 'your-api-key',
   websocket: {
-    enableSessionPersistence: true // Включить сохранение токенов сессий
+    reconnect: true,               // Автоматическое переподключение
+    reconnectAttempts: 5,           // Максимальное количество попыток
+    rejectUnauthorized: false       // Для самоподписанных сертификатов
   }
 });
 ```
 
-## Проверка здоровья соединений
-
-SDK предоставляет механизм регулярной проверки здоровья соединений и автоматического переподключения при обнаружении проблем:
-
-```javascript
-// Настройка проверки здоровья соединений
-wsClient.setupConnectionHealthCheck(
-  30000 // Интервал проверки в миллисекундах
-);
-
-// Отключение проверки здоровья
-if (wsClient.healthCheckTimer) {
-  clearInterval(wsClient.healthCheckTimer);
-  wsClient.healthCheckTimer = null;
-}
-```
-
-## Работа с ping/pong
-
-Для поддержания активных соединений и измерения времени отклика SDK использует механизм ping/pong:
-
-```javascript
-// Включение автоматического ping/pong
-wsClient.enablePingPong(
-  15000, // Интервал между ping-сообщениями (мс)
-  3      // Порог таймаута (количество пропущенных pong)
-);
-
-// Отключение механизма ping/pong
-wsClient.disablePingPong();
-
-// Получение статистики ping/pong
-const stats = wsClient.getPingStats(WebSocketNamespace.REASONING);
-console.log('Статистика ping/pong:', stats);
-
-// Подписка на события таймаута соединения
-wsClient.onPingPongEvent('connection_timeout', (data) => {
-  console.log('Таймаут соединения:', data);
-});
-```
-
-## Примеры использования
-
-### Работа с потоковой передачей мышления
-
-```javascript
-const { CodeSolverSDK } = require('solver-sdk');
-
-async function streamingThinking() {
-  const sdk = new CodeSolverSDK({
-    baseURL: 'https://api.example.com',
-    apiKey: 'ваш-ключ-api',
-    websocket: {
-      reconnect: true,
-      pingInterval: 30000
-    }
-  });
-  
-  // Подключаем WebSocket
-  await sdk.chat.connectWebSocket();
-  
-  // Создаем буферы для накопления контента
-  let thinkingBuffer = '';
-  let responseBuffer = '';
-  
-  // Настраиваем обработчик событий
-  const handleEvent = (eventType, data) => {
-    switch(eventType) {
-      case 'thinking_delta':
-        thinkingBuffer += data.text || '';
-        // Обновляем UI с мышлением
-        updateThinkingUI(thinkingBuffer);
-        break;
-        
-      case 'text_delta':
-        responseBuffer += data.text || '';
-        // Обновляем UI с ответом
-        updateResponseUI(responseBuffer);
-        break;
-        
-      case 'message_stop':
-        console.log('Обработка завершена');
-        break;
-    }
-  };
-  
-  // Отправляем запрос
-  const messages = [
-    { role: 'user', content: 'Объясни принцип работы квантового компьютера' }
-  ];
-  
-  try {
-    const response = await sdk.chat.streamChatWithThinking(
-      messages,
-      {
-        model: 'claude-3-7-sonnet-20240229',
-        thinking: true,
-        temperature: 0.7
-      },
-      handleEvent
-    );
-    
-    console.log('Запрос отправлен, ID сокета:', response.socketId);
-    
-    // После завершения можно отключиться
-    setTimeout(() => {
-      sdk.chat.disconnectWebSocket();
-      console.log('Соединение закрыто');
-    }, 1000);
-    
-    return {
-      thinking: thinkingBuffer,
-      response: responseBuffer
-    };
-  } catch (error) {
-    console.error('Ошибка при отправке запроса:', error);
-    sdk.chat.disconnectWebSocket();
-    throw error;
-  }
-}
-
-// Функции для обновления UI
-function updateThinkingUI(text) {
-  console.log('Обновление блока мышления');
-  // document.getElementById('thinking-container').textContent = text;
-}
-
-function updateResponseUI(text) {
-  console.log('Обновление блока ответа');
-  // document.getElementById('response-container').textContent = text;
-}
-
-// Запуск функции
-streamingThinking().catch(console.error);
-```
-
-### Работа с региональным переключением
-
-```javascript
-const { CodeSolverSDK } = require('solver-sdk');
-
-async function chatWithRegionalFailover() {
-  const sdk = new CodeSolverSDK({
-    baseURL: 'https://api.example.com',
-    apiKey: 'ваш-ключ-api',
-    providers: {
-      anthropic: {
-        region: 'us-east-1' // Базовый регион
-      }
-    }
-  });
-  
-  // Подключаем WebSocket
-  await sdk.chat.connectWebSocket();
-  
-  // Настраиваем обработчик для отображения региона и ошибок
-  sdk.chat.on('region_switch', (data) => {
-    console.log(`Переключение на регион: ${data.region}`);
-  });
-  
-  sdk.chat.on('error', (data) => {
-    console.error('Ошибка:', data);
-  });
-  
-  // Отправляем запрос с автоматическим переключением регионов при ошибках
-  try {
-    const response = await sdk.chat.chatWithRegionFailover(
-      [{ role: 'user', content: 'Расскажи о квантовой физике' }],
-      {
-        model: 'claude-3-7-sonnet-20240229',
-        thinking: true,
-        // Порядок перебора регионов при ошибках
-        regionPreference: ['us-east-1', 'eu-west-1', 'ap-southeast-2']
-      }
-    );
-    
-    console.log('Ответ получен из региона:', response.region);
-    console.log('Ответ:', response.choices[0].message.content);
-    
-    return response;
-  } catch (error) {
-    console.error('Не удалось получить ответ ни из одного региона:', error);
-    throw error;
-  } finally {
-    await sdk.chat.disconnectWebSocket();
-  }
-}
-
-chatWithRegionalFailover().catch(console.error);
-```
-
-## Справочник всех событий WebSocket
-
-Полный список всех поддерживаемых WebSocket событий, их описание, формат данных и примеры использования доступны в отдельном документе:
-
-[Справочник WebSocket событий SDK](./WEBSOCKET_EVENTS.md)
+## Дополнительная информация
 
-В этом справочнике содержится подробная информация обо всех константах событий, их строковых значениях, форматах данных и рекомендациях по использованию в различных сценариях.
+Для детального описания всех возможностей WebSocket, смотрите [руководство по мышлению](./features/THINKING.md) и примеры в директории [examples/websocket](../examples/websocket).