内容
# Crawlio 代理
[](https://www.npmjs.com/package/crawlio-browser)
[](LICENSE)
## [文档](https://docs.crawlio.app/browser-agent/overview) | [API 参考](https://docs.crawlio.app/browser-agent/tools) | [Chrome 扩展](https://www.crawlio.app/browser-agent)
MCP 服务器，通过 CDP 对实时 Chrome 浏览器提供全面控制。包含 100 个工具（93 个浏览器工具 + 3 个提取工具 + 3 个录制工具 + 1 个编译工具），具备框架感知智能、类型化证据基础设施和置信度跟踪的发现能力 — 捕获静态爬虫无法看到的内容。
> **注意：** 该仓库取代了 [`crawlio-browser-mcp`](https://github.com/AshDevFr/crawlio-browser-mcp)。所有开发工作现在都在这里进行。
**链接：**
- [Chrome 应用商店](https://chromewebstore.google.com/detail/crawlio-for-chrome/amkgjkmjjihbaigdebmphghodhblmopg?utm_source=github-readme&utm_medium=readme&utm_campaign=browser-agent-funnel&utm_content=readme-cws-badge&utm_term=install-extension)
- [文档](https://docs.crawlio.app/browser-agent/overview?utm_source=github-readme&utm_medium=readme&utm_campaign=docs-traffic&utm_content=readme-docs-link&utm_term=read-docs)
- [网站](https://www.crawlio.app/browser-agent?utm_source=github-readme&utm_medium=readme&utm_campaign=browser-agent-funnel&utm_content=readme-website-link&utm_term=learn-more)
## 何时使用 Crawlio 代理
当您的 AI 需要与**真实浏览器**交互时 — 单页应用、身份验证页面、动态内容、JS 渲染框架。与无头浏览器工具不同，Crawlio 代理连接到您的**实际 Chrome**，通过轻量级扩展，使 AI 可以访问您的登录会话、cookie 和完整的浏览器状态。
**Crawlio 代理 vs 无头浏览器工具：** 无头工具启动独立的浏览器进程。Crawlio 代理连接到您现有的 Chrome — 无需独立浏览器，无需登录流程，可完全访问您的标签页和会话。
## 快速入门
1. 安装 [Chrome 扩展](https://www.crawlio.app/browser-agent)
2. 运行初始化向导：
```bash
npx crawlio-browser init
```
就这样。自动检测并配置 14 个 MCP 客户端：Claude Code、Cursor、VS Code、Codex、Gemini CLI、Claude Desktop、ChatGPT Desktop、Windsurf、Cline、Zed、Goose、OpenCode、MCPorter 和 Cline CLI。
### 初始化向导选项
```bash
npx crawlio-browser init # 默认：代码模式，stdio 传输
npx crawlio-browser init --full # 完整模式（100 个独立工具）
npx crawlio-browser init --portal # 门户模式（持久化 HTTP 服务器）
npx crawlio-browser init --cloudflare # 添加 Cloudflare MCP（89 个工具，无 wrangler）
npx crawlio-browser init --dry-run # 显示将发生的情况
npx crawlio-browser init --yes # 跳过提示（CI / 脚本安装）
npx crawlio-browser init -a claude # 目标特定 MCP 客户端
```
### 传输模式
| 模式 | 命令 / URL | 协议 | 最适合 |
|------|--------------|----------|----------|
| **stdio** | `npx crawlio-browser` | JSON-RPC via stdin/stdout | Claude Desktop, Cursor, Windsurf — 客户端管理进程生命周期 |
| **门户（HTTP）** | `POST http://127.0.0.1:3001/mcp` | MCP Streamable HTTP | Claude Code, ChatGPT Desktop — 服务器在会话重启时存活 |
| **门户（SSE）** | `GET /sse` + `POST /message` | 服务器发送事件 | 需要 SSE 传输的旧客户端 |
门户模式推荐用于 Claude Code — 服务器在上下文压缩和会话重启时持续存在。在 macOS 上，`--portal` 安装了一个 launchd 代理，以便在登录时自动启动。
### 手动设置（任意客户端）
<details>
<summary><b>每个客户端的手动配置</b></summary>
**Claude Desktop** — 添加到 `claude_desktop_config.json`：
```json
{ "mcpServers": { "crawlio-browser": { "command": "npx", "args": ["-y", "crawlio-browser"] } } }
```
**Claude Code（门户模式）** — 启动 `npx crawlio-browser --portal`，然后添加到 `.mcp.json`：
```json
{ "mcpServers": { "crawlio-browser": { "type": "http", "url": "http://127.0.0.1:3001/mcp" } } }
```
**Claude Code（stdio）：**
```bash
claude mcp add crawlio-browser -- npx -y crawlio-browser
```
**Cursor** — 添加到 `.cursor/mcp.json`：
```json
{ "mcpServers": { "crawlio-browser": { "command": "npx", "args": ["-y", "crawlio-browser"] } } }
```
**Windsurf** — 添加到 Windsurf 设置 > MCP：
```json
{ "mcpServers": { "crawlio-browser": { "command": "npx", "args": ["-y", "crawlio-browser"] } } }
```
**Cline（VS Code）** — 添加到 `settings.json`：
```json
{ "cline.mcpServers": { "crawlio-browser": { "command": "npx", "args": ["-y", "crawlio-browser"] } } }
```
**ChatGPT Desktop** — 设置 > 集成 > MCP：
URL：`http://127.0.0.1:3001/mcp` | 类型：可流式 HTTP
</details>
## 工作原理
```
AI 客户端（stdio/http） --> MCP 服务器（Node.js） --> Chrome 扩展（MV3）
crawlio-browser WebSocket -> CDP
```
MCP 服务器通过 WebSocket 与 Chrome 扩展通信。扩展通过 Chrome DevTools 协议（CDP）控制浏览器。
## 功能
### 框架感知智能
每个 `execute` 调用都会探测浏览器的框架签名，并注入一个具有框架原生访问器的“智能”对象。React 状态、Vue 响应性、Next.js 路由、Shopify购物车数据 — 17 个框架命名空间，跨 4 个层级，在运行时检测，并在每次导航时重建。AI 不会查询通用 DOM；而是查询框架自己的数据结构。
### 基于证据的分析
方法模式在代码模式的基础上添加了更高阶的方法和类型化的证据系统。`smart.extractPage()` 在单个调用中运行 7 个并行操作 — 页面捕获、性能指标、安全状态、字体检测、元提取、辅助功能审计和移动设备就绪检查。失败的操作会产生类型化的 `CoverageGap` 记录，而不是沉默的 `null`。使用 `smart.finding()` 创建的发现会根据支持数据的缺失自动调整置信度。
### 会话记录和重放
将浏览器交互记录为结构化数据，然后将它们编译为可重用的 SKILL.md 自动化脚本。12 个交互工具在记录期间自动拦截 — 点击、输入、导航、滚动 — 每个工具都捕获参数、结果、时间以及页面 URL。单个 `compileRecording()` 调用会将会话转换为确定性的自动化脚本。
### 自动稳定和行动能力
每个变异操作（`click`、`type`、`navigate`、`select_option`）在执行前都会运行行动能力检查 — 轮询可见性、维度、启用状态和叠加层检测。操作后，渐进式回退 settle 延迟（`[0, 20, 100, 100, 500]ms`）会等待 DOM 突变稳定。AI 不需要操作之间的手动 `sleep()` 调用。
## 架构：JIT 上下文运行时
JIT 上下文 MCP 运行时是一种分层执行架构，其中每一层都吸收了原本会落在模型上的复杂性。模型看到三个工具和一个干净的 SDK。表面下的一切都是运行时吸收现实。
```
┌───────────────────────────────────┐
│ AI 模型（LLM） │
│ 编写代码、读取错误、循环 │
└───────────────┬───────────────────┘
│ 3 个工具：search、execute、connect_tab
▼
┌─────────────────────────────────────────────────────────────────┐
│ JIT 上下文 MCP 运行时 │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ 方法模式 │ │
│ │ 行为协议 + 高阶方法 │ │
│ │ scrollCapture · waitForIdle · extractPage · comparePages │ │
│ │ detectTables · extractTable · waitForNetworkIdle · │ │
│ │ extractData │ │
│ │ │ │
│ │ ↳ 吸收：行为差异、临时组成、 │ │
│ │ 不一致的输出形状、数据提取模式 │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ 多态上下文 │ │
│ │ 17 个框架命名空间，实时注入 │ │
│ │ react · vue · angular · nextjs · shopify · ... │ │
│ │ │ │
│ │ ↳ 吸收：框架不透明度、压缩代码、 │ │
│ │ DevTools 钩子复杂度 │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ 行动能力引擎 │ │
│ │ 7 个核心智能方法，内置韧性 │ │
│ │ click · type · navigate · waitFor · evaluate · │ │
│ │ snapshot · screenshot │ │
│ │ │ │
│ │ ↳ 吸收：DOM 时间、液压延迟、CSS 动画、 │ │
│ │ 禁用状态、重叠元素 │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ 绑定 IPC 桥 │ │
│ │ WebSocket ↔ Chrome 扩展、消息队列、 │ │
│ │ 心跳、自动重连、过时检测 │ │
│ │ │ │
│ │ ↳ 吸收：连接中断、标签页刷新、 │ │
│ │ 端口冲突、扩展生命周期 │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ 133 个原始命令 （bridge.send） │ │
│ │ 通过 Chrome 扩展的 CDP 级浏览器控制 │ │
│ └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────┐
│ 实时 Chrome 浏览器 │
│ 持久会话、实时 DOM、 │
│ 框架运行时、用户状态 │
└───────────────────────────────────┘
```
### 每一层吸收的内容
| 层 | 没有它 | 有它 |
|-------|-----------|---------|
| **绑定 IPC 桥** | 脚本在标签页刷新时崩溃，挂起的命令在重新连接时丢失，启动时端口冲突 | 具有消息队列（100 消息容量）的弹性 WebSocket，心跳超时检测（15 秒间隔），自动重连和排干 |
| **行动能力引擎** | `click('#btn')` 在按钮渲染、CSS 转换期间或叠加层覆盖时触发 | 渐进式轮询（存在 → 有尺寸 → 可见 → 不禁用 → 不遮挡）并带有 `[0, 20, 100, 100, 500]ms` 回退 |
| **多态上下文** | 模型看到压缩的 `<div>` 元素；读取 React 状态需要确切的钩子路径、渲染器映射和纤维根 API | 运行时探测实时 JS 环境，检测 17 个框架，注入命名空间方法（`smart.react.getVersion()`、`smart.nextjs.getData()`） |
| **方法模式** | 模型临时组成基元 - 不一致的滚动循环、错过的边缘情况、变化的返回形状 | 8 个测试方法编码正确的模式；行为协议约束工作流 |
### 执行生命周期
1. **发现** — 模型调用 `search("page capture performance")` 并获取相关命令的文档
2. **框架检测** — 运行时探测实时 DOM，检测活动框架，构造多态 `smart` 对象，具有适当的命名空间
3. **作用域组装** — 模型的代码编译为异步函数，并注入参数：`bridge`（133 命令）、`crawlio`（HTTP 客户端）、`sleep`、`TIMEOUTS`、`smart`（7 个核心 + 8 个高阶 + 多达 17 个框架命名空间）、`compileRecording`
4. **执行** — 方法模式方法组成下层：`extractPage()` 发出 7 个并行 `bridge.send()` 调用；`click()` 运行行动能力引擎；`react.getVersion()` 评估框架特定表达式
5. **错误恢复（代理 REPL）** — 发生故障时，浏览器保持在产生错误的确切状态。模型读取结构化错误，调整并再次调用 `execute`。框架缓存持续存在 — 除非 URL 更改，否则不会重新检测
### 设计原则
1. **向下吸收复杂性** — 每个难度类别（连接管理、DOM 时间、框架检测、多步骤组成）都由最适合它的层处理。模型仅在顶部遇到干净的接口。
2. **根据目标塑造 SDK** — 多态上下文系统检测页面内容并重塑可用方法以匹配。模型针对稳定接口编写；运行时在底层进行适配。
3. **在周期之间保留状态** — 绑定的架构意味着模型可以失败、学习和重试针对相同的实时环境 — 将错误处理从“从头开始”转换为“调整和继续”。
### 比较
| 维度 | 标准 MCP | Cloudflare 代码模式 | JIT 上下文运行时 |
|-----------|-------------|---------------------|---------------------|
| **上下文中的工具** | 50-100+ 模式 | 2 个（`search`、`execute`） | 3 个（`search`、`execute`、`connect_tab`） |
| **执行环境** | 无（工具调用） | V8 隔离（无状态） | 本地异步沙盒（有状态，绑定到实时浏览器） |
| **DOM 访问** | 通过单个工具调用 | 无 | 实时、持久、框架感知 |
| **框架感知** | 无 | 无 | 17 个命名空间，实时注入 |
| **行动韧性** | 模型必须处理计时 | 无（无 DOM） | 内置行动能力轮询 + settle 延迟 |
| **错误恢复** | 重新调用单个工具 | 重新创建隔离 | 在相同实时状态下重新执行（代理 REPL） |
| **多步骤模式** | 模型临时组成 | 模型编写循环 | 8 个测试的高阶方法 + 行为协议 |
[阅读完整架构指南 →](https://docs.crawlio.app/browser-agent/overview)
## 两种模式
### 代码模式（3 个工具）— 默认
将 100 个工具折叠为 3 个高级别工具，约 95% 的模式令牌减少：
| 工具 | 描述 |
|------|-------------|
| `search` | 通过关键词发现可用命令 |
| `execute` | 在作用域中运行异步 JS，带有 `bridge`、`crawlio`、`smart`、`sleep` 和 `compileRecording` |
| `connect_tab` | 连接到浏览器标签页 |
```javascript
// 导航并截图
await bridge.send({ type: 'browser_navigate', url: 'https://example.com' }, 30000);
await sleep(2000);
const screenshot = await bridge.send({ type: 'take_screenshot' }, 10000);
return screenshot;
```
### 完整模式（100 个工具）
将所有工具直接公开给 LLM。启用 `--full`：
```bash
npx crawlio-browser init --full
```
## 智能对象
在代码模式下，`smart` 对象提供具有自动等待和行动能力检查的框架感知帮助程序。
### 核心方法
| 方法 | 描述 |
|--------|-------------|
| `smart.evaluate(expression)` | 通过 CDP 在页面中执行 JS |
| `smart.click(selector, opts?)` | 自动等待点击，延迟 500ms |
| `smart.type(selector, text, opts?)` | 自动等待输入，延迟 300ms |
| `smart.navigate(url, opts?)` | 导航，延迟 1000ms |
| `smart.waitFor(selector, timeout?)` | 轮询直到元素可操作 |
| `smart.snapshot()` | 可访问性树快照 |
| `smart.screenshot()` | 全页截图（base64 PNG） |
### 高阶方法
| 方法 | 描述 |
|--------|-------------|
| `smart.scrollCapture(opts?)` | 滚动到底部，在每个位置捕获截图。检测卡住的滚动、底部检测、部分上限和滚动重置。 |
| `smart.waitForIdle(timeout?)` | 基于 MutationObserver 的空闲检测 — 等待 500ms 安静窗口。超时硬上限为 15s。替换盲 `sleep()` 调用。 |
| `smart.extractPage(opts?)` | 1 个调用中的 7 个并行操作 — 页面捕获、性能、安全、字体、元、辅助功能、移动设备准备。返回类型化的 `PageEvidence`，带有 `CoverageGap[]` | 任何失败的内容 |
| `smart.comparePages(urlA, urlB)` | 导航到两个 URL，在每个 URL 上运行 `extractPage()`，返回一个 `ComparisonScaffold`，包含 11 个维度、共享/缺失字段和可比较的指标。 |
### 类型化证据
用于结构化分析发现并具有置信度传播的方法：
| 方法 | 描述 |
|--------|-------------|
| `smart.finding(data)` | 创建一个验证的 `Finding`，包含声明、证据、sourceUrl、置信度和方法。拒绝具有特定错误的格式不正确输入。 |
| `smart.findings()` | 获取所有会话累积的发现（返回副本） |
| `|smart.findings()` | 获取所有会话累积的发现（返回副本） |
| `smart.clearFindings()` | 重置会话发现和覆盖间隙 |
当发现的维度与活动间隙匹配时，会自动限制置信度：
| 输入置信度 | 活动间隙 | 输出 |
| --- | --- | --- |
| `high` | `reducesConfidence: true` | `medium` + `confidenceCapped: true` |
| `medium` | `reducesConfidence: true` | `low` + `confidenceCapped: true` |
| `low` | 任意 | `low`（下限） |
| 任意 | 无匹配间隙 | 不变 |
### 框架命名空间
当检测到框架时，智能对象会暴露框架特定的帮助函数：
<details>
<summary><b>React</b> — <code>smart.react</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `getVersion()` | 版本字符串和包类型 |
| `getRootCount()` | React 根组件数量 |
| `hasProfiler()` | 是否有性能分析器可用 |
| `isHookInstalled()` | DevTools 钩子是否已安装 |
</details>
<details>
<summary><b>Vue.js</b> — <code>smart.vue</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `getVersion()` | Vue 版本字符串 |
| `getAppCount()` | Vue 应用实例数量 |
| `getConfig()` | 应用配置对象 |
| `isDevMode()` | DevTools 是否已启用 |
</details>
<details>
<summary><b>Angular</b> — <code>smart.angular</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `getVersion()` | ng-version 属性值 |
| `isDebugMode()` | 调试 API 是否可用 |
| `isIvy()` | Ivy 编译器是否活跃 |
| `getRootCount()` | Angular 根元素数量 |
| `getState()` | 完整状态对象 |
</details>
<details>
<summary><b>Svelte</b> — <code>smart.svelte</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `getVersion()` | Svelte 版本字符串 |
| `getMeta()` | Svelte 元数据对象 |
| `isDetected()` | Svelte 是否被检测到 |
</details>
<details>
<summary><b>Redux</b> — <code>smart.redux</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `isInstalled()` | Redux DevTools 是否已安装 |
| `getStoreState()` | 完整存储状态 |
</details>
<details>
<summary><b>Alpine.js</b> — <code>smart.alpine</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `getVersion()` | Alpine 版本字符串 |
| `getStoreKeys()` | 存储对象键 |
| `getComponentCount()` | `[x-data]` 组件数量 |
</details>
<details>
<summary><b>Next.js</b> — <code>smart.nextjs</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `getData()` | `__NEXT_DATA__` 对象 |
| `getRouter()` | 路由状态（路径，查询，asPath） |
| `getSSRMode()` | SSR 模式（混合，应用路由器，静态） |
| `getRouteManifest()` | 当前页面数据 |
</details>
<details>
<summary><b>Nuxt</b> — <code>smart.nuxt</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `getData()` | `__NUXT__` 对象 |
| `getConfig()` | 应用配置 |
| `isSSR()` | 是否服务器渲染 |
</details>
<details>
<summary><b>Remix</b> — <code>smart.remix</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `getContext()` | `__remixContext` 对象 |
| `getRouteData()` | 状态加载数据 |
</details>
<details>
<summary><b>Shopify</b> — <code>smart.shopify</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `getShop()` | 商店元数据（主题，本地化，货币） |
| `getCart()` | 购物车对象 |
</details>
<details>
<summary><b>WordPress</b> — <code>smart.wordpress</code></summary>
| 方法 | 返回值 |
|--------|---------|
| `isWP()` | WordPress 是否存在 |
| `getRestUrl()` | REST API 端点 |
| `getPlugins()` | 活动插件列表 |
</details>
<details>
<summary><b>更多框架</b> — Gatsby, WooCommerce, Laravel, Django, Drupal, jQuery</summary>
| 命名空间 | 方法 |
|-----------|---------|
| `smart.gatsby` | `getData()`, `getPageData()` |
| `smart.woocommerce` | `getParams()` |
| `smart.laravel` | `getCSRF()` |
| `smart.django` | `getCSRF()` |
| `smart.drupal` | `getSettings()` |
| `smart.jquery` | `getVersion()` |
</details>
## 方法模式
方法模式是一种建立在代码模式之上的领域层。它为 `execute` 沙盒添加了高阶方法、类型证据系统和行为协议，而不改变工具表面。模型仍然看到三个工具。相同的 `smart` 对象。底层仍然是 133 命令目录。变化的是 `execute` 内部发生了什么。
### 成熟度阶梯
| 层 | 优化目标 | 行为差异 | 证据质量 |
|-------|---------------|---------------------|-----------------|
| **原始 MCP** (100 工具) | 完整性 | 高 — 平坦的工具列表，无组合指导 | 无 — 无结构文本 |
| **代码模式** (3 工具) | 标记效率 | 中等 — 正确的基元，临时组合 | 无 — 模型定义的形状 |
| **方法模式 v1** (+ 8 方法 + 协议) | 一致性 | 低 — 适当的方法，协议约束 | 约定 — `{ finding, evidence, url }` |
| **方法模式 v2** (+ 类型证据 + 差距 + 置信度) | 正确性 | 最小 — 类型模式，工具强制执行的结果 | 结构 — 类型记录，差距跟踪，置信度传播 |
### 架构
```
┌────────────────────────────────────────────────────────────┐
│ 执行沙盒 │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 行为协议 (网络研究技能) │ │
│ │ 获取 → 标准化 → 分析 │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ 证据基础设施 │ │
│ │ finding() · findings() · clearFindings() │ │
│ │ 类型记录 · 覆盖范围 · 置信度传播 │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ 高阶方法 [8] │ │
│ │ scrollCapture · waitForIdle · extractPage · │ │
│ │ comparePages · detectTables · extractTable · │ │
│ │ waitForNetworkIdle · extractData │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ 智能核心 [7 方法] │ │
│ │ evaluate · click · type · navigate · waitFor · │ │
│ │ snapshot · screenshot │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ 框架命名空间 [最多 17 个，JIT 注入] │ │
│ │ react · vue · angular · nextjs · shopify · ... │ │
│ ├──────────────────────────────────────────────────────┤ │
│ │ bridge.send() — 133 个原始命令 │ │
│ └──────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
```
每个层都编码了更多的领域知识。`bridge.send({ type: "capture_page" })` 捕获一个页面。`smart.extractPage()` 捕获一个页面并运行性能指标、安全状态、字体检测、辅助功能分析和移动设备就绪检查 — 七个操作，一个调用，补充数据失败时优雅地失败，类型化的间隙用于任何失败的内容。
### 证据基础设施
**覆盖范围** — 当 `extractPage()` 中的补充操作失败时，它们不会静默返回 `null`。而是记录一个类型化的间隙，包含维度、原因、影响以及是否降低相关发现的置信度：
```javascript
// 示例间隙，来自失败的性能指标调用
{ dimension: "performance", reason: "CDP domain disabled", impact: "method-failed", reducesConfidence: true }
```
**工具强制执行的结果** — `smart.finding()` 在工具级别验证每个字段。模型无法生成一个不满足模式的结果 — 它要么返回一个有效的结果，要么得到一个明确的错误。结果在会话中通过 `smart.findings()` 累积。
**会话聚合** — 结果和覆盖范围在 `execute` 调用之间持续存在。模型可以在多个调用中生成结果，然后通过 `smart.findings()` 检索完整的结果集。通过 `smart.clearFindings()` 重置。
### 端到端示例：竞争性审计
```javascript
// 1. 提取和比较两个站点（包括脚手架和间隙）
const comparison = await smart.comparePages(
'https://acme.com',
'https://rival.com'
);
// 2. 生成结果 — 置信度根据数据可用性自动调整
smart.finding({
claim: '竞争对手的加载速度比 Acme 快 2.3 倍，最大内容加载时间',
evidence: [
`Acme LCP: ${comparison.siteA.performance?.webVitals?.lcp}ms`,
`竞争对手 LCP: ${comparison.siteB.performance?.webVitals?.lcp}ms`,
],
sourceUrl: 'https://acme.com',
confidence: 'high',
method: 'comparePages + extractPage performance metrics',
dimension: 'performance', // 如果性能数据失败，置信度上限为“medium”
});
smart.finding({
claim: 'Acme 有 12 张图片没有替代文本；竞争对手有 0 张',
evidence: [
`Acme imagesWithoutAlt: ${comparison.siteA.accessibility?.imagesWithoutAlt}`,
`竞争对手 imagesWithoutAlt: ${comparison.siteB.accessibility?.imagesWithoutAlt}`,
],
sourceUrl: 'https://acme.com',
confidence: 'high',
method: 'comparePages + extractPage accessibility summary',
dimension: 'accessibility',
});
// 3. 捕获视觉证据
await smart.navigate('https://acme.com');
await smart.waitForIdle();
const acmeVisuals = await smart.scrollCapture({ maxSections: 5 });
// 4. 返回累计会话结果 + 视觉证据
return {
findings: smart.findings(),
scaffold: comparison.scaffold,
gaps: { acme: comparison.siteA.gaps, rival: comparison.siteB.gaps },
visualEvidence: { acme: acmeVisuals.sectionCount + ' sections captured' },
};
```
## 示例
#### 导航、提取和分析
```javascript
// 连接到活动标签，提取结构化页面证据
const page = await smart.extractPage();
const finding = smart.finding({
claim: `站点使用 ${page.capture.framework?.name || '未检测到框架'}`,
evidence: [`框架：${JSON.stringify(page.capture.framework)}`],
sourceUrl: page.meta?.canonical || '活动标签',
confidence: 'high',
method: 'extractPage 框架检测',
});
return { page: page.meta, finding };
```
#### 移动设备模拟 + 截图
```javascript
// 模拟 iPhone 并捕获
await bridge.send({ type: 'emulate_device', device: 'iPhone 14' }, 10000);
await smart.navigate('https://example.com');
await smart.waitForIdle();
const screenshot = await smart.screenshot();
return screenshot;
```
#### 记录和编译自动化
```javascript
// 记录浏览器会话，然后编译为可重用的技能
await bridge.send({ type: 'start_recording' }, 10000);
await smart.navigate('https://example.com');
await smart.click('button.submit');
await smart.type('#email', 'test@example.com');
const session = await bridge.send({ type: 'stop_recording' }, 10000);
return compileRecording(session.session, 'signup-flow');
```
#### 拦截和模拟网络
```javascript
// 阻止分析，模拟 API 响应
await bridge.send({
type: 'browser_intercept',
pattern: '*analytics*',
action: 'block'
}, 10000);
await bridge.send({
type: 'browser_intercept',
pattern: '*/api/user',
action: 'mock',
body: JSON.stringify({ name: '测试用户' }),
statusCode: 200
}, 10000);
await smart.navigate('https://example.com');
return await smart.snapshot();
```
## 会话记录
将浏览器会话记录为结构化数据，然后将它们编译为可重用的自动化技能。12 种交互工具在记录期间自动拦截（点击、输入、导航、滚动等），捕获参数、结果、计时和页面 URL。
```javascript
// 在代码模式下：记录、交互、编译
await bridge.send({ type: 'start_recording' }, 10000);
// ... 与页面交互 ...
const session = await bridge.send({ type: 'stop_recording' }, 10000);
const skill = compileRecording(session.session, 'my-automation');
return skill;
```
在完整模式下，记录可用作 4 个独立工具：`start_recording`、`stop_recording`、`get_recording_status` 和 `compile_recording`。
## 自动稳定
变更工具（`browser_click`、`browser_type`、`browser_navigate`、`browser_select_option`）使用行动能力检查：
1. **预检**：在执行操作前检查元素的可见性、稳定性和启用状态
2. **操作**：调度 CDP 命令
3. **稳定后**：等待 DOM 变更稳定，逐步回退 `[0, 20, 100, 100, 500]ms`
这意味着 AI 不需要手动在操作之间添加 `sleep()` 或 `waitFor()` 调用 — 工具会自动处理 SPA 渲染延迟。
## 框架检测
使用全局变量、DOM 标记、元标签、HTTP 头和脚本 URL 检测 **64 种技术**，涵盖 4 个层级：
| 层级 | 框架 | 信号强度 |
|------|-----------|----------------|
| **元框架** | Next.js, Nuxt, SvelteKit, Remix, Gatsby | 唯一全局变量 + 父检测 |
| **核心** | React, Vue.js, Angular, Svelte, Astro, Qwik, SolidJS, Lit, Preact | 全局变量 + DOM 标记 |
| **CMS 和平台** | WordPress, Shopify, Webflow, Squarespace, Wix, Drupal, Magento, Ghost, Bubble | 元标签 + 全局变量 |
| **库和工具** | jQuery, Bootstrap, Tailwind CSS, Alpine.js, HTMX, Turbo, Stencil, Redux, Ember.js, Backbone.js | DOM + 全局变量 |
多框架检测返回一个 **主要** 框架（元框架优先）以及一个包含完整堆栈的 `subFrameworks` 数组。
## 工具参考
<details>
<summary><b>所有 100 个工具</b> — 连接、捕获、导航、网络、存储、模拟等</summary>
### 连接和状态
| 工具 | 描述 |
|------|-------------|
| `connect_tab` | 通过 URL、标签 ID 或活动标签连接到浏览器标签 |
| `disconnect_tab` | 与当前标签断开连接 |
| `list_tabs` | 列出所有具有 ID 和 URL 的打开标签 |
| `get_connection_status` | 检查 CDP 连接状态 |
| `reconnect_tab` | 强制重新连接以修复过时的连接 |
| `get_capabilities` | 列出所有工具及其可用性 |
### 页面捕获
| 工具 | 描述 |
|------|-------------|
| `capture_page` | 完整捕获：框架 + 网络 + 控制台 + DOM |
| `detect_framework` | 检测 JavaScript 框架和版本 |
| `start_network_capture` | 开始记录网络请求 |
| `stop_network_capture` | 停止记录并返回捕获的请求 |
| `get_console_logs` | 获取控制台日志（错误、警告、信息） |
| `get_cookies` | 获取 cookie（敏感值被遮蔽） |
| `get_dom_snapshot` | 简化的 DOM 树，支持 shadow DOM 和 iframe |
| `take_screenshot` | 截图为 base64 PNG |
| `get_response_body` | 获取捕获的网络请求的响应正文 |
### 导航和交互
| 工具 | 描述 |
|------|-------------|
| `browser_navigate` | 导航到 URL（自动稳定） |
| `browser_click` | 按 CSS 选择器点击元素（自动稳定，左/右/中，修饰符） |
| `browser_double_click` | 双击元素 |
| `browser_type` | 在元素中输入文本（自动稳定） |
| `browser_press_key` | 按键盘键（Enter、Tab、Escape、快捷键） |
| `browser_hover` | 悬停在元素上 |
| `browser_select_option` | 按值选择 `<option>` （自动稳定） |
| `browser_scroll` | 滚动页面或元素 |
| `browser_drag` | 从一个元素拖到另一个元素 |
| `browser_file_upload` | 上传文件到 `<input type="file">` |
| `browser_wait` | 等待 N 毫秒 |
| `browser_wait_for` | 等待元素状态（可见、隐藏、附加、分离） |
### 网络
| 工具 | 描述 |
|------|-------------|
| `browser_intercept` | 拦截 URL 模式的请求，修改头部或模拟响应 |
| `emulate_network` | 网络节流（离线、3G、4G、WiFi 预设） |
| `set_cache_disabled` | 禁用/启用浏览器缓存 |
| `set_extra_headers` | 为所有请求添加自定义头部 |
| `get_websocket_connections` | 列出活动 WebSocket 连接 |
| `get_websocket_messages` | 获取 WebSocket 消息历史 |
### 帧和标签页
| 工具 | 描述 |
|------|-------------|
| `get_frame_tree` | 获取帧层次结构（主帧 + iframe） |
| `switch_to_frame` | 切换执行上下文到 iframe |
| `switch_to_main_frame` | 切换回主帧 |
| `create_tab` | 用 URL 创建新标签页 |
| `close_tab` | 按 ID 关闭标签页 |
| `switch_tab` | 按 ID 聚焦标签页 |
### Cookie 和存储
| 工具 | 描述 |
|------|-------------|
| `set_cookie` | 设置 cookie（支持 CDP 的 httpOnly） |
| `delete_cookies` | 删除按名称/域/路径的 cookie |
| `get_storage` | 读取 localStorage 或 sessionStorage |
| `set_storage` | 写入存储项目 |
| `clear_storage` | 清除所有存储项目 |
| `get_databases` | 列出 IndexedDB 数据库 |
| `query_object_store` | 查询 IndexedDB 对象存储 |
| `clear_database` | 清除或删除 IndexedDB 数据库 |
### 对话框
| 工具 | 描述 |
|------|-------------|
| `get_dialog| | 获取待处理的 JS 对话框（alert/confirm/prompt） |
| `handle_dialog` | 接受或拒绝对话框 |
### 模拟
| 工具 | 描述 |
|------|-------------|
| `set_viewport` | 设置视口尺寸 |
| `set_user_agent` | 重写用户代理字符串 |
| `emulate_device` | 模拟设备（iPhone、iPad、Pixel、Galaxy、桌面） |
| `set_geolocation` | 重写地理位置坐标 |
| `set_stealth_mode` | 反检测模式（选择加入，修补 webdriver 指纹） |
### 安全
| 工具 | 描述 |
|------|-------------|
| `get_security_state` | TLS 证书详细信息，协议，密码 |
| `ignore_certificate_errors` | 忽略证书错误用于暂存环境 |
### 服务工作线程
| 工具 | 描述 |
|------|-------------|
| `list_service_workers` | 列出所有服务工作线程注册 |
| `stop_service_worker` | 停止/注销服务工作线程 |
| `bypass_service_worker` | 绕过服务工作线程进行网络请求 |
### DOM 操作
| 工具 | 描述 |
|------|-------------|
| `set_outer_html` | 替换元素的 HTML |
| `set_attribute` | 设置元素属性 |
| `remove_attribute` | 删除元素属性 |
| `remove_node` | 从 DOM 中删除元素 |
### CSS 和 JS 覆盖率
| 工具 | 描述 |
|------|-------------|
| `start_css_coverage` / `stop_css_coverage` | 跟踪哪些 CSS 规则被使用 |
| `start_js_coverage` / `stop_js_coverage` | 跟踪哪些 JS 代码被执行 |
| `get_computed_style` | 获取元素的计算样式 |
| `force_pseudo_state` | 强制 :hover, :focus, :active 状态 |
</details>
### 性能与内存
| 工具 | 描述 |
|------|-------------|
| `get_performance_metrics` | Chrome 指标 + Web 重要指标（LCP、CLS、FID） |
| `get_dom_counters` | 统计 DOM 节点、文档、事件监听器 |
| `force_gc` | 强制垃圾回收 |
| `take_heap_snapshot` | V8 堆快照摘要 |
### PDF 与无障碍
| 工具 | 描述 |
|------|-------------|
| `print_to_pdf` | 生成 PDF（自定义纸张、边距、方向） |
| `get_accessibility_tree` | 用于屏幕阅读器审计的无障碍树 |
### 目标与上下文
| 工具 | 描述 |
|------|-------------|
| `get_targets` | 列出所有 Chrome 目标（页面、Worker、扩展） |
| `attach_to_target` | 将 CDP 会话附加到任何目标 |
| `create_browser_context` | 创建隔离（类似隐身）的上下文 |
### 可视化调试
| 工具 | 描述 |
|------|-------------|
| `highlight_element` | 用彩色叠加层高亮显示元素 |
| `show_layout_shifts` | 可视化 CLS 区域 |
| `show_paint_rects` | 可视化绘制/重绘区域 |
### 会话记录
| 工具 | 描述 |
|------|-------------|
| `start_recording` | 开始记录浏览器会话 |
| `stop_recording` | 停止记录并返回会话数据 |
| `get_recording_status` | 检查记录状态 |
| `compile_recording` | 将会话编译为 SKILL.md 自动化 |
### Crawlio 应用集成
> 可选 — 需要在本地运行 [Crawlio.app](https://crawlio.app)。
| 工具 | 描述 |
|------|-------------|
| `extract_site` | 启动活动标签页网址的 Crawlio 爬取 |
| `get_crawl_status` | 获取爬取进度和状态 |
| `get_enrichment` | 获取浏览器增强数据 |
| `get_crawled_urls` | 获取已爬取的网址及其状态和分页 |
| `enrich_url` | 导航 + 捕获 + 一步提交增强 |
</details>
## 要求
- **Node.js** >= 18
- **Chrome**（或 Chromium）且已安装 [Crawlio Agent 扩展](https://www.crawlio.app/browser-agent)
- **Crawlio.app**（可选）— 用于站点爬取和增强
## 资源
- [文档](https://docs.crawlio.app/browser-agent/overview)
- [API 参考](https://docs.crawlio.app/browser-agent/tools)
- [产品页面](https://www.crawlio.app/browser-agent)
- [Chrome 扩展](https://www.crawlio.app/browser-agent)
- [npm 包](https://www.npmjs.com/package/crawlio-browser)
- [更新日志](https://github.com/Crawlio-app/crawlio-browser-agent/releases)
- [前置仓库](https://github.com/AshDevFr/crawlio-browser-mcp) — 该项目取代 `crawlio-browser-mcp`
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器