mokosh/README.md

Mokosh — Session Capture

Chrome MV3 extension that records operator sessions for bug reports.

Фаза 1 — Локальная запись + экспорт архива

Установка и запуск

Разработка

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

# Сборка для разработки с HMR
npm run dev

# Сборка для продакшена
npm run build

Установка расширения в Chrome

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

   npm run build
   

2. Откройте Chrome и перейдите по адресу: chrome://extensions/

3. Включите "Режим разработчика" (Developer mode) в правом верхнем углу

4. Нажмите кнопку "Загрузить распакованное расширение" (Load unpacked)

5. Выберите папку dist в корне проекта

6. Расширение установлено!

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

1. При первом открытии popup расширение запросит разрешение на запись экрана

2. Разрешение обязательно для работы расширения

3. Расширение автоматически начнет запись:

   • Видео: последние 30 секунд (кольцевой буфер)
   • DOM-события через rrweb: последние 10 минут
   • Лог действий пользователя: последние 10 минут

4. Для сохранения отчета об ошибке:

   • Нажмите на иконку расширения
   • Нажмите кнопку "Сохранить отчёт об ошибке"
   • Архив автоматически загрузится в папку "Загрузки"

Структура архива

Архив session_report_YYYY-MM-DD_HH-MM-SS.zip содержит:

session_report_2025-05-15_14-32-10.zip
├── video/
│   └── last_30sec.webm         # склеенные чанки видеобуфера
├── rrweb/
│   └── session.json            # массив DOM-событий rrweb
├── logs/
│   └── events.json             # лог действий пользователя
├── screenshot.png              # скриншот в момент сохранения
└── meta.json                   # метаданные сессии

Технический стек

• Тип расширения: Chrome Extension, Manifest V3
• Service Worker: Background script (Manifest V3)
• Захват экрана: chrome.tabCapture API
• Захват DOM: rrweb (npm: rrweb)
• Лог событий: Content Script
• Упаковка архива: JSZip (npm: jszip)
• Сохранение файла: chrome.downloads API
• Хранение буфера: In-memory (Service Worker + Content Script)
• Build: Vite + crxjs + TypeScript

Особенности

Маскирование чувствительных данных

• Пароли (input[type=password]) маскируются автоматически в rrweb и логах
• Поля с атрибутом data-sensitive="true" также маскируются в rrweb

Записываемые события

Пользовательские события

• click — клик по любому элементу
• input — изменение значения поля (без паролей)
• navigation — переходы по страницам (popstate, hashchange, History API)
• js_error — JavaScript ошибки (window.onerror, unhandledrejection)
• network_error — сетевые ошибки (fetch/XHR с кодом ответа >= 400)

Кольцевой буфер

• Видео: 30 секунд, первый чанк (WebM заголовок) хранится всегда
• rrweb события: 10 минут, максимум 5000 событий
• Пользовательские события: 10 минут

Память

• Ожидаемое потребление: ~5-10 МБ в фоновом режиме

Критерии приёмки Фазы 1

• ✅ Расширение устанавливается в Chrome без ошибок
• ✅ Видеобуфер непрерывно работает на любой вкладке
• ✅ В буфере всегда есть не более 30 секунд видео
• ✅ rrweb пишет DOM-события без ошибок на типовых страницах
• ✅ Лог событий фиксирует клики, навигацию и сетевые ошибки
• ✅ При нажатии кнопки архив скачивается в "Загрузки" за < 5 секунд
• ✅ Архив открывается, last_30sec.webm воспроизводится в браузере
• ✅ Пароли не попадают в лог и rrweb-снимки
• ✅ RAM-потребление расширения не превышает 50 МБ в фоне

Отладка

Console Logs

Расширение пишет подробные логи в консоль:

• Service Worker: Chrome DevTools → Extensions → Service Worker → Console
• Content Script: Chrome DevTools на любой странице → Console
• Popup: Правый клик по popup → Проверить

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

ai-call-extension/
├── src/
│   ├── background/          # Service Worker
│   │   └── index.ts
│   ├── content/            # Content Script
│   │   └── index.ts
│   ├── popup/              # Popup UI
│   │   ├── index.html
│   │   ├── index.ts
│   │   └── style.css
│   └── shared/             # Общие типы и утилиты
│       ├── types.ts
│       └── logger.ts
├── icons/                  # Иконки расширения
├── dist/                   # Собранные файлы
├── manifest.json           # Manifest расширения
├── vite.config.ts          # Конфигурация Vite
├── tsconfig.json           # Конфигурация TypeScript
└── package.json

Лицензия

MIT

Контакты

Для вопросов и предложений обращайтесь в support.