JSPM

  • Created
  • Published
  • Downloads 14
  • Score
    100M100P100Q82171F
  • License MIT

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

Package Exports

  • solver-sdk

Readme

Solver SDK v2.7.0 🚀

Production-ready SDK для интеграции с Code Solver Backend API с поддержкой VS Code Extension.

🎉 Версия 2.7.0: VS Code интеграция с 10x ускорением! HTTP Streaming для команд VS Code, гибридная архитектура, 45ms vs 443ms старая архитектура.

NPM Version NPM Downloads License

⚡ Что нового в v2.7.0

  • 🚀 VS Code интеграция: Нативное выполнение команд через HTTP Streaming
  • 10x ускорение: 45ms vs 443ms старая архитектура команд VS Code
  • 🏗️ Гибридная архитектура: HTTP Streaming + WebSocket для оптимальной производительности
  • 🎯 Новые типы: VSCodeCommandEvent, CommandExecutionResult, VSCodeCommands
  • 🔄 Двусторонняя связь: Backend ←→ SDK ←→ Extension
  • 📊 Real-time feedback: Мгновенные результаты выполнения команд
  • 🛡️ Backwards compatible: Все существующие методы работают без изменений

📋 Для разработчиков

🎯 VS Code Extension разработчики

🔧 Backend интеграция

📖 Остальная документация

🎯 Основные возможности

  • 🚀 Production готовность (v2.5.0):

    • "Fail Fast" подход без fallback'ов
    • Честные ошибки без маскировки проблем
    • Полный контроль WebSocket подключений
    • API диагностика с детальными отчетами
  • 🎮 Гибкая инициализация (v2.5.0):

    • CodeSolverSDK.create() - с валидацией API
    • new CodeSolverSDK() - быстрая инициализация
    • autoConnect: false - ручное управление WebSocket
    • Алиасы методов для удобства (create(), start(), stop())
  • 🔌 Контролируемые WebSocket:

    • Ручное подключение только когда нужно
    • Автоматический ping/pong механизм
    • Интеллектуальное переподключение
    • Мониторинг здоровья соединения
  • 🧠 Потоковое мышление AI:

    • streamChat() с поддержкой Anthropic Claude thinking и VS Code команд
    • Полная поддержка ContentBlock[] и signature блоков
    • Сохранение криптографических подписей
    • Обработка signature_delta событий
  • 🎯 VS Code Extension интеграция (v2.7.0):

    • Нативное выполнение команд через HTTP Streaming
    • 10x ускорение (45ms vs 443ms старая архитектура)
    • Поддержка всех VS Code команд (создание файлов, редактирование, поиск)
    • Real-time feedback и error handling
  • 🔍 Семантический поиск:

    • Инкрементальная индексация файлов
    • Семантический поиск по коду
    • Работа с зависимостями проектов
  • 🌐 Кросс-платформенность:

    • ESM, CommonJS, браузер, Node.js
    • Полная TypeScript типизация
    • Региональные Anthropic endpoints

Установка

npm install solver-sdk

🚀 Быстрый старт

🎯 VS Code Extension интеграция (основной use case)

// 📄 Полный код в docs/QUICK_START.md
import { CodeSolverSDK } from 'solver-sdk';

const sdk = await CodeSolverSDK.create({
  baseURL: 'http://localhost:3000',
  apiKey: 'your-api-key'
});

// 45ms команды VS Code - 10x ускорение!
const stream = await sdk.chat.streamChat(messages, {
  onVSCodeCommand: async (command) => {
    return await vscode.commands.executeCommand(command.command, ...command.args);
  }
});

📚 Смотрите полный 5-минутный старт

✅ Быстрая инициализация (без проверки API)

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

// Быстрое создание без валидации
const sdk = new CodeSolverSDK({
  baseURL: 'http://localhost:3000',
  apiKey: 'your-api-key',
  websocket: { autoConnect: false }  // 🔧 Важно!
});

// Использование с честными ошибками
try {
  const projects = await sdk.projects.getAllProjects();
  console.log('✅ Проекты:', projects);
} catch (error) {
  console.error('❌ Честная ошибка:', error.message);
  // Нет fallback'ов - проблему нужно решать
}

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

import { CodeSolverSDK } from 'solver-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>

API

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

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

Опции 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') Нет
websocket object Настройки WebSocket (reconnect, timeout и др.) Нет

Продвинутые функции

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

// Получение списка проектов
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: 'Объясни, как работает этот проект'
});

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

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

// Обработка событий мышления
wsClient.on('content_block_delta', (data) => {
  if (data.delta?.type === 'thinking_delta') {
    console.log('Фрагмент размышления:', data.delta.thinking);
  } else if (data.delta?.type === 'text_delta') {
    console.log('Фрагмент ответа:', data.delta.text);
  }
});

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

// Мониторинг качества соединения
const diagnostics = wsClient.diagnoseConnection(WebSocketNamespace.REASONING);
console.log(`Состояние соединения:`, diagnostics);

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

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

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

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

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

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

Потоковая передача мышления

Версия 1.7.4 включает полную поддержку потоковой передачи мышления через Anthropic API, а также улучшенную обработку ошибок:

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,
    authToken: 'your-auth-token' // Унифицированный параметр для аутентификации WebSocket
  };
  
  // Обработчик событий WebSocket
  const handleEvent = (eventType, data) => {
    switch(eventType) {
      case 'content_block_start':
        if (data.content_block && data.content_block.type === 'thinking') {
          console.log('Начало размышлений:');
        }
        break;
        
      case 'content_block_delta':
        if (data.delta && data.delta.type === 'thinking_delta') {
          process.stdout.write(data.delta.thinking); // Потоковый вывод размышлений
        } else if (data.delta && data.delta.type === 'text_delta') {
          process.stdout.write(data.delta.text); // Потоковый вывод итогового текста
        }
        break;
        
      case 'error':
        console.error('Ошибка:', data.message);
        
        // Обработка ошибки географических ограничений
        if (data.type === 'geo_restriction') {
          console.error('Необходимо включить VPN для доступа к API Anthropic из вашего региона');
        }
        break;
    }
  };
  
  try {
    // Отправляем запрос с потоковым мышлением
    const response = await sdk.chat.streamChatWithThinking(
      messages,
      options,
      handleEvent
    );
    
    console.log(`Запрос успешно отправлен. Socket ID: ${response.socketId}`);
  } catch (error) {
    console.error('Ошибка:', error);
    
    // Проверка наличия ошибки географических ограничений
    if (error.type === 'geo_restriction') {
      console.error('Необходимо включить VPN для доступа к API Anthropic из вашего региона');
    }
  }
}

streamThinking();

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

  • message_start - начало сообщения от модели
  • content_block_start - начало блока контента (текст или thinking)
  • content_block_delta - дельта блока контента со следующими типами:
    • delta.type === 'thinking_delta' - фрагмент размышления модели
    • delta.type === 'text_delta' - фрагмент текстового ответа
    • delta.type === 'input_json_delta' - фрагмент JSON для инструментов
    • delta.type === 'signature_delta' - подпись блока мышления
  • content_block_stop - завершение блока контента
  • message_delta - дельта сообщения
  • message_stop - завершение сообщения

Примеры

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

# Проверка подключения к API
npm run example:check-api

# Индексация проектов
npm run example:indexing

# Работа с зависимостями
npm run example:dependencies

Совместимость

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

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

Разработка и тестирование

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

# Сборка SDK
npm run build

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

# Тесты для рассуждений и WebSocket
npm run test:reasoning:all

# Запуск примеров
npm run example:check-api

Локальная разработка

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

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

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

Лицензия

MIT