browser

用途

Superset Browser Control 用于让智能体通过 Superset 工作区中的浏览器窗格来操作网页。它提供一组 superset browser 命令，每个操作都在用户可见的窗格中执行，并作用于该窗格真实的、已登录的会话。当高层命令不足以完成任务时，还可以通过原始 Chrome DevTools Protocol (CDP) 端点进行更底层的控制。

该工具适用于需要打开 URL、预览或验证正在运行的 Web 应用、检查页面状态、点击并输入内容等场景。

主要能力

• 打开与导航：使用 superset browser open 打开新标签页或复用当前窗格；使用 superset browser navigate 将已有窗格指向新 URL。仅接受 http(s) 和 about: URL，裸输入如 localhost:3000 会被升级，而 file://、chrome://、data: 会被拒绝。
• 截图：使用 superset browser screenshot 捕获 PNG，默认返回 base64，也可用 --out 写入文件。
• 读取控制台：使用 superset browser console 读取窗格捕获的控制台输出，可限制行数。
• 执行 JavaScript：使用 superset browser eval 在页面中执行代码并返回结果，用于读取结构化数据（如 .textContent、.value、location.href）或触发元素点击。
• 底层 CDP 交互：使用 superset browser cdp 获取窗格的 CDP WebSocket 端点，进而通过 Page、Runtime、DOM、Input、Network 等域实现点击、输入、滚动、等待选择器等 Playwright 级流程。
• 导入登录：在 macOS 上，使用 superset browser import-login 可将系统浏览器（Chrome、Edge、Brave、Arc、Dia、Comet 等 Chromium 浏览器）的 Cookie 导入窗格，使窗格登录到用户已使用的站点。导入前需用户明确同意，且会导入该配置文件磁盘上的所有 Cookie，而不仅是单个站点。

使用方式

1. 确定控制面：运行命令检查 list、open、navigate、screenshot、eval、console、cdp 等动词是否可用。若缺失，运行 superset update 后重试。应用内置 CLI 仅随桌面应用更新。
2. 解析工作区：在工作区内使用 $SUPERSET_WORKSPACE_ID；否则通过 superset workspaces list --local --json 选择目标。远程主机需传 --host <id>。
3. 查找或打开窗格：使用 superset browser list 列出窗格；使用 superset browser open 打开新标签页（--target new-tab）或复用当前标签页。每个窗格有稳定的 paneId，作用域限定在其工作区，操作时需传递相同的工作区。
4. 使用高层命令驱动：通过 navigate 导航、screenshot 截图、console 检查错误、eval 读取数据。优先使用这些命令，仅当需要真实输入事件时才使用原始 CDP。
5. 导入登录（可选）：当用户表示已在某浏览器登录，或窗格遇到登录墙时，可询问用户是否导入登录。列出已安装浏览器让用户选择，然后执行导入并重新加载窗格。macOS 上首次运行会请求访问 Keychain 的权限。非 Chromium 浏览器或非 macOS 系统不支持导入。仅磁盘上的 Cookie 可导入，许多站点使用内存中的会话 Cookie，需用户先退出源浏览器以刷新登录信息。
6. 通过 CDP 完成完整交互：获取窗格的 CDP WebSocket 端点后，可使用 JavaScript 建立连接并发送 CDP 命令。注意每个窗格只允许一个并发 CDP 会话，第二个连接会被拒绝（关闭码 1013）。点击后应确认 document.activeElement 再输入文本，并在每次操作后轮询选择器或状态，而非固定等待。使用 Enter 提交时，keyDown 事件需携带 text: "\r"。
7. 验证结果：从页面本身确认结果，而不是仅凭命令返回成功。读取 location.href、通过 eval 检查 DOM、或截图后确认，并在宣布成功前检查控制台错误。
8. 发布证据（可选）：当交付物是截图证据（如缺陷报告、前后对比、操作演示）时，可将截图放入目录并配以 index.html，使用 superset pages publish 发布目录。发布前需阅读每张截图，必要时裁剪或涂黑敏感信息，并确认可见性（默认组织可见，可用 --visibility just_me 设为仅自己），发布前与用户确认。

适用场景

• 预览开发服务器或验证用户正在观看的 UI。
• 在应用中逐步点击流程，检查页面行为。
• 读取页面结构化数据或控制台错误以辅助调试。
• 需要真实输入事件（点击、输入、滚动）的复杂交互流程。
• 生成带有截图证据的缺陷报告或操作演示并发布。

限制与安全边界

• 窗格仅在桌面应用中存在；没有桌面应用连接的主机没有窗格，所有命令会清晰报错。
• 窗格操作作用域限定在其工作区，不能跨工作区访问。
• 应用内窗格共享一个浏览器配置文件，因此 eval 和 CDP 可触及用户在任一窗格登录的任何站点。严禁读取 Cookie、令牌或凭据，严禁外泄会话数据，严禁在认证站点执行任务以外的操作。
• 在提交表单、购买或其他重要操作前，必须与用户确认。
• 登录墙由用户自行处理，智能体不得输入密码或 MFA。可提议导入登录，但不能代替用户完成认证。
• 未经明确同意，不得安装 Browser Use、启用 Chrome 远程调试、附加到用户已登录的配置文件或启动计费的云浏览器。如果用户拒绝，应报告无法完成的内容，而不是绕过。
• 导入登录仅限 macOS 上的 Chromium 浏览器；其他系统或浏览器不支持。导入会复制整个配置文件的 Cookie，而不仅是当前站点。
• 导航离开用户正在查看的内容本身是一种变更，建议使用 --target new-tab 创建临时界面，除非用户要求，否则不要关闭标签页或清除历史。
• 发布证据时注意截图可能包含会话令牌、邮箱、客户名称或敏感仪表盘内容，默认组织可见，需谨慎处理。