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 等本地代理工具，使模型能夠專注於理解目標和做出決策，而穩定的瀏覽器操作由本地可複用自動化處理。