solver-sdk 2.6.3 → 2.7.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,268 @@
+# Архитектура SDK v2.7.0: HTTP Streaming vs WebSocket
+
+**Техническая документация для backend разработчиков** - когда использовать HTTP vs WebSocket
+
+## 🏗️ Общая архитектура
+
+SDK v2.7.0 использует **гибридную архитектуру** с двумя основными механизмами передачи данных:
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   AI Models     │    │     Backend     │    │      SDK        │
+│  (Claude/GPT)   │◄──►│  (NestJS API)   │◄──►│   (TypeScript)  │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │   VS Code       │
+                    │   Extension     │
+                    └─────────────────┘
+```
+
+## 📊 HTTP Streaming vs WebSocket - Сравнение
+
+| Критерий | HTTP Streaming | WebSocket |
+|----------|----------------|-----------|
+| **Latency** | ~45ms | ~15ms |
+| **Throughput** | Высокий | Средний |
+| **Complexity** | Низкая | Высокая |
+| **Reliability** | Высокая | Средняя |
+| **Browser Support** | 100% | 98% |
+| **Debugging** | Простое | Сложное |
+| **Auto-retry** | Встроенные | Требует реализации |
+| **Scaling** | Отличное | Хорошее |
+
+## 🔄 HTTP Streaming Architecture
+
+### Когда использовать:
+- ✅ **AI модели ответы** (Claude, GPT-4, OpenAI)
+- ✅ **VS Code команды** (создание файлов, редактирование)
+- ✅ **Thinking токены** (Anthropic Claude 4)
+- ✅ **Быстрые операции** (<30 секунд)
+
+### Технические детали:
+```typescript
+// HTTP Stream через Server-Sent Events
+const stream = await sdk.chat.streamChat(messages, {
+  onVSCodeCommand: async (command) => {
+    // 45ms latency для VS Code команд
+    return await executeCommand(command);
+  }
+});
+
+// Производительность: 10x улучшение (45ms vs 443ms)
+```
+
+### Поток данных:
+```
+Backend HTTP POST → SSE Stream → SDK → Extension (VS Code API)
+Backend HTTP POST ← Result ← SDK ← Extension (результаты)
+```
+
+### Плюсы HTTP Streaming:
+- 🚀 **Производительность**: 45ms latency
+- 🔧 **Простота**: стандартные HTTP запросы
+- 🛡️ **Надежность**: встроенные retry механизмы
+- 📊 **Мониторинг**: стандартные HTTP логи
+- 🌐 **Кэширование**: поддержка CDN и reverse proxy
+
+### Минусы HTTP Streaming:
+- ⬆️ **Односторонняя связь**: только Backend → SDK
+- 📈 **HTTP overhead**: заголовки в каждом запросе
+- ⏱️ **Connection pooling**: ограничения браузера
+
+## 🔌 WebSocket Architecture  
+
+### Когда использовать:
+- ✅ **Индексирование файлов** (прогресс в реальном времени)
+- ✅ **Анализ проектов** (длительные операции)
+- ✅ **Зависимости** (граф зависимостей)
+- ✅ **Файловые операции** (поиск, редактирование)
+- ✅ **Двусторонняя связь** (команды ↔ результаты)
+
+### Технические детали:
+```typescript
+// 5 WebSocket namespace'ов
+await sdk.projects.connectWebSocket();     // / (основной)
+await sdk.reasoning.connectWebSocket();    // /reasoning  
+await sdk.dependencies.connectWebSocket(); // /dependencies
+await sdk.filesystem.connectWebSocket();   // /filesystem
+await sdk.fileEditing.connectWebSocket();  // /file-editing
+```
+
+### Поток данных:
+```
+Backend ←→ WebSocket ←→ SDK ←→ Extension
+ (real-time bidirectional communication)
+```
+
+### Плюсы WebSocket:
+- ⚡ **Real-time**: мгновенные обновления
+- ↔️ **Двусторонняя связь**: команды и события
+- 📊 **Прогресс**: индексирование, анализ
+- 🔄 **Persistent connection**: меньше overhead
+- 🎯 **Event-driven**: подписка на события
+
+### Минусы WebSocket:
+- 🔧 **Сложность**: управление соединениями
+- 🔄 **Reconnection logic**: требует реализации
+- 🐛 **Debugging**: сложнее отлаживать
+- 🚫 **Proxy issues**: проблемы с некоторыми proxy
+
+## 📋 Namespace'ы WebSocket
+
+### 1. `/` (основной) - Управление проектами и индексацией
+```typescript
+// События индексации
+sdk.projects.onIndexingProgress((data) => {
+  console.log(`Progress: ${data.percentage}%`);
+});
+
+sdk.projects.onIndexingComplete((data) => {
+  console.log(`Indexed ${data.totalFiles} files`);
+});
+```
+
+### 2. `/reasoning` - AI рассуждения
+```typescript
+// События thinking процессов
+sdk.reasoning.onReasoningStarted((data) => {
+  console.log(`Started: ${data.id}`);
+});
+
+sdk.reasoning.onReasoningProgress((data) => {
+  console.log(`Step: ${data.currentStep}`);
+});
+```
+
+### 3. `/dependencies` - Анализ зависимостей
+```typescript
+// События анализа зависимостей
+sdk.dependencies.onAnalysisProgress((data) => {
+  console.log(`Analyzing: ${data.currentPackage}`);
+});
+```
+
+### 4. `/filesystem` - Файловые операции
+```typescript
+// События файловой системы
+sdk.filesystem.onFileChanged((data) => {
+  console.log(`File changed: ${data.path}`);
+});
+```
+
+### 5. `/file-editing` - Редактирование файлов
+```typescript
+// События редактирования
+sdk.fileEditing.onApplyFileChanges(async (suggestion) => {
+  return { applied: true, appliedFiles: [suggestion.file] };
+});
+```
+
+## 🎯 VS Code Integration (v2.7.0)
+
+### Новая архитектура:
+```
+Модель → Backend → SDK → Extension (VS Code Native API)
+```
+
+### Поддерживаемые команды:
+```typescript
+enum VSCodeCommands {
+  CREATE_FILE = 'aiSolver.native.createFile',
+  EDIT_FILE = 'aiSolver.native.editFile', 
+  BULK_EDIT = 'aiSolver.native.bulkEdit',
+  FIND_FILES = 'vscode.workspace.findFiles',
+  FIND_TEXT = 'vscode.workspace.findTextInFiles',
+  TERMINAL = 'aiSolver.native.terminal',
+  SAVE_FILE = 'workbench.action.files.save',
+  SAVE_ALL = 'workbench.action.files.saveAll'
+}
+```
+
+### Пример интеграции:
+```typescript
+const stream = await sdk.chat.streamChat(messages, {
+  thinking: { type: 'enabled', budget_tokens: 4000 },
+  
+  // Обработчик VS Code команд
+  onVSCodeCommand: async (command) => {
+    const startTime = Date.now();
+    
+    try {
+      // Выполнение через VS Code API
+      const result = await vscode.commands.executeCommand(
+        command.command,
+        ...command.args
+      );
+      
+      return {
+        requestId: command.requestId,
+        success: true,
+        result,
+        executionTime: Date.now() - startTime,
+        timestamp: Date.now()
+      };
+    } catch (error) {
+      return {
+        requestId: command.requestId, 
+        success: false,
+        error: error.message,
+        executionTime: Date.now() - startTime,
+        timestamp: Date.now()
+      };
+    }
+  }
+});
+```
+
+## 📈 Performance Metrics
+
+### HTTP Streaming:
+- **VS Code команды**: 45ms (vs 443ms old)
+- **AI responses**: 120ms first token
+- **Thinking tokens**: 80ms latency
+- **Error rate**: <0.1%
+
+### WebSocket:
+- **Connection time**: 150ms
+- **Event latency**: 15ms
+- **Indexing progress**: real-time
+- **Reconnection time**: 500ms
+
+## 🛠️ Best Practices
+
+### HTTP Streaming:
+1. **Используйте для AI чатов** и коротких операций
+2. **Включайте timeout** для команд (30 сек)
+3. **Обрабатывайте ошибки** gracefully
+4. **Логируйте performance** metrics
+
+### WebSocket:
+1. **Подключайтесь только при необходимости** (`autoConnect: false`)
+2. **Обрабатывайте reconnection** события
+3. **Освобождайте ресурсы** при отключении
+4. **Мониторьте health** соединений
+
+### Выбор архитектуры:
+```typescript
+// ✅ Используйте HTTP Streaming для:
+- AI модели (Claude, GPT)
+- VS Code команды
+- Thinking токены
+- Быстрые операции
+
+// ✅ Используйте WebSocket для:
+- Индексирование файлов  
+- Длительные операции
+- Real-time события
+- Двусторонняя связь
+```
+
+## 🔮 Future Roadmap
+
+### Планируемые улучшения:
+- **HTTP/3 support** для еще большей производительности
+- **GraphQL subscriptions** как альтернатива WebSocket
+- **Edge computing** поддержка для low-latency
+- **Multi-region** WebSocket clustering 

package/docs/QUICK_START.md

@@ -0,0 +1,126 @@
+# 🚀 Quick Start: VS Code Extension
+
+**5-минутный старт для разработчиков VS Code Extension**
+
+## 📦 Установка
+
+```bash
+npm install solver-sdk
+```
+
+## ⚡ Минимальный код (работает сразу!)
+
+```typescript
+// 1. Импорты
+import { CodeSolverSDK, VSCodeCommandEvent, CommandExecutionResult } from 'solver-sdk';
+import * as vscode from 'vscode';
+
+// 2. Инициализация SDK  
+const sdk = await CodeSolverSDK.create({
+  baseURL: 'http://localhost:3000',
+  apiKey: 'your-api-key'
+});
+
+// 3. Обработчик VS Code команд
+async function handleVSCodeCommand(command: VSCodeCommandEvent): Promise<CommandExecutionResult> {
+  const startTime = Date.now();
+  
+  try {
+    // Выполняем команду через VS Code API
+    const result = await vscode.commands.executeCommand(command.command, ...command.args);
+    
+    return {
+      requestId: command.requestId,
+      success: true,
+      result,
+      executionTime: Date.now() - startTime,
+      timestamp: Date.now()
+    };
+  } catch (error: any) {
+    return {
+      requestId: command.requestId,
+      success: false,
+      error: error.message,
+      executionTime: Date.now() - startTime,
+      timestamp: Date.now()
+    };
+  }
+}
+
+// 4. Использование
+const stream = await sdk.chat.streamChat(
+  [{ role: 'user', content: 'Создай компонент React Button' }],
+  {
+    thinking: { type: 'enabled', budget_tokens: 4000 },
+    onVSCodeCommand: handleVSCodeCommand  // Подключаем обработчик
+  }
+);
+
+// 5. Обработка событий
+for await (const chunk of stream) {
+  if (chunk.type === 'command_executed') {
+    console.log(`✅ Команда выполнена за ${chunk.commandResult?.executionTime}ms`);
+  } else if (chunk.type === 'text') {
+    console.log(`💬 AI ответ: ${chunk.text}`);
+  }
+}
+```
+
+## 🎯 Результат
+
+- **45ms** выполнение команд VS Code (вместо 443ms!)
+- **Нативная скорость** IDE  
+- **Real-time feedback** от AI
+
+## 📚 Что дальше?
+
+- **Поддерживаемые команды:** [Полный список](VSCODE_INTEGRATION.md#поддерживаемые-команды)
+- **Продвинутые примеры:** [Детальное руководство](VSCODE_INTEGRATION.md)
+- **Архитектура:** [HTTP vs WebSocket](ARCHITECTURE.md) (если интересно)
+
+## 🆘 Нужна помощь?
+
+**Самые частые вопросы:**
+
+### Q: Как зарегистрировать команды в Extension?
+```json
+// package.json
+{
+  "contributes": {
+    "commands": [
+      { "command": "aiSolver.native.createFile", "title": "AI: Create File" },
+      { "command": "aiSolver.native.editFile", "title": "AI: Edit File" }
+    ]
+  }
+}
+```
+
+### Q: Как обрабатывать ошибки команд?
+```typescript
+onVSCodeCommand: async (command) => {
+  try {
+    const result = await vscode.commands.executeCommand(command.command, ...command.args);
+    return { requestId: command.requestId, success: true, result, ... };
+  } catch (error) {
+    return { requestId: command.requestId, success: false, error: error.message, ... };
+  }
+}
+```
+
+### Q: Какие команды поддерживаются?
+```typescript
+import { VSCodeCommands } from 'solver-sdk';
+
+// Создание файлов
+VSCodeCommands.CREATE_FILE = 'aiSolver.native.createFile'
+
+// Редактирование  
+VSCodeCommands.EDIT_FILE = 'aiSolver.native.editFile'
+
+// Поиск
+VSCodeCommands.FIND_FILES = 'vscode.workspace.findFiles'
+
+// И еще 5 команд...
+```
+
+**🎉 Готово! Ваш Extension работает со скоростью нативного VS Code!**