solver-sdk/docs/thinking/thinking-mode.md

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

# Руководство по интеграции функциональности мышления (Thinking Mode)

В этом документе описывается полный процесс интеграции функциональности мышления в клиентские приложения с использованием SDK версии 1.7.2.

## Обзор функциональности

**Режим мышления** (Thinking Mode) - это расширенная функциональность, которая позволяет получать доступ к промежуточным рассуждениям языковой модели в процессе формирования ответа. Это дает следующие преимущества:

- Прозрачность в процессе генерации ответа
- Отладка и улучшение качества ответов
- Возможность показать пользователю как модель пришла к своему решению
- Поэтапное отображение процесса мышления в реальном времени (через WebSocket)

## Архитектура взаимодействия

```
Client (SDK) <--WebSocket--> NestJS Server <--HTTP Stream--> Anthropic API
```

Существует два способа работы с функциональностью мышления:

1. **REST API** - синхронный режим, где ответ возвращается после завершения генерации
2. **WebSocket** - потоковый режим, с получением событий мышления в реальном времени

## Интеграция через REST API

Простейший способ получить доступ к мышлению модели - использовать REST API:

```javascript
const response = await sdk.chat.chat([
  { role: 'user', content: 'Как работает алгоритм быстрой сортировки?' }
], {
  model: 'claude-3-7-sonnet-20240229',
  thinking: true
});

// Ход мыслей доступен в свойстве thinking первого элемента choices
const thinking = response.choices[0].thinking;
```

## Интеграция через WebSocket (рекомендуемый подход)

Интеграция через WebSocket позволяет получать события мышления в реальном времени и показывать пользователю как модель формирует ответ шаг за шагом.

### Шаг 1: Инициализация SDK и подключение WebSocket

```javascript
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'ваш-ключ-api'
});

// Подключаем WebSocket
await sdk.chat.connectWebSocket();
```

### Шаг 2: Определение обработчика событий

```javascript
// Функция обработки событий
function 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;
  }
}
```

### Шаг 3: Отправка запроса с потоковой передачей мышления

```javascript
// Сообщения для отправки
const messages = [
  { role: 'user', content: 'Как реализовать алгоритм сортировки слиянием?' }
];

// Опции запроса
const options = {
  model: 'claude-3-7-sonnet-20240229',
  thinking: true,           // Активируем режим мышления
  temperature: 0.7
};

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

console.log(`Запрос успешно отправлен. Socket ID: ${response.socketId}`);
```

### Шаг 4: Отключение от сервера после использования

```javascript
// Отключаемся от WebSocket сервера
await sdk.chat.disconnectWebSocket();
```

## Полный пример интеграции в клиентское приложение

```javascript
class ThinkingModeIntegration {
  constructor(apiKey, baseURL) {
    this.sdk = new CodeSolverSDK({
      baseURL,
      apiKey
    });
    
    this.thinkingText = '';
    this.responseText = '';
    this.isProcessing = false;
  }
  
  // Инициализация и подключение к WebSocket
  async connect() {
    const response = await this.sdk.chat.connectWebSocket();
    return response.socketId;
  }
  
  // Отправка запроса с мышлением
  async sendWithThinking(messages, options = {}) {
    this.isProcessing = true;
    this.thinkingText = '';
    this.responseText = '';
    
    // Настраиваем опции по умолчанию
    const defaultOptions = {
      model: 'claude-3-7-sonnet-20240229',
      thinking: true,
      temperature: 0.7
    };
    
    const mergedOptions = { ...defaultOptions, ...options };
    
    try {
      // Отправляем запрос с обработчиком событий
      const response = await this.sdk.chat.streamChatWithThinking(
        messages,
        mergedOptions,
        this.handleEvent.bind(this)
      );
      
      return response;
    } catch (error) {
      console.error('Ошибка при отправке запроса:', error);
      this.isProcessing = false;
      throw error;
    }
  }
  
  // Обработчик событий WebSocket
  handleEvent(eventType, data) {
    switch(eventType) {
      case 'thinking_delta':
        this.thinkingText += data.text || '';
        
        // Вызываем колбэк для обновления UI мышления
        if (this.onThinkingUpdate) {
          this.onThinkingUpdate(this.thinkingText);
        }
        break;
      
      case 'text_delta':
        this.responseText += data.text || '';
        
        // Вызываем колбэк для обновления UI ответа
        if (this.onResponseUpdate) {
          this.onResponseUpdate(this.responseText);
        }
        break;
        
      case 'message_stop':
        this.isProcessing = false;
        
        // Вызываем колбэк завершения
        if (this.onComplete) {
          this.onComplete({
            thinking: this.thinkingText,
            response: this.responseText
          });
        }
        break;
        
      case 'error':
        this.isProcessing = false;
        
        // Вызываем колбэк ошибки
        if (this.onError) {
          this.onError(data);
        }
        break;
    }
  }
  
  // Отключение от сервера
  async disconnect() {
    await this.sdk.chat.disconnectWebSocket();
  }
  
  // Регистрация обработчиков событий
  registerCallbacks({
    onThinkingUpdate,
    onResponseUpdate,
    onComplete,
    onError
  }) {
    this.onThinkingUpdate = onThinkingUpdate;
    this.onResponseUpdate = onResponseUpdate;
    this.onComplete = onComplete;
    this.onError = onError;
  }
}

// Пример использования
async function main() {
  const thinkingMode = new ThinkingModeIntegration(
    'ваш-ключ-api',
    'https://api.example.com'
  );
  
  // Подключаемся к WebSocket
  await thinkingMode.connect();
  
  // Регистрируем обработчики
  thinkingMode.registerCallbacks({
    onThinkingUpdate: (thinking) => {
      console.log('Обновление мышления');
      document.getElementById('thinkingOutput').innerHTML = thinking;
    },
    onResponseUpdate: (response) => {
      console.log('Обновление ответа');
      document.getElementById('finalAnswer').innerHTML = response;
    },
    onComplete: (result) => {
      console.log('Завершено!');
      document.getElementById('status').textContent = 'Готово';
    },
    onError: (error) => {
      console.error('Ошибка:', error);
      document.getElementById('status').textContent = 'Ошибка: ' + error.message;
    }
  });
  
  // Отправляем запрос
  const messages = [
    { role: 'user', content: 'Объясни, как работает алгоритм быстрой сортировки?' }
  ];
  
  document.getElementById('status').textContent = 'Обработка...';
  
  await thinkingMode.sendWithThinking(messages);
  
  // После завершения работы
  // await thinkingMode.disconnect();
}
```

## Рекомендации по интеграции в UI

При интеграции функциональности мышления в пользовательский интерфейс рекомендуется:

1. **Показывать индикатор загрузки** пока идет инициализация соединения
2. **Выделять шаги мышления** визуально отдельно от окончательного ответа
3. **Предусмотреть автоскроллинг** для длинных цепочек рассуждений
4. **Добавить возможность скрыть/показать** ход мыслей для пользователей
5. **Обеспечить обработку отключения** от сервера (например, при закрытии вкладки/приложения)

### Пример HTML/CSS структуры для отображения мышления

```html
<div class="thinking-container">
  <div class="thinking-header">
    <h3>Ход мыслей модели</h3>
    <button id="toggleThinking">Скрыть</button>
    <span id="status">Готово</span>
  </div>
  
  <div id="thinkingOutput" class="thinking-steps">
    <!-- Шаги мышления будут добавляться здесь -->
  </div>
  
  <div class="final-answer">
    <h3>Ответ модели</h3>
    <div id="finalAnswer">
      <!-- Финальный ответ будет здесь -->
    </div>
  </div>
</div>
```

## Отладка и устранение проблем

### Распространенные проблемы и их решения

1. **Нет соединения WebSocket**
   - Проверьте, правильно ли указан baseURL
   - Убедитесь, что порт не блокируется фаерволом
   - Проверьте наличие CORS ограничений
   - Используйте метод `sdk.getWebSocketClient().diagnoseConnection()` для диагностики

2. **Не приходят события мышления**
   - Убедитесь, что активирован параметр `thinking: true`
   - Проверьте, что соединение WebSocket активно
   - Убедитесь, что используется поддерживаемая модель

3. **Разрыв соединения в процессе работы**
   - Увеличьте timeout в настройках WebSocket
   - Включите механизм ping/pong для поддержания соединения
   - Используйте опцию `websocket.reconnect: true` в настройках SDK

### Включение расширенной диагностики

В SDK версии 1.7.2 добавлены мощные инструменты для диагностики WebSocket соединений:

```javascript
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'ваш-ключ-api',
  websocket: {
    debug: true,                 // Включаем подробное логирование
    reconnect: true,             // Автоматическое переподключение
    reconnectAttempts: 5,        // Количество попыток переподключения
    reconnectDelay: 1000         // Задержка перед переподключением (мс)
  }
});

// Включаем механизм ping/pong для поддержания соединения
const wsClient = sdk.getWebSocketClient();
wsClient.enablePingPong(30000, 3);

// Диагностика состояния соединения
const diagnostics = wsClient.diagnoseConnection();
console.log('Диагностика соединения:', diagnostics);
```

## Версии и совместимость

Функциональность мышления поддерживается в:
- SDK версии 1.5.0 и выше
- Потоковая передача мышления (streaming) полностью поддерживается с версии 1.7.2
- Backend API версии 1.5.0 и выше
- Совместима с моделями Claude 3 Opus, Claude 3 Sonnet и Claude 3 Haiku

## Дополнительные ресурсы

- [Архитектура потоковой передачи мышления](../THINKING_ARCHITECTURE.md)
- [Руководство по потоковой передаче мышления](../streaming-thinking-guide.md)
- [WebSocket API](../WEBSOCKET.md)
- [Документация Anthropic по потоковой передаче](https://docs.anthropic.com/en/api/messages-streaming)