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 等本地代理工具，使模型能够专注于理解目标和做出决策，而稳定的浏览器操作由本地可复用自动化处理。