solver-sdk 3.1.2 → 3.1.3

package/docs/VSCODE_INTEGRATION.md

@@ -1,269 +0,0 @@
-# VS Code Extension Integration
-
-> **Практическое руководство интеграции SDK с VS Code Extension**
-
-## 🚀 Быстрая интеграция
-
-### 1. Базовая настройка
-
-```typescript
-import { CodeSolverSDK } from 'solver-sdk';
-import * as vscode from 'vscode';
-
-// Инициализация SDK
-let sdk: CodeSolverSDK;
-
-export async function activate(context: vscode.ExtensionContext) {
-  // Создание SDK
-  sdk = await CodeSolverSDK.create({
-    baseURL: 'http://localhost:3000'
-  });
-  
-  // Регистрация команд
-  const indexCommand = vscode.commands.registerCommand(
-    'myExtension.indexProject',
-    indexCurrentWorkspace
-  );
-  
-  const searchCommand = vscode.commands.registerCommand(
-    'myExtension.searchFunctions',
-    searchAndNavigate
-  );
-  
-  context.subscriptions.push(indexCommand, searchCommand);
-}
-```
-
-## 📊 Индексация с прогресс-баром
-
-```typescript
-async function indexCurrentWorkspace() {
-  if (!vscode.workspace.workspaceFolders) {
-    vscode.window.showErrorMessage('Откройте папку проекта');
-    return;
-  }
-  
-  const folder = vscode.workspace.workspaceFolders[0];
-  const projectPath = folder.uri.fsPath;
-  const projectName = folder.name;
-  
-  return vscode.window.withProgress({
-    location: vscode.ProgressLocation.Notification,
-    title: 'Индексация проекта',
-    cancellable: true
-  }, async (progress, token) => {
-    try {
-      progress.report({ message: 'Создание проекта...' });
-      const project = await sdk.projects.findOrCreateProject(projectPath, projectName);
-      
-      progress.report({ message: 'Запуск индексации...' });
-      await sdk.projects.startIndexing(project.id);
-      
-      while (!token.isCancellationRequested) {
-        const status = await sdk.projects.getProjectStatus(project.id);
-        
-        if (status.status === 'ready') {
-          vscode.window.showInformationMessage('✅ Проект проиндексирован!');
-          return project;
-        }
-        
-        if (status.status === 'error') {
-          throw new Error(status.error);
-        }
-        
-        const percentage = status.progress || 0;
-        progress.report({ 
-          increment: percentage,
-          message: `${percentage}% - ${status.currentFile || 'Обработка...'}`
-        });
-        
-        await new Promise(resolve => setTimeout(resolve, 2000));
-      }
-      
-    } catch (error) {
-      vscode.window.showErrorMessage(`Ошибка: ${error.message}`);
-    }
-  });
-}
-```
-
-## 🔍 Поиск функций с навигацией
-
-```typescript
-async function searchAndNavigate() {
-  const projects = await sdk.projects.getReadyProjects();
-  
-  if (projects.length === 0) {
-    vscode.window.showWarningMessage('Нет проиндексированных проектов');
-    return;
-  }
-  
-  const query = await vscode.window.showInputBox({
-    prompt: 'Поиск функций',
-    placeholder: 'Введите название функции или описание...'
-  });
-  
-  if (!query) return;
-  
-  try {
-    const results = await sdk.search.searchFunctions(projects[0].id, {
-      query,
-      limit: 20
-    });
-    
-    if (results.results.length === 0) {
-      vscode.window.showInformationMessage('Ничего не найдено');
-      return;
-    }
-    
-    const functionItems = results.results.map(fn => ({
-      label: `$(symbol-function) ${fn.name}`,
-      description: fn.signature,
-      detail: `${fn.filePath}:${fn.startLine}`,
-      function: fn
-    }));
-    
-    const selectedFunction = await vscode.window.showQuickPick(functionItems);
-    
-    if (selectedFunction) {
-      await navigateToFunction(selectedFunction.function);
-    }
-    
-  } catch (error) {
-    vscode.window.showErrorMessage(`Ошибка поиска: ${error.message}`);
-  }
-}
-
-async function navigateToFunction(fn: any) {
-  try {
-    const doc = await vscode.workspace.openTextDocument(fn.filePath);
-    const editor = await vscode.window.showTextDocument(doc);
-    
-    const range = new vscode.Range(
-      fn.startLine - 1, 0,
-      fn.endLine - 1, 0
-    );
-    
-    editor.selection = new vscode.Selection(range.start, range.end);
-    editor.revealRange(range, vscode.TextEditorRevealType.InCenter);
-    
-  } catch (error) {
-    vscode.window.showErrorMessage(`Ошибка навигации: ${error.message}`);
-  }
-}
-```
-
-## 💬 AI Chat интеграция
-
-```typescript
-async function askAI() {
-  const editor = vscode.window.activeTextEditor;
-  if (!editor) {
-    vscode.window.showWarningMessage('Откройте файл в редакторе');
-    return;
-  }
-  
-  const selection = editor.selection;
-  const selectedText = editor.document.getText(selection);
-  
-  let contextText = '';
-  if (selectedText) {
-    contextText = `
-
-Выделенный код:
-\`\`\`${editor.document.languageId}
-${selectedText}
-\`\`\``;
-  }
-  
-  const question = await vscode.window.showInputBox({
-    prompt: 'Задайте вопрос AI',
-    placeholder: 'Что делает этот код? Как его улучшить?'
-  });
-  
-  if (!question) return;
-  
-  return vscode.window.withProgress({
-    location: vscode.ProgressLocation.Notification,
-    title: 'AI анализирует код...',
-    cancellable: false
-  }, async (progress) => {
-    try {
-      const response = await sdk.chat.chat([{
-        role: 'user',
-        content: question + contextText
-      }], {
-        model: 'claude-3-5-sonnet-20241022',
-        maxTokens: 8192
-      });
-      
-      const doc = await vscode.workspace.openTextDocument({
-        content: `Q: ${question}
-
-A: ${response.content[0].text}`,
-        language: 'markdown'
-      });
-      
-      await vscode.window.showTextDocument(doc);
-      
-    } catch (error) {
-      vscode.window.showErrorMessage(`Ошибка AI: ${error.message}`);
-    }
-  });
-}
-```
-
-## ⚙️ Конфигурация package.json
-
-```json
-{
-  "name": "my-code-assistant",
-  "displayName": "AI Code Assistant",
-  "description": "AI помощник для анализа и поиска кода",
-  "version": "1.0.0",
-  "engines": {
-    "vscode": "^1.60.0"
-  },
-  "categories": ["Other"],
-  "activationEvents": [
-    "onStartupFinished"
-  ],
-  "main": "./out/extension.js",
-  "contributes": {
-    "commands": [
-      {
-        "command": "myExtension.indexProject",
-        "title": "📊 Проиндексировать проект",
-        "category": "AI Assistant"
-      },
-      {
-        "command": "myExtension.searchFunctions",
-        "title": "🔍 Поиск функций",
-        "category": "AI Assistant"
-      },
-      {
-        "command": "myExtension.askAI",
-        "title": "💬 Спросить AI",
-        "category": "AI Assistant"
-      }
-    ],
-    "keybindings": [
-      {
-        "command": "myExtension.searchFunctions",
-        "key": "ctrl+shift+f",
-        "mac": "cmd+shift+f"
-      },
-      {
-        "command": "myExtension.askAI",
-        "key": "ctrl+shift+a",
-        "mac": "cmd+shift+a"
-      }
-    ]
-  },
-  "dependencies": {
-    "solver-sdk": "^3.0.0"
-  }
-}
-```
-
-SDK готов для интеграции в VS Code Extension! 🚀

package/docs/features/THINKING.md

@@ -1,324 +0,0 @@
-# Anthropic Claude 4 Thinking + Tool Calling
-
-Полная поддержка Anthropic Claude 4 с расширенным мышлением (thinking) и инструментами (tool calling). SDK предоставляет все необходимые функции для работы с complex content, signature handling и правильным tool_choice.
-
-## 🚀 Критические особенности
-
-### ✅ **Complex Content поддержка**
-SDK поддерживает массивы `ContentBlock[]` вместо простых строк:
-
-```typescript
-interface ChatMessage {
-  role: 'system' | 'user' | 'assistant';
-  content: string | ContentBlock[]; // ✅ Поддержка массива блоков
-}
-```
-
-### ✅ **Tool Choice ограничения**
-С thinking поддерживаются только `'auto'` и `'none'`:
-
-```typescript
-// ✅ Правильно
-tool_choice: { type: 'auto' }   // или { type: 'none' }
-
-// ❌ НЕ поддерживается с thinking
-tool_choice: { type: 'any' }   // Ошибка!
-tool_choice: { type: 'tool', name: 'read_file' } // Ошибка!
-```
-
-### ✅ **Signature handling**
-Автоматическое сохранение и передача криптографических подписей:
-
-```typescript
-{
-  type: 'thinking',
-  thinking: 'размышления модели...',
-  signature: 'WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem...' // ✅ Сохраняется
-}
-```
-
-## 📋 Основные функции
-
-### Helper функции для complex content
-
-```typescript
-import { 
-  createStandardDevelopmentTools,
-  createToolResultMessage,
-  extractThinkingBlocks,
-  extractToolUseBlocks,
-  createComplexAssistantMessage,
-  createUserMessage
-} from 'solver-sdk';
-```
-
-## 🎯 Полный пример использования
-
-### 1. **Первый запрос с thinking + tools**
-
-```javascript
-const { CodeSolverSDK, createStandardDevelopmentTools, createUserMessage } = require('solver-sdk');
-
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://localhost:3001',
-  apiKey: 'your-api-key'
-});
-
-async function demonstrateThinkingWithTools() {
-  // 1. Получаем стандартные инструменты (как в Cursor)
-  const tools = createStandardDevelopmentTools();
-  
-  // 2. Создаем запрос пользователя
-  const userRequest = createUserMessage(
-    'Создай Node.js скрипт для чтения package.json'
-  );
-
-  // 3. Отправляем запрос с правильными параметрами
-  const response = await sdk.chat.chat([userRequest], {
-    model: 'claude-sonnet-4-20250514',
-    max_tokens: 16000,
-    thinking: {
-      type: 'enabled',
-      budget_tokens: 10000 // Минимум 1024
-    },
-    tools: tools,
-    tool_choice: { type: 'auto' }, // ✅ ТОЛЬКО auto/none с thinking!
-    beta: 'interleaved-thinking-2025-05-14' // Автоматически включается
-  });
-
-  return response;
-}
-```
-
-### 2. **Обработка thinking и tool_use блоков**
-
-```javascript
-import { extractThinkingBlocks, extractToolUseBlocks } from 'solver-sdk';
-
-// Извлекаем блоки из ответа
-const thinkingBlocks = extractThinkingBlocks(response.content);
-const toolUseBlocks = extractToolUseBlocks(response.content);
-
-console.log('🧠 Блоков мышления:', thinkingBlocks.length);
-console.log('🔧 Блоков tool_use:', toolUseBlocks.length);
-
-// Показываем thinking с signature
-thinkingBlocks.forEach((block, idx) => {
-  console.log(`Мышление ${idx + 1}:`, block.thinking);
-  if (block.signature) {
-    console.log('🔐 Signature:', block.signature);
-  }
-});
-```
-
-### 3. **Выполнение инструментов и продолжение диалога**
-
-```javascript
-import { 
-  createToolResultMessage, 
-  createComplexAssistantMessage 
-} from 'solver-sdk';
-
-if (toolUseBlocks.length > 0) {
-  const toolUse = toolUseBlocks[0];
-  
-  // Выполняем инструмент (здесь симуляция)
-  const toolResult = await executeToolLocally(toolUse);
-  
-  // ✅ КРИТИЧНО: Создаем правильную последовательность сообщений
-  const toolResultMessage = createToolResultMessage(
-    toolUse.id,
-    toolResult,
-    false // не ошибка
-  );
-
-  // ✅ КРИТИЧНО: Создаем complex content сообщение от ассистента
-  const assistantMessage = createComplexAssistantMessage(
-    thinkingBlocks, // Сохраняем thinking с signature!
-    toolUseBlocks,  // Сохраняем tool_use
-    [] // Текстовые блоки (если есть)
-  );
-
-  // Продолжаем диалог с сохранением thinking
-  const messages = [
-    userRequest,
-    assistantMessage,    // ✅ Complex content с thinking + tool_use
-    toolResultMessage    // Результат выполнения инструмента
-  ];
-
-  const finalResponse = await sdk.chat.chat(messages, {
-    model: 'claude-sonnet-4-20250514',
-    max_tokens: 16000,
-    thinking: { type: 'enabled', budget_tokens: 10000 },
-    tools: tools,
-    tool_choice: { type: 'auto' },
-    beta: 'interleaved-thinking-2025-05-14'
-  });
-}
-```
-
-## 🌊 Потоковая передача
-
-### Streaming с thinking + tools
-
-```javascript
-async function streamingExample() {
-  const stream = sdk.chat.streamChat([userRequest], {
-    model: 'claude-sonnet-4-20250514',
-    max_tokens: 16000,
-    thinking: {
-      type: 'enabled',
-      budget_tokens: 8000
-    },
-    tools: tools,
-    tool_choice: { type: 'auto' },
-    beta: 'interleaved-thinking-2025-05-14',
-    stream: true
-  });
-
-  // Обрабатываем поток
-  for await (const chunk of stream) {
-    if (chunk.type === 'content_block_delta' && chunk.delta) {
-      // ✅ Thinking события
-      if (chunk.delta.type === 'thinking_delta') {
-        console.log('Мышление:', chunk.delta.thinking);
-      }
-      // ✅ Signature события
-      else if (chunk.delta.type === 'signature_delta') {
-        console.log('🔐 Signature:', chunk.delta.signature);
-      }
-      // ✅ Текстовые события
-      else if (chunk.delta.type === 'text_delta') {
-        console.log('Ответ:', chunk.delta.text);
-      }
-    }
-    // ✅ Tool use события
-    else if (chunk.type === 'content_block_start' && chunk.content_block?.type === 'tool_use') {
-      console.log('🛠️ Инструмент:', chunk.content_block.name);
-    }
-    // Завершение потока
-    else if (chunk.type === 'message_stop') {
-      break;
-    }
-  }
-}
-```
-
-## 🛠️ Стандартные инструменты разработки
-
-```javascript
-import { createStandardDevelopmentTools } from 'solver-sdk';
-
-const tools = createStandardDevelopmentTools();
-// Возвращает массив из 8 инструментов:
-// - read_file
-// - create_file
-// - edit_file
-// - search_files
-// - list_directory
-// - terminal_command
-// - semantic_search
-// - analyze_project_context
-```
-
-## 🚨 Обработка ошибок инструментов
-
-```javascript
-import { createToolResultMessage } from 'solver-sdk';
-
-// При ошибке выполнения инструмента
-const errorResult = createToolResultMessage(
-  toolUse.id,
-  'Ошибка: Файл не найден',
-  true // ✅ КРИТИЧНО: флаг ошибки
-);
-
-// Продолжаем диалог с ошибкой
-const messages = [userRequest, assistantMessage, errorResult];
-const errorResponse = await sdk.chat.chat(messages, options);
-```
-
-## 📊 Типы событий в потоке
-
-### **Thinking события**
-```typescript
-'content_block_start' + content_block.type === 'thinking'
-'content_block_delta' + delta.type === 'thinking_delta'
-'content_block_delta' + delta.type === 'signature_delta' // ✅ НОВОЕ!
-'content_block_stop'
-```
-
-### **Tool use события**
-```typescript
-'content_block_start' + content_block.type === 'tool_use'
-'content_block_delta' + delta.type === 'text_delta'
-'content_block_stop'
-```
-
-### **Text ответ**
-```typescript
-'content_block_start' + content_block.type === 'text'
-'content_block_delta' + delta.type === 'text_delta'
-'content_block_stop'
-```
-
-## ⚙️ Правильная конфигурация
-
-### Обязательные параметры
-
-```typescript
-{
-  model: 'claude-sonnet-4-20250514',
-  thinking: {
-    type: 'enabled',
-    budget_tokens: 10000 // Минимум 1024
-  },
-  tools: createStandardDevelopmentTools(),
-  tool_choice: { type: 'auto' }, // ТОЛЬКО auto/none
-  beta: 'interleaved-thinking-2025-05-14',
-  max_tokens: 16000
-}
-```
-
-### Дополнительные параметры
-
-```typescript
-{
-  top_p: 0.98, // От 0.95 до 1 с thinking
-  stream: true,
-  projectId: 'your-project-id', // Для автовыполнения инструментов
-  // temperature НЕ поддерживается с thinking
-}
-```
-
-## 🎯 Готовность к тестированию
-
-### ✅ **Готово в SDK:**
-- Complex Content поддержка с `ContentBlock[]`
-- Правильная валидация `tool_choice` 
-- Signature preservation в thinking блоках
-- Все необходимые helper функции
-- Streaming обработка всех событий
-- Cursor-подобные стандартные инструменты
-
-### 🚀 **Простые тесты для проверки:**
-
-```javascript
-// 1. Простой tool calling
-"Прочитай файл package.json"
-→ thinking → read_file → ответ
-
-// 2. Сложный multi-tool workflow  
-"Найди все баги в коде и исправь их"
-→ thinking → semantic_search → read_file → edit_file → thinking → ответ
-
-// 3. Cursor-подобные запросы
-"Добавь аутентификацию в это приложение"
-→ thinking → analyze_project_context → semantic_search → create_file → edit_file
-```
-
-## 📞 Результат
-
-**SDK ПОЛНОСТЬЮ ГОТОВ** для работы с Anthropic Claude 4 thinking + tool calling. Все критические требования клиента реализованы и протестированы.
-
-**Статус:** ✅ ГОТОВ к немедленному тестированию