Package Exports

solver-sdk

Readme

Solver SDK

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

Возможности

Совместимость с ESM и CommonJS
Поддержка браузера и Node.js
Типизация TypeScript
WebSocket для реалтайм функций
Поддержка Server-Sent Events (SSE)
Инкрементальная индексация отдельных файлов
Обработка ошибок и повторные попытки
Полная документация 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);

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

wsClient.on('complete', (data) => {
  console.log('Завершено:', data.content);
  wsClient.disconnectAll();
});

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

// Инкрементальная индексация отдельного файла
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 поддерживает следующие опции при инициализации:

Опция	Тип	Описание	Обязательна
`baseURL`	string	Базовый URL API	Да
`apiKey`	string	API ключ для авторизации	Нет
`timeout`	number	Таймаут для HTTP запросов (мс)	Нет
`headers`	object	Пользовательские HTTP заголовки	Нет
`httpsAgent`	object	Опции для HTTPS агента (Node.js)	Нет
`mode`	string	Режим работы SDK ('browser', 'node', 'auto')	Нет

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

Подробная документация по использованию 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 в режиме разработки с локальным сервером:

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

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 (потоковое получение событий мышления)

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

async function streamThinking() {
  const sdk = new CodeSolverSDK({
    baseURL: 'https://api.example.com',
    apiKey: 'ваш-ключ-api'
  });
  
  // Получаем WebSocket клиент
  const wsClient = sdk.getWebSocketClient();
  
  // Обработчик событий мышления
  const handleThinking = (data) => {
    console.log('Новый шаг мышления:', data.content);
  };
  
  try {
    // Подключаемся к WebSocket серверу с обработчиком мышления
    const reasoningId = await wsClient.connectToThinkingSession('system', handleThinking);
    
    // Создаем рассуждение
    const result = await sdk.reasoning.createReasoning({
      projectId: 'project-123',
      query: 'Объясни асинхронное программирование в JavaScript',
      options: {
        thinking: true,
        socketId: wsClient.getSocketId()
      }
    });
    
    // Запускаем рассуждение
    await sdk.reasoning.startReasoning(result.id);
    
    console.log('Рассуждение запущено, шаги мышления будут приходить через WebSocket');
  } catch (error) {
    console.error('Ошибка:', error);
  }
}

streamThinking();

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

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

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

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

Параметр level позволяет настроить детализацию процесса мышления:

CONCISE - краткие шаги рассуждения
STANDARD - стандартный уровень детализации (по умолчанию)
DETAILED - подробное рассуждение с промежуточными шагами
VERBOSE - максимальная детализация процесса мышления

const result = await sdk.reasoning.createReasoning({
  projectId: 'project-123',
  query: 'Объясни, как работает blockchain',
  level: 'DETAILED', // Уровень детализации мышления
  options: {
    thinking: true,
    socketId: wsClient.getSocketId()
  }
});

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

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

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

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

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.