solver-sdk
Version:
SDK для интеграции с Code Solver Backend API (совместимо с браузером и Node.js), с поддержкой функциональности мышления (Thinking Mode)
438 lines (344 loc) • 16.5 kB
Markdown
# Solver SDK
SDK для интеграции с Code Solver Backend API. Поддерживает работу как в браузере, так и в Node.js.
<p align="center">
<a href="https://www.npmjs.com/package/solver-sdk"><img src="https://img.shields.io/npm/v/solver-sdk.svg" alt="NPM Version" /></a>
<a href="https://www.npmjs.com/package/solver-sdk"><img src="https://img.shields.io/npm/dm/solver-sdk.svg" alt="NPM Downloads" /></a>
<a href="https://github.com/code-solver/browser-sdk/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/solver-sdk.svg" alt="License" /></a>
</p>
## 📋 Содержание
- [Основные возможности](#основные-возможности)
- [Установка](#установка)
- [Быстрый старт](#быстрый-старт)
- [CommonJS (Node.js)](#в-среде-commonjs-nodejs)
- [ESM (Node.js)](#в-среде-esm-nodejs)
- [Браузер](#в-браузере)
- [API](#api)
- [Основные компоненты](#основные-компоненты)
- [Опции SDK](#опции-sdk)
- [Продвинутые функции](#продвинутые-функции)
- [Проекты и индексация](#работа-с-проектами)
- [Поиск кода](#поиск-кода)
- [WebSocket и подписки](#работа-с-рассуждениями-через-websocket)
- [Работа с зависимостями](#api-для-работы-с-зависимостями)
- [Потоковая передача мышления](#потоковая-передача-мышления)
- [Региональные эндпоинты](#работа-с-региональными-эндпоинтами)
- [Примеры](#примеры)
- [Совместимость](#совместимость)
- [Разработка и тестирование](#разработка-и-тестирование)
- [Документация](#документация)
- [Лицензия](#лицензия)
## Основные возможности
- **Кросс-платформенность**: совместимость с ESM, CommonJS, браузером и Node.js
- **Типизация**: полная поддержка TypeScript
- **Расширенная работа с WebSocket**:
- Автоматический ping/pong механизм для мониторинга соединений
- Сбор статистики времени отклика (RTT) и состояния соединений
- Интеллектуальный механизм переподключения с экспоненциальной задержкой
- Настраиваемый мониторинг здоровья соединения
- **Потоковая передача мышления**:
- Метод `streamChatWithThinking()` для потоковой передачи процесса мышления модели
- Полная поддержка событий Anthropic API (`thinking_delta`, `text_delta` и др.)
- Стандартизированный формат для всех типов событий
- **Работа с регионами**:
- Поддержка региональных эндпоинтов Anthropic API
- Автоматическое переключение между регионами при ошибках
- Поддержка регионов: 'us-east-1', 'eu-west-1', 'ap-southeast-2'
- **Индексация и поиск**:
- Инкрементальная индексация отдельных файлов
- Семантический поиск кода
- **Обработка ошибок**:
- Интеллектуальные повторные попытки
- Обширная диагностика соединений
## Установка
```bash
npm install solver-sdk
```
## Быстрый старт
### В среде CommonJS (Node.js)
```javascript
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)
```javascript
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);
```
### В браузере
```html
<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') | Нет |
| `providers` | object | Настройки провайдеров API (Anthropic и др.) | Нет |
| `websocket` | object | Настройки WebSocket (reconnect, timeout и др.) | Нет |
## Продвинутые функции
### Работа с проектами
```javascript
// Получение списка проектов
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);
```
### Поиск кода
```javascript
// Поиск кода
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
```javascript
// Создание рассуждения
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('thinking_delta', (data) => {
console.log('Фрагмент размышления:', data.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 для работы с зависимостями
```javascript
// Получение зависимостей конкретного файла
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, а также улучшенную обработку ошибок:
```javascript
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 'thinking_start':
console.log('Начало размышлений:');
break;
case 'thinking_delta':
process.stdout.write(data.text); // Потоковый вывод размышлений
break;
case 'text_delta':
process.stdout.write(data.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)
- `thinking_delta` - фрагмент размышления модели
- `text_delta` - фрагмент итогового текста
- `content_block_stop` - завершение блока контента
- `message_stop` - завершение сообщения
### Работа с региональными эндпоинтами
```javascript
// Настройка SDK с указанием предпочтительного региона
const sdk = new CodeSolverSDK({
baseURL: 'https://api.example.com',
apiKey: 'your-api-key',
providers: {
anthropic: {
region: 'eu-west-1' // Использовать европейский регион
}
}
});
// Запрос с автоматическим переключением между регионами при ошибках
const response = await sdk.chat.chatWithRegionFailover([
{ role: 'user', content: 'Расскажи о квантовых компьютерах' }
], {
model: 'claude-3-7-sonnet-20240229'
});
// Запрос с явным указанием региона
const responseFromAsia = await sdk.chat.chat([
{ role: 'user', content: 'Расскажи о квантовых компьютерах' }
], {
model: 'claude-3-7-sonnet-20240229',
region: 'ap-southeast-2' // Явно указываем регион
});
```
## Примеры
В директории [`examples`](./examples) доступны примеры использования SDK:
```bash
# Проверка подключения к API
npm run example:check-api
# Индексация проектов
npm run example:indexing
# Работа с зависимостями
npm run example:dependencies
# Проверка доступности регионов
npm run example:regions
```
## Совместимость
SDK тщательно протестирован в различных средах и поддерживает:
- **Браузеры**: Chrome 80+, Firefox 72+, Safari 14+, Edge 80+
- **Node.js**: Версии 14.x и выше (как CommonJS, так и ESM)
- **VS Code**: Desktop и Web версии
## Разработка и тестирование
```bash
# Установка зависимостей
npm install
# Сборка SDK
npm run build
# Запуск всех тестов
npm test
# Тесты для рассуждений и WebSocket
npm run test:reasoning:all
# Запуск примеров
npm run example:check-api
```
### Локальная разработка
```javascript
const sdk = new CodeSolverSDK({
baseURL: 'https://localhost:3000',
apiKey: 'test-api-key',
httpsAgent: new https.Agent({
rejectUnauthorized: false // Для самоподписанных сертификатов
}),
websocket: {
reconnect: true,
rejectUnauthorized: false
}
});
```
## Документация
Подробная документация доступна в директории [`docs`](./docs):
- [Начало работы](./docs/GETTING_STARTED.md)
- [Работа с проектами](./docs/PROJECTS.md)
- [Индексация проектов](./docs/INDEXING.md)
- [Потоковая передача мышления](./docs/THINKING_ARCHITECTURE.md)
- [Работа с регионами](./docs/ADVANCED.md)
- [Полное API](./docs/API.md)
## Лицензия
[MIT](./LICENSE)