Подключение локального браузера и развёртывание

aihelpme.ru через daemon BrowserSkill и расширение браузера BrowserSkill подключает браузер на компьютере пользователя к диалогу интеллектуального рассуждения. Расширение поддерживает Chrome и Microsoft Edge (на базе Chromium 125 и выше); для других браузеров на Chromium совместимость не гарантируется. Браузер работает на компьютере пользователя, а daemon — на стороне приложения aihelpme.ru, песочница навыков не требуется. Для сохранения веб-страниц и вопросов к базам знаний в боковой панели используется другой плагин «Помощник управления знаниями».

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

Расширение требует версии 0.3.1 и выше; установите любым из способов:

• Chrome: Chrome Web Store
• Edge: Надстройки Edge
• Комплектный ZIP: если доступ к магазину невозможен, скачайте его в разделе «Подключение браузера» → «Ручная установка (запасной вариант)». После распаковки откройте chrome://extensions (в Edge — edge://extensions), включите «Режим разработчика» и выберите «Загрузить распакованное расширение».

Если версия подключённого расширения ниже 0.3.1, страница «Подключение браузера» предложит обновиться.

Сопряжение и использование

1. Откройте в боковой панели «Инструментарий → Подключение браузера». Старая ссылка «Настройки → Подключение браузера» автоматически перенаправляет сюда.
2. Скопируйте созданную на странице одноразовую ссылку сопряжения, вставьте её в расширении в «Настройки подключения → Удалённое подключение» и сохраните.
3. В поле интеллектуального рассуждения включите «Локальный браузер» и отправьте задачу. Успешное сопряжение не означает автоматического включения в каждом раунде.
4. При первом вызове создаётся отдельное окно задачи; предпросмотр диалога позволяет найти страницу на экране, приостановить, продолжить или завершить текущую задачу браузера.

Статус подключения отображается на вкладке «Подключение браузера» (подключено, офлайн или не сопряжено). При сопряжении маленький значок браузера справа от «Инструментария» в боковой панели также помечает статус точкой: зелёная — подключено, оранжевая — офлайн. Если это не нужно, на странице «Подключение браузера» можно отключить «Показывать статус подключения в боковой панели»; эта настройка сохраняется только в текущем браузере. На той же странице можно задать «Команду поиска в браузере», указав предпочитаемую поисковую систему и адрес поиска.

Авторизация сохраняется по пространству и пользователю; в пределах одного пространства несколько диалогов используют одну авторизацию устройства, но у каждого своя задача. Сейчас на каждое пространство + пользователя хранится одна авторизация устройства; активация нового устройства заменяет старое.

Ссылка сопряжения действительна пять минут. Токен устройства действует 90 дней и автоматически ротируется через 30 дней; создание новой ссылки не сразу отключает старое устройство — авторизация заменяется только после успешной активации. Отзыв устройства, отключение пользователя или удаление участника пространства блокируют дальнейшее использование.

Участие человека и восстановление задач

Задача может работать с вкладками, созданными ею самой; в окне задачи также можно работать с новыми вкладками, открытыми щелчком или нажатием клавиши и прошедшими проверку источника, при завершении задачи они сохраняются. Отдельные всплывающие окна и вкладки пользователя берутся взаймы через tab_borrow: после подтверждения авторизации согласно настройкам браузера задача работает с ними, а по завершении возвращает через tab_return. При завершении задачи закрываются явно созданные ею страницы, а взятые взаймы — возвращаются.

Ручное перетаскивание в окно задачи не равно авторизации; если неавторизованная страница уже находится в окне задачи, пользователю нужно сначала переместить её в обычное окно, а затем взять взаймы. Запрос на подтверждение займа должен отображаться на HTTP(S)-странице в обычном окне; страницы настроек расширения, новая вкладка и отдельные всплывающие окна не подходят. Если после займа исходное окно исчезло, при возврате может быть создано обычное запасное окно; возвращаемые страницы не закрываются с завершением задачи.

Вход, код подтверждения или шаги авторизации инициируются через request_help. По подсказке в предпросмотре перейдите в браузер и по завершении подтвердите в подсказке помощи в браузере; затем Agent снова наблюдает за страницей и продолжает. Простое «пожалуйста, войдите» в чате не создаст подсказку о ручном вмешательстве. Ожидание помощи длится не более пяти минут; при тайм-ауте или отмене сцена сохраняется и приостанавливается.

Приостановка отменяет текущий вызов браузера, но не отменяет сопряжение; после нажатия «Продолжить», если раунд Agent уже завершён, нужно также отправить команду продолжения. После сбоя или перезапуска сервиса задачи не воспроизводят автоматически щелчки, отправку и другие действия — после восстановления сначала проверьте страницу.

Обычные успешные задачи завершаются автоматически; сцена может сохраняться, когда пользователь просит сохранить страницу, при ручной помощи или аварийном прерывании. Надпись «Последний кадр сохранён» в предпросмотре означает, что опрос сейчас остановлен, но не означает, что управление браузером освобождено. Завершение задачи браузера не равно остановке всего диалога.

Развёртывание одного экземпляра

Комплектный образ приложения содержит daemon, ZIP расширения и лицензию, а также предустановленные пути к файлам; комплектный frontend Nginx обрабатывает WebSocket. При обновлении обновляйте одновременно приложение, frontend и расширение пользователя.

Нативное развёртывание собирается в корне репозитория:

./scripts/build_browserskill.sh

Требуются Git, Node.js, Python 3, Rust/Cargo и компилятор C; в Linux также CMake. Фиксированная версия исходников управляется в scripts/browserskill-release.json: сборка идёт напрямую из upstream-исходников, дополнительные патчи не применяются, результат выводится в artifacts/browserskill/. Используйте daemon для соответствующей ОС и архитектуры и настройте по фактическому пути установки:

BROWSERSKILL_BINARY=/opt/weknora/browserskill/bsk
BROWSERSKILL_EXTENSION_PATH=/opt/weknora/browserskill/browser-skill-weknora-0.3.1.zip
BROWSERSKILL_MAX_CONNECTIONS=32

По умолчанию адрес сопряжения WSS формируется из origin текущей страницы пользователя с сохранением порта. Переопределения задаются только при развёртывании на отдельном домене шлюза или по особому пути:

BROWSERSKILL_PUBLIC_URL=wss://weknora.example.com/api/v1/local-browser/extension

Локально можно использовать localhost WS; для удалённого доступа требуется WSS-сертификат, которому доверяет браузер. Во внутренней сети можно использовать доверенный корпоративный CA. Явное указание BROWSERSKILL_BINARY= отключает возможность; после изменения переменных окружения Docker пересоберите контейнеры командой docker compose up -d app frontend.

Комплектное расширение и daemon нужно обновлять вместе; расширение требует версии 0.3.1 и выше (Chrome Web Store, надстройки Edge или комплектный ZIP). Перезапись исходного каталога распаковки и повторная загрузка сохраняют ID расширения; при переустановке ID меняется, и требуется повторное сопряжение. При распространении сохраняйте BrowserSkill-LICENSE.

Несколько реплик и входной прокси

Все приложения используют общую базу данных; авторизации устройств, аренды подключений и метки прерываний сохраняются в базе данных. Каждое приложение при необходимости запускает общий daemon; другие реплики передают задачи узлу, удерживающему подключение расширения, через подписанный внутренний RPC.

# у каждой реплики своё значение, должен быть прямой адрес этого узла, нельзя указывать адрес балансировщика
BROWSERSKILL_INTERNAL_URL=http://10.0.0.12:8080
# одинаково для всех реплик, передавайте из Secret случайное значение не короче 32 символов
BROWSERSKILL_CLUSTER_SECRET=<shared-random-secret>

В Kubernetes можно составить прямой адрес из Pod IP. Не используйте отдельные файлы SQLite каждой реплики вместо общей базы данных. Внутренний HTTP подходит только для доверенной изолированной сети; при необходимости защитить передачу используйте HTTPS и доверенные сертификаты.

Входной прокси должен:

• пересылать WebSocket Upgrade для /api/v1/local-browser/extension и POST /authorize.
• запрещать доступ к /api/v1/local-browser/internal из публичного входа, разрешая его только между узлами приложения. Комплектный frontend уже отклоняет этот путь; при прямом открытии доступа к приложению или пользовательском Ingress это тоже нужно предусмотреть.
• избегать логирования Authorization, Sec-WebSocket-Protocol и тела запроса авторизации.

Аренда подключения длится 45 секунд и продлевается каждые десять секунд; восстановление после падения узла зависит от истечения старой аренды и отката переподключения расширения. После восстановления сервиса проверьте состояние задач; операции с неизвестным результатом автоматически не воспроизводятся.

Диагностика и приёмка

Симптом	Куда смотреть
Нет комплектного расширения для скачивания или возможность недоступна	Пути к daemon и файлам расширения, права на исполнение, целевая архитектура и версия образа приложения
Подсказка о слишком старой версии расширения	Обновите до 0.3.1 и выше из Chrome Web Store, надстроек Edge или комплектного ZIP, перезапишите каталог распаковки и перезагрузите
Авторизация успешна, но WSS не работает	Публичный адрес/порт, доверенный сертификат, WebSocket Upgrade на внешнем прокси
Устройство подключено, но задача не выполняется	Переключатель этого раунда, не приостановлена ли задача, не ожидает ли она займа вкладки или ручной помощи
Нет подсказки о ручной помощи	Вызвана ли request_help в записи выполнения; не отключена ли ручная помощь в расширении
Сбой после переключения реплики	Общая ли база данных, верен ли прямой адрес узла, общий ли секрет и сетевая политика
Предпросмотр зависает	Скрыта ли страница, сохраняет ли задача последний кадр, конкретный тайм-аут CDP в расширении; предпросмотр — это скриншоты с низкой частотой кадров, а не видео

Значение по умолчанию 32 — предел защиты активных устройств одного узла, а не гарантия пропускной способности. Перед запуском проверьте на целевом кластере сопряжение, переподключение, отзыв, ручную помощь и маршрутизацию между репликами, а также наблюдайте за CPU, RSS, трафиком скриншотов, задержкой RPC и временем переподключения daemon. Точка входа для тестирования на реальном расширении — internal/browserskill/extension_test.go, используется отдельный каталог профиля тестового браузера.