WebCap：面向AI代理的可複用瀏覽器能力工具

WebCap 是一款專為AI代理設計的本地優先瀏覽器自動化工具包。它使代理能夠檢查真實的瀏覽器標籤頁、執行可複用的頁面指令碼、將成功的工作流儲存以供後續命令列使用，並將自然語言的瀏覽器請求轉化為AI原生的使用者指令碼。代理透過 web-cap CLI 與 WebCap 互動，CLI 會自動管理所需的本地執行時，使用者無需單獨啟動命令。

快速開始包括安裝 Web Cap 技能和瀏覽器擴充套件：使用 npx skills add edgestorage/web-cap 安裝技能，然後從釋出頁面下載並安裝 Chrome 擴充套件，最後透過 web-cap session-status 檢查連線。WebCap 提供了豐富的示例，例如在 Hacker News 上執行可複用指令碼總結前五個帖子的評論，或者用一句話隱藏 YouTube Gaming 的“熱門直播”板塊，且未來訪問時該板塊仍保持隱藏。

WebCap 採用指令碼優先的方法，與傳統的操作優先工具不同。代理可以在頁面內執行包含 Playwright 風格輔助函式的 JavaScript，並將有用的指令碼註冊為可複用的瀏覽器技能。這使得 WebCap 更適合需要檢查頁面結構、適應特定產品 UI 的工作流。其核心價值在於將驗證過的瀏覽器操作轉化為可複用的指令碼和工作流，從而提高準確性和執行速度，減少令牌消耗。

WebCap 提供了豐富的功能：瀏覽器擴充套件執行時、命令列介面、Playwright 風格的頁面輔助函式（如 inspect、wait、click、fill、query 和文本讀取）、本地指令碼登錄檔、AI原生使用者指令碼生成、瀏覽器標籤建立和事件監控命令，以及本地優先的狀態儲存。代理還可以使用共享的 Web Cap Hub 倉庫中的現成指令碼，該倉庫收集了常見網站的即用指令碼並提供了編寫新站點特定工作流的示例。

在證據收集方面，WebCap 能夠在指令碼執行前後進行觀察：拍攝可見元素的快照，跟蹤 DOM 變化，然後返回可見元素的差異，包括新增、刪除和更新的項。執行證據還可以包括瀏覽器端事件，如開啟的標籤頁、URL 變化、重新載入、滾動變化、受控的點選、鍵盤輸入和指令碼呼叫。這意味著代理不僅獲得指令碼宣告的 JSON 結果，還能檢查瀏覽器在指令碼執行後的可見變化，這對於驗證、恢復以及決定是否將新成功的指令碼註冊為可複用能力非常有用。

代理導向的細節包括：頁面定位（指令碼定義包含目標站點、URL 模式、頁面提示、標籤、型別、狀態和版本），兩種指令碼型別（讀取指令碼用於檢查或提取頁面狀態，操作指令碼用於操作頁面或觸發瀏覽器端變化），使用者交接觀察（wait-events 命令等待使用者完成瀏覽器操作，然後以 JSON Lines 格式流式傳輸互動路徑），本地執行歷史（內聯指令碼在本地跟蹤狀態和結果後設資料），成功守衛註冊（僅當執行結果包含 ok: true 時才持久化指令碼），以及標籤感知執行（命令可以針對特定 --tab-id，預設跟隨活動的連線瀏覽器標籤頁）。

未來路線圖包括 Web Cap Hub CLI（提供可複用指令碼的快速安裝和下載支援）、Firefox 擴充套件、客戶端構建和分發改進（減少對 Node.js 和 npm 環境的依賴）、瀏覽器端 AI 聊天和本地 AI 工具整合（提供瀏覽器內 AI 聊天入口點，連線 Codex 和 Claude Code 等本地工具），以及將指令碼編譯移至客戶端以減少擴充套件大小和複雜性。

系統架構如下：代理透過 CLI 命令與 Web Cap CLI 互動，CLI 管理本地執行時，透過 WebSocket 連線瀏覽器擴充套件，最終與真實的瀏覽器標籤頁通訊。CLI 自動處理執行時啟動和連線細節。專案包含多個包：extension/（瀏覽器擴充套件入口點和執行時程式碼）、lib/（CLI、本地執行時、指令碼登錄檔和編排邏輯）、shared/（共享協議、指令碼模式和驗證幫助程式）、skills/（可透過 skills CLI 安裝的代理技能）、tests/（Vitest 覆蓋）、scripts/（專案實用程式和生成的執行時幫助程式）。

開發要求 Node.js 20 或更新版本、pnpm 9.x 以及基於 Chromium 的瀏覽器。快速開始開發：安裝依賴（pnpm install）、啟動擴充套件開發構建（pnpm dev）、載入擴充套件並開啟頁面。CLI 命令包括 script-execute（在選定的瀏覽器標籤頁中執行指令碼程式碼，接受 --timeout-ms、--script-file、--input-file、--no-evidence 和 --register 等可選設定）、browser-new-tab、session-status 和 wait-events。指令碼模型是 JavaScript 函式，接收 JSON 輸入並返回 JSON 輸出，執行時注入 Playwright 風格的頁面輔助函式。對於多頁面指令碼，可以使用 cap.goto(url, nextInput) 導航到 URL 並重新執行指令碼，需透過 nextInput 顯式傳遞所有跨頁面欄位。

總體而言，WebCap 為 AI 代理提供了一個高效、可複用的瀏覽器自動化層，適用於 Codex、Claude Code 等本地代理工具，使模型能夠專注於理解目標和做出決策，而穩定的瀏覽器操作由本地可複用自動化處理。