# Ручные сценарии расширений Chrome {/* #manual-chrome-extension-scenarios */}

Ручная запись выполняется как административное задание захвата: **Desktop → Web Extension** (Настольная платформа → Web Extension). Внутреннее окружение — `WebExtension`, в метаданных и публичном MCP — `web-extension`. Агент скачивает выбранное расширение Chrome Web Store и открывает одноразовый профиль Chromium с ним и расширением захвата Reconstruct. Оператор выполняет навигацию; Reconstruct сохраняет экраны и наблюдаемые переходы как [`reconstruct.scene.v1`](/docs/ru/data-format).

## Создание и запуск задания {/* #create-and-run-a-job */}

1. В Admin → Jobs → Create (Администрирование → Задания → Создать) выберите **Desktop → Web Extension**. Снимите Web, если нужно только расширение. Мобильные окружения остаются Web, iOS и Android.
2. В Environment Settings → Web Extension (Параметры окружения → Web Extension) вставьте ссылку выбранного расширения Chrome Web Store. Локальные каталоги расширений и личные профили браузеров не принимаются.
3. Поставьте задание в очередь. Его получит включённый Capture Agent с назначением **Desktop / Web Extension**. Обработчики Web и Web Extension не могут получать задания друг друга.
4. Агент скачивает подписанный CRX3 через службу обновления Google и проверяет выбранный ID расширения и подпись издателя перед распаковкой в закрытый каталог задания. При загрузке распакованным пакет сохраняет магазинный ID. Метаданные версии включают `browserExtension` с проверенными ID, локализованным названием, версией пакета и SHA-256; название каталога берётся из пакета. Пути архива, число файлов и размер после распаковки проверяются до использования.
5. Chromium открывает собственную вводную вкладку расширения. Иначе используется объявленная страница параметров или всплывающее окно действия. Расширение без точки входа UI завершается ошибкой.
6. Откройте **Reconstruct Agent Browser Bridge** в меню расширений браузера. Его окно показывает ID активного задания и число сохранённых экранов. Для каждого экрана используйте **Capture screen** (Захватить экран). Там же доступны **Pause** (Пауза), **Resume** (Продолжить) и **Finish recording** (Завершить запись).

Отдельного CLI-рекордера или дополнительного MCP записи запускать не нужно. Управление привязано к активному заданию и закрытому токену локального сеанса; значения полей, произвольные подписи и исходные URL не принимаются. Администраторы также могут наблюдать и управлять браузером в Admin → Jobs → job → **Live browser** (Живой браузер); ввод разрешён только при ожидании оператора. Другое расширение или задание отклоняется. Если расширение открывает другую вкладку, активируйте её перед захватом; перед переключением проверяется её принадлежность. Пароли, создание кошелька, соглашения и регистрация остаются ручными действиями.

## Задания входа и автоматическое исследование {/* #sign-in-jobs-and-automatic-exploration */}

Расширения с первоначальной настройкой, например создание кошелька MetaMask, можно записывать полуавтоматически. В Environment Settings → Web Extension установите **Sign-in** (Вход) в **Operator registers** (Оператор регистрируется) или **Operator signs in** (Оператор входит).

1. Задание ждёт оператора. Завершите настройку в Admin → Jobs → job → **Live browser** или в самом браузере задания. Сохраняйте экраны через **Capture screen**; экраны паролей и фраз восстановления никогда не сохраняются.
2. Выберите **Finish sign-in** (Завершить вход, консоль), **Continue** (Продолжить, Admin) или **Finish sign-in and explore** (Завершить вход и исследовать, окно Reconstruct).
3. Затем Reconstruct посещает всплывающее окно, страницу параметров, боковую панель расширения и маршруты его навигационных элементов, сохраняя экран на маршрут. Он никогда не нажимает элементы, которые могут что-либо отправить, подписать, подтвердить, раскрыть, экспортировать, заблокировать, удалить или создать.
4. Если расширение блокируется, задание ожидает в состоянии **Signed out** (Выполнен выход), пока оператор не разблокирует его и снова не выберет **Finish sign-in**. Когда маршрутов не остаётся или достигнут лимит страниц, запись завершается и загружается на проверку.

Web-задания имеют тот же **Sign-in**: экраны входа сохраняются как этапы, обход пропускает ссылки выхода и приостанавливается при завершении сеанса. CAPTCHA, SMS-коды и принятие условий всегда выполняет оператор. Подробности — в `backend/docs/operator-sign-in.md`.

## Настройка агента {/* #agent-setup */}

Соберите соответствующий адаптер браузера командой `yarn nx run chrome:build` в `backend/agent-browser-extensions`. Хосту нужны Node.js 24+, Python 3 и Chromium с поддержкой расширений. Настройте существующий Capture Agent через игнорируемые локальные параметры или переменные окружения:

```json
{
  "Agent": {
    "Id": "extension-worker",
    "ApiUrl": "https://internal-admin-api.example",
    "ChromiumPath": "/Applications/Chromium.app/Contents/MacOS/Chromium",
    "ExtensionDir": "/checkout/backend/agent-browser-extensions/chrome"
  },
  "WebExtension": {
    "RecorderDirectory": "/checkout/backend/tools/manual-recorder",
    "NodePath": "node",
    "PythonPath": "python3"
  }
}
```

Передайте существующий `ApiTokens:Agent` через секретную конфигурацию. Существующий Web-слушатель Kestrel должен быть loopback. Запустите бинарный Capture Agent с `extension serve`, затем назначьте его запись на **Desktop / Web Extension** в Admin. Каждый режим хоста владеет своим слушателем и блокировкой; не запускайте два обработчика на одной конечной точке. Удалённым обработчикам требуется управляемый изолированный хост браузера и явное `WebExtension:ManagedBrowserIsolated`, поскольку расширения исполняют собственный сетевой и фоновый код. Этот флаг не создаёт изоляцию. Существующий явный `Agent:AllowHttpApi` применяется к loopback API разработки.

Обработчик отвечает за получение заданий, heartbeat, отмену и повторные загрузки. Внутренний дочерний Node использует закрытые межпроцессные каналы без отладочного TCP-порта. Завершение закрывает браузер задания и удаляет временный профиль. Используйте пустой тестовый кошелёк: сценарий не сохраняет учётные данные или пригодный кошелёк.

## Секреты и проверка изображений {/* #secrets-and-image-review */}

Приостановите запись перед вводом паролей, фраз восстановления, ключей и кодов. Возобновите после ухода с чувствительных экранов. Защищённые текстовые экраны безопасно блокируются и создают пробел наблюдения. Редактируемые элементы и потомки маскируются до снимка; значения полей не читаются в Scene. Проверки до и после отклоняют захват при изменении защищённого состояния, маски, навигации или содержимого во время съёмки.

Canvas и другие непрозрачные пиксели остаются видимыми в **закрытых медиа проверки**. Проверки DOM не доказывают отсутствие секретов. Инспекция и маскирование выполняются синхронно в одной операции изолированного мира; JavaScript остаётся включённым для снимка, чтобы нативный canvas мог отрисоваться.

**Finish recording** автоматически упаковывает и загружает результат как неопубликованный захват. Каждая контрольная точка владеет страницей, Scene и снимком. Индекс сценария ссылается на страницы без копирования их текста. В Admin просмотрите каждый снимок в **Hide personal data** (Скрыть персональные данные), размойте чувствительные области или удалите небезопасные медиа и публикуйте после проверки. Скрытие также очищает покрытый текст Scene, доступные имена, повторённые значения и медиассылки. Отдельно сохранённые оригиналы требуют своей проверки. Элементы записи не могут публиковать или возвращать необработанные изображения.

## Реконструкция через MCP {/* #reconstruction-through-mcp */}

После проверки и публикации агенты находят версию в обычном каталоге Capture MCP. Используйте `get_scenario_scene` для загрузки кадров, профилей и переходов, собранных из текущих данных страниц, включая скрытия Admin. Для одобренных изображений используйте обычные инструменты опубликованных страниц. Проверяйте реконструкцию по каждому нужному экрану и профилю; успешные инструменты сами по себе не доказывают визуальную точность.

## Свидетельства и ограничения {/* #evidence-and-limits */}

Контрольные точки — статические наблюдения. Снимайте после навигации, открытия меню, модальностей и другого содержимого, в каждом нужном размере окна. Соседние наблюдения измеряют изменившийся/неизменившийся результат, а не доказывают автоматически выполненный клик. Паузы и блокировки создают явные пробелы. Режим не записывает тайно каждый клик, не воспроизводит регистрацию, не снимает нативные диалоги разрешений ОС и не выводит анимацию из статичных изображений. Секретные шаги остаются ручными и отсутствуют в опубликованном сценарии. Лимит страниц ограничивает контрольные точки (автовыбор по умолчанию — 200); бюджет Scene — 100 000 узлов на задание. Также действуют лимиты времени и элементов.

## Доступность заявок {/* #request-availability */}

В **Admin → Requests → Job defaults → Request submissions** (Администрирование → Заявки → Параметры заданий → Отправка заявок) задайте допустимые пары тип продукта/окружение. По умолчанию: Desktop/Web, Desktop/Web Extension и Mobile/Web. **Allow new requests** (Разрешить новые заявки) закрывает или открывает все новые отправки; сохранение сохраняет выбранные пары и при закрытии. Существующие заявки и опубликованные захваты доступны. Та же сохранённая политика применяется к API и аутентифицированному MCP, включая клиентов с устаревшими вариантами формы. Пока отправка закрыта, точка вариантов не возвращает платформы. Селекторы типа/окружения каталога показывают только захваченные для продукта окружения; доступность заявок не скрывает опубликованные свидетельства.