Snapshot

Snapshot 是 AI Agent 讀取網頁的方式。它會把目前頁面整理成精簡的結構化文字，並為按鈕、輸入框、連結等可操作元素分配暫時編號，例如 @1、@2。Agent 會根據這份 Snapshot 決定下一步操作，而不是讀取整頁 HTML 或猜測螢幕座標。

它解決什麼問題

網頁對人而言是視覺介面，對 Agent 而言則是包含數萬個 Token 的 HTML、腳本、樣式與動態狀態。直接傳給 LLM 有兩個常見代價：

• Token 成本高。一般後台頁面可能就有 30k Token，每一步操作前都要重新讀取。
• 抓不到重點。完整 DOM 裡大部分內容（樣式、腳本、隱藏節點）和決策無關，反而干擾判斷。

Snapshot 以瀏覽器的 accessibility tree（無障礙樹，瀏覽器為螢幕閱讀器維護的語意視圖）為基礎，把頁面壓縮成大約幾百個 Token：

• 頁面標題和當前 URL。
• 可見文字和主要結構。
• 可點擊、可填寫、可選擇的交互元素，以及它們的角色與名稱。
• 每個交互元素對應的臨時編號 @N。

Agent 讀完這份 Snapshot 後就能決定要點擊哪個按鈕、填寫哪個輸入框，不必讀取完整 HTML，也不需要螢幕座標。

@N 引用是什麼

快照裡每個可交互元素會被分配一個臨時編號：

@1 [input]  "搜索"
@2 [button] "提交"
@3 [link]   "下一頁"

Agent 用這些編號執行操作，例如 await click('@2')。

@N 只對當前這一次快照有效。頁面變化後（跳轉、刷新、彈窗、表單提交、切標籤頁、局部重新渲染），舊編號可能失效。可靠的做法是頁面變化後重新拍一次快照，而不是長期保存 @N。

如果後續需要穩定引用某個元素，請使用 Snapshot 輸出裡的 loc=... 作為穩定 selector，或直接撰寫 CSS selector。詳見 ego-browser。

你什麼時候會感知到 Snapshot

絕大多數情況下你不需要手動操作快照，Agent 會自己讀。你可能在兩種場景裡看到它：

1. Agent 說「重新獲取快照」或「頁面快照」，表示它檢測到頁面變化、需要重讀當前狀態。
2. 任務結果裡附帶快照片段作為複核證據。

給 Agent 的任務描述

Snapshot 讓 Agent 看得清頁面，但任務邊界要由你來定。一個好的任務描述包含：

• 目標頁面或網站。
• 需要讀取、填寫、點擊或下載什麼。
• 不允許做什麼（刪除、發佈、付款、發送郵件等）。
• 遇到驗證碼、支付、授權時是否暫停。
• 預期的傳回格式（表格、摘要、螢幕截圖、本機檔案路徑）。

例子：

開啟我的 GitHub Notifications，篩選出需要我 review 的 PR，列出儲存庫名稱、標題和連結。
不要歸檔，不要標記已讀。

打開後臺訂單頁，篩選昨天的訂單，下載 CSV。
出現登入驗證或匯出確認時停下來讓我處理，並告訴我檔案儲存位置。

複核 Agent 的結果

任務完成後，可以從這些線索判斷 Agent 是否做對：

• 是否說明存取過的頁面和關鍵動作。
• 傳回結果是否包含可核對的資訊（標題、編號、連結、金額、時間）。
• 下載任務是否提供本機檔案路徑。
• 修改或提交類任務是否在最終確認前暫停過。
• 頁面是否還保留在 Space 中，可以切過去查看。

結果看起來不對時，讓 Agent 重新拍一次當前頁面的快照，而不是基於之前的回答繼續推測。

常見情況

為什麼 Agent 說引用失效？

頁面在上一次快照之後變化了，讓它重新拍一次快照即可。

Snapshot 能讀取所有內容嗎？

不一定。不可見內容、圖片裡的文字、複雜 canvas、受限制的跨網域 iframe 可能無法完整出現在 Snapshot 裡。在這些情況下，Agent 可能需要搭配螢幕截圖、文字擷取或人工確認。

Snapshot 會修改資料嗎？

不會。Snapshot 只讀取頁面結構。真正改變頁面狀態的是後續的點擊、填寫、提交、上傳、刪除等操作。

我需要記住 @1、@2 嗎？

不需要。把它理解成「當前頁面裡的臨時元素編號」，Agent 負責使用，你負責把目標和邊界講清楚。