discord-gemini-translator

Регламент разработки Discord Gemini Translator (GEMINI.md)

Данный документ является обязательным регламентом для всех AI-агентов и разработчиков, вносящих изменения в кодовую базу расширения discord-gemini-translator.
Любые модификации кода должны строго соответствовать правилам, ограничениям и стандартам, описанным ниже.

1. Архитектурный контекст и стек технологий

Проект представляет собой браузерное расширение для Google Chrome и Chromium-браузеров (Manifest V3), обеспечивающее двусторонний мгновенный перевод чата и синхронные субтитры голосовых каналов в веб-версии Discord (https://discord.com/*).

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

  1. manifest.json: Описание расширения MV3, права (storage), host_permissions для Discord и Google Generative Language API.
  2. background/background.js (Service Worker):
    • Взаимодействие с Google Gemini API по REST (/v1beta/models/...:generateContent).
    • Потоковое WebSocket-соединение с Gemini Multimodal Live API (wss://generativelanguage.googleapis.com/...).
    • Локальный LRU-кэш переводов в chrome.storage.local.
    • Фильтрация текстовых (filterValidModels) и голосовых (filterLiveModels) моделей.
  3. content/content.js (ISOLATED World):
    • Внедрение элементов интерфейса в Discord DOM (кнопки перевода, оверлей субтитров, карточки перевода, бейдж выбора языка).
    • Наблюдение за сообщениями через оптимизированный MutationObserver.
    • Интеграция с редактором ввода Slate.js (replaceSlateText).
    • Локализация интерфейса контентного скрипта (CONTENT_I18N).
  4. content/inject.js (MAIN World):
    • Запускается в главном контексте страницы для прямого доступа к WebRTC (RTCPeerConnection.prototype.addTrack, ontrack, AudioContext).
    • Перехват входящего звука голосового канала.
    • Встроенный локальный Voice Activity Detection (VAD) для отсечения тишины и экономии квот.
    • Даунсэмплинг звука в PCM 16kHz (16-bit Mono Little-Endian) и передача чанков в content.js через window.postMessage.
  5. popup/ (Popup Window):
    • Окно настроек (popup.html, popup.css, popup.js).
    • Валидация и локальное хранение API-ключа.
    • Двуязычный интерфейс (RU/EN) на атрибутах data-i18n.

2. СТРОГО ЗАПРЕЩЕНО (⛔ Forbidden / Red Flags)

  1. ⛔ ХАРДКОД СТРОК ИНТЕРФЕЙСА НА ОДНОМ ЯЗЫКЕ:
    • Запрещено добавлять в popup/popup.html любые видимые текстовые элементы без атрибута data-i18n или data-i18n-title.
    • Запрещено присваивать статические строки на русском/английском языке в свойства DOM (textContent, title, placeholder, innerHTML, alert) в обход словарей (CONTENT_I18N и translations).
    • Запрещено наличие кириллических символов в английских словарях (translations.en и CONTENT_I18N.en).
    • Запрещено приписывать статус текстом к кнопке (например, делать Авто (ВКЛ) или Voice\n(ON)). Активный статус отображается строго через CSS-класс .active, цвет, иконку и подсказку title.
  2. ⛔ ВНЕДРЕНИЕ СБОРОЧНЫХ ИНСТРУМЕНТОВ И npm-РАНТАЙМ-ЗАВИСИМОСТЕЙ:
    • Запрещено добавлять Webpack, Rollup, Vite, Babel, TypeScript или зависимости в package.json, требующие этапа build для запуска расширения. Расширение должно загружаться напрямую из папки в chrome://extensions.
  3. ⛔ ПРЯМАЯ МОДИФИКАЦИЯ РЕДАКТОРА DISCORD ЧЕРЕЗ .value ИЛИ .innerText:
    • Discord использует Slate.js / React. Прямое присвоение ломает внутреннее дерево состояний редактора.
    • Обязательно использовать функцию replaceSlateText с эмуляцией событий beforeinput, выделением Range и document.execCommand('insertText').
  4. ⛔ НЕСКОУПЛЕННЫЕ CSS-СТИЛИ:
    • Все стили расширения обязаны начинаться с префикса dgt- (Discord Gemini Translator), например: .dgt-btn, .dgt-overlay, .dgt-badge.
    • Запрещено модифицировать нативные селекторы Discord (button, div, .channelTextArea, .slateTextArea и т.д.) без контекста родительских элементов расширения.
  5. ⛔ УТЕЧКА МЫСЛЕЙ МОДЕЛИ (THOUGHT LEAKS) И ЗАДЕРЖКИ РАССУЖДЕНИЙ:
    • Для моделей серии Gemini 2.5 Flash в REST-запросах обязательно отключать бюджет размышлений: thinkingConfig: { thinkingBudget: 0 }, чтобы перевод происходил за 200–400 мс без лагов.
    • В Live API обязательно отфильтровывать фрагменты с флагом thought: true — технические мысли не должны попадать в субтитры пользователю.
  6. ⛔ УТЕЧКА API-КЛЮЧЕЙ И ПРИВАТНЫХ ДАННЫХ:
    • API-ключ Gemini хранится строго в chrome.storage.local.
    • Запрещено передавать ключ на любые сторонние серверы, прокси или эндпоинты аналитики. Единственный разрешённый сетевой адресат — generativelanguage.googleapis.com.
  7. ⛔ БЕСКОНЕЧНЫЕ ЦИКЛЫ В MUTATIONOBSERVER:
    • Все создаваемые расширением плашки и блоки перевода должны маркироваться специальными классами (dgt-translated, dgt-auto-translated, dgt-reverse-box).
    • Обработчик мутаций обязан проверять наличие этих классов и не запускать повторный перевод собственных элементов.
  8. ⛔ ИГНОРИРОВАНИЕ ПАДАЮЩИХ ТЕСТОВ:
    • Нельзя завершать работу агента, если npm test возвращает хотя бы 1 ошибку. Тесты не «отключаются» и не «комментируются» — код обязан им соответствовать.

3. ОБЯЗАТЕЛЬНЫЕ СТАНДАРТЫ И ТРЕБОВАНИЯ (✅ Requirements)

3.1. Интернационализация (i18n)

3.2. Интеграция со Slate.js и Discord UI

3.3. Gemini API и Gemini Live Audio

3.4. Дизайн, стили и UX

4. РЕГЛАМЕНТ ТЕСТИРОВАНИЯ (🧪 Testing Protocol)

  1. Фреймворк: Нативный Node.js test runner (node:test + node:assert/strict).
  2. Файлы тестов: Размещаются в директории tests/*.test.js.
  3. Обязательные тесты:
    • tests/i18n-no-hardcode.test.js — аудит локализации, предотвращение хардкода, проверка DOM-присвоений.
    • tests/background.test.js — логика Service Worker, REST-запросы, кэширование, обработка ошибок.
    • tests/content.test.js — интеграция с чатом, селекторы, замена текста Slate.
    • tests/inject-audio.test.js — аудиоконвертер, VAD, PCM 16kHz, Base64.
    • tests/live-captions.test.js — парсинг событий WebSocket Live API, отсечение размышлений, сборка предложений.
    • tests/popup.test.js — фильтрация моделей, валидация настроек.
  4. Правило запуска: Перед тем как объявить задачу выполненной, агент ОБЯЗАН выполнить команду: 
    npm test

    и убедиться, что результат равен 100% pass (0 fail).

5. ЧТО РАЗРЕШЕНО И ПРИВЕТСТВУЕТСЯ (💡 Allowed & Encouraged)

6. ЧЕКЛИСТ ПЕРЕД ЗАВЕРШЕНИЕМ ЗАДАЧИ (Definition of Done)

Прежде чем вернуть ответ пользователю, агент обязан проверить:

This site is open source. Improve this page.