---
title: "06 · Browser Subagent 与 UI 验证"
description: "用 Antigravity Browser Subagent 做 UI 验证：URL allowlist、浏览器扩展、console、截图、录屏、walkthrough 和 prompt injection 风险。"
verifiedAt: "2026-05-07"
---

Browser Subagent 让 Antigravity 不只会改 UI，还能打开页面、点击、输入、观察结果，并留下截图或录屏。官方 Browser 文档说明，Antigravity 能打开、读取并控制 Chrome，用于测试开发网站、读取互联网数据源和自动化浏览器任务；当主 agent 需要浏览器交互时，会调用专门的 browser subagent。

这正是它做前端任务最有价值的部分，也是最需要安全边界的部分。浏览器能看见真实页面，也能误触真实后台。

> [!NOTE]
> **一句话标准**：只要任务影响用户界面，就不要只接受代码 diff；要求 browser 验证和可复查 artifact。

> [!TIP]
> **阅读目标**：读完本章，你应该能写出一条只允许访问 `localhost` 的 UI 验收 prompt，并知道 screenshot、recording、console、walkthrough 分别验证什么。

## 1. 浏览器验证的价值

传统 AI 改 UI 常见问题：

- 代码能编译，但页面空白。
- desktop 好看，mobile 重叠。
- 按钮存在，但点击没反应。
- 成功路径可以，失败路径没提示。
- 文案溢出或遮挡。

Browser Subagent 的价值是把这些问题提前暴露出来。

官方 Browser Subagent 文档说明，它使用专门操作 Antigravity 管理浏览器页面的模型，和 main agent 选择的模型不同。它可以点击、滚动、输入、读取 console logs，并通过 DOM capture、screenshots、markdown parsing 或 videos 读取页面状态。

这说明前端任务不能只要求“跑 build”。你要让 agent 证明页面真的被打开、操作、观察过。

## 2. Browser Subagent 的边界

浏览器能力有三个关键边界：

| 边界 | 官方事实 | 实操含义 |
| --- | --- | --- |
| 单独 profile | Antigravity 使用 separate browser profile（独立 Chrome 配置文件） | 默认没有你的日常登录态——但**只需登录一次，下次会保留** |
| 控制 overlay | 页面被控制时会显示蓝色边框和动作面板 | agent 操作时不要手动抢页面 |
| 后台 tab | browser subagent 可以操作未聚焦 tab | 不等于允许它自由访问外部网站 |
| 切回原 Chrome | 这是独立应用，dock 里有单独图标 | 想回到日常 Chrome 必须**完全退出 Antigravity 的浏览器**再重启 Chrome（仅关窗口不够） |

如果 Antigravity 找不到 Chrome，需要在设置里指定 Chrome binary path。也可以在 Settings 的 Browser 区域关闭 browser tools，或修改 browser profile 的存放位置。

> [!IMPORTANT]
> Separate profile 是安全边界，不是缺点。真实后台、支付、广告、授权页面默认由人操作，agent 只做只读观察或本地环境验证。

## 3. UI 任务 prompt 模板

```text
修改登录页错误提示样式。
要求：
1. 修改前先说明影响范围。
2. 修改后启动本地服务。
3. 用浏览器验证空密码、错误密码、成功登录三个路径。
4. 提供 desktop 和 mobile 截图。
5. 提供 walkthrough，列出未覆盖风险。
6. 执行 terminal 命令前请求确认。
```

这个 prompt 明确了路径、viewport、证据和权限。

更适合真实项目的版本可以加上边界：

```text
只允许访问 http://localhost:3000。
不要访问生产站、后台、支付页或任何需要登录的页面。
验证宽度：390、768、1440。
每个宽度都检查：导航、主按钮、长文案、弹窗关闭按钮、底部区域。
最后说明 console 是否有 error，并给 walkthrough。
```

## 4. 验证流程图

```mermaid
flowchart TD
    Change["UI 改动"] --> Server["启动本地服务"]
    Server --> Browser["打开 allowlisted URL"]
    Browser --> Path["执行用户路径"]
    Path --> Observe["观察 DOM / console / screenshot"]
    Observe --> Pass{"符合预期?"}
    Pass -->|是| Record["截图 / 录屏 / walkthrough"]
    Pass -->|否| Fix["回到代码修复"]
    Fix --> Server
```

## 5. URL allowlist

浏览器能力越强，URL 越要收窄。

| 场景 | 推荐 |
| --- | --- |
| 本地前端 | allow `localhost` 或固定本地域 |
| 官方文档 | allow 官方域名 |
| 第三方网页 | 临时 allow，任务后移除 |
| 登录后台 | 默认人工操作，agent 只读 |
| 支付/广告/授权页 | 不让 agent 自动点击提交 |

> [!WARNING]
> 未知网页可能包含 prompt injection。不要让 browser agent 在不受控网页里自由浏览，再回头读你的项目文件。

可以把 URL 策略写进 prompt：

```text
Browser 限制：
1. 只能打开 http://localhost:3000 和 http://localhost:3000/docs。
2. 不要搜索网页，不要访问第三方 URL。
3. 如果页面跳到外部登录、支付或授权页，立刻停止并报告。
4. 只读 console，不在页面执行自定义 JavaScript。
```

这类边界比“你注意安全”更有效。

## 6. Console 与 network

官方 Browser Subagent 文档明确提到它可以读取 console logs。前端任务要主动要求它检查：

- console error
- 页面加载失败
- 点击后是否有异常
- 表单提交是否触发预期反馈
- loading 是否能结束

不要只看截图。截图不能证明 console 没报错。

如果页面有 API 请求，还要让它观察这些状态：

| 状态 | 要看什么 |
| --- | --- |
| loading | 是否卡住、是否有占位 |
| success | UI 是否出现成功反馈 |
| error | 是否有可读错误信息 |
| empty | 空状态是否可理解 |
| slow network | 是否会出现重复点击或布局跳动 |

## 7. 截图和录屏怎么要求

最小要求：

```text
请提供：
1. desktop 截图
2. mobile 截图
3. 关键交互路径的 browser recording 或 walkthrough
4. console 是否有错误
```

对于商业页面，还要加：

- 文案不溢出。
- 按钮可点击。
- loading 和错误状态存在。
- 空状态、长文本、移动端都可读。
- 不遮挡导航、底部按钮、弹窗关闭按钮。

官方 Screenshots 文档说明，截图会作为 image artifacts 保存并支持评论；官方 Browser Recordings 文档说明，browser subagent 每次操作浏览器时可能生成动作录屏，并保存为 recording artifact。实操上：

| 证据 | 适合验证 |
| --- | --- |
| Screenshot | 静态布局、响应式、视觉遮挡 |
| Browser Recording | 多步操作、点击路径、表单流程 |
| Console logs | 运行时错误、点击异常、加载失败 |
| Walkthrough | 汇总做了什么、怎么验证、剩余风险 |

不要只收一张桌面截图。移动端、长文本、错误状态往往才是问题集中处。

## 8. 不要让浏览器替你做什么

| 不要 | 原因 |
| --- | --- |
| 自动登录真实账号后台 | 登录态和数据风险 |
| 自动提交付款/广告/授权 | 金钱和权限风险 |
| 访问私人邮件和云盘 | 隐私风险 |
| 在未知页面执行 JavaScript | prompt injection 风险 |
| 把截图当唯一验收 | 截图看不到失败路径 |

## 9. 一套前端验收清单

每次 Antigravity 改 UI，至少要求它交付：

1. 改动文件列表和 diff 摘要。
2. 本地启动或构建命令结果。
3. 390px mobile 截图。
4. 768px tablet 截图。
5. 1440px desktop 截图。
6. 关键点击路径的 recording 或 walkthrough。
7. console error 检查结果。
8. 未覆盖的浏览器、登录态或接口风险。

如果是商业页面，再加两条：

```text
检查所有可点击按钮是否有 hover / disabled / loading 状态。
检查长标题、长按钮文案和窄屏导航是否溢出。
```

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. Browser Subagent 为什么不等同于你的日常 Chrome 登录态？
2. Screenshot、recording、console 分别适合发现哪类问题？
3. 为什么 UI 任务要显式写 URL allowlist？

通过标准：你能为真实前端任务写出带 URL、viewport、证据、权限边界的 browser 验收 prompt。

## 官方来源

- [Google Antigravity Browser](https://antigravity.google/docs/browser) - 官方说明 Chrome 控制、separate browser profile、browser tools 设置和 Chrome binary path。
- [Google Antigravity Browser Subagent](https://antigravity.google/docs/browser-subagent) - 官方说明 browser subagent 的模型、工具、overlay 和后台 tab 行为。
- [Google Antigravity Screenshots](https://antigravity.google/docs/screenshots) - 官方说明截图作为 image artifact 保存并支持评论。
- [Google Antigravity Browser Recordings](https://antigravity.google/docs/browser-recordings) - 官方说明浏览器动作录屏和 recording artifact。
- [Google Antigravity Walkthrough](https://antigravity.google/docs/walkthrough) - 官方说明浏览器任务的 walkthrough 可能包含截图和录屏。

## 接下来去哪

<Cards>
  <Card title="Rules / Workflows / Skills" description="把 UI 验收 prompt 沉淀成 workflow 或 skill。" href="/docs/antigravity/understanding/07-rules-workflows-skills" />
  <Card title="MCP 与权限" description="继续学习 browser、terminal、file、MCP 的统一权限治理。" href="/docs/antigravity/understanding/08-mcp-permissions-sandbox" />
</Cards>
