dsh-plugin-agent-browser
d3d-root/dsh-plugin-agent-browser
DeepSeek Harness 右侧栏中的真实浏览器,每个对话单独运行,可由 Agent 工具操作。
安装
dsh plugin --profile web add github:d3d-root/dsh-plugin-agent-browserREADME
Браузер агента для DeepSeek Harness
Настоящий Chromium в правой панели DSH: свой у каждого чата, с управлением из инструментов агента. Пользователь и агент работают в одном и том же окне — агент кликает, а вы видите результат и можете вмешаться.
- Один чат — один браузер. Открыли браузер в двух чатах — получили два независимых Chromium с разными cookie и разными логинами.
- Два агента одновременно. Каждый инструмент адресуется сессии своего агента, поэтому агенты не перехватывают команды друг друга.
- Видно человеку. Это не headless и не трансляция картинки:
<webview>с нативной прокруткой, вводом и кликами. - Капчи решаются. Есть настоящие события мыши Chromium и «человеческая» траектория перетаскивания для слайдер-пазлов.
- Ставится в один клик из списка плагинов DSH: плагин оформлен как бандл.
Содержание
- Как это выглядит
- Установка
- Инструменты агента
- Настройка
- Как это устроено
- Чем отличается от MCP
- Безопасность
- Диагностика
- Разработка
- Ограничения
Дополнительно: подробная установка · история версий · план развития · как устроено внутри · сравнение с MCP · как выложить свою версию
Как это выглядит
В правой панели появляется вкладка «Браузер агента»: адресная строка, кнопки навигации и сам сайт. В заголовке вкладки — имя открытой страницы, в адресной строке справа — короткая подпись чата, чтобы не путать браузеры, когда их открыто несколько.

┌──────────────────────────────────────────────┬───────────────────────────┐
│ Чат с агентом │ ← ↻ ⌂ [адрес] чат 3f2a… │
│ │───────────────────────────│
│ Агент: открываю страницу и ищу товар… │ │
│ │ настоящий сайт │
│ │ (Chromium) │
└──────────────────────────────────────────────┴───────────────────────────┘
Установка
Способ 1: через интерфейс DSH (рекомендуется)
-
Откройте боковую панель DSH → Plugins.
-
Нажмите Add plugin.
-
Вставьте имя пакета:
dsh-plugin-agent-browser -
Дождитесь установки и включите плагин переключателем.
-
Полностью перезапустите 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_html | HTML страницы (для разбора структуры) |
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 — настройки плагина).
| Поле | По умолчанию | Смысл |
|---|---|---|
startUrl | https://www.google.com | стартовая страница новой вкладки |
language | auto | язык подписей: auto, ru, en |
focusOnOpen | false | оставлять ли чат агента на экране. false — экран возвращается пользователю |
autoOpen | true | открывать вкладку автоматически, если её нет |
allowChatSwitch | true | разрешать ли кратко показать чат, чтобы создать вкладку. Один раз на чат |
idleTabTimeoutMs | 900000 (15 мин) | через сколько закрывать вкладку без команд. 0 — не закрывать |
maxTabs | 8 | сколько вкладок держать одновременно. 0 — без предела |
userAgent | Chrome 152 / Windows | UA для browser_set_ua |
timeoutMs | 30000 | сколько ждать ответа браузера на команду |
openTimeoutMs | 20000 | сколько ждать готовности только что открытой вкладки |
port | 0 | порт резервного сервера (0 — любой свободный) |
debug | true | писать отладочный журнал |
trace | false | писать в журнал каждую команду с длительностью |
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 | профиль на сессию | зависит от флагов сервера |
| Установка | плагин DSH | Node + браузер + конфиг 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.