---
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="/zh-Hant/docs/antigravity/understanding/07-rules-workflows-skills" />
  <Card title="MCP 與許可權" description="繼續學習 browser、terminal、file、MCP 的統一許可權治理。" href="/zh-Hant/docs/antigravity/understanding/08-mcp-permissions-sandbox" />
</Cards>
