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 старая архитектура.
⚡ Что нового в 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 разработчики
- 📄 5-минутный старт - минимальный код для работы
- 📚 Полное руководство - детальные примеры и best practices
🔧 Backend интеграция
- 🏗️ Архитектура - HTTP vs WebSocket решения
- 🔌 WebSocket API - события и namespace'ы
- 🔑 Аутентификация - настройка 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:
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- Основной класс 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