BrowAI Browser Plugin

Бесплатная lite-версия расширения для браузера Chrome/Edge, которое добавляет AI-ассистента для анализа кода прямо на веб-страницах. Плагин автоматически находит блоки кода и позволяет задавать вопросы о них, не покидая текущую страницу.

🚀 Основные возможности

Автоматическое обнаружение кода

• Автоматически находит блоки кода на любых сайтах (GitHub, Stack Overflow, Habr, Reddit, документация и т.д.)
• Поддерживает различные форматы:
  <pre><code>
  , отдельные теги
  <code>
  , GitHub blob/diff контейнеры
• Добавляет кнопку "Объяснить с BrowAI" к каждому найденному блоку кода

Боковая панель чата

• Удобная боковая панель справа с полнофункциональным чатом
• Показывает контекст выбранного кода с сохранением форматирования
• История диалогов с возможностью создания нескольких бесед
• Переименование и удаление диалогов
• Изменение размера панели перетаскиванием
• Поддержка темной и светлой темы
• Анимация помощника (питомец) во время генерации ответа
• Индикатор скролла для удобной навигации по сообщениям
• Звуковые уведомления о готовых ответах (опционально)

Множественные способы открытия чата

• Кнопка на блоке кода — клик по кнопке "Объяснить с BrowAI" на любом блоке кода
• Плавающая кнопка — кнопка в правом нижнем углу для открытия чата в любой момент (можно отключить в настройках)
• Иконка расширения — клик по иконке плагина в панели инструментов браузера
• Контекстное меню — правый клик по выделенному тексту → "Объяснить выделение с BrowAI"

Голосовой ввод (Salute Speech)

• Распознавание речи через Salute Speech API
• Фраза-триггер для активации распознавания
• Автоотправка после распознавания (опционально)
• Голосовая активация без нажатия кнопки (опционально)

Автоматический анализ ошибок

• Опциональный автоматический анализ ошибок консоли браузера
• Создание диалогов для каждой ошибки
• Уведомления о готовых ответах
• Настраивается в параметрах расширения

Сезонные анимации

• Праздничные эффекты на страницах (можно включить/выключить)
• Декоративные анимации для особых дат

🤖 Поддерживаемые AI провайдеры

LM Studio

• Подключение к локальному серверу LM Studio
• По умолчанию:
  http://127.0.0.1:1234/v1/chat/completions
• Настройка endpoint и имени модели

OpenAI API

• Поддержка официального OpenAI API
• Настраиваемый базовый URL (по умолчанию
  https://api.openai.com/v1
  )
• Выбор модели (по умолчанию
  gpt-4o-mini
  )
• API ключ хранится локально на устройстве

OpenRouter API

• Доступ к множеству моделей через OpenRouter
• Настраиваемый базовый URL
• Опциональный Referer URL
• API ключ хранится локально

Cloud AI Factory

• Поддержка российского облачного сервиса
• По умолчанию:
  https://foundation-models.api.cloud.ru/v1
• Поддержка моделей GigaChat
• API ключ хранится локально

⚙️ Настройки

Основные параметры

• Провайдер — выбор AI провайдера (LM Studio, OpenAI, OpenRouter, Cloud AI Factory)
• Temperature — параметр температуры для генерации (0-2, по умолчанию 0.2)
• Max tokens — максимальное количество токенов в ответе (64-4096, по умолчанию 512)
• System prompt — системный промпт для настройки поведения AI

Интерфейс

• Показывать плавающую кнопку — включение/выключение плавающей кнопки чата на страницах
• Всплывающие уведомления — показывать уведомления когда ответ готов
• Звуковые уведомления — воспроизведение звука при получении ответа
• Автоматический анализ ошибок — автоматически анализировать ошибки консоли
• Сезонные анимации — включение праздничных эффектов на страницах
• Тема чата — выбор темной или светлой темы

Голосовой ввод (Salute Speech)

• Настройка Client ID и Client Secret из личного кабинета Сбера
• Проверка подключения к Salute Speech API
• Настройка фразы-триггера и параметров распознавания

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

Проект полностью реализован на Clean Architecture с четким разделением ответственности:

• Domain Layer — бизнес-логика, entities, use cases, интерфейсы репозиториев
• Application Layer — координация use cases, DTO, сервисы, мапперы
• Infrastructure Layer — реализация репозиториев, провайдеров, утилит, хранилища
• Presentation Layer — UI, контроллеры, фабрики
• Shared Layer — общие константы, ошибки, типы

✅ Рефакторинг завершен — весь код следует принципам Clean Architecture.

Подробнее см. ARCHITECTURE.md.

📦 Установка и сборка

Требования

• Node.js версии 18 или выше
• npm (устанавливается вместе с Node.js)
• Браузер Chrome или Edge (Chromium-based)

Установка Node.js

Вариант A: Через Homebrew (рекомендуется для macOS)

Вариант B: Скачать с официального сайта

1. Перейдите на https://nodejs.org/
2. Скачайте LTS версию для вашей ОС
3. Установите скачанный пакет

Быстрая установка

1. Клонируйте репозиторий:

2. Установите зависимости:

   Это установит:

   • TypeScript
   • @types/chrome (типы для Chrome Extension API)
   • @types/node (типы для Node.js)
   • esbuild (для бандлинга)
   • lottie-web (для анимаций)

3. Соберите проект:

   Или используйте скрипт установки:

   Процесс сборки включает:

   • TypeScript компиляция (
     tsc
     ) - компилирует все
     .ts
     файлы в
     .js
   • Бандлинг (
     esbuild
     ) - объединяет модули content scripts в один файл без
     import/export

4. Загрузите расширение в браузер:

   • Откройте
     chrome://extensions/
     (или
     edge://extensions/
     )
   • Включите "Режим разработчика"
   • Нажмите "Загрузить распакованное расширение"
   • Выберите папку проекта

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

Структура после сборки

После выполнения

dist/
├── background/
│   ├── background.js
│   └── aiProviders.js
├── content/
│   ├── content.js                    # Основной content script
│   ├── chat/                         # Компоненты чата
│   ├── toolbar/                      # Кнопки и плавающая панель
│   ├── settings/                     # Модальные окна настроек
│   ├── voice/                        # Голосовой ввод (Salute Speech)
│   └── seasonal-animations.js        # Праздничные анимации
├── popup/
│   └── popup.js                      # Popup окно расширения
├── options/
│   └── options.js                    # Страница настроек
├── config/
│   ├── defaults.js                   # Конфигурация по умолчанию
│   └── settings.js                   # Управление настройками
├── services/
│   ├── metrics/
│   │   └── metricsService.js
│   └── device.js
├── types/
│   └── index.js                      # Общие типы TypeScript
└── utils/
    ├── chromeRuntime.js              # Безопасные вызовы Chrome API
    ├── debounce.js                   # Debounce утилита
    ├── domHelpers.js                 # Помощники для DOM
    ├── eventBus.js                   # Система событий
    ├── markdown.js                   # Рендеринг Markdown
    └── storage.js                    # Работа с хранилищем

Важно о сборке

• Content scripts объединяются через esbuild в формат IIFE (Immediately Invoked Function Expression)
• Все зависимости включаются в один файл
• Файлы готовы к использованию в Chrome extensions без дополнительной настройки

Решение проблем сборки

Если возникают ошибки типа "Cannot use import statement outside a module":

1. Убедитесь, что выполнили
   npm run build
   (не только
   tsc
   )
2. Проверьте, что файлы в
   dist/content/
   не содержат
   import/export
3. Перезагрузите расширение в Chrome

🛠️ Структура проекта

Проект использует Clean Architecture с разделением на слои:

browser_plugin/
├── src/
│   ├── domain/                      # Domain Layer (Бизнес-логика)
│   │   ├── entities/                 # Сущности (Message, Conversation, Provider, Settings)
│   │   ├── repositories/             # Интерфейсы репозиториев
│   │   ├── use-cases/                # Use Cases (бизнес-логика)
│   │   └── providers/                # Интерфейсы провайдеров
│   │
│   ├── application/                  # Application Layer (Координация)
│   │   ├── dto/                      # Data Transfer Objects
│   │   ├── mappers/                  # Мапперы Entity ↔ DTO
│   │   ├── services/                 # Сервисы приложения
│   │   └── providers/                # Реестр провайдеров
│   │
│   ├── infrastructure/               # Infrastructure Layer (Внешние зависимости)
│   │   ├── storage/                  # Репозитории хранилища
│   │   ├── providers/                # Плагины провайдеров AI
│   │   └── utils/                     # Утилиты инфраструктуры
│   │
│   ├── presentation/                 # Presentation Layer (UI)
│   │   └── content/
│   │       ├── controllers/           # Контроллеры чата и диалогов
│   │       └── factories/             # Фабрики для DI
│   │
│   ├── shared/                       # Shared Layer (Общие компоненты)
│   │   ├── constants/                # Общие константы
│   │   └── errors/                   # Общие классы ошибок
│   │
│   ├── di/                           # Dependency Injection
│   │   ├── Container.ts              # DI контейнер
│   │   └── bindings.ts               # Настройка зависимостей
│   │
│   ├── content/                      # Content Scripts (мигрированы на Clean Architecture)
│   │   ├── chat/                     # Компоненты чата
│   │   ├── settings/                  # Настройки
│   │   ├── toolbar/                   # Кнопки и плавающая панель
│   │   ├── voice/                     # Голосовой ввод (Salute Speech)
│   │   └── ...
│   │
│   ├── background/                   # Background Service Worker
│   ├── popup/                         # Popup окно расширения
│   ├── options/                      # Страница настроек
│   ├── config/                       # Конфигурация (мигрирована)
│   ├── services/                     # Сервисы (мигрированы)
│   ├── types/                        # Типы TypeScript
│   └── utils/                        # Утилиты (централизованы)
│
├── dist/                             # Скомпилированные файлы
├── icons/                            # Иконки расширения
├── manifest.json                     # Манифест расширения
├── package.json                      # Зависимости проекта
├── tsconfig.json                     # Конфигурация TypeScript
└── build-bundle.js                   # Скрипт сборки bundle

Подробнее об архитектуре см. ARCHITECTURE.md.

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

Анализ кода на странице

1. Откройте любую страницу с кодом (GitHub, Stack Overflow и т.д.)
2. Найдите блок кода — на нём автоматически появится кнопка "Объяснить с BrowAI"
3. Нажмите на кнопку — откроется боковая панель с чатом
4. Код автоматически анализируется и отправляется в AI
5. Задайте дополнительный вопрос о коде или просто нажмите Enter для базового объяснения
6. Используйте кнопку "⟳ Повторить" под ответом, если нужно перегенерировать ответ

Анализ выделенного текста

1. Выделите любой текст на странице
2. Правый клик → "Объяснить выделение с BrowAI"
3. Откроется чат с выделенным текстом в контексте

Использование плавающей кнопки

1. Плавающая кнопка появляется в правом нижнем углу страницы
2. Клик по кнопке открывает чат без привязки к конкретному коду
3. Можно задать общий вопрос или начать новый диалог

Голосовой ввод

1. Включите голосовой ввод в настройках
2. Настройте фразу-триггер (по умолчанию "микрофон")
3. В чате скажите фразу-триггер, затем ваш вопрос
4. Речь будет распознана и вставлена в поле ввода
5. При включенной автоотправке сообщение отправится автоматически

Управление диалогами

• Новый диалог — кнопка "＋" для создания новой беседы
• Переименование — кнопка "✎" для изменения названия диалога
• Удаление — кнопка "🗑" для удаления диалога
• Переключение — выпадающий список для выбора активного диалога
• Уведомления — индикатор "●" показывает диалоги с новыми сообщениями

Управление провайдером

• Выбор провайдера — выпадающий список в верхней части панели чата
• Настройки провайдера — кнопка "⚙" для быстрого доступа к настройкам
• Звуковые уведомления — кнопка "🔊/🔇" для переключения звука

🔧 Настройка провайдеров

LM Studio

1. Запустите LM Studio локально
2. В настройках расширения выберите провайдер "LM Studio"
3. Укажите API endpoint (по умолчанию
   http://127.0.0.1:1234/v1/chat/completions
   )
4. Укажите имя модели
5. Сохраните настройки

OpenAI

1. Получите API ключ на platform.openai.com
2. В настройках выберите провайдер "OpenAI API"
3. Укажите базовый URL (по умолчанию
   https://api.openai.com/v1
   )
4. Выберите модель (например,
   gpt-4o-mini
   )
5. Введите API ключ
6. Сохраните настройки

OpenRouter

1. Получите API ключ на openrouter.ai
2. В настройках выберите провайдер "OpenRouter"
3. Укажите базовый URL (по умолчанию
   https://openrouter.ai/api/v1
   )
4. Выберите модель (например,
   openrouter/auto
   )
5. При необходимости укажите Referer URL
6. Введите API ключ
7. Сохраните настройки

Cloud AI Factory

1. Получите API ключ от Cloud AI Factory
2. В настройках выберите провайдер "Cloud AI Factory"
3. Укажите базовый URL (по умолчанию
   https://foundation-models.api.cloud.ru/v1
   )
4. Выберите модель (например,
   ai-sage/GigaChat3-10B-A1.8B
   )
5. При необходимости укажите Referer URL
6. Введите API ключ
7. Сохраните настройки

🔒 Безопасность

• API ключи хранятся только локально на вашем устройстве в
  chrome.storage.local
• API ключи не синхронизируются между устройствами
• Телеметрия не отправляется на сторонние сервисы (используются только провайдеры с API key)
• Все запросы к AI провайдерам идут напрямую с вашего устройства
• Обработка ошибок Extension context invalidated для стабильной работы

🐛 Устранение неполадок

Чат не открывается

• Проверьте, что плагин включен (иконка расширения → переключатель)
• Перезагрузите страницу
• Проверьте консоль браузера на наличие ошибок
• Убедитесь, что расширение не было перезагружено (Extension context invalidated)

Провайдер не отвечает

• Проверьте настройки провайдера в options.html
• Для LM Studio убедитесь, что сервер запущен
• Для API провайдеров проверьте правильность API ключа
• Проверьте сетевое подключение
• Используйте кнопку "⟳ Повторить" для повторной отправки запроса

Кнопки не появляются на коде

• Убедитесь, что плагин включен
• Проверьте, что блок кода достаточно большой (минимум 50 символов или 2 строки)
• Некоторые сайты могут блокировать инъекцию скриптов
• Перезагрузите страницу для повторного сканирования

Голосовой ввод не работает

• Проверьте, что голосовой ввод включен в настройках
• Убедитесь, что Client ID и Client Secret указаны правильно
• Проверьте подключение к Salute Speech API через кнопку "Проверить подключение"
• Убедитесь, что микрофон разрешен в браузере

Сообщения не отображаются

• Проверьте, что выбран правильный диалог
• Попробуйте переключиться на другой диалог и вернуться обратно
• Перезагрузите страницу для восстановления состояния

📚 Документация

Основная документация

• ARCHITECTURE.md — подробное описание Clean Architecture проекта
• API.md — документация API всех слоев архитектуры
• CONTRIBUTING.md — руководство для контрибьюторов

Документация по слоям

• src/domain/README.md — Domain Layer
• src/application/README.md — Application Layer
• src/infrastructure/README.md — Infrastructure Layer
• src/infrastructure/providers/README.md — AI провайдеры
• src/infrastructure/utils/README.md — Утилиты инфраструктуры

Дополнительно

• docs/METRICS.md — метрики и события телеметрии
• docs/plans/, docs/tasks/ — планы и задачи

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

Проверка сборки

После сборки проверьте, что файлы созданы:

Если директория

Структура кода

Проект полностью реализован на Clean Architecture:

• Domain Layer — бизнес-логика, entities, use cases, интерфейсы репозиториев
• Application Layer — координация use cases, DTO, сервисы, мапперы
• Infrastructure Layer — реализация репозиториев, провайдеров, утилит
• Presentation Layer — UI, контроллеры, фабрики, адаптеры
• Shared Layer — общие константы, ошибки, типы

Добавление нового функционала

Добавление нового AI провайдера

1. Создайте класс плагина в
   src/infrastructure/providers/
   , расширяющий
   BaseProviderPlugin
2. Реализуйте методы
   call()
   ,
   validateConfig()
   ,
   getDefaultConfig()
3. Зарегистрируйте в
   ProviderRegistry

Подробнее см. infrastructure/providers/README.md и CONTRIBUTING.md.

Добавление нового use case

1. Создайте класс use case в
   src/domain/use-cases/
2. Добавьте метод в соответствующий сервис в
   src/application/services/
3. Используйте через сервис в контроллерах

📄 Лицензия

Проект распространяется по лицензии, разрешающей свободное использование и распространение. Коммерческая продажа запрещена. Подробности — в файле LICENSE.

🤝 Вклад в проект

Инструкции по установке, стилю кода и процессу разработки — в CONTRIBUTING.md.