在智能体开发中，让 agent 拥有真实的浏览器能力是常见需求。Web Bridge 是一个 MCP server 插件，利用真实浏览器（Chromium/Firefox/WebKit）提供导航、点击、填表和截图能力。它通过无障碍树快照来识别页面元素，使 agent 能够精确操作页面而无需依赖视觉模型。
这是什么¶
Web Bridge 是一个基于真实浏览器的自动化工具。它使用 TypeScript 编写，运行在 Node.js ≥ 20 环境下，通过 MCP 协议（stdio 传输）与 DSH 通信。其核心机制是将网页渲染为无障碍树快照，并为 DSH 暴露 22 个 web_ 前缀的工具。
核心能力¶
- 真实浏览器驱动：支持 Chromium、Firefox 和 WebKit，默认使用 Chromium。
- 无障碍树驱动：
web_snapshot生成带引用编号的页面结构，实现精确交互。 - 页面交互：支持点击、填表、下拉选择、悬停、滚动、键盘输入等操作。
- 视觉能力：支持视口、全页、元素截图，格式支持 PNG/JPEG。
- 脚本执行：可在页面上下文中执行 JavaScript，并自动处理循环引用、BigInt 等类型的清洗。
- 多标签页与精细等待：支持标签页的创建、切换、关闭，以及按加载状态、元素状态、URL 或固定时长进行等待。
- 会话管理：支持持久化用户数据目录，并可通过
web_shutdown释放资源。
安装与启用¶
安装前请确保 Node.js 版本 ≥ 20。
在 DSH 中通过插件命令添加：
dsh plugin --profile demo add github:JohnXu22786/browser-automation
该命令会将插件添加到 demo 配置文件中。安装完成后，插件将自动加载并初始化浏览器进程。
典型用法¶
配置管理¶
Web Bridge 的配置优先级为：默认值 < 配置文件 < 环境变量。
- 配置文件：在项目根目录创建配置文件，如
web-bridge.config.json。
{
"browser": { "name": "chromium", "headless": true, "viewport": { "width": 1280, "height": 720 } },
"context": { "ignoreHTTPSErrors": false, "permissions": ["geolocation"] },
"timeouts": { "action": 10000, "navigation": 60000, "settle": 500 },
"sandbox": true,
"testIdAttribute": "data-testid"
}
启动命令：`node dist/index.js --config web-bridge.config.json`。
- 环境变量：通过
WEB_BRIDGE_前缀的环境变量覆盖配置。WEB_BRIDGE_BROWSER：指定浏览器引擎。WEB_BRIDGE_HEADLESS：控制无头模式。WEB_BRIDGE_VIEWPORT：设置视口大小。WEB_BRIDGE_ACTION_TIMEOUT：单次操作超时时间（毫秒）。WEB_BRIDGE_NAV_TIMEOUT：导航超时时间。WEB_BRIDGE_SETTLE_MS：操作后等待异步任务 settled 的时间。
工具调用示例¶
- 导航：
web_open用于打开 URL，支持http/https/file/data协议。 - 获取快照：
web_snapshot返回页面的无障碍树结构，元素带有引用编号，用于后续精确定位。 - 交互：
web_click使用引用编号或选择器点击元素；web_fill用于填表。 - 截图：
web_screenshot可截取视口、全页或指定元素。
适用场景与注意¶
该插件适合需要高精度页面操作、处理复杂表单或执行动态网页脚本的场景。
权限与安全提示：
* 插件以当前 DSH 进程的权限运行。
* Navigation 工具会触发真实的网络请求和页面渲染。
* Interaction 工具会触发鼠标事件和脚本执行。
* 在安装前，请务必检查插件的源码和许可证（MIT）。
总结¶
Web Bridge 通过真实浏览器和无障碍树快照机制，为 DSH 提供了可靠的浏览器自动化能力。它支持精细的交互控制和会话管理，适合构建需要与 Web 应用深度交互的智能体。
