Web Cap 完全指南：为 AI Agent 构建可复用的浏览器能力层
当 AI 编码 Agent（如 Claude Code、Codex）需要操控网页时，传统做法是让 Agent 每次从头探索页面结构、定位按钮、填写表单。这种方式的问题很直观：每次都要消耗大量 Token 去”重新认识”同一个页面，且重复操作容易出错。
Web Cap 换了一个思路——把浏览器操作拆解为可复用的脚本能力，让 Agent 一次验证、永久复用。
为什么需要”脚本优先”的浏览器自动化
现有浏览器自动化工具的常见模式是”动作优先”：Agent 被告知「点击某个 selector」「填写某个输入框」「截一张图」。这套模式的问题是：
- 每次从头探索：Agent 每次都要读取页面 DOM，理解布局，找到正确的控制元素
- 错误恢复成本高：一次点击失败后，Agent 需要重新分析页面状态再尝试
- 经验无法积累：今天学会的操作，明天换个 Agent 会话又要重学
Web Cap 的脚本优先（script-first） 思路正好反过来：
让 Agent 在页面内运行 JavaScript，把验证过的操作流程注册为可复用脚本，后续直接调用，不需要重新发现。
安装：两条命令打通
Web Cap 的安装分两步——安装 CLI 和安装浏览器扩展。
安装 CLI
最直接的方式是通过 npm 全局安装：
npm install -g web-capability
安装后可用 web-cap 命令。确认连通性：
web-cap session-status
如果安装了 skills CLI，也可以用 skill 方式安装（会自动处理 CLI 安装和连接检查）：
npx skills add edgestorage/web-cap
安装浏览器扩展
- 打开 Web Cap Releases 页面
- 下载
chrome.zip文件 - 解压该文件
- 在 Chrome 中打开
chrome://extensions - 开启开发者模式
- 将解压后的文件夹拖入扩展页面
- 在扩展详情页开启 Allow User Scripts
扩展安装后，CLI 就能通过 WebSocket 连接到浏览器标签页执行脚本了。
核心概念：脚本模型
Web Cap 的核心是脚本模型。脚本是一个导出 default async function 的 JavaScript 模块，接收 JSON 输入，返回 JSON 输出：
export default async function (input) {
const title = await page.title();
const text = await page.locator(input.selector).textContent();
return {
ok: true,
title,
text,
};
}
运行时会在脚本执行期间注入 Playwright 风格的 page helper，支持：
page.locator()/page.getByRole()定位元素locator.click()/locator.fill()操作元素locator.textContent()/locator.waitFor()读取和等待page.title()获取页面标题
成功门槛注册：只有在返回 { ok: true } 时，加 --register 才会把脚本存入本地注册表。这个设计保证了注册表里的脚本都是经过验证的。
两种脚本类型
| 类型 | 用途 | 示例 |
|---|---|---|
read 脚本 | 检查或提取页面状态 | 获取 GitHub 仓库的 star 数、抽取表格数据 |
act 脚本 | 操作页面或触发变化 | 填写表单、点击按钮、隐藏内容区块 |
CLI 实战：四种典型用法
1. 执行一次性脚本
web-cap script-execute \
--tab-id 1 \
--script "export default async function (input) { return { ok: true, input }; }" \
--input '{"hello":"world"}' \
--timeout-ms 30000
2. 加载文件脚本并注册复用
web-cap script-execute \ --tab-id 1 \ --script-file ./script.js \ --input-file ./input.json \ --register
将大段脚本写入文件来执行，--register 仅在返回 ok: true 时持久化。
3. 复用社区脚本 Hub
Web Cap Hub 收集了面向常见网站的现成脚本：
git clone https://github.com/edgestorage/web-cap-hub.git
cd web-cap-hub
web-cap script-execute \
--tab-id 1 \
--script-file .web-cap/github.com/read-repository-summary.js \
--input '{"owner":"edgestorage","repo":"web-cap"}'
4. 用户接手观察
当 Agent 遇到需要用户手动操作的步骤时，可以用 wait-events 等待并观察用户行为：
web-cap wait-events --duration-ms 10000
该命令会输出用户操作的 JSON Lines 流——包括点击、输入、页面跳转等事件，Agent 可以根据这些推断用户做了什么，然后继续工作。
执行证据：Agent 的”眼睛”
Web Cap 最实用的设计之一是执行证据（evidence）系统。开启后，CLI 会在脚本执行前后做三件事：
- 执行前：记录页面可见元素快照
- 执行中：跟踪 DOM 变化
- 执行后：重新采样变化区域，返回包含
added、removed、updated的可见元素差异
证据级别可配置：
web-cap config set evidence all # 全部证据 web-cap config set evidence events,visibleElements # 仅事件+可见元素
这意味着 Agent 拿到的不仅是脚本返回的 JSON，还能看到”执行后页面实际发生了什么”——这对失败恢复和决定是否注册脚本非常关键。
适用场景
场景 1：AI Agent 做代码审查前的页面检查
让 Claude Code 打开 GitHub PR 页面，提取 diff 信息和评论列表，然后进行代码审查。用 Web Cap 封装为 read-pr.js 脚本，后续每次审查时直接调用。
场景 2：数据分析 Agent 抽取网页信息
让 Codex 登录内部管理后台，从数据看板页面抽取关键指标。注册为 dashboard-extract.js 脚本后，每次需要数据时一行命令搞定。
场景 3：自动化测试 Agent
Agent 需要反复测试某个 Web 应用的功能流程（登录 → 搜索 → 导出）。每个步骤编写独立的 act 脚本组合使用，以降低每次运行的环境依赖。
与其他工具的对比
| 维度 | Web Cap | Playwright | Browser Use |
|---|---|---|---|
| 定位 | Agent 浏览器能力层 | 开发者测试框架 | Agent 浏览器操控框架 |
| 脚本复用 | 内置注册表 + Hub | 需自建 | 无原生复用机制 |
| 执行证据 | 内置 DOM 差异采集 | 截图对比 | 部分支持 |
| 用户接手 | wait-events 原生支持 | 不支持 | 需自建 |
| 安装复杂度 | npm + 扩展 | npm + 驱动 | pip + 浏览器驱动 |
注意事项
- Chrome 为主：当前扩展在 Chromium 系浏览器上验证，Firefox 支持在路线图中
- Node.js 20+：CLI 依赖 Node.js 环境，需要确保版本
- 受限页面不可用：
chrome://、about:等受限页面不在支持范围内 - 发布前建议手动验证：对复杂脚本，建议先加载扩展做一次真实页面测试
总结
Web Cap 的核心理念是：让 Agent 的浏览器操作从”每次即兴发挥”变成”可积累的能力库”。脚本优先的设计配合执行证据系统和社区 Hub，将 AI Agent 访问网页的方式从”每次都像第一次逛陌生网站”提升为”像熟练工一样走预设路径”。
对于频繁需要与 Web 页面交互的 AI 编码 Agent 来说，这是一个值得添加到工具链中的轻量级能力层。
项目信息：GitHub edgestorage/web-cap · Apache-2.0 许可 · TypeScript 实现 · 6 GitHub Stars