Browser Tool
基于 Cursor 官方 Browser 文档解释浏览器验证、console、network、设计侧栏、approval 和企业 allowlist。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| Browser Tool | 浏览器工具 | Agent 预览和验收页面的能力。 |
| 页面验收 | verify | 看渲染效果确认改对了。 |
| 任务范围 | scope | 限定浏览器能做到哪。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你用 Cursor 的浏览器工具验收页面、控好范围。
你是 Cursor 浏览器工具使用顾问，帮我用浏览器工具验收页面、在页面上反馈并控好任务范围。
【角色】
你熟悉浏览器工具的预览、页面反馈、任务范围控制，知道哪些任务适合用它。
【输入】
- 要验收的页面 / 功能：___
- 关注点（布局 / 交互 / 响应式）：___
- 是否让它据反馈改：___
- 风险偏好：___
【工作流程】
1. 用浏览器工具预览页面
2. 在问题处反馈、描述期望
3. 让它据反馈改、再复验
4. 控制任务范围避免越界
【输出规范】
▌一、预览验收步骤
▌二、反馈写法
▌三、据反馈改 + 复验
▌四、任务范围控制
【硬约束】
- 浏览器任务限范围，不碰账号后台
- UI 改动在浏览器实际复验
- 反馈描述具体期望
- 改动可回滚
- 纯后端 / 不需页面验证的别用
- 给的方案具体可执行
- 给的每条结论都要落到具体可照做的步骤或示例，不停留在「建议」「考虑一下」这类没法直接执行的空泛表述Cursor Browser Tool 让 Agent 控制浏览器，用于测试应用、视觉编辑布局、审计 accessibility、把设计转代码、调试 UI 和自动化测试流程。官方文档强调它能访问 console logs 和 network traffic，所以它不只是“截图工具”。
阅读目标：读完本章，你应该能让 Agent 用 Browser 验证本地 UI，并知道什么时候必须要求 manual approval 和 origin allowlist。
1. Browser 能做什么
官方列出的 browser capabilities：
| 能力 | 用途 |
|---|---|
| Navigate | 打开 URL、跟链接、前进后退、刷新 |
| Click | 点击、双击、右键、hover 可见元素 |
| Type | 填表单、搜索框、textarea |
| Scroll | 浏览长页面，找到隐藏内容 |
| Screenshot | 截图验证布局和视觉状态 |
| Console Output | 读取 JS 错误、日志和 warning |
| Network Traffic | 监控请求、响应、状态码和 payload |
flowchart TD
UI["UI task"] --> Browser["Cursor Browser"]
Browser --> Screenshot["Screenshot"]
Browser --> Console["Console output"]
Browser --> Network["Network traffic"]
Browser --> Action["Click / Type / Scroll"]
Screenshot --> Evidence["Visual evidence"]
Console --> Debug["Runtime debugging"]
Network --> API["API diagnosis"]2. Native integration 的意义
官方文档说明 Browser actions、screenshots 会显示在 chat，也可以在 separate window 或 inline pane 中显示 browser window。Cursor 还优化了几件事：
- browser logs 写入文件，Agent 可以 grep 并选择性读取。
- screenshot 直接作为图片进入 file reading tool。
- Agent 会收到日志总行数和 preview snippets。
- Agent 会检测 running development servers 和正确端口，避免重复启动或猜端口。
这对网站断点和 UI 验收很重要：Agent 应该先识别已有 dev server，再打开正确端口截图，不应该随便另启一个服务。
3. Design sidebar 和视觉修改
官方 Browser 文档说明，Browser 包含 design sidebar，可以在 Cursor 里直接调整站点。
可调整：
| 类型 | 例子 |
|---|---|
| Position and layout | flex、grid、alignment |
| Dimensions | width、height、padding、margin |
| Colors | design tokens、color picker、gradient |
| Appearance | shadow、opacity、border radius |
| Theme testing | light / dark themes |
当视觉调整符合预期后，点击 apply 会触发 agent 更新代码。也可以选择多个元素并用文本描述改动。
视觉调整必须回到代码 diff。不要只看浏览器里“临时调好了”，最终要确认代码已经正确改动。
4. Tool approval 和安全模式
官方安全说明列出三种 approval 模式：
| Mode | 含义 |
|---|---|
| Manual approval | 每个 browser action 都要 review 和 approve，推荐 |
| Allow-listed actions | allow list 匹配的动作自动跑，其他要审批 |
| Auto-run | 全部自动执行，谨慎使用 |
官方明确提醒：不要在 untrusted code 或 unfamiliar websites 上使用 auto-run。Agent 可能执行恶意脚本或提交敏感数据。
5. 企业控制和 Origin Allowlist
企业用户可通过 MCP controls 管理 Browser。官方说明管理员可以：
- 在 MCP Configuration 中开启 browser features。
- 配置 Browser Origin Allowlist（按 origin 白名单，origin = 协议+域名+端口，如
https://example.com:443）。 - 限制 agent 自动导航到哪些 origin。
- 控制 MCP tools 能在哪些 origin 上运行。
重要边界：
- 用户仍可手动导航到 allowlist 外 URL。
- 但一旦在非 allowlist origin，browser tools 会被阻止。
- Redirect、link navigation、client-side navigation 有 edge cases，需要定期审查 allowlist。
深读：为什么 Browser 是断点验收的关键工具
代码 diff 看不出按钮是否在 390px 宽度溢出，也看不出移动端菜单是否遮挡内容。Browser Tool 能同时提供 screenshot、console、network 和交互路径证据，适合做真实 UI 断点检查。
对教程站这类文档站，最低应检查首页、导航、搜索、教程目录、正文页、代码块、表格、Cards、details、Mermaid 在 mobile、tablet、desktop 下是否溢出或遮挡。
本章自检
完成本章后，用这 3 个问题检查自己是否真正理解：
- Browser Tool 除了截图，还能读取哪些运行时证据？
- Manual approval、Allow-listed actions、Auto-run 的风险差异是什么？
- 企业 Origin Allowlist 能控制什么，不能完全阻止什么 edge case？
通过标准：你能写出一条本地 UI 验收任务，要求 Cursor 检查 viewport、截图、console、network 和 diff。
官方来源
- Cursor Browser Tool —— 官方说明 browser capabilities、native integration、design sidebar、approval、security 和 enterprise origin allowlist。
- Cursor Browser Help —— Help Center 说明浏览器打开、点击、填表和截图能力。