Frondalysis - VSCode Extension

Расширение для Visual Studio Code, которое предоставляет интеграцию с LLM (Large Language Model) для помощи в разработке. Включает чат-интерфейс, инструменты для работы с файлами, систему правил и WebSocket-соединение с внешним сервером.

📋 Содержание

• Технологии
• Быстрый старт
• Архитектура
• Разработка
• Отладка
• Структура проекта
• Git Workflow
• Полезные ссылки

🛠️ Технологии

• Frontend: Vue 3, TypeScript
• Backend: WebSocket, Docker
• IDE: Visual Studio Code Extension API

🚀 Установка расширения (готовая сборка)

Перед началом убедитесь, что Visual Studio Code установлен на вашем компьютере.

1. Скачайте и запустите установочный файл .bat по ссылке.
2. Скрипт автоматически установит файл расширения (.vsce) в VS Code — после этого расширение готово к использованию.
3. (Опционально) Перенесите иконку расширения в правую часть боковой панели, для удобства.
4. (Опционально) Для комфортной работы рекомендуется использовать тему "Темная тема (Visual Studio)". Изменить тему можно, нажав на значок ⚙️ в левом нижнем углу → Тема → Цветовая тема.

🚀 Быстрый старт

Установка

# Клонирование репозитория из GitLab
git clone <repository-url>

# Установка зависимостей
npm install

# Сборка проекта (автоматически установит зависимости для webview-chat)
npm run build

Запуск в режиме разработки (F5)

1. Откройте проект в VS Code:

   • Запустите VS Code
   • Выберите File → Open Folder (или Ctrl+K, Ctrl+O)
   • Выберите папку с проектом из Git

2. Запустите расширение:

   • Важно: Убедитесь, что файл src/extension.ts открыт в редакторе (это точка входа расширения)
   • Нажмите клавишу F5 (или Ctrl+F5 для запуска без отладки)
   • VS Code откроет новое окно с заголовком [Extension Development Host]

   Примечание: Если F5 не работает, возможно нужно установить Yeoman и generator-code:

   # Глобальная установка (рекомендуется)
   npm install -g yo generator-code
   
   # Или локальная установка (альтернатива)
   npx --package yo --package generator-code -- yo code
   

3. Найдите панель расширения:

   • В новом окне VS Code найдите иконку расширения в левой боковой панели (Activity Bar)
   • Иконка будет называться "Chat" или "LLM Helper"
   • Нажмите на неё, чтобы открыть панель чата

4. Проверка работы:

   • В панели чата вы должны увидеть интерфейс для общения с LLM
   • Если панель пустая, проверьте консоль разработчика (Help → Toggle Developer Tools)

Использование

• Активация: Расширение активируется при открытии панели "Chat"
• Интерфейс: Чат-панель в боковой панели VSCode
• Команды: Доступны через контекстное меню файлов и Command Palette

🏗️ Архитектура

Поток данных

Пользователь → Vue App → VSCode Webview → ChatSidebarViewProvider → WebSocket → Backend

Детальное описание потока:

1. Пользователь вводит сообщение в чат-интерфейс
2. Vue App (webview-chat/) обрабатывает пользовательский ввод и отправляет сообщение
3. VSCode Webview передает сообщение из Vue приложения в расширение VS Code
4. ChatSidebarViewProvider (src/features/chat/) получает сообщение и подготавливает его для отправки
5. WebSocket (src/core/websocket/) устанавливает соединение с внешним сервером
6. Backend (внешний сервер) обрабатывает запрос и возвращает ответ
7. Обратный поток: Backend → WebSocket → ChatSidebarViewProvider → VSCode Webview → Vue App → Пользователь

Ключевые компоненты:

• Vue App: Фронтенд интерфейс чата
• Webview: Мост между Vue и VS Code API
• ViewProvider: Управляет состоянием чата и сообщениями
• WebSocket: Сетевое соединение с LLM сервером
• Backend: Внешний сервер с LLM (например, OpenAI API)

🛠️ Разработка

Команды сборки

# Полная сборка (Vue + TypeScript)
npm run build

# Только Vue приложение (автоматически устанавливает зависимости)
npm run build:vue

# Только TypeScript
npm run compile

# Режим разработки (Vue + TypeScript watch)
npm run dev

# Только Vue в режиме разработки
npm run dev:vue

# Отслеживание изменений TypeScript
npm run watch

# Проверка кода
npm run lint

Примечание: Команда npm run build автоматически:

1. Устанавливает зависимости для webview-chat (если нужно)
2. Собирает Vue приложение
3. Компилирует TypeScript код расширения

Режим разработки

Вариант 1 - Простой (рекомендуется):

npm run dev

Эта команда соберет Vue приложение и запустит TypeScript в режиме watch.

Вариант 2 - Раздельный:

1. TypeScript: npm run watch (в одном терминале)
2. Vue: npm run dev:vue (в другом терминале)
3. Отладка: F5 в VSCode

Workflow для разработчиков

1. Создайте feature branch: git checkout -b feature/your-feature-name
2. Внесите изменения в код
3. Выполните проверки: npm run lint && npm run build
4. Создайте Merge Request в GitLab

🐛 Отладка

Типичные проблемы

1. F5 не запускает расширение

   • Убедитесь, что вы находитесь в корневой папке проекта (где находится package.json)
   • Откройте файл src/extension.ts в редакторе
   • Установите Yeoman: npm install -g yo generator-code
   • Перезапустите VS Code

2. WebSocket не подключается

   • Проверьте .env файл
   • Убедитесь, что backend сервер запущен
   • Если бекенд через Docker, то убедитесь что Docker активен

3. Vue приложение не загружается

   • Выполните npm run build
   • Проверьте наличие файлов в media/chat/

4. Команды не работают

   • Проверьте активацию расширения
   • Перезапустите VSCode

Логирование

• WebSocket: Все сообщения логируются в консоль VSCode
• LLM Actions: Результаты действий отображаются в уведомлениях
• Ошибки: Показываются в уведомлениях VSCode

📁 Структура проекта

llm-helper/
├─ src/                     # Исходный код расширения (TypeScript)
│  ├─ commands/             # Регистрация и реализация VS Code команд
│  ├─ core/                 # Базовые абстракции, типы, IPC-контракты
│  │  ├─ api/               # API клиенты и запросы
│  │  ├─ service/           # Базовые сервисы
│  │  ├─ types/             # Общие типы и интерфейсы
│  │  ├─ utils/             # Утилиты
│  │  └─ websocket/         # WebSocket соединение
│  ├─ features/             # Основные функции расширения
│  │  ├─ chat/              # Чат-функциональность
│  │  └─ diff/              # Система сравнения файлов
│  ├─ services/             # Сервисы интеграции
│  ├─ views/                # Создание и управление webview-панелями
│  └─ extension.ts          # Точка входа: activate/deactivate
├─ webview-chat/            # Vue.js приложение для webview
│  ├─ src/                  # Исходный код Vue приложения
│  │  ├─ components/        # Vue компоненты
│  │  ├─ types/             # TypeScript типы
│  │  └─ main.ts            # Точка входа Vue
│  ├─ public/               # Статические ресурсы
│  ├─ index.html            # HTML шаблон
│  ├─ vite.config.ts        # Конфигурация Vite
│  ├─ tsconfig.*.json       # TypeScript конфигурации
│  └─ package.json          # Зависимости Vue приложения
├─ out/                     # Скомпилированный JavaScript (из src/)
├─ media/                   # Статические ресурсы для webview
│  ├─ chat/                 # Собранные файлы Vue приложения
│  └─ icon.svg              # Иконка расширения
├─ package.json             # Основные зависимости и скрипты
├─ tsconfig.json            # TypeScript конфигурация
├─ eslint.config.mjs        # ESLint конфигурация
└─ README.md                # Документация

🔄 Git Workflow

• Главная ветка: main - стабильная версия
• Ветка разработки: dev - основная ветка для разработки
• Фиче-ветки: feature/название-фичи - для новых функций
• Хотфиксы: hotfix/описание-исправления - для срочных исправлений

Workflow:

1. Создайте feature branch от dev
2. Внесите изменения и закоммитьте
3. Создайте Merge Request в GitLab
4. После ревью и тестов - мерж в dev
5. Периодически мерж dev в main для релизов

🔗 Полезные ссылки

• VSCode Extension API
• Vue.js 3
• TypeScript
• WebSocket