solver-sdk 2.5.0 → 2.6.0

package/docs/WEBSOCKET.md

@@ -1,168 +1,431 @@
-# Работа с WebSocket в Solver SDK
+# WebSocket API v2.5.0
 
-Эта документация описывает, как использовать WebSocket соединения через высокоуровневые методы Solver SDK для работы в реальном времени.
+Полная документация по работе с WebSocket соединениями в AI Solver SDK v2.5.0.
 
-## Инициализация SDK
+## Инициализация с контролируемыми подключениями
 
 ```javascript
-const { CodeSolverSDK } = require('solver-sdk');
+import { CodeSolverSDK } from '@ai-solver/sdk';
 
-// Создаем экземпляр SDK с настройками
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.example.com',
-  apiKey: 'your-api-key',
-  websocket: {
-    reconnect: true,      // Автоматическое переподключение при разрыве соединения
-    reconnectAttempts: 5, // Максимальное количество попыток переподключения
-    reconnectDelay: 3000  // Задержка между попытками (мс)
-  }
+// Рекомендуемый способ с autoConnect: false
+const sdk = CodeSolverSDK.create({
+  baseURL: 'http://localhost:3000',
+  apiKey: 'dev_sk_test_12345678',
+  autoConnect: false // Контролируемые WebSocket подключения
 });
 
-// Единое подключение ко всем сервисам
-await sdk.connect();
+// Диагностика перед подключением
+const wsStatus = await sdk.diagnoseWebSocket();
+console.log('WebSocket readiness:', wsStatus);
 ```
 
-## Работа с индексацией проектов
+## WebSocket Namespaces
+
+SDK поддерживает 3 основных WebSocket namespace:
+
+1. **Projects** (`/projects`) - события проектов и индексации
+2. **Reasoning** (`/reasoning`) - события AI reasoning процессов
+3. **Chat** (`/chat`) - события потокового чата и thinking
+
+## Projects WebSocket
+
+### Подключение
 
 ```javascript
-// Подключение к WebSocket для проектов
+// Подключение к projects namespace
 await sdk.projects.connectWebSocket();
 
-// Отслеживание прогресса индексации
-sdk.projects.on('indexing_progress', (data) => {
-  console.log(`Прогресс индексации: ${data.progress}%`);
-  console.log(`Обработано файлов: ${data.processedFiles} из ${data.totalFiles}`);
+// Проверка статуса подключения
+const isConnected = sdk.projects.isWebSocketConnected();
+console.log('Projects WebSocket connected:', isConnected);
+```
+
+### События индексации
+
+#### `indexing_progress`
+
+Прогресс индексации в реальном времени.
+
+```javascript
+sdk.projects.onIndexingProgress((data) => {
+  console.log(`Progress: ${data.percentage}%`);
+  console.log(`Files: ${data.processedFiles}/${data.totalFiles}`);
+  console.log(`Current: ${data.currentFile}`);
+  console.log(`Status: ${data.status}`);
+  console.log(`Speed: ${data.filesPerSecond} files/sec`);
 });
+```
 
-// Завершение индексации
-sdk.projects.on('indexing_complete', (data) => {
-  console.log('Индексация завершена!', data.success ? 'Успешно' : 'С ошибками');
-  
-  // Отключение после завершения
-  sdk.projects.disconnectWebSocket();
+#### `indexing_complete`
+
+Завершение индексации.
+
+```javascript
+sdk.projects.onIndexingComplete((data) => {
+  console.log('Indexing completed:', data.projectId);
+  console.log('Total files:', data.totalFiles);
+  console.log('Duration:', data.duration);
+  console.log('Success:', data.success);
+  console.log('Errors:', data.errors);
 });
+```
+
+#### `indexing_error`
+
+Ошибки индексации.
 
-// Запуск индексации проекта
-await sdk.projects.indexProject('project-id');
+```javascript
+sdk.projects.onIndexingError((error) => {
+  console.error('Indexing error:', error.message);
+  console.error('Project:', error.projectId);
+  console.error('File:', error.fileName);
+  console.error('Code:', error.errorCode);
+});
 ```
 
-## Работа с рассуждениями (Reasoning)
+### Пример полного цикла индексации
 
 ```javascript
-// Создание рассуждения
-const reasoning = await sdk.reasoning.createReasoning({
-  projectId: 'project-id',
-  query: 'Объясни этот проект'
+async function indexProjectWithProgress(projectId) {
+  // Подключение к WebSocket
+  await sdk.projects.connectWebSocket();
+  
+  // Настройка обработчиков
+  sdk.projects.onIndexingProgress((data) => {
+    const progress = Math.round(data.percentage);
+    console.log(`[${progress}%] ${data.currentFile}`);
+  });
+  
+  sdk.projects.onIndexingComplete((data) => {
+    console.log('✅ Indexing completed!');
+    console.log(`📊 ${data.totalFiles} files indexed in ${data.duration}ms`);
+    sdk.projects.disconnectWebSocket();
+  });
+  
+  sdk.projects.onIndexingError((error) => {
+    console.error('❌ Indexing failed:', error.message);
+    sdk.projects.disconnectWebSocket();
+  });
+  
+  // Запуск индексации
+  await sdk.projects.startIndexing(projectId);
+}
+```
+
+## Reasoning WebSocket
+
+### Подключение
+
+```javascript
+// Подключение к reasoning namespace
+await sdk.reasoning.connectWebSocket();
+```
+
+### События reasoning
+
+#### `reasoning_started`
+
+Начало reasoning процесса.
+
+```javascript
+sdk.reasoning.onReasoningStarted((data) => {
+  console.log('🚀 Reasoning started:', data.id);
+  console.log('📝 Query:', data.query);
+  console.log('🎯 Project:', data.projectId);
 });
+```
 
-// Подключение к WebSocket для рассуждений
-await sdk.reasoning.connectWebSocket(reasoning.id);
+#### `reasoning_progress`
 
-// Подписка на события
-sdk.reasoning.on('thinking', (data) => {
-  console.log('Мышление:', data.content);
+Прогресс reasoning.
+
+```javascript
+sdk.reasoning.onReasoningProgress((data) => {
+  console.log('⚡ Progress:', data.progress);
+  console.log('📍 Step:', data.currentStep);
+  console.log('🔍 Action:', data.action);
 });
+```
+
+#### `reasoning_completed`
 
-sdk.reasoning.on('complete', (data) => {
-  console.log('Результат:', data.content);
-  // Отключение после завершения
-  sdk.reasoning.disconnectWebSocket();
+Завершение reasoning.
+
+```javascript
+sdk.reasoning.onReasoningCompleted((data) => {
+  console.log('✅ Reasoning completed:', data.id);
+  console.log('📊 Results:', data.results);
+  console.log('⏱️ Duration:', data.duration);
 });
+```
 
-// Запуск рассуждения
-await sdk.reasoning.startReasoning(reasoning.id);
+#### `reasoning_error`
+
+Ошибки reasoning.
+
+```javascript
+sdk.reasoning.onReasoningError((error) => {
+  console.error('❌ Reasoning error:', error.message);
+  console.error('🆔 Reasoning ID:', error.reasoningId);
+});
 ```
 
-## Потоковый чат с мышлением AI
+### Пример reasoning с WebSocket
 
 ```javascript
-// Обработчик событий для потокового получения ответа и мышления
-const handleEvent = (eventType, data) => {
-  if (eventType === 'thinking_delta' && data.thinking) {
-    console.log('Мышление:', data.thinking);
-  } else if (eventType === 'text_delta' && data.text) {
-    process.stdout.write(data.text);
-  } else if (eventType === 'message_stop') {
-    console.log('\nОтвет завершен');
-  }
-};
+async function runReasoningWithEvents(projectId, query) {
+  // Подключение
+  await sdk.reasoning.connectWebSocket();
+  
+  // Обработчики
+  sdk.reasoning.onReasoningStarted((data) => {
+    console.log('🚀 Started reasoning:', data.id);
+  });
+  
+  sdk.reasoning.onReasoningProgress((data) => {
+    console.log(`⚡ ${data.progress}% - ${data.currentStep}`);
+  });
+  
+  sdk.reasoning.onReasoningCompleted((data) => {
+    console.log('✅ Results:', data.results);
+    sdk.reasoning.disconnectWebSocket();
+  });
+  
+  // Создание и запуск
+  const reasoning = await sdk.reasoning.create({
+    projectId: projectId,
+    query: query
+  });
+  
+  await sdk.reasoning.start(reasoning.id);
+}
+```
 
-// Отправка запроса 
-const messages = [
-  { role: 'user', content: 'Расскажи о JavaScript' }
-];
+## Chat WebSocket
 
-const options = {
-  model: 'claude-3-7-sonnet-20240229',
-  thinking: true,
-  temperature: 0.7
-};
+### Подключение
 
-// Отправка с потоковым получением ответа
-const response = await sdk.chat.streamChatWithThinking(
-  messages, 
-  options,
-  handleEvent
-);
+```javascript
+// Подключение к chat namespace
+await sdk.chat.connectWebSocket();
 ```
 
-## Работа с зависимостями
+### События потокового чата
+
+#### `text_delta`
+
+Фрагменты текстового ответа.
 
 ```javascript
-// Подключение к пространству имен зависимостей
-await sdk.dependencies.connectWebSocket(projectId);
+sdk.chat.onTextDelta((text) => {
+  process.stdout.write(text); // Вывод в реальном времени
+});
+```
+
+#### `thinking_delta`
 
-// Подписка на события зависимостей
-sdk.dependencies.on('dependency_update', (data) => {
-  console.log('Обновление зависимостей:', data);
+Фрагменты thinking блоков (Claude 4).
+
+```javascript
+sdk.chat.onThinkingDelta((thinking) => {
+  console.log('🧠 Thinking:', thinking);
 });
+```
+
+#### `tool_use`
+
+Использование инструментов AI.
+
+```javascript
+sdk.chat.onToolUse((tool) => {
+  console.log('🔧 Tool used:', tool.name);
+  console.log('📥 Input:', tool.input);
+});
+```
+
+#### `message_complete`
+
+Завершение сообщения.
+
+```javascript
+sdk.chat.onMessageComplete((message) => {
+  console.log('✅ Message completed');
+  console.log('📄 Full content:', message.content);
+});
+```
+
+### Потоковый чат с thinking
+
+```javascript
+async function streamChatWithThinking(messages) {
+  // Подключение
+  await sdk.chat.connectWebSocket();
+  
+  let fullResponse = '';
+  let thinkingContent = '';
+  
+  // Обработчики
+  sdk.chat.onThinkingDelta((thinking) => {
+    thinkingContent += thinking;
+    console.log('🧠 Thinking fragment:', thinking);
+  });
+  
+  sdk.chat.onTextDelta((text) => {
+    fullResponse += text;
+    process.stdout.write(text);
+  });
+  
+  sdk.chat.onToolUse((tool) => {
+    console.log(`\n🔧 Using tool: ${tool.name}`);
+  });
+  
+  sdk.chat.onMessageComplete((message) => {
+    console.log('\n✅ Response completed');
+    console.log('💭 Full thinking:', thinkingContent);
+    sdk.chat.disconnectWebSocket();
+  });
+  
+  // Отправка с thinking
+  await sdk.chat.stream(messages, {
+    thinking: true,
+    model: 'claude-3-5-sonnet-20241022',
+    tool_choice: { type: 'auto' }
+  });
+}
+```
+
+## Управление подключениями
+
+### Подключение/отключение
+
+```javascript
+// Подключение к конкретным namespace
+await sdk.projects.connectWebSocket();
+await sdk.reasoning.connectWebSocket();
+await sdk.chat.connectWebSocket();
 
 // Отключение
-await sdk.dependencies.disconnectWebSocket();
+await sdk.projects.disconnectWebSocket();
+await sdk.reasoning.disconnectWebSocket();
+await sdk.chat.disconnectWebSocket();
+
+// Проверка статуса
+console.log('Projects WS:', sdk.projects.isWebSocketConnected());
+console.log('Reasoning WS:', sdk.reasoning.isWebSocketConnected());
+console.log('Chat WS:', sdk.chat.isWebSocketConnected());
 ```
 
-## Автоматическая авторизация
+### Диагностика WebSocket
 
-**Важно:** Авторизация происходит автоматически, если указан `apiKey` при инициализации SDK. Отдельных действий для авторизации не требуется.
+```javascript
+// Полная диагностика WebSocket
+const wsStatus = await sdk.diagnoseWebSocket();
+console.log('WebSocket Diagnostics:', wsStatus);
+
+/* Пример ответа:
+{
+  projects: { connected: true, url: 'ws://localhost:3000/projects' },
+  reasoning: { connected: false, url: 'ws://localhost:3000/reasoning' },
+  chat: { connected: true, url: 'ws://localhost:3000/chat' }
+}
+*/
+```
 
-## Обработка ошибок и переподключение
+## Обработка ошибок WebSocket
 
-Используйте параметры `reconnect` и `reconnectAttempts` для автоматического переподключения при разрыве соединения:
+```javascript
+// Обработка ошибок подключения
+try {
+  await sdk.projects.connectWebSocket();
+} catch (error) {
+  console.error('WebSocket connection failed:', error.message);
+  // Fallback к HTTP API
+}
+
+// Обработка разрывов соединения
+sdk.projects.on('disconnect', () => {
+  console.log('Projects WebSocket disconnected');
+  // Логика переподключения
+});
+
+sdk.reasoning.on('error', (error) => {
+  console.error('Reasoning WebSocket error:', error);
+});
+```
+
+## WebSocket URLs
+
+| Namespace | URL | Описание |
+|-----------|-----|----------|
+| Projects | `ws://localhost:3000/projects` | События проектов и индексации |
+| Reasoning | `ws://localhost:3000/reasoning` | События AI reasoning |
+| Chat | `ws://localhost:3000/chat` | Потоковый чат и thinking |
+
+## Аутентификация
+
+WebSocket соединения автоматически используют API ключ из настроек SDK:
 
 ```javascript
-// Инициализация SDK с настройками переподключения
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.example.com',
-  apiKey: 'your-api-key',
-  websocket: {
-    reconnect: true,
-    reconnectAttempts: 5,
-    reconnectDelay: 3000
-  }
+const sdk = CodeSolverSDK.create({
+  baseURL: 'http://localhost:3000',
+  apiKey: 'dev_sk_test_12345678', // Автоматически используется для WS
+  autoConnect: false
 });
+```
 
-// Проверка доступности сервера перед началом работы
-const isHealthy = await sdk.checkHealth();
-if (!isHealthy) {
-  console.error('API недоступен');
-  return;
-}
+## Производительность
+
+### Рекомендации
+
+1. **Используйте autoConnect: false** для контроля подключений
+2. **Подключайтесь только к нужным namespace** для экономии ресурсов
+3. **Отключайтесь после завершения** операций
+4. **Используйте диагностику** для мониторинга состояния
+
+### Пример оптимизированного использования
 
-// Попытка подключения
-const connected = await sdk.connect();
-if (!connected) {
-  console.warn('WebSocket соединение не установлено, работа будет ограничена');
+```javascript
+async function optimizedWorkflow(projectId, query) {
+  const sdk = CodeSolverSDK.create({
+    baseURL: 'http://localhost:3000',
+    apiKey: 'dev_sk_test_12345678',
+    autoConnect: false
+  });
+  
+  try {
+    // 1. Индексация проекта
+    await sdk.projects.connectWebSocket();
+    await sdk.projects.startIndexing(projectId);
+    
+    await new Promise(resolve => {
+      sdk.projects.onIndexingComplete(() => {
+        sdk.projects.disconnectWebSocket();
+        resolve();
+      });
+    });
+    
+    // 2. Reasoning
+    await sdk.reasoning.connectWebSocket();
+    const reasoning = await sdk.reasoning.create({ projectId, query });
+    await sdk.reasoning.start(reasoning.id);
+    
+    await new Promise(resolve => {
+      sdk.reasoning.onReasoningCompleted(() => {
+        sdk.reasoning.disconnectWebSocket();
+        resolve();
+      });
+    });
+    
+    console.log('✅ Workflow completed');
+    
+  } catch (error) {
+    console.error('❌ Workflow failed:', error);
+  }
 }
 ```
 
-## Основные события WebSocket
+---
 
-| Событие | Описание |
-|---------|----------|
-| `message_start` | Начало сообщения |
-| `thinking_delta` | Обновление мышления AI |
-| `text_delta` | Часть текстового ответа |
-| `message_stop` | Конец сообщения |
-| `indexing_progress` | Прогресс индексации |
-| `indexing_complete` | Завершение индексации |
-| `error` | Уведомление об ошибке |
+**Документация WebSocket API для SDK v2.5.0**  
+**Совместимость:** AI Solver Backend v1.0.0  
+**Обновлено:** 28 июня 2025