Yandex 浏览器操控 DmitPerson42/dsh-yandex-browser

dsh-yandex-browser

DeepSeek Harness 插件：拉起 Яндекс Браузер，带持久化配置档和调试端口，让智能体能在你真实的浏览器里干活——连同你登录过的那些授权——并给模型提供直接操作页面的工具。

为什么需要它

智能体在浏览器里通常用的是用完即弃的配置档：每次启动都是一个干净的浏览器，没有标签页、没有扩展、没有 cookies。麻烦就来了：打不开邮箱，进不了个人中心，用不了扩展。

这个插件解决的正是这件事：智能体的浏览器有一个持久化配置档（%USERPROFILE%\.dsh\browsers\yandex）。你手动登录一次账号，之后会话一直活着，智能体直接拿来用。

它是怎么工作的

Яндекс Браузер 就是 Chromium，所以它能开本地调试端口（Chrome DevTools Protocol）。外部程序通过这个端口看到标签页、打开新标签页、在页面里执行 JavaScript。插件做三件事：

DSH GUI -> композиция
|-- yandex_browser: поднимает браузер на порту 9222 и следит за ним
|-- yandex_page: читает страницу (текст, элементы, eval, скриншот)
|-- yandex_act: действует на странице (переход, клик, ввод, вкладки)
-- MCP yandex (необязательно): Playwright с теми же 25 инструментами

插件不依赖 MCP：yandex_page 和 yandex_act 直接通过同一个端口跟浏览器对话。当 MCP 客户端连不上时，正需要这一层——它以前就是这么干的，然后超时挂掉。

工具

yandex_browser —— 生命周期

| 动作 | 做什么 |
| status | 浏览器是否已启动、版本、端点地址、配置档路径、已打开的标签页 |
| start | 用智能体的配置档和调试端口启动浏览器（如果已经启动，什么都不做） |
| open | 在新标签页打开 URL；浏览器没启动就先启动 |
| login | 打开登录页（默认是 Яндекс Паспорт），让你自己输密码 |
| tabs | 已打开标签页的列表 |
| close | 关闭浏览器；已保存的登录状态留在配置档里 |

yandex_page —— 读取

| 动作 | 做什么 |
| text | 页面文本，加上带标注的交互元素列表 |
| eval | 执行任意 JavaScript 表达式并返回结果 |
| screenshot | 保存 PNG（默认只截可见区域，参数 fullPage 截整页） |
| tabs | 标签页及其 id；插件创建的标签页带标记 |

text 不只返回 innerText，还返回来自 aria-label、title 和 placeholder 的元素标注。正是它让基于 Web Components 的界面变得可读：比如 Google 云端硬盘，文件行住在自定义元素里，普通页面文本里根本没有它们。

yandex_act —— 操作

| 动作 | 做什么 |
| navigate | 在当前标签页或新标签页跳转到 URL |
| click | 点击通过 CSS 选择器或可见文本找到的元素 |
| type | 在输入框中输入文本（会清空输入框，兼容 React 表单），可选发送 Enter |
| key | 按键（Enter、Tab、Escape、方向键、PageUp/PageDown） |
| activate | 把标签页显示给用户 |
| close | 关闭一个标签页 |
| close_created | 关闭这个插件打开过的所有标签页 |
| wait | 等待元素按选择器或文本出现 |

典型流程：status -> open -> text（看清页面上有什么）-> click / type -> close。

智能体绝不输入密码。要登录账号时，它调用 login，由你在可见的浏览器窗口里输入数据。

关于标签页的规则

智能体打开的标签页，放着不管就是垃圾。所以插件会记住自己打开过的所有标签页 id（存在配置档里的 agent-tabs.json，DSH 重启后依然保留），并能用一条命令关掉它们：

yandex_act action: "close_created" # 关掉插件打开过的一切

你自己的标签页插件不会碰：只能按明确 id 关闭，id 由 yandex_page action: "tabs" 或 yandex_act 返回。

安装

dsh plugin --profile web add github:DmitPerson42/dsh-yandex-browser

插件按普通 bundle 安装：包声明 dsh.bundle.patch，旁边的 cordis.patch.yml 把它加进配置档。重启 DSH GUI 就行。

等插件进了目录，也能用插件市场里的按钮按同样方式安装（dsh plugin --profile web add dshmarket）。

手动安装，不用命令行

git clone https://github.com/DmitPerson42/dsh-yandex-browser
pwsh -File .\dsh-yandex-browser\install.ps1

脚本把插件复制到 ~\.dsh\plugins\dsh-yandex-browser（不带依赖，只用 Node 内置模块），并打印出需要加到 ~\.dsh\profiles\web\cordis.patch.yml 的内容：

- insert:
- id: yandex-browser
name: "file:///C:/Users/Druli/.dsh/plugins/dsh-yandex-browser/lib/index.js"
config:
autoStart: true

改完配置后重启 DSH GUI。

重要：修正 MCP 客户端

同一个 cordis.patch.yml 里有 MCP 服务器 yandex。原始配置把地址当位置参数传：

args: ["-y", "@playwright/mcp@latest", "http://127.0.0.1:9222"] # 这样不行

当前版本的 Playwright MCP 不接受这个参数，会报 too many arguments. Expected 0 arguments but got 1，导致服务器一直卡在 disconnected 状态。需要显式加标志：

args:
- "-y"
- "@playwright/mcp@latest"
- "--cdp-endpoint"
- "http://localhost:9222"

这里有两点，都经过实践验证。

地址要写成字面量。 patch 记录里的 !!js 语法不会被求值：MCP 服务器拿到的是字符串 process.env.YANDEX_CDP ?? 'http://localhost:9222'，然后报 Invalid URL 挂掉。要改端口，就同时改这一行和插件的 port。
必须是 localhost，不是 127.0.0.1。 浏览器有时在 IPv4 上开调试套接字，有时只在 IPv6 上开——这台机器上它有一次只监听 [::1]，请求 127.0.0.1 就看不到它。Node 里的 localhost 会同时遍历两个协议栈。插件也这么做：两个地址都试，响应里给出真正有回应的那个。

登录账号——只做一次

1. 带插件启动 DSH：浏览器会自己起来（autoStart: true）。
2. 让智能体去做：「打开 Yandex 登录页」——或者调用 yandex_browser，传 action: "login"。
3. 在浏览器窗口里手动登录账号。勾上「记住我」，如果它提议「在所有设备上退出登录」——不用勾，密码存在配置档里。
4. 完成。会话保存在智能体的配置档里，之后每次启动都能用。

顺便值得登一次你希望智能体浏览器里有的扩展：扩展装进配置档，重启后依然在。

配置

| 字段 | 默认值 | 含义 |
| autoStart | true | 加载插件时启动浏览器，让 MCP 客户端立刻找到活着的端点 |
| cdpEndpoint | YANDEX_CDP 或 http://localhost:9222 | DevTools 地址 |
| profileDir | YANDEX_BROWSER_PROFILE 或 ~\.dsh\browsers\yandex | 持久配置档 |
| executable | YANDEX_BROWSER_PATH 或自动查找 | browser.exe 路径 |
| port | YANDEX_BROWSER_PORT 或端点里的端口 | 调试端口 |
| screenshotDir | ~\.dsh\browser-shots | 没显式传 file 时截图存哪 |
| tabStateFile | <profileDir>\agent-tabs.json | 插件创建的标签页记忆 |

端口和配置档跟 MCP 客户端绑定：改 YANDEX_CDP——两个都跟着变。

检查

node .\test\smoke.mjs # 只测 status，不启动浏览器
node .\test\smoke.mjs --launch # start + open + tabs
node .\test\check-login.mjs # 用户是否已登录账号
node .\test\mcp-check.mjs # 在活着的浏览器上起 MCP，并打印工具
node .\test\page-tools.mjs # 底层 CDP 跑一遍：标签页、文本、eval、截图
node .\test\tools.mjs # 三个工具全跑，用本地测试页
node .\test\close-test-browsers.mjs # 关掉测试实例：端口写在参数里

tools.mjs 是主测试：它用假的工具注册表加载插件，在新标签页打开 test/fixtures/page.html，读页面、输入文本、按文字和 aria-label 点按钮、截图、关标签页。不需要 DSH 就能跑——有智能体浏览器开着就够。

check-login 不靠重定向：它从 yandex_login 这个 cookie 读账号名，看有没有 Session_id，再打开 passport.yandex.ru/profile——如果登录表单没出现，会话就是活的。其他 cookie 的值不读。

如果出了岔子

后台页面不响应。 Chromium 会冻结后台标签页，而冻结的标签页不响应任何 Runtime.evaluate —— 看起来就像死掉的页面。插件自己解决这个问题：每个会话开始时都会执行 Page.bringToFront。副作用是，智能体正在操作的标签页会弹到最前面。这很明显，但否则没法读取后台页面。

端口 9222 已被另一个浏览器占用 —— 插件会告诉你具体是哪个。关掉它，或者通过 YANDEX_CDP 换端口（别忘了 YANDEX_BROWSER_PORT，让插件和 MCP 指向同一个地址）。

首次启动超过一分钟 —— 冷配置档会一次性创建自己的组件（AsrSubtitles、component_crx_cache 等），并显示欢迎页面。插件最多等待 60 秒；之后的启动只需几秒。

MCP server is disconnected —— 客户端没等到浏览器，重连次数已耗尽。用 yandex_browser action: "start" 启动浏览器，然后重启 DSH 会话。这不影响 yandex_page 和 yandex_act —— 它们每次调用都会重新连接。

浏览器不启动，配置档为空 —— 从 Chromium 136 开始，--remote-debugging-port 对主配置档不再生效。插件始终用单独的 --user-data-dir 启动浏览器；这一点不能改，否则端口不会打开。

第二个实例起不来 —— 如果你已经用日常配置档打开了 Yandex Browser，智能体仍会启动一个带自己配置档的独立实例。两者可以同时运行；端口只被智能体的实例占用。

沙箱 —— 在 workspace-write 模式下，插件无法在工作目录之外创建配置档。在 DSH 中插件运行在宿主进程里，所以正常情况下没有这个问题；这个限制只影响从沙箱里跑测试（这种情况下 tools.mjs 会把截图写到临时目录，并警告标签页列表写入失败 —— 不影响测试结果）。

代码结构

| 文件 | 作用 |
| lib/index.js | 三个工具、浏览器生命周期、标签页记账 |
| lib/cdp.js | 底层 CDP 客户端：HTTP 端点、标签页 WebSocket 会话、页面读取脚本 |
| test/*.mjs | 不依赖 DSH 的测试跑批：冒烟、登录、MCP、CDP、全部工具 |
| install.ps1 | 把插件复制到配置档，并给出 cordis.patch.yml 的提示 |

CDP 会话都是短命的：一次操作一个 WebSocket，用完立刻关闭。这样没有东西会泄漏，而且这种会话能扛住操作中途被关闭或重载的标签页。

许可证

MIT。