solver-sdk 1.8.0 → 1.9.0

package/docs/ERROR_HANDLING.md

@@ -0,0 +1,240 @@
+# Обработка ошибок в Solver SDK
+
+Документация по системе обработки ошибок в Solver SDK, включая общие ошибки, ошибки WebSocket и географические ограничения.
+
+## Содержание
+
+- [Общие принципы](#общие-принципы)
+- [Типы ошибок](#типы-ошибок)
+- [HTTP ошибки](#http-ошибки)
+- [WebSocket ошибки](#websocket-ошибки)
+- [Ошибки географических ограничений](#ошибки-географических-ограничений)
+- [Примеры обработки ошибок](#примеры-обработки-ошибок)
+
+## Общие принципы
+
+Solver SDK использует следующие принципы при работе с ошибками:
+
+1. **Унифицированный формат** — все ошибки имеют единую структуру
+2. **Информативные сообщения** — ошибки содержат детальное описание проблемы
+3. **Коды ошибок** — каждая ошибка имеет уникальный код для идентификации
+4. **Типизация** — ошибки классифицируются по типам для удобной обработки
+
+## Типы ошибок
+
+Основные типы ошибок в SDK:
+
+| Тип ошибки | Описание |
+|------------|----------|
+| `http_error` | Ошибки HTTP запросов |
+| `websocket_error` | Ошибки WebSocket соединений |
+| `validation_error` | Ошибки валидации входных данных |
+| `authentication_error` | Ошибки аутентификации |
+| `rate_limit_error` | Ошибки превышения лимита запросов |
+| `provider_error` | Ошибки провайдеров API (Anthropic, OpenAI) |
+| `geo_restriction` | Ошибки географических ограничений |
+
+## HTTP ошибки
+
+HTTP ошибки возникают при проблемах с HTTP запросами:
+
+```javascript
+try {
+  const result = await sdk.chat.chat([{ role: 'user', content: 'Hello' }]);
+} catch (error) {
+  console.error(`Код ошибки: ${error.code}`);
+  console.error(`Сообщение: ${error.message}`);
+  
+  // Проверка типа ошибки
+  if (error.code === 401) {
+    console.error('Ошибка аутентификации: проверьте API ключ');
+  } else if (error.code === 429) {
+    console.error('Превышен лимит запросов: повторите позже');
+  }
+}
+```
+
+## WebSocket ошибки
+
+WebSocket ошибки обрабатываются через обработчики событий:
+
+```javascript
+const handleEvent = (eventType, data) => {
+  if (eventType === 'error') {
+    console.error(`WebSocket ошибка: ${data.message} (код: ${data.code})`);
+    
+    // Обработка конкретных типов ошибок
+    switch (data.type) {
+      case 'connection_error':
+        console.error('Проблема с подключением, пробуем переподключиться...');
+        break;
+      case 'authentication_error':
+        console.error('Проблема аутентификации, запрашиваем новый токен...');
+        break;
+      case 'timeout_error':
+        console.error('Превышен таймаут ожидания ответа');
+        break;
+    }
+  }
+};
+
+// Передаем обработчик событий
+await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
+```
+
+## Ошибки географических ограничений
+
+> **Добавлено в версии 1.7.4**
+
+Начиная с версии 1.7.4 SDK поддерживает специальную обработку ошибок географических ограничений API Anthropic. Эти ошибки возникают, когда запросы отправляются из регионов, не поддерживаемых API Anthropic:
+
+```javascript
+try {
+  const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
+} catch (error) {
+  // Проверка наличия ошибки географических ограничений
+  if (error.type === 'geo_restriction') {
+    console.error('==============================================');
+    console.error('⚠️  ОШИБКА ГЕОГРАФИЧЕСКОГО ОГРАНИЧЕНИЯ API ANTHROPIC');
+    console.error('⚠️  Для работы с API Anthropic требуется VPN или прокси');
+    console.error('⚠️  Anthropic API доступен только из определенных регионов');
+    console.error('==============================================');
+    
+    // Возможные действия:
+    // 1. Предложить пользователю включить VPN
+    // 2. Переключиться на другой провайдер API
+    // 3. Использовать прокси-сервер
+  }
+}
+```
+
+Через обработчик WebSocket событий:
+
+```javascript
+const handleEvent = (eventType, data) => {
+  if (eventType === 'error' && data.type === 'geo_restriction') {
+    console.error('Необходимо включить VPN для доступа к API Anthropic из вашего региона');
+    
+    // Выполнить действия по настройке VPN или показать инструкции пользователю
+  }
+};
+```
+
+### Причины ошибок географических ограничений
+
+Основные причины возникновения ошибок географических ограничений:
+
+1. **Региональные ограничения API Anthropic** — API доступен только из определенных регионов (США, Европа и некоторые другие)
+2. **Регуляторные требования** — законодательство некоторых стран ограничивает доступ к определенным API
+3. **IP-блокировка** — некоторые IP-адреса могут быть заблокированы провайдером API
+
+### Решение проблемы
+
+Для решения проблемы географических ограничений:
+
+1. **Использование VPN** — подключитесь через VPN к поддерживаемому региону (США, Европа)
+2. **Прокси-сервер** — настройте прокси для запросов к API
+3. **Альтернативные провайдеры** — используйте альтернативных провайдеров, доступных в вашем регионе
+
+## Примеры обработки ошибок
+
+### Комплексная обработка ошибок
+
+```javascript
+async function exampleWithErrorHandling() {
+  const sdk = new CodeSolverSDK({
+    baseURL: 'https://api.example.com',
+    apiKey: 'your-api-key'
+  });
+  
+  const messages = [
+    { role: 'user', content: 'Explain quantum computing' }
+  ];
+  
+  const options = {
+    model: 'claude-3-7-sonnet-20240229',
+    thinking: true,
+    authToken: 'your-auth-token'
+  };
+  
+  // Обработчик WebSocket событий
+  const handleEvent = (eventType, data) => {
+    // Обработка ошибок
+    if (eventType === 'error') {
+      console.error(`Ошибка: ${data.message}`);
+      
+      // Проверка типа ошибки
+      switch (data.type) {
+        case 'geo_restriction':
+          console.error('Географическое ограничение: требуется VPN');
+          break;
+        case 'authentication_error':
+          console.error('Ошибка аутентификации: неверный токен');
+          break;
+        case 'rate_limit_error':
+          console.error('Превышен лимит запросов');
+          break;
+        default:
+          console.error(`Неизвестная ошибка типа: ${data.type}`);
+          break;
+      }
+    }
+  };
+  
+  try {
+    const response = await sdk.chat.streamChatWithThinking(messages, options, handleEvent);
+    console.log(`Успешно отправлен запрос, Socket ID: ${response.socketId}`);
+  } catch (error) {
+    console.error(`Критическая ошибка: ${error.message}`);
+    
+    // Обработка специфических типов ошибок
+    if (error.type === 'geo_restriction') {
+      showVpnInstructions(); // Показать инструкции по настройке VPN
+    } else if (error.status === 429) {
+      scheduleRetry(5000); // Запланировать повторную попытку через 5 секунд
+    } else {
+      reportError(error); // Отправить отчет об ошибке
+    }
+  }
+}
+```
+
+### Обработка ошибок при работе с рассуждениями
+
+```javascript
+try {
+  // Создание рассуждения
+  const reasoning = await sdk.reasoning.createReasoning({
+    projectId: 'project-123',
+    query: 'Analyze this codebase'
+  });
+  
+  // Подключение WebSocket
+  await sdk.reasoning.connectWebSocket({
+    reasoningId: reasoning.id,
+    authToken: 'your-auth-token',
+    onError: (error) => {
+      console.error(`WebSocket ошибка: ${error.message}`);
+      
+      if (error.type === 'geo_restriction') {
+        // Показать сообщение о необходимости VPN
+        showVpnAlert();
+      }
+    }
+  });
+  
+  // Запуск рассуждения
+  await sdk.reasoning.startReasoning(reasoning.id);
+} catch (error) {
+  console.error(`HTTP ошибка: ${error.message}`);
+  
+  // Обработка HTTP ошибок
+  if (error.status === 401) {
+    // Перенаправить на страницу входа
+    redirectToLogin();
+  } else if (error.status === 403) {
+    // Показать сообщение об отсутствии доступа
+    showAccessDeniedMessage();
+  }
+}
+``` 

package/docs/INTEGRATION_EXAMPLES.md

@@ -0,0 +1,342 @@
+# Примеры интеграции с VS Code/Cursor
+
+В этом документе приведены примеры использования SDK с VS Code или Cursor расширениями.
+
+## Содержание
+- [Инициализация SDK](#инициализация-sdk)
+- [Работа с проектами](#работа-с-проектами)
+- [Отслеживание прогресса индексации](#отслеживание-прогресса-индексации)
+- [Потоковый чат с мышлением](#потоковый-чат-с-мышлением)
+- [Поиск в коде](#поиск-в-коде)
+
+## Инициализация SDK
+
+Пример инициализации SDK в расширении VS Code/Cursor:
+
+```typescript
+import * as vscode from 'vscode';
+import { CodeSolverSDK } from 'solver-sdk';
+
+// Инициализация SDK
+const sdk = new CodeSolverSDK({
+  baseURL: 'https://api.example.com',
+  apiKey: 'your-api-key',
+  websocket: {
+    reconnect: true,
+    reconnectAttempts: 5,
+    reconnectDelay: 3000,
+    rejectUnauthorized: false // для самоподписанных сертификатов
+  }
+});
+
+// Проверка доступности API
+async function checkConnection() {
+  try {
+    const isHealthy = await sdk.checkHealth();
+    if (isHealthy) {
+      vscode.window.showInformationMessage('API доступен');
+    } else {
+      vscode.window.showErrorMessage('API недоступен');
+    }
+  } catch (error) {
+    vscode.window.showErrorMessage(`Ошибка соединения: ${error.message}`);
+  }
+}
+```
+
+## Работа с проектами
+
+Пример автоматической работы с проектом при открытии рабочей области:
+
+```typescript
+import * as path from 'path';
+
+// Получение проекта по пути рабочей области
+async function handleWorkspace() {
+  try {
+    // Получаем путь к текущей рабочей области
+    const workspaceFolders = vscode.workspace.workspaceFolders;
+    if (!workspaceFolders || workspaceFolders.length === 0) {
+      vscode.window.showWarningMessage('Откройте папку проекта');
+      return;
+    }
+    
+    const workspacePath = workspaceFolders[0].uri.fsPath;
+    const projectName = path.basename(workspacePath);
+    
+    // Получаем проект или создаем новый 
+    const project = await sdk.projects.getOrCreateProject(
+      workspacePath,
+      projectName
+    );
+    
+    if (project) {
+      vscode.window.showInformationMessage(`Проект "${projectName}" идентифицирован (ID: ${project.id})`);
+      return project;
+    }
+  } catch (error) {
+    vscode.window.showErrorMessage(`Ошибка: ${error.message}`);
+  }
+  
+  return null;
+}
+```
+
+## Отслеживание прогресса индексации
+
+Пример отслеживания прогресса индексации:
+
+```typescript
+// Запуск индексации проекта
+async function indexProject(projectId, projectName) {
+  try {
+    // Запускаем индексацию
+    await sdk.projects.indexProject(projectId);
+    
+    // Показываем прогресс
+    vscode.window.withProgress({
+      location: vscode.ProgressLocation.Notification,
+      title: `Индексация проекта "${projectName}"`,
+      cancellable: true
+    }, async (progress, token) => {
+      // Подключаемся к WebSocket для индексации
+      await sdk.projects.connectWebSocket();
+      
+      return new Promise((resolve) => {
+        // Отслеживаем прогресс
+        sdk.projects.on('indexing_progress', (data) => {
+          progress.report({ 
+            message: `${data.progress}% (${data.processedFiles}/${data.totalFiles} файлов)`,
+            increment: data.progress
+          });
+        });
+        
+        // Отслеживаем завершение
+        sdk.projects.on('indexing_complete', (data) => {
+          if (data.success) {
+            vscode.window.showInformationMessage('Индексация успешно завершена!');
+          } else {
+            vscode.window.showWarningMessage(`Индексация завершена с ошибками: ${data.errorMessage || 'неизвестная ошибка'}`);
+          }
+          sdk.projects.disconnectWebSocket();
+          resolve();
+        });
+        
+        // Обработка отмены
+        token.onCancellationRequested(() => {
+          sdk.projects.stopIndexing(projectId)
+            .then(() => {
+              vscode.window.showInformationMessage('Индексация отменена');
+              sdk.projects.disconnectWebSocket();
+              resolve();
+            });
+        });
+      });
+    });
+  } catch (error) {
+    vscode.window.showErrorMessage(`Ошибка индексации: ${error.message}`);
+  }
+}
+```
+
+## Потоковый чат с мышлением
+
+Пример использования потокового чата с мышлением:
+
+```typescript
+// Регистрация команды чата с мышлением
+context.subscriptions.push(
+  vscode.commands.registerCommand('solver.chatWithThinking', async () => {
+    try {
+      // Запрашиваем ввод от пользователя
+      const question = await vscode.window.showInputBox({
+        prompt: 'Введите вопрос'
+      });
+      
+      if (!question) return;
+      
+      // Создаем и показываем панель для результата
+      const panel = vscode.window.createWebviewPanel(
+        'chatWithThinking',
+        'Ответ с мышлением',
+        vscode.ViewColumn.Beside,
+        { enableScripts: true }
+      );
+      
+      // Начальный HTML для панели
+      panel.webview.html = `
+        <!DOCTYPE html>
+        <html>
+        <head>
+          <style>
+            body { font-family: var(--vscode-font-family); padding: 10px; }
+            .thinking { color: #666; font-style: italic; white-space: pre-wrap; }
+            .answer { white-space: pre-wrap; }
+          </style>
+        </head>
+        <body>
+          <h3>Вопрос: ${question}</h3>
+          <div class="thinking" id="thinking"></div>
+          <h4>Ответ:</h4>
+          <div class="answer" id="answer"></div>
+        </body>
+        </html>
+      `;
+      
+      // Сообщения для чата
+      const messages = [
+        { role: 'user', content: question }
+      ];
+      
+      // Опции для чата
+      const options = {
+        model: 'claude-3-7-sonnet-20240229',
+        thinking: true,
+        temperature: 0.7
+      };
+      
+      // Обработчик событий чата
+      const handleEvent = (eventType, data) => {
+        if (eventType === 'thinking_delta' && data.thinking) {
+          // Обновляем содержимое мышления
+          panel.webview.postMessage({
+            command: 'appendThinking',
+            content: data.thinking
+          });
+        } else if (eventType === 'text_delta' && data.text) {
+          // Обновляем содержимое ответа
+          panel.webview.postMessage({
+            command: 'appendAnswer',
+            content: data.text
+          });
+        }
+      };
+      
+      // Отправляем запрос с мышлением
+      await sdk.chat.streamChatWithThinking(
+        messages, 
+        options,
+        handleEvent
+      );
+      
+      // Настраиваем обработку сообщений в WebView
+      panel.webview.onDidReceiveMessage(message => {
+        const thinkingElement = document.getElementById('thinking');
+        const answerElement = document.getElementById('answer');
+        
+        if (message.command === 'appendThinking') {
+          thinkingElement.textContent += message.content;
+        } else if (message.command === 'appendAnswer') {
+          answerElement.textContent += message.content;
+        }
+      });
+      
+    } catch (error) {
+      vscode.window.showErrorMessage(`Ошибка чата: ${error.message}`);
+    }
+  })
+);
+```
+
+## Поиск в коде
+
+Пример семантического поиска в проекте:
+
+```typescript
+// Поиск в проекте
+async function searchInProject(projectId, query) {
+  try {
+    // Показываем индикатор прогресса
+    return vscode.window.withProgress({
+      location: vscode.ProgressLocation.Notification,
+      title: 'Поиск в проекте...',
+      cancellable: false
+    }, async (progress) => {
+      // Выполняем поиск
+      const results = await sdk.search.semanticSearch(projectId, {
+        query: query,
+        limit: 10,
+        includeContent: true
+      });
+      
+      if (results.results.length === 0) {
+        vscode.window.showInformationMessage('Результаты не найдены');
+        return;
+      }
+      
+      // Отображаем результаты
+      const panel = vscode.window.createWebviewPanel(
+        'searchResults',
+        'Результаты поиска',
+        vscode.ViewColumn.Beside,
+        { enableScripts: true }
+      );
+      
+      // Формируем HTML для отображения результатов
+      panel.webview.html = `
+        <!DOCTYPE html>
+        <html>
+        <head>
+          <style>
+            body { font-family: var(--vscode-font-family); padding: 10px; }
+            .result { margin-bottom: 15px; padding: 10px; border: 1px solid #ccc; }
+            .path { cursor: pointer; color: var(--vscode-textLink-foreground); }
+            .snippet { background: var(--vscode-editor-inactiveSelectionBackground); padding: 10px; margin-top: 5px; white-space: pre-wrap; }
+          </style>
+        </head>
+        <body>
+          <h3>Результаты для: ${query}</h3>
+          ${results.results.map((result, index) => `
+            <div class="result">
+              <div class="path" data-path="${result.filePath}" data-start="${result.startLine}" data-end="${result.endLine}">
+                ${result.filePath}:${result.startLine}-${result.endLine}
+              </div>
+              <div class="snippet">${result.snippet || result.content || ''}</div>
+            </div>
+          `).join('')}
+          
+          <script>
+            // Добавляем обработчик для открытия файлов
+            document.querySelectorAll('.path').forEach(elem => {
+              elem.addEventListener('click', () => {
+                const vscode = acquireVsCodeApi();
+                vscode.postMessage({
+                  command: 'openFile',
+                  filePath: elem.dataset.path,
+                  startLine: parseInt(elem.dataset.start),
+                  endLine: parseInt(elem.dataset.end)
+                });
+              });
+            });
+          </script>
+        </body>
+        </html>
+      `;
+      
+      // Обработка сообщений от WebView
+      panel.webview.onDidReceiveMessage(
+        message => {
+          if (message.command === 'openFile') {
+            const uri = vscode.Uri.file(message.filePath);
+            vscode.workspace.openTextDocument(uri).then(doc => {
+              vscode.window.showTextDocument(doc).then(editor => {
+                const range = new vscode.Range(
+                  new vscode.Position(message.startLine - 1, 0),
+                  new vscode.Position(message.endLine - 1, 0)
+                );
+                editor.revealRange(range);
+              });
+            });
+          }
+        },
+        undefined,
+        context.subscriptions
+      );
+      
+      return results;
+    });
+  } catch (error) {
+    vscode.window.showErrorMessage(`Ошибка поиска: ${error.message}`);
+  }
+}
+```