Passer au contenu principal
D

dsh-plugin-agent-browser

d3d-root/dsh-plugin-agent-browser

A real browser in the DeepSeek Harness right sidebar — one per chat, driven by agent tools

Installer

dsh plugin --profile web add github:d3d-root/dsh-plugin-agent-browser

README

Браузер агента для DeepSeek Harness

Настоящий Chromium в правой панели DSH: свой у каждого чата, с управлением из инструментов агента. Пользователь и агент работают в одном и том же окне — агент кликает, а вы видите результат и можете вмешаться.

  • Один чат — один браузер. Открыли браузер в двух чатах — получили два независимых Chromium с разными cookie и разными логинами.
  • Два агента одновременно. Каждый инструмент адресуется сессии своего агента, поэтому агенты не перехватывают команды друг друга.
  • Видно человеку. Это не headless и не трансляция картинки: <webview> с нативной прокруткой, вводом и кликами.
  • Капчи решаются. Есть настоящие события мыши Chromium и «человеческая» траектория перетаскивания для слайдер-пазлов.
  • Ставится в один клик из списка плагинов DSH: плагин оформлен как бандл.

Содержание

Дополнительно: подробная установка · история версий · план развития · как устроено внутри · сравнение с MCP · как выложить свою версию


Как это выглядит

В правой панели появляется вкладка «Браузер агента»: адресная строка, кнопки навигации и сам сайт. В заголовке вкладки — имя открытой страницы, в адресной строке справа — короткая подпись чата, чтобы не путать браузеры, когда их открыто несколько.

Браузер агента в правой панели DSH

┌──────────────────────────────────────────────┬───────────────────────────┐
│  Чат с агентом                               │ ← ↻ ⌂ [адрес]    чат 3f2a… │
│                                              │───────────────────────────│
│  Агент: открываю страницу и ищу товар…       │                           │
│                                              │      настоящий сайт       │
│                                              │      (Chromium)           │
└──────────────────────────────────────────────┴───────────────────────────┘

Установка

Способ 1: через интерфейс DSH (рекомендуется)

  1. Откройте боковую панель DSH → Plugins.

  2. Нажмите Add plugin.

  3. Вставьте имя пакета:

    dsh-plugin-agent-browser
    
  4. Дождитесь установки и включите плагин переключателем.

  5. Полностью перезапустите DSH — выйдите из приложения и запустите заново.

Этот способ даёт кнопку обновления в списке плагинов: DSH сверяет версию с реестром и предлагает новую в один клик.

Способ 2: из GitHub

Если не хотите зависеть от npm. В Add plugin вставьте адрес репозитория

https://github.com/d3d-root/dsh-plugin-agent-browser

Можно указать и абсолютный путь к скачанной папке плагина.

У этого способа кнопки обновления нет — обновляться нужно командой (см. Обновление).

Способ 3: через терминал

Если интерфейс не подходит — например, настраиваете DSH скриптом:

$Dsh = "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd"

# из npm (появится кнопка обновления)
& $Dsh plugin --profile desktop add "dsh-plugin-agent-browser"

# либо из GitHub
& $Dsh plugin --profile desktop add "github:d3d-root/dsh-plugin-agent-browser"

Затем полностью перезапустите DSH — выйдите из приложения и запустите заново.

Плагин объявляет dsh.bundle.patch, поэтому менеджер плагинов принимает его как бандл и сам добавляет в dsh.profile.bundles профиля.

Почему нужен полный перезапуск. Серверная половина плагина подхватывается на лету, а клиентская входит в сборку страницы только при её загрузке. Плагин сообщает об этом сам: через 7 секунд в правом нижнем углу появляется баннер с кнопкой «Перезагрузить», а browser_status прямо пишет, что делать. Если баннера нет — значит всё загрузилось.

Подробная инструкция со всеми вариантами и разбором проблем — в docs/install.md.

Проверка, что всё встало

Спросите агента:

открой example.com и покажи заголовок

Или проверьте журнал — в нём должна быть строка клиент подключён: окон 1:

Get-Content "$env:TEMP\dsh-agent-browser.log" -Tail 5

Обновление

Версию видно в browser_status (строка «Версия плагина») и в журнале.

Есть два способа установки, и обновляются они по-разному:

Как поставленКак обновляется
из npm — dsh plugin add dsh-plugin-agent-browserкнопка в списке плагинов, в один клик
из GitHub — dsh plugin add github:d3d-root/…командой ниже

Кнопку обновления DSH показывает только для пакетов из реестра: он сверяет версию с npm и предлагает новую. Это не «молча поставилось», а «при открытии списка плагинов видно, что вышла новая версия». После обновления нужен перезапуск приложения.

Для установки из GitHub — одна команда, она переустановит плагин с последнего коммита и покажет смену версии:

$Dsh = "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd"
& $Dsh plugin --profile desktop add "github:d3d-root/dsh-plugin-agent-browser"

Переход с GitHub на npm — одна переустановка, после неё появится кнопка:

& $Dsh plugin --profile desktop add "dsh-plugin-agent-browser"

Подробности и откат — в docs/install.md, история версий — в CHANGELOG.md.

Пакет: https://www.npmjs.com/package/dsh-plugin-agent-browser


Инструменты агента

Плагин регистрирует 35 инструментов. Все они работают с браузером того чата, в котором вызваны.

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

ИнструментЧто делает
browser_openоткрыть вкладку в этом чате (первый вызов)
browser_revealпоказать вкладку на экране, не меняя получателя команд
browser_closeзакрыть вкладку этого чата
browser_close_idleзакрыть вкладки, которые давно не получали команд
browser_tabsсписок всех браузеров во всех чатах и какой из них ваш
browser_statusдоступен ли браузер и какая страница открыта
browser_traceпоследние команды с длительностями — для разбора «не работает»

Навигация и чтение

ИнструментЧто делает
browser_navigateоткрыть адрес, дождаться загрузки
browser_readадрес, заголовок и видимый текст страницы
browser_htmlHTML страницы (для разбора структуры)
browser_evalвыполнить JavaScript и вернуть результат
browser_back / browser_forwardназад / вперёд
browser_reloadобновить страницу
browser_waitждать селектор или текст (или просто пауза)
browser_scrollпрокрутить страницу
browser_page_stateдиагностика: origin, готовность, cookie, прокрутка
browser_find_in_pageпоиск по тексту как Ctrl+F, с подсветкой
browser_zoomмасштаб страницы

Действия

ИнструментЧто делает
browser_clickклик по видимому тексту элемента
browser_click_atклик в точке (синтетическое событие)
browser_mouse_clickклик настоящим событием Chromium
browser_typeввести текст в поле, при желании отправить форму
browser_keyнажать клавишу (Enter, Escape, Tab, стрелки…)
browser_find_allпронумерованный список элементов по селектору или тексту
browser_click_indexклик по номеру из browser_find_all
browser_extractмассив объектов по CSS-селекторам — таблицы и карточки
browser_downloadскачать файл в рабочий каталог; тип определяется по содержимому
browser_uploadприкрепить файлы в input[type=file]

Капчи и картинки

ИнструментЧто делает
browser_screenshotскриншот в PNG (видимой области, области или всей страницы)
browser_dragперетаскивание с человеческой траекторией (слайдер-пазлы)
browser_set_uaподменить User-Agent на обычный Chrome
browser_pdfсохранить страницу в PDF

Вход и сессии

ИнструментЧто делает
browser_save_sessionсохранить cookie и localStorage сайта между перезапусками
browser_restore_sessionвернуть сохранённое состояние входа
browser_storage_clearзабыть все сохранённые входы

browser_screenshot и browser_download пишут файл только в папку скриншотов и рабочий каталог сессии — см. Безопасность. Относительный путь считается от рабочего каталога чата.

Синтаксис browser_extract

fields — это «имя поля → что взять у строки». Три формы:

ЗначениеЧто вернёт
""текст самой строки (карточки)
"@href"атрибут href у самой строки
".title"текст вложенного элемента
"a@href"атрибут href у вложенного элемента

Пример — карточки товаров одним проходом:

{
  "selector": ".card",
  "fields": { "title": ".title", "price": ".price", "link": "a@href" }
}

Настройка

Все поля необязательны. Правятся в config записи плагина (в профиле это cordis.patch.yml, в UI — настройки плагина).

ПолеПо умолчаниюСмысл
startUrlhttps://www.google.comстартовая страница новой вкладки
languageautoязык подписей: auto, ru, en
focusOnOpenfalseоставлять ли чат агента на экране. false — экран возвращается пользователю
autoOpentrueоткрывать вкладку автоматически, если её нет
allowChatSwitchtrueразрешать ли кратко показать чат, чтобы создать вкладку. Один раз на чат
idleTabTimeoutMs900000 (15 мин)через сколько закрывать вкладку без команд. 0 — не закрывать
maxTabs8сколько вкладок держать одновременно. 0 — без предела
userAgentChrome 152 / WindowsUA для browser_set_ua
timeoutMs30000сколько ждать ответа браузера на команду
openTimeoutMs20000сколько ждать готовности только что открытой вкладки
port0порт резервного сервера (0 — любой свободный)
debugtrueписать отладочный журнал
tracefalseписать в журнал каждую команду с длительностью
logFileвременная папкасвой путь журнала

Пример:

- insert:
    - id: agent-browser
      name: dsh-plugin-agent-browser
      config:
        startUrl: https://duckduckgo.com
        language: ru
        # Не выдёргивать пользователя из его чата
        focusOnOpen: false
        # Закрывать вкладки через 10 минут без работы
        idleTabTimeoutMs: 600000

Как это устроено

Плагин состоит из трёх частей и одного общего моста.

┌──────────────────────────── DSH ────────────────────────────┐
│                                                             │
│  Хост (Node)                        Клиент (браузер)        │
│  ┌────────────────────┐             ┌─────────────────────┐  │
│  │ lib/index.js       │             │ lib/client.js       │  │
│  │ 35 инструментов    │             │ панель + сторож     │  │
│  └─────────┬──────────┘             └──────────┬──────────┘  │
│            │ HTTP                              │ HTTP        │
│            └──────────► lib/bridge.mjs ◄───────┘             │
│                        маршрутизация по сессии              │
│                              │                               │
│                    ┌─────────┴──────────┐                    │
│                    │ <webview> сессии A │  свой Chromium     │
│                    │ <webview> сессии B │  свой Chromium     │
│                    └────────────────────┘                    │
└─────────────────────────────────────────────────────────────┘

Почему мост, а не прямой вызов. Инструмент выполняется в хосте (Node), а браузер живёт в окне (Chromium). Это разные процессы, поэтому между ними нужен транспорт. Мост — тонкий маршрутизатор: он держит список панелей, знает их сессии и передаёт команды длинным опросом.

Транспорт. Основной путь — маршрут /dsh-agent-browser на встроенном веб-сервере DSH: тот же origin, что у страницы, никаких портов и CORS, два окна DSH не конфликтуют. Если встроенного сервера нет (окно открыто через file://), плагин поднимает собственный сервер на 127.0.0.1 и сообщает клиенту адрес через index.html.

Как инструмент узнаёт свой чат. У каждого вызова инструмента есть exec.agent.id — идентификатор сессии. Хост передаёт его мосту, мост выбирает панель этой сессии. Поэтому два агента в разных чатах не мешают друг другу.

Как открывается вкладка в фоне. Вкладку можно создать только в сессии, чей store правой панели уже создан, а создаётся он при показе чата. Для уже показанного чата плагин использует openTabIn — вкладка появляется в фоне, и экран не трогается вовсе. Для чата, который ни разу не открывали, store ещё нет: плагин показывает этот чат ровно до готовности store, возвращает вас обратно и создаёт вкладку уже в фоне. Это происходит один раз на чат за запуск приложения — дальше store существует, и переключений больше нет.

Если не нужно даже это, поставьте allowChatSwitch: false: тогда в неоткрытом чате браузер не создастся, и плагин попросит открыть чат вручную.

Изоляция между чатами. Каждая вкладка принадлежит своему чату навсегда: ключ панели на мосте — чат::tab2 (DSH нумерует вкладки счётчиком на каждую сессию, поэтому tab2 есть в каждом чате). Команда без определённой сессии отклоняется, а не уходит в чужой браузер.

Уборка вкладок. Каждая вкладка — отдельный процесс Chromium. Раз в минуту плагин смотрит, у кого давно не было команд, и закрывает такие вкладки в фоне, не трогая экран. Порог — idleTabTimeoutMs (15 минут), предел одновременных — maxTabs (8). Закрыть вручную: browser_close_idle.

Почему у чатов разные профили. Ключ аренды <webview> — это строка workspace: один и тот же ключ даёт общий профиль Chromium, разные ключи — изолированные. Плагин берёт ключ dsh-agent-browser:<id сессии>, поэтому у каждого чата свои cookie и свои логины.


Чем отличается от MCP

Оба способа дают агенту инструменты, но браузер живёт в разных местах.

Этот плагинMCP-сервер (например, @playwright/mcp)
Где браузер<webview> внутри DSHотдельный процесс вне DSH
Видит ли человекда, и может вмешатьсяобычно да, но это чужое окно
Помочь с капчейчеловек кликает в том же окнетолько через отдельный Live View
Свой браузер на чатда, из коробкинужно поднимать отдельные контексты
Изоляция cookieпрофиль на сессиюзависит от флагов сервера
Установкаплагин DSHNode + браузер + конфиг MCP
Доступ к UI DSHда (открыть панель, переключить чат)нет
Стоимость контекста35 компактные схемысвои схемы + большие снимки страниц

Когда MCP лучше: нужна трассировка, PDF, мокинг сети, запись видео — то, чего здесь нет; или браузер нужен не только DSH, но и другим клиентам.

Когда этот плагин лучше: нужен видимый человеку браузер, совместная работа «агент + человек», несколько чатов с разными профилями, решение капч.

Подробный разбор с источниками — в docs/mcp-vs-plugin.md.


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

Что сделано, чтобы мост не стал дырой:

  • Только этот компьютер. Маршрут отклоняет запросы, пришедшие не с loopback-адреса. Даже если DSH слушает сеть, мост снаружи недоступен.
  • Токен. Каждый запуск генерирует случайный токен; он передаётся только в заголовке x-agent-browser-token. В строке запроса токена нет — иначе он попадал бы в журналы и историю.
  • Предел тела запроса — 8 МБ. Иначе один запрос мог бы съесть память.
  • CORS не звёздочка. Резервный сервер отвечает access-control-allow-origin: null (origin страницы на file://), а не *.
  • Запись скриншотов ограничена папкой скриншотов и рабочим каталогом сессии: инструмент пишет файл напрямую, минуя файловую политику DSH, поэтому сам проверяет путь и не даёт перезаписать чужой файл.
  • Навигация только по http/https. <webview> в DSH запрещает переходы на file:// и другие схемы, а также на хост самого DSH.
  • Хостовое скачивание не ходит на локальные адреса. Запасной путь через процесс DSH обходит CORS, а значит, обошёл бы и запрет <webview> обращаться к служебным сервисам. Поэтому 127.0.0.1, localhost, частные сети и link-local (169.254.*) на этом пути запрещены — такие файлы забирает сама страница, если ей это разрешено.

Чего сознательно нет:

  • Плагин не отключает проверки безопасности Electron: nodeIntegration, contextIsolation, sandbox остаются штатными.
  • Инструмент browser_eval исполняет произвольный JS на открытой странице. Это его смысл, но помните: страница получает то, что вы ей передали, а ответ уходит модели.

Диагностика

Журнал плагина:

%TEMP%\dsh-agent-browser.log

Что смотреть:

  • мост готов: http://… — транспорт поднялся, адрес рабочий;
  • транспорт не поднялся: … — обычно нет веб-сервера и занят порт;
  • панель подключилась: … (сессия …) — браузер нашёл мост;
  • webview готов: … (чат …) — Chromium запустился.

Частые проблемы:

СимптомПричина и что делать
«клиентская половина не загружена»плагин включили уже после запуска приложения — перезапустите DSH целиком
Баннер в углу «Плагин загружен не полностью»то же самое; в баннере есть кнопка «Перезагрузить»
«в этой сессии браузер не открыт»вызовите browser_open
«браузер доступен только в приложении DSH»открыто как веб-страница, а не в приложении
Всё было хорошо, потом пересталоперезапустите DSH: мост живёт в процессе
DSH вообще не открывается, экран ошибкисм. ниже «DSH не открывается» — это база cookies, есть скрипт

Ctrl+R помогает не всегда: Electron может отдать ту же закэшированную сборку. Надёжный способ — закрыть приложение и запустить заново.

Почему иногда нужен перезапуск

Плагин состоит из двух половин: серверной (в процессе DSH) и клиентской (в окне). Серверная подхватывается на лету, а клиентская входит в сборку страницы только при её загрузке. Если включить плагин, не перезапуская приложение, серверная половина уже работает, а клиентской в открытом окне ещё нет.

Плагин сообщает об этом сам, тремя способами:

  • баннером в правом нижнем углу — он появляется через 7 секунд после загрузки окна, если клиентская половина не отметилась. В баннере есть кнопка «Перезагрузить» (быстрая попытка) и совет перезапустить приложение;
  • ответом инструментов — browser_status различает «мост не поднялся» и «клиент не загружен» и пишет, что именно делать;
  • строкой в журнале через 20 секунд после старта.

Клиент умеет забирать токен моста сам (через /bootstrap), поэтому рассинхрон лечится перезапуском, а не переустановкой плагина.

DSH не открывается: «Web authentication failed»

Это не проблема плагина, но с ним легко столкнуться, потому что установка и настройка требуют перезапусков. Симптом: вместо рабочего окна — экран ошибки, а в журнале:

%APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*.log
  Error: desktop welcome: Web authentication failed

Причина: каждый запуск DSH поднимает локальный сервер на новом порту и добавляет служебную cookie для 127.0.0.1. Старые записи не удаляются. Когда их набирается много (порядка 70), авторизация при старте перестаёт проходить. Переустановка той же версии не помогает: файлы приложения целы, дело в базе cookies.

Лечится скриптом в комплекте — он закрывает только эту проблему:

# посмотреть, что найдено, ничего не меняя
.\scripts\fix-dsh-start.ps1 -Check

# починить (DSH должен быть закрыт)
.\scripts\fix-dsh-start.ps1

# вернуть как было
.\scripts\fix-dsh-start.ps1 -Restore

Скрипт удаляет только служебные cookies 127.0.0.1 и localhost. Cookies сайтов, задачи, настройки, провайдеры и плагины остаются нетронутыми. Перед изменением он делает резервную копию базы и печатает её SHA-256, после — проверяет целостность (quick_check) и отказывается работать, если DSH ещё запущен.

Профилактика: не перезапускайте DSH без необходимости. Обычная перезагрузка страницы (Ctrl+R) для плагина часто бесполезна, но и не копит cookies; полный перезапуск приложения — копит.


Разработка

# тесты моста (без сети и без DSH)
npm test

# проверка синтаксиса
node --check lib/index.js
node --check lib/bridge.mjs

Структура:

lib/bridge.mjs    маршрутизация команд по сессиям, транспорт, лимиты
lib/index.js      хост: инструменты, конфиг, журнал, маршрут на веб-сервере
lib/client.js     клиент: панель <webview>, сторож открытия вкладок
lib/download.mjs  запасное скачивание силами хоста (когда странице мешает CORS)
test/             тесты: мост, инструменты, клиентский код, скачивание
docs/install.md   подробная установка и разбор проблем
docs/architecture.md  как устроено внутри
docs/mcp-vs-plugin.md сравнение с MCP-браузерами
docs/publishing.md    как выложить свою версию

Тесты покрывают именно то, что чаще всего ломается: маршрутизацию по сессиям, выбор панели, длинный опрос, управляющие команды и защиту транспорта. Отдельно проверяется слой инструментов (текст ответа, который видит модель) и код, который уезжает в страницу — на нём держатся browser_extract и browser_drag.


Ограничения

  • Нужно приложение DSH (Electron): в обычном браузере <webview> недоступен, и панель честно об этом скажет.
  • Профили браузеров живут в памяти процесса: после перезапуска DSH cookie теряются. Это цена изоляции — см. docs/architecture.md. Сохранить вход конкретного сайта можно вручную: browser_save_session, вернуть — browser_restore_session.
  • Одна вкладка на чат по умолчанию; несколько вкладок в одном чате возможны, но команды идут в видимую (или в ту, что указана в tabId).
  • browser_find_in_page в Electron 44 не может опереться на встроенный поиск Chromium: webview.findInPage() не присылает found-in-page (electron#54199). Плагин ждёт событие 400 мс и затем считает совпадения сам, подсвечивая первое через window.find. Число совпадений верное, подсветка — только первого.
  • browser_screenshot в фоне: Chromium не отрисовывает скрытую вкладку, поэтому снимок может не получиться. Если вкладка только что вышла на экран, инструмент повторяет съёмку сам (до трёх раз); если она действительно скрыта — отвечает об этом прямо и просит browser_reveal, вместо того чтобы висеть до таймаута.
  • browser_download сначала забирает файл через fetch внутри страницы (так обходится запрет на скачивания в Electron и сохраняется вход пользователя). Если сайт запрещает чтение с чужого origin (CORS), файл забирает хост — но уже без cookie браузера, поэтому закрытые файлы может не отдать. На локальные адреса (127.0.0.1, частные сети) хостовый путь не ходит: иначе агент обошёл бы запрет <webview> обращаться к служебным сервисам.

Лицензия

MIT — см. LICENSE.

Plugins associés