solver-sdk/docs/WEBSOCKET.md

SDK для интеграции с Code Solver Backend API

# Работа с WebSocket в Solver SDK

Эта документация описывает, как использовать WebSocket соединения через высокоуровневые методы Solver SDK для работы в реальном времени.

## Инициализация SDK

```javascript
const { CodeSolverSDK } = require('solver-sdk');

// Создаем экземпляр SDK с настройками
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'your-api-key',
  websocket: {
    reconnect: true,      // Автоматическое переподключение при разрыве соединения
    reconnectAttempts: 5, // Максимальное количество попыток переподключения
    reconnectDelay: 3000  // Задержка между попытками (мс)
  }
});

// Общее подключение к базовым WebSocket сервисам
await sdk.connect();
```

## Работа с файловой системой

```javascript
// Обязательно: для файловой системы projectId всегда необходим
const projectId = 'your-project-id';

// Метод 1: Подключение через файловую систему 
await sdk.filesystem.connectWebSocket(projectId);

// Метод 2: Альтернативный способ подключения
await sdk.filesystem.connectToProject(projectId);

// Чтение файла через REST API (предпочтительный метод)
const content = await sdk.context.getFileContent(projectId, 'src/index.js');

// Отключение
await sdk.filesystem.disconnectWebSocket();
```

## Работа с индексацией проектов

```javascript
// Подключение к WebSocket для проектов без указания projectId
await sdk.projects.connectWebSocket();

// Или можно сразу указать проект (projectId опциональный)
await sdk.projects.connectWebSocket('project-id');

// Отслеживание прогресса индексации
sdk.projects.on('indexing_progress', (data) => {
  console.log(`Прогресс индексации: ${data.progress}%`);
  console.log(`Обработано файлов: ${data.processedFiles} из ${data.totalFiles}`);
});

// Завершение индексации
sdk.projects.on('indexing_complete', (data) => {
  console.log('Индексация завершена!', data.success ? 'Успешно' : 'С ошибками');
  
  // Отключение после завершения
  sdk.projects.disconnectWebSocket();
});

// Запуск индексации проекта
await sdk.projects.indexProject('project-id');
```

## Работа с рассуждениями (Reasoning)

```javascript
// Создание рассуждения
const reasoning = await sdk.reasoning.createReasoning({
  projectId: 'project-id',
  query: 'Объясни этот проект'
});

// Подключение к WebSocket для рассуждений
// Не требует projectId в методе connectWebSocket
await sdk.reasoning.connectWebSocket();

// Присоединение к конкретному рассуждению
await sdk.reasoning.joinReasoning(reasoning.id);

// Подписка на события
sdk.reasoning.on('thinking', (data) => {
  console.log('Мышление:', data.content);
});

sdk.reasoning.on('complete', (data) => {
  console.log('Результат:', data.content);
  // Отключение после завершения
  sdk.reasoning.disconnectWebSocket();
});

// Запуск рассуждения
await sdk.reasoning.startReasoning(reasoning.id);
```

## Работа с зависимостями

```javascript
// Подключение к WebSocket для зависимостей без указания projectId
await sdk.dependencies.connectWebSocket();

// Затем необходимо присоединиться к конкретному проекту
await sdk.dependencies.joinProject('your-project-id');

// Подписка на события зависимостей
sdk.dependencies.on('dependency_update', (data) => {
  console.log('Обновление зависимостей:', data);
});

// Отключение
await sdk.dependencies.disconnectWebSocket();
```

## Смена активного проекта

SDK поддерживает концепцию "активного проекта", что позволяет переключаться между проектами без полного переподключения:

```javascript
// Установка активного проекта
sdk.setActiveProject('new-project-id');

// После этого вызова SDK автоматически переподключит 
// filesystem-namespace к новому проекту
```

## Потоковый чат с мышлением AI

```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Ответ завершен');
  }
};

// Отправка запроса 
const messages = [
  { role: 'user', content: 'Расскажи о JavaScript' }
];

const options = {
  model: 'claude-3-7-sonnet-20240229',
  thinking: true,
  temperature: 0.7,
  projectId: 'project-id' // Указываем projectId для контекста проекта
};

// Отправка с потоковым получением ответа
const response = await sdk.chat.streamChatWithThinking(
  messages, 
  options,
  handleEvent
);
```

## Автоматический ping/pong и reconnect

WebSocket клиенты в SDK автоматически обрабатывают ping/pong сообщения и reconnect:

```javascript
// Все WebSocket клиенты имеют автоматический ping/pong
// с настраиваемыми таймаутами
const sdk = new CodeSolverSDK({
  websocket: {
    pingInterval: 25000,  // Интервал отправки ping (мс)
    pingTimeout: 10000,   // Таймаут ожидания pong (мс)
    reconnect: true,      // Автоматическое переподключение
    reconnectAttempts: 5  // Макс. количество попыток
  }
});

// При разрыве соединения SDK попытается автоматически переподключиться
// Вам не нужно писать свой код для обработки reconnect
```

## Метод connect в SDK и пространства имен

Метод `sdk.connect()` подключает только базовые пространства имен и не устанавливает подключение ко всем сервисам:

```javascript
// Общее подключение не передает projectId для файловой системы
await sdk.connect();

// Поэтому для работы с файловой системой нужно явно подключиться
await sdk.filesystem.connectWebSocket('your-project-id');

// Или можно при подключении сразу указать projectId, который будет использован для подключения к файловой системе
await sdk.connect('your-project-id');
```

## Сравнение сигнатур методов connectWebSocket

| API | Метод | Требуется projectId? |
|-----|-------|---------------------|
| `sdk.filesystem` | `connectWebSocket(projectId)` | **Обязательно** |
| `sdk.filesystem` | `connectToProject(projectId)` | **Обязательно** |
| `sdk.projects` | `connectWebSocket([projectId])` | **Опционально** |
| `sdk.reasoning` | `connectWebSocket()` | **Нет** |
| `sdk.reasoning` | `joinReasoning(reasoningId)` | **Обязательно** |
| `sdk.dependencies` | `connectWebSocket()` | **Нет** |
| `sdk.dependencies` | `joinProject(projectId)` | **Обязательно** |

## Обработка ошибок и переподключение

Используйте параметры `reconnect` и `reconnectAttempts` для автоматического переподключения при разрыве соединения:

```javascript
// Инициализация SDK с настройками переподключения
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'your-api-key',
  websocket: {
    reconnect: true,
    reconnectAttempts: 5,
    reconnectDelay: 3000
  }
});

// Проверка доступности сервера перед началом работы
const isHealthy = await sdk.checkHealth();
if (!isHealthy) {
  console.error('API недоступен');
  return;
}

// Подключение к WebSocket серверу
const connected = await sdk.connect();
if (!connected) {
  console.warn('WebSocket соединение не установлено, работа будет ограничена');
}

// Для работы с файловой системой необходимо отдельное подключение с projectId
const projectId = 'your-project-id';
await sdk.filesystem.connectWebSocket(projectId);
```

## Использование в Cursor

В Cursor клиенте projectId обычно получается через API проектов:

```javascript
// Получаем projectId для текущей рабочей области
const workspacePath = '/path/to/project';
const project = await sdk.projects.getOrCreateProjectByPath(workspacePath);
const projectId = project.id;

// Используем полученный projectId для подключения к файловой системе
await sdk.filesystem.connectWebSocket(projectId);
```

## Статус реализации функций

| Функция | Статус | Примечание |
|---------|--------|------------|
| `sdk.connect()` | ✅ Реализовано | Включает базовое подключение ко всем namespace |
| `sdk.setActiveProject()` | ✅ Реализовано | Работает в связке с filesystem-клиентом |
| `sdk.filesystem.connectWebSocket()` | ✅ Реализовано | Подключение к WebSocket для файловой системы |
| `sdk.filesystem.connectToProject()` | ✅ Реализовано | Альтернативный синтаксис для connectWebSocket |
| `sdk.context.getFileContent()` | ✅ Реализовано | Рекомендуемый метод для чтения файлов (через REST) |
| `sdk.projects.connectWebSocket()` | ✅ Реализовано | Подключение к namespace индексации |
| `sdk.reasoning.connectWebSocket()` | ✅ Реализовано | Требует последующего `joinReasoning()` |
| `sdk.dependencies.connectWebSocket()` | ✅ Реализовано | Требует последующего `joinProject()` |
| `sdk.chat.streamChatWithThinking()` | ✅ Реализовано | Потоковое получение ответов с мышлением |

## Основные события WebSocket

| Событие | Описание |
|---------|----------|
| `message_start` | Начало сообщения |
| `thinking_delta` | Обновление мышления AI |
| `text_delta` | Часть текстового ответа |
| `message_stop` | Конец сообщения |
| `indexing_progress` | Прогресс индексации |
| `indexing_complete` | Завершение индексации |
| `error` | Уведомление об ошибке |