Package Exports
- solver-sdk
Readme
Solver SDK v2.5.0 🚀
Production-ready SDK для интеграции с Code Solver Backend API.
🎉 Версия 2.5.0: Все критические проблемы исправлены! WebSocket контроль, алиасы методов, "fail fast" ошибки.
⚡ Что нового в v2.5.0
- ✅ WebSocket контроль:
autoConnect: falseдля ручного управления - ✅ Алиасы методов:
reasoning.create(),reasoning.start(),reasoning.stop() - ✅ "Fail Fast" ошибки: Убраны все fallback'ы, четкие сообщения об ошибках
- ✅ API диагностика:
diagnoseAPI()для проверки endpoints - ✅ Чистая архитектура: Удалены deprecated методы
- ✅ Честные исключения: WebSocket методы сразу бросают ошибку если не подключены
📋 Содержание
- Основные возможности
- Установка
- Быстрый старт
- API
- Продвинутые функции
- Примеры
- Совместимость
- Разработка и тестирование
- Документация
- Лицензия
🎯 Основные возможности
🚀 Production готовность (v2.5.0):
- "Fail Fast" подход без fallback'ов
- Честные ошибки без маскировки проблем
- Полный контроль WebSocket подключений
- API диагностика с детальными отчетами
🎮 Гибкая инициализация (v2.5.0):
CodeSolverSDK.create()- с валидацией APInew CodeSolverSDK()- быстрая инициализацияautoConnect: false- ручное управление WebSocket- Алиасы методов для удобства (
create(),start(),stop())
🔌 Контролируемые WebSocket:
- Ручное подключение только когда нужно
- Автоматический ping/pong механизм
- Интеллектуальное переподключение
- Мониторинг здоровья соединения
🧠 Потоковое мышление AI:
streamChatWithThinking()для Anthropic Claude thinking- Полная поддержка
ContentBlock[]иsignatureблоков - Сохранение криптографических подписей
- Обработка
signature_deltaсобытий
🔍 Семантический поиск:
- Инкрементальная индексация файлов
- Семантический поиск по коду
- Работа с зависимостями проектов
🌐 Кросс-платформенность:
- ESM, CommonJS, браузер, Node.js
- Полная TypeScript типизация
- Региональные Anthropic endpoints
Установка
npm install solver-sdk🚀 Быстрый старт
✅ Рекомендуемый способ (новый в v2.5.0)
const { CodeSolverSDK } = require('solver-sdk');
// ✅ ЛУЧШИЙ способ - с валидацией API
const sdk = await CodeSolverSDK.create({
baseURL: 'http://localhost:3000',
apiKey: 'your-api-key',
websocket: {
autoConnect: false // 🔧 Контролируем WebSocket вручную
}
});
// ✅ Диагностика API (новое в v2.5.0)
const diagnosis = await sdk.diagnoseAPI();
if (!diagnosis.healthy) {
console.log('❌ Проблемы с API:', diagnosis.errors);
return;
}
// ✅ Контролируемое подключение WebSocket
if (needWebSocket) {
const indexingClient = sdk.getIndexingClient();
await indexingClient.connectToIndexing();
}
// ✅ Новые алиасы методов (v2.5.0)
await sdk.reasoning.create({ projectId: 'id', query: 'test' });
await sdk.reasoning.start('reasoning-id');
await sdk.reasoning.stop('reasoning-id');✅ Быстрая инициализация (без проверки 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- Основной класс SDKReasoningApi- 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:
- Начало работы
- Работа с проектами
- Индексация проектов
- Потоковая передача мышления
- Работа с регионами
- Полное API