Solver SDK

SDK для интеграции с Code Solver Backend API. Поддерживает работу как в браузере, так и в Node.js.

Возможности

• Совместимость с ESM и CommonJS
• Поддержка браузера и Node.js
• Типизация TypeScript
• WebSocket для реалтайм функций
  • Автоматический ping/pong механизм для мониторинга соединений
  • Сбор статистики времени отклика (RTT) и состояния соединений
  • Автоматическое обнаружение проблем с соединением
• Поддержка Server-Sent Events (SSE)
• Инкрементальная индексация отдельных файлов
• Обработка ошибок и повторные попытки
• Поддержка региональных эндпоинтов Anthropic API
• Полная документация API

Установка

npm install solver-sdk

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

В среде CommonJS (Node.js)

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

// Создание экземпляра SDK
const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000',
  apiKey: 'your-api-key'
});

// Использование SDK
async function example() {
  // Проверка соединения с сервером
  const isHealthy = await sdk.checkHealth();
  console.log('Сервер доступен:', isHealthy);
  
  // Получение списка моделей
  const models = await sdk.reasoning.getModels();
  console.log('Доступные модели:', models);
}

example().catch(console.error);

В среде ESM (Node.js)

// Вариант 1: Динамический импорт через createRequire
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const { CodeSolverSDK } = require('solver-sdk');

// Вариант 2: Прямой импорт (если в package.json указан "type": "module")
// import * as sdk from 'solver-sdk';
// const { CodeSolverSDK } = sdk;

// Создание экземпляра SDK
const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000',
  apiKey: 'your-api-key'
});

// Пример использования
async function example() {
  const isHealthy = await sdk.checkHealth();
  console.log('Сервер доступен:', isHealthy);
}

example().catch(console.error);

В браузере

<script src="node_modules/solver-sdk/dist/umd/code-solver-sdk.min.js"></script>
<script>
  // SDK доступен глобально как CodeSolverSDK
  const sdk = new CodeSolverSDK.default({
    baseURL: 'https://localhost:3000',
    apiKey: 'your-api-key'
  });
  
  // Пример использования
  sdk.checkHealth()
    .then(isHealthy => console.log('Сервер доступен:', isHealthy))
    .catch(console.error);
</script>

Примеры

Работа с проектами

// Получение списка проектов
const projects = await sdk.projects.getAllProjects();
console.log('Проекты:', projects);

// Создание нового проекта
const newProject = await sdk.projects.createProject('Мой проект', '/path/to/project');
console.log('Новый проект:', newProject);

// Запуск индексации
await sdk.projects.indexProject(newProject.id);

Поиск кода

// Поиск кода
const searchResults = await sdk.search.searchCode(projectId, {
  query: 'function example',
  limit: 10
});
console.log('Результаты поиска:', searchResults);

// Семантический поиск кода
const semanticResults = await sdk.search.semanticSearch(projectId, {
  query: 'функция для обработки HTTP запросов',
  limit: 10
});
console.log('Семантические результаты:', semanticResults);

Работа с рассуждениями через WebSocket

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

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

// Подключение через WebSocket
const wsClient = sdk.getWebSocketClient();
await wsClient.connectToReasoning(reasoning.id);

// Включение механизма ping/pong для мониторинга состояния соединения
wsClient.enablePingPong(30000, 3);

// Обработка событий мышления
wsClient.on('thinking', (data) => {
  console.log('Размышление:', data.content);
});

wsClient.on('complete', (data) => {
  console.log('Завершено:', data.content);
  
  // Отключаем механизм ping/pong и закрываем соединение
  wsClient.disablePingPong();
  wsClient.disconnectAll();
});

// Мониторинг качества соединения
setInterval(() => {
  const stats = wsClient.getPingStats(WebSocketNamespace.REASONING);
  console.log(`Среднее время отклика: ${stats.averageRtt}ms`);
}, 60000);

Индексация отдельных файлов

// Инкрементальная индексация отдельного файла
async function updateSingleFile() {
  const projectId = 'your-project-id';
  const filePath = 'src/components/App.js';
  const fileContent = 'console.log("Hello World");';
  
  // Обновление индекса отдельного файла
  const result = await sdk.projects.updateFileIndex(
    projectId, 
    filePath, 
    {
      content: fileContent,  // Содержимое файла
      force: false           // true для принудительного обновления
    }
  );
  
  console.log(`Файл ${result.filePath} успешно проиндексирован`);
  console.log(`Метаданные файла:`, result.fileIndex);
  
  // Альтернативный вариант через ContextApi
  await sdk.context.updateFileIndex(
    projectId,
    filePath, 
    fileContent,
    false // force flag
  );
}

// Чтение файла с диска и обновление индекса
async function updateFileFromDisk() {
  const projectId = 'your-project-id';
  const filePath = 'src/components/App.js';
  
  // Обновление индекса без передачи содержимого
  // SDK прочитает файл с диска
  const result = await sdk.projects.updateFileIndex(projectId, filePath);
  
  console.log(`Файл ${result.filePath} успешно проиндексирован`);
}

API для работы с зависимостями

SDK предоставляет API для работы с зависимостями файлов в проекте, что позволяет анализировать структуру проекта, импорты/экспорты и выявлять циклические зависимости.

Получение зависимостей файла

// Получение зависимостей конкретного файла
const fileDependencies = await sdk.dependencies.getFileDependencies(projectId, {
  filePath: 'src/app.js'
});

console.log('Импорты:', fileDependencies.imports);
console.log('Импортируется в:', fileDependencies.importedBy);
console.log('Экспорты:', fileDependencies.exports);
console.log('Экспортируемые из импортов:', fileDependencies.exportedBy);

Получение графа зависимостей

// Получение полного графа зависимостей проекта
const dependencyGraph = await sdk.dependencies.getDependencyGraph(projectId);

console.log('Узлы графа:', dependencyGraph.nodes);
console.log('Связи в графе:', dependencyGraph.edges);

Анализ зависимостей

// Анализ графа зависимостей и поиск циклов
const analysis = await sdk.dependencies.analyzeDependencyGraph(projectId);

console.log('Циклические зависимости:', analysis.cycles);
console.log('Статистика графа:', analysis.statistics);

Статистика зависимостей

// Получение статистики зависимостей в проекте
const stats = await sdk.dependencies.getDependencyStatistics(projectId);

console.log('Общее количество зависимостей:', stats.totalDependencies);
console.log('Уникальные файлы:', stats.uniqueFiles);
console.log('Импорты:', stats.importCount);
console.log('Экспорты:', stats.exportCount);
console.log('Циклические зависимости:', stats.cyclicDependenciesCount);

Получение связанных компонентов

// Получение связанных компонентов для файла
const relatedComponents = await sdk.dependencies.getRelatedComponents(projectId, {
  filePath: 'src/app.js',
  maxDepth: 3,
  includeIncoming: true,
  includeOutgoing: true,
  maxNodes: 20
});

console.log('Исходный файл:', relatedComponents.source);
console.log('Связанные компоненты:', relatedComponents.nodes);

WebSocket события для зависимостей

Для получения уведомлений об изменениях в зависимостях в реальном времени можно использовать WebSocket:

// Подключение к WebSocket для зависимостей
const wsClient = sdk.getWebSocketClient();
await wsClient.connectToDependencies(projectId);

// Обработка события обновления зависимостей
wsClient.on('dependency_update', (data) => {
  console.log('Обновление зависимостей:', data);
  console.log('Затронутые файлы:', data.affectedFiles);
});

Тестирование и совместимость

SDK тщательно тестируется в различных средах:

# Запуск всех тестов
npm test

# Тесты браузерной совместимости
npm run test:browser

# Тесты Node.js совместимости
npm run test:node

# Тесты VS Code Web совместимости
npm run test:vscode

# Проверка покрытия кода тестами
npm run test:coverage

Поддерживаемые среды

SDK протестирован и работает в следующих средах:

• Браузеры: Chrome 80+, Firefox 72+, Safari 14+, Edge 80+
• Node.js: Версии 14.x и выше (как CommonJS, так и ESM)
• VS Code: Desktop и Web версии

Решение проблем совместимости

Если у вас возникли проблемы с совместимостью, обратитесь к разделу "Устранение неполадок" в файле INTEGRATION.md.

Сборка из исходного кода

Для сборки SDK из исходного кода:

# Установка зависимостей
npm install

# Сборка SDK
npm run build

# Очистка директории сборки
npm run clean

Опции SDK

SDK поддерживает следующие опции при инициализации:

Документация

Подробная документация по использованию SDK доступна в директории docs:

• Начало работы - инструкции по установке и базовому использованию SDK
• Работа с проектами - управление проектами через SDK
• Индексация проектов - работа с индексацией и отслеживание через WebSocket
• Документация API - полная документация по всем методам SDK

Тестирование и локальная разработка

Предварительные требования

Для локальной разработки и тестирования требуется:

• Node.js 16+
• npm 8+
• Запущенный локальный сервер Code Solver Backend (по умолчанию на https://localhost:3000)

Тестирование SDK

SDK включает несколько типов тестов:

Модульные тесты

Эти тесты проверяют внутреннюю логику SDK без взаимодействия с реальным бэкендом:

# Запуск всех тестов
npm test

# Запуск тестов для индексации
npm run test:indexing

Интеграционные тесты

Эти тесты проверяют взаимодействие SDK с реальным бэкендом:

# Запуск интеграционных тестов индексации
npm run test:integration

Важно: Для запуска интеграционных тестов необходимо, чтобы локальный сервер Code Solver Backend был запущен на https://localhost:3000.

Примеры использования

В директории examples находятся примеры использования SDK:

Проверка подключения к API

Пример проверяет доступность API и WebSocket соединения:

npm run example:check-api

Индексация проектов

Пример демонстрирует процесс индексации проекта с отслеживанием через WebSocket:

npm run example:indexing

Режим разработки

Для запуска SDK в режиме разработки с локальным сервером:

1. Запустите локальный сервер Code Solver Backend
2. Используйте следующие настройки в вашем коде:

const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000',
  apiKey: 'test-api-key',
  httpsAgent: new https.Agent({
    rejectUnauthorized: false // Для самоподписанных сертификатов
  }),
  websocket: {
    reconnect: true,
    rejectUnauthorized: false
  }
});

Игнорирование самоподписанных сертификатов

При разработке с локальным сервером используйте:

# В Node.js скриптах
NODE_TLS_REJECT_UNAUTHORIZED=0 node your-script.js

Лицензия

MIT

API Reference

Основные компоненты

• CodeSolverSDK - Основной класс SDK
• ReasoningApi - API для работы с рассуждениями
• ProjectsApi - API для работы с проектами
• SearchApi - API для поиска кода
• AgentsApi - API для работы с агентами
• ContextApi - API для работы с контекстом кода
• CodeModificationApi - API для модификации кода

Настройка соединения с сервером

const sdk = new CodeSolverSDK({
  baseURL: 'https://localhost:3000', // URL сервера (обязательный параметр)
  apiKey: 'your-api-key',            // API ключ (если требуется)
  timeout: 30000,                   // Таймаут запросов в миллисекундах
  headers: {                        // Дополнительные HTTP заголовки
    'Custom-Header': 'value'
  }
});

Версия 1.0.5

• Улучшена совместимость с CommonJS и ESM модулями
• Добавлена поддержка WebSocket соединений
• Добавлена встроенная зависимость ws для Node.js

Режим мышления (Thinking Mode)

Режим мышления позволяет получать промежуточные рассуждения модели в процессе формирования ответа. Это особенно полезно для отладки и понимания логики работы AI.

Использование через REST API

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

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

// Запрос с включенным режимом мышления
const response = await sdk.chat.chat([
  { role: 'user', content: 'Как реализовать алгоритм сортировки слиянием?' }
], {
  model: 'Claude',
  thinking: true // Активируем режим мышления
});

// Вывод хода мыслей
if (response.choices && response.choices[0] && response.choices[0].thinking) {
  console.log('Ход мыслей модели:');
  console.log(response.choices[0].thinking);
}

// Вывод финального ответа
console.log('Ответ модели:');
console.log(response.choices[0].message.content);

Использование через WebSocket (потоковое получение событий мышления)

В версии 1.7.0 SDK добавлена полная поддержка событий потокового мышления в соответствии с документацией Anthropic. Теперь вы можете получать события thinking_delta, text_delta, signature_delta и другие в режиме реального времени.

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

async function streamThinking() {
  const sdk = new CodeSolverSDK({
    baseURL: 'https://api.example.com',
    apiKey: 'ваш-ключ-api'
  });
  
  // Сообщения для отправки
  const messages = [
    { role: 'user', content: 'Объясни, как работает blockchain' }
  ];
  
  // Опции запроса
  const options = {
    model: 'claude-3-7-sonnet-20240229',
    temperature: 0.7,
    thinking: true
  };
  
  // Обработчик событий WebSocket
  const handleEvent = (eventType, data) => {
    switch(eventType) {
      case 'thinking_start':
        console.log('Начало размышлений:');
        break;
        
      case 'thinking_delta':
        process.stdout.write(data.text); // Потоковый вывод размышлений
        break;
        
      case 'text_delta':
        process.stdout.write(data.text); // Потоковый вывод итогового текста
        break;
    }
  };
  
  try {
    // Отправляем запрос с потоковым мышлением
    const response = await sdk.chat.streamChatWithThinking(
      messages,
      options,
      handleEvent
    );
    
    console.log(`Запрос успешно отправлен. Socket ID: ${response.socketId}`);
  } catch (error) {
    console.error('Ошибка:', error);
  }
}

streamThinking();

Поддерживаемые события WebSocket

SDK теперь поддерживает полный набор событий из документации Anthropic:

• message_start - начало сообщения от модели
• content_block_start - начало блока контента (текст или thinking)
• thinking_delta - фрагмент размышления модели
• text_delta - фрагмент итогового текста
• signature_delta - подпись блока размышлений
• content_block_stop - завершение блока контента
• message_delta - изменения верхнего уровня сообщения
• message_stop - завершение сообщения
• ping - событие для поддержания соединения
• tool_use_start - начало использования инструмента
• input_json_delta - фрагмент JSON входных данных для инструмента

Примеры использования

Полные примеры кода можно найти в директории examples:

• examples/chat-example.js - пример использования thinking в обычном чате
• examples/thinking-example.js - пример использования thinking через WebSocket

Параметры режима мышления

Вы можете управлять режимом мышления с помощью следующих параметров:

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

// Использование с автоматическим созданием WebSocket соединения
const response = await sdk.chat.streamChatWithThinking(messages, options, eventHandler);

// Или с существующим socketId
const connectResponse = await sdk.chat.connectWebSocket();
options.socketId = connectResponse.socketId;
const response = await sdk.chat.streamChatWithThinking(messages, options, eventHandler);

Обновление до версии 1.6.1

В версии 1.6.1 исправлены критические проблемы с WebSocket соединениями:

1. Исправлена обработка callback-функций в WebSocket событиях.
2. Добавлена правильная передача параметра namespace в Socket.IO событиях.
3. Улучшено логирование для упрощения отладки проблем с соединением.
4. Добавлена обработка таймаутов при ожидании ответов от сервера.

Как обновиться

npm update solver-sdk

или с указанием конкретной версии:

npm install solver-sdk@1.6.1

Важные изменения

Публичный API SDK остался без изменений, но внутренняя логика работы с WebSocket была значительно улучшена. Если вы столкнулись с проблемами при подключении к серверу WebSocket или получении данных через Socket.IO, обновление до версии 1.6.1 должно их решить.

Обновления и важные изменения

Синхронизация WebSocket событий (v1.6.3)

Произведена полная синхронизация констант WebSocket событий между SDK и бэкендом. Добавлена поддержка новых событий:

• REASONING_CREATED (reasoning:created)
• JOINED_REASONING (joined_reasoning)
• JOIN_RESPONSE (join_response)
• UPDATE_CONTEXT_OPTIONS (update_context_options)
• ESTIMATE_CONTEXT (estimate_context)
• CONTEXT_OPTIONS_UPDATED (context_options_updated)
• CONTEXT_ESTIMATION (context_estimation)
• CHAT_REQUEST (chat_request)
• CHAT_STARTED (chat_started)
• MESSAGE_START (message_start)
• CONTENT_BLOCK_START (content_block_start)
• THINKING_DELTA (thinking_delta)
• TEXT_DELTA (text_delta)
• CONTENT_BLOCK_STOP (content_block_stop)
• MESSAGE_STOP (message_stop)
• TYPESCRIPT_ERRORS (typescript_errors)
• TYPESCRIPT_ERRORS_RECEIVED (typescript_errors_received)
• TEST_MODULES_CREATED (test_modules_created)
• CREATE_TEST_MODULES (create_test_modules)
• CONNECTION_PING (connection_ping)
• CONNECTION_PONG (connection_pong)
• RECONNECT_TOKEN (reconnect_token)
• JOIN (join)
• JOINED (joined)

Улучшенная совместимость с модульными системами

Добавлены тесты совместимости для проверки работы SDK в различных окружениях:

• CommonJS (для Node.js)
• ESM (для современного JavaScript)

Для запуска тестов используйте:

cd test
./run-tests.sh

Результаты тестирования

✅ CommonJS тесты: Успешно пройдены ✅ ESM тесты: Успешно пройдены через ESM/CommonJS адаптер ✅ WebSocket событий: Все 62 события синхронизированы между бэкендом и SDK

Примечание по совместимости

При использовании SDK в браузере и Node.js окружении могут быть различия в работе некоторых API, особенно WebSocket. Для Node.js рекомендуется использовать пакет ws и настроить соответствующие параметры в опциях SDK.