Browser Tool
基於 Cursor 官方 Browser 文件解釋瀏覽器驗證、console、network、設計側欄、approval 和企業 allowlist。
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 說明瀏覽器開啟、點選、填表和截圖能力。