06 · Browser Subagent 与 UI 验证
用 Antigravity Browser Subagent 做 UI 验证：URL allowlist、浏览器扩展、console、截图、录屏、walkthrough 和 prompt injection 风险。
Browser Subagent 让 Antigravity 不只会改 UI，还能打开页面、点击、输入、观察结果，并留下截图或录屏。官方 Browser 文档说明，Antigravity 能打开、读取并控制 Chrome，用于测试开发网站、读取互联网数据源和自动化浏览器任务；当主 agent 需要浏览器交互时，会调用专门的 browser subagent。
这正是它做前端任务最有价值的部分，也是最需要安全边界的部分。浏览器能看见真实页面，也能误触真实后台。
一句话标准：只要任务影响用户界面，就不要只接受代码 diff；要求 browser 验证和可复查 artifact。
阅读目标：读完本章，你应该能写出一条只允许访问 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 的存放位置。
Separate profile 是安全边界，不是缺点。真实后台、支付、广告、授权页面默认由人操作，agent 只做只读观察或本地环境验证。
3. UI 任务 prompt 模板
修改登录页错误提示样式。
要求：
1. 修改前先说明影响范围。
2. 修改后启动本地服务。
3. 用浏览器验证空密码、错误密码、成功登录三个路径。
4. 提供 desktop 和 mobile 截图。
5. 提供 walkthrough，列出未覆盖风险。
6. 执行 terminal 命令前请求确认。这个 prompt 明确了路径、viewport、证据和权限。
更适合真实项目的版本可以加上边界：
只允许访问 http://localhost:3000。
不要访问生产站、后台、支付页或任何需要登录的页面。
验证宽度：390、768、1440。
每个宽度都检查：导航、主按钮、长文案、弹窗关闭按钮、底部区域。
最后说明 console 是否有 error，并给 walkthrough。4. 验证流程图
flowchart TD
Change["UI 改动"] --> Server["启动本地服务"]
Server --> Browser["打开 allowlisted URL"]
Browser --> Path["执行用户路径"]
Path --> Observe["观察 DOM / console / screenshot"]
Observe --> Pass{"符合预期?"}
Pass -->|是| Record["截图 / 录屏 / walkthrough"]
Pass -->|否| Fix["回到代码修复"]
Fix --> Server5. URL allowlist
浏览器能力越强，URL 越要收窄。
| 场景 | 推荐 |
|---|---|
| 本地前端 | allow localhost 或固定本地域 |
| 官方文档 | allow 官方域名 |
| 第三方网页 | 临时 allow，任务后移除 |
| 登录后台 | 默认人工操作，agent 只读 |
| 支付/广告/授权页 | 不让 agent 自动点击提交 |
未知网页可能包含 prompt injection。不要让 browser agent 在不受控网页里自由浏览，再回头读你的项目文件。
可以把 URL 策略写进 prompt：
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. 截图和录屏怎么要求
最小要求：
请提供：
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，至少要求它交付：
- 改动文件列表和 diff 摘要。
- 本地启动或构建命令结果。
- 390px mobile 截图。
- 768px tablet 截图。
- 1440px desktop 截图。
- 关键点击路径的 recording 或 walkthrough。
- console error 检查结果。
- 未覆盖的浏览器、登录态或接口风险。
如果是商业页面，再加两条：
检查所有可点击按钮是否有 hover / disabled / loading 状态。
检查长标题、长按钮文案和窄屏导航是否溢出。本章自检
完成本章后，用这 3 个问题检查自己是否真正理解：
- Browser Subagent 为什么不等同于你的日常 Chrome 登录态？
- Screenshot、recording、console 分别适合发现哪类问题？
- 为什么 UI 任务要显式写 URL allowlist？
通过标准：你能为真实前端任务写出带 URL、viewport、证据、权限边界的 browser 验收 prompt。
官方来源
- Google Antigravity Browser - 官方说明 Chrome 控制、separate browser profile、browser tools 设置和 Chrome binary path。
- Google Antigravity Browser Subagent - 官方说明 browser subagent 的模型、工具、overlay 和后台 tab 行为。
- Google Antigravity Screenshots - 官方说明截图作为 image artifact 保存并支持评论。
- Google Antigravity Browser Recordings - 官方说明浏览器动作录屏和 recording artifact。
- Google Antigravity Walkthrough - 官方说明浏览器任务的 walkthrough 可能包含截图和录屏。