# AI浏览器操作引擎

`浏览器自动化` `AI智能体` `MCP` `DOM操作` `网页抓取`

<div align="center">

### Actionbook

**面向AI智能体的浏览器操作引擎**
<br />
Actionbook 提供最新的操作手册和DOM结构，
<br />
让您的智能体无需猜测即可立即操作任何网站。

[官网](https://actionbook.dev) · [GitHub](https://github.com/actionbook/actionbook) · [X](https://x.com/ActionbookHQ) · [Discord](https://discord.gg/7sKKp7XQ2d)

</div>

<br />

## 目录

- [为什么选择 Actionbook？](#为什么选择-actionbook)
- [快速开始](#快速开始)
- [安装](#安装)
- [使用示例](#使用示例)
- [可用工具](#可用工具)
- [开发](#开发)
- [贡献](#贡献)

## 为什么选择 Actionbook？

### ❌ 没有 Actionbook

构建可靠的浏览器智能体既困难又昂贵：

- **执行缓慢：** 智能体需要花费大量时间解析完整的HTML页面来查找元素。
- **高Token成本：** 向LLM发送整个DOM树会消耗大量上下文窗口。
- **选择器脆弱：** 网站UI更新会立即破坏硬编码的选择器和智能体逻辑。
- **幻觉问题：** 面对复杂、无结构的DOM时，LLM经常猜测出错误的操作。

### ✅ 使用 Actionbook

Actionbook 将包含相关DOM选择器的最新操作手册直接放入您的LLM上下文中。

- **10倍更快：** 智能体访问预计算的"操作手册"，无需探索即可知道该做什么。
- **100倍Token节省：** 智能体不再接收完整HTML页面，而是以简洁的语义JSON定义接收相关DOM元素。
- **弹性自动化：** 操作手册经过维护和版本管理。如果网站发生变化，手册会更新，而不是您的智能体。
- **通用兼容：** 适用于任何LLM（OpenAI、Anthropic、Gemini）和任何AI操作框架。

观看Actionbook如何让智能体将Airbnb搜索任务的完成速度提升10倍。

## 快速开始

2分钟内开始使用Actionbook：

**第一步：安装CLI**

```bash
npm install -g @actionbookdev/cli

# 安装自动化浏览器（Chromium）
actionbook browser install
```

**第二步：与任何AI智能体配合使用**

在使用任何AI编程助手（Claude Code、Cursor等）时，将以下内容添加到您的提示词中：

```
使用 Actionbook 理解并操作网页。
```

智能体将自动使用CLI获取操作手册并执行浏览器操作。

**第三步（可选）：添加技能**

为增强智能体集成，添加Actionbook技能：

```bash
npx skills add actionbook/actionbook
```

## 安装

Actionbook提供三种集成方式：

| 方式 | 最适合 | 安装时间 |
|--------|----------|-------------------|
| **CLI（推荐）** | AI智能体、浏览器自动化、命令行 | < 1分钟 |
| **MCP服务器** | AI IDE（Cursor、Claude Code、VS Code） | < 1分钟 |
| **JavaScript SDK** | 自定义智能体、程序化集成 | < 2分钟 |

### 前提条件

安装前，请确保您具备：

- ✅ **Node.js** >= v18.0.0 （[下载](https://nodejs.org)）

> **💡 提示：** 使用 `node --version` 检查您的Node.js版本
>
> **注意：** Actionbook目前处于公开测试阶段，无需API密钥！

---

### 方式一：CLI（推荐）

全局安装CLI，从命令行或任何AI智能体使用Actionbook。

```bash
npm install -g @actionbookdev/cli

# 安装自动化浏览器（Chromium）
actionbook browser install
```

**基本命令：**

```bash
# 搜索操作手册
actionbook search "airbnb search"

# 通过ID获取操作详情
actionbook get "site/airbnb.com/page/home/element/search-button"

# 浏览器自动化
actionbook browser open airbnb.com
actionbook browser click '[data-testid="search-button"]'
actionbook browser fill 'input[name="location"]' 'Tokyo'
```

---

### 方式二：MCP服务器

如果您使用支持MCP的AI IDE，请选择此方式。

<details>
<summary><b>Cursor</b></summary>

前往：`Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`

粘贴以下配置：

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>Claude Code</b></summary>

运行以下命令：

```bash
claude mcp add actionbook -- npx -y @actionbookdev/mcp@latest --api-key YOUR_API_KEY
```

</details>

<details>
<summary><b>VS Code</b></summary>

将以下内容添加到VS Code设置（JSON）：

```json
{
  "mcp": {
    "servers": {
      "actionbook": {
        "command": "npx",
        "args": ["-y", "@actionbookdev/mcp@latest"]
      }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

将以下内容添加到 `~/.codeium/windsurf/mcp_config.json` 文件：

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

将以下内容添加到 `claude_desktop_config.json` 文件：

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>Cline</b></summary>

前往：`Settings` -> `MCP Servers` -> `Add new MCP server`

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>Zed</b></summary>

将以下内容添加到Zed的settings.json：

```json
{
  "context_servers": {
    "actionbook": {
      "command": {
        "path": "npx",
        "args": ["-y", "@actionbookdev/mcp@latest"]
      }
    }
  }
}
```

</details>

<details>
<summary><b>JetBrains IDEs</b></summary>

前往：`Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)`

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>Amazon Q Developer CLI</b></summary>

将以下内容添加到 `~/.aws/amazonq/mcp.json` 文件：

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>Warp</b></summary>

前往：`Settings` -> `AI` -> `Manage MCP servers`

```json
{
  "actionbook": {
    "command": "npx",
    "args": ["-y", "@actionbookdev/mcp@latest", "--api-key", "YOUR_API_KEY"],
    "env": {},
    "working_directory": null,
    "start_on_launch": true
  }
}
```

</details>

<details>
<summary><b>Roo Code</b></summary>

前往：`Settings` -> `MCP Servers` -> `Add new MCP server`

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>Augment Code</b></summary>

前往：`Settings` -> `MCP Servers` -> `Add Server`

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>Trae</b></summary>

前往：`Settings` -> `MCP Servers` -> `Add Server`

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>Gemini CLI</b></summary>

将以下内容添加到 `~/.gemini/settings.json` 文件：

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "npx",
      "args": ["-y", "@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>使用 Bun</b></summary>

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "bunx",
      "args": ["@actionbookdev/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>使用 Deno</b></summary>

```json
{
  "mcpServers": {
    "actionbook": {
      "command": "deno",
      "args": [
        "run",
        "--allow-all",
        "npm:@actionbookdev/mcp"
      ]
    }
  }
}
```

</details>

---

### 方式三：JavaScript SDK

使用此方式将Actionbook直接集成到基于任何LLM框架构建的自定义AI智能体中。

**第一步：安装SDK**

```bash
# 使用 npm
npm install @actionbookdev/sdk

# 使用 pnpm
pnpm add @actionbookdev/sdk

# 使用 yarn
yarn add @actionbookdev/sdk

# 使用 bun
bun add @actionbookdev/sdk
```

**第二步：基本用法**

```typescript
import { Actionbook } from '@actionbookdev/sdk'

// 初始化客户端（公开测试期间无需API密钥）
const actionbook = new Actionbook()

// 搜索操作手册
const results = await actionbook.searchActions('airbnb search')
console.log(`找到 ${results.length} 个操作：`, results)

// 通过ID获取特定操作
const action = await actionbook.getActionById(results[0].id)
console.log('操作详情：', action)

// 访问选择器
const selector = action.selectors.css ||
                 action.selectors.dataTestId ||
                 action.selectors.ariaLabel

console.log('使用此选择器：', selector)
```

**工具定义：**

每个方法都附带 `description` 和 `params`，便于与任何LLM框架集成。

```typescript
import { Actionbook } from '@actionbookdev/sdk'

const actionbook = new Actionbook()

// 描述
actionbook.searchActions.description  // "按关键词搜索操作手册"

// 参数 - JSON Schema格式
actionbook.searchActions.params.json  // { type: "object", properties: { query: { type: "string" } }, required: ["query"] }

// 参数 - Zod格式
actionbook.searchActions.params.zod   // z.object({ query: z.string() })
```

**集成示例：**

<details>
<summary><b>与 Vercel AI SDK 集成</b></summary>

```typescript
import { Actionbook } from '@actionbookdev/sdk'
import { generateText, tool } from 'ai'
import { openai } from '@ai-sdk/openai'

const actionbook = new Actionbook()

const { text } = await generateText({
  model: openai('gpt-4o'),
  tools: {
    searchActions: tool({
      description: actionbook.searchActions.description,
      parameters: actionbook.searchActions.params.zod,
      execute: async ({ query }) => actionbook.searchActions(query),
    }),
    getActionById: tool({
      description: actionbook.getActionById.description,
      parameters: actionbook.getActionById.params.zod,
      execute: async ({ id }) => actionbook.getActionById(id),
    }),
  },
  maxSteps: 5,
  prompt: '搜索LinkedIn消息操作并获取操作手册',
})
```

</details>

<details>
<summary><b>与 OpenAI SDK 集成</b></summary>

```typescript
import { Actionbook } from '@actionbookdev/sdk'
import OpenAI from 'openai'

const actionbook = new Actionbook()
const openai = new OpenAI()

const tools: OpenAI.ChatCompletionTool[] = [
  {
    type: 'function',
    function: {
      name: 'searchActions',
      description: actionbook.searchActions.description,
      parameters: actionbook.searchActions.params.json,
    },
  },
  {
    type: 'function',
    function: {
      name: 'getActionById',
      description: actionbook.getActionById.description,
      parameters: actionbook.getActionById.params.json,
    },
  },
]

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  tools,
  messages: [{ role: 'user', content: '搜索Google登录操作' }],
})
```

</details>

<details>
<summary><b>与 Anthropic Claude SDK 集成</b></summary>

```typescript
import { Actionbook } from '@actionbookdev/sdk'
import Anthropic from '@anthropic-ai/sdk'

const actionbook = new Actionbook()
const anthropic = new Anthropic()

const tools: Anthropic.Tool[] = [
  {
    name: 'searchActions',
    description: actionbook.searchActions.description,
    input_schema: actionbook.searchActions.params.json,
  },
  {
    name: 'getActionById',
    description: actionbook.getActionById.description,
    input_schema: actionbook.getActionById.params.json,
  },
]

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  tools,
  messages: [{ role: 'user', content: '搜索Twitter发帖操作' }],
})
```

</details>

<details>
<summary><b>与 Google Gemini SDK 集成</b></summary>

```typescript
import { Actionbook } from '@actionbookdev/sdk'
import { GoogleGenAI } from '@google/genai'

const actionbook = new Actionbook()
const genai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY })

const tools = [
  {
    functionDeclarations: [
      {
        name: 'searchActions',
        description: actionbook.searchActions.description,
        parameters: actionbook.searchActions.params.json,
      },
      {
        name: 'getActionById',
        description: actionbook.getActionById.description,
        parameters: actionbook.getActionById.params.json,
      },
    ],
  },
]

const response = await genai.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: [{ role: 'user', parts: [{ text: '搜索YouTube上传操作' }] }],
  config: { tools },
})
```

</details>

<details>
<summary><b>与 Stagehand 集成</b></summary>

```typescript
import { Actionbook } from '@actionbookdev/sdk'
import { tool } from 'ai'

const actionbook = new Actionbook()

const agent = stagehand.agent({
  model: 'openai/gpt-4o',
  tools: {
    searchActions: tool({
      description: actionbook.searchActions.description,
      inputSchema: actionbook.searchActions.params.zod,
      execute: async ({ query }) => actionbook.searchActions(query),
    }),
    getActionById: tool({
      description: actionbook.getActionById.description,
      inputSchema: actionbook.getActionById.params.zod,
      execute: async ({ id }) => actionbook.getActionById(id),
    }),
  },
})

await agent.execute('搜索Airbnb预订操作并获取操作手册')
```

</details>

---

## 示例

在 [playground](./playground) 目录中探索真实世界的示例：

- [**stagehand-agent**](./playground/stagehand-agent) - 使用Stagehand + AI SDK + Actionbook的浏览器自动化智能体
- [**generate-scraper-script**](./playground/generate-scraper-script) - 使用Claude Code生成精确的网页爬虫代码
- [**actionbook-scraper**](./playground/actionbook-scraper) - 使用经过验证的Actionbook选择器的网页爬虫插件
- [**arxiv-viewer**](./playground/arxiv-viewer) - 访问和阅读arXiv上的学术论文
- [**rust-learner**](./playground/rust-learner) - 学习Rust语言特性和crate更新
- [**lib-rs-scraper**](./playground/lib-rs-scraper) - 从lib.rs抓取Rust crate信息

## 可用工具

Actionbook MCP提供以下工具：

__`search_actions`__

根据查询搜索可用的操作手册。

- `query`（必填）：用于查找相关操作手册的搜索查询（例如："airbnb search"、"google login"）

__`get_action_by_id`__

通过ID检索特定的操作手册，包括DOM选择器和分步说明。

- `id`（必填）：操作手册的唯一标识符

## 保持关注

在Github上为Actionbook点星以支持我们并获取最新信息。

加入社区：

- [在Discord上与我们交流](https://discord.gg/7sKKp7XQ2d) - 获取帮助、分享您的智能体并讨论想法
- [在X上关注 @ActionbookHQ](https://x.com/ActionbookHQ) - 产品更新和公告

## 开发

这是一个使用 [pnpm](https://pnpm.io/) 工作区和 [Turborepo](https://turborepo.com/) 的单体仓库。

### 前提条件

- Node.js >= 18（推荐20+）
- pnpm >= 10
- PostgreSQL数据库（本地或托管，如 [Neon](https://neon.tech) / [Supabase](https://supabase.com)）

### 首次设置

1. 安装依赖：

```bash
pnpm install
```

2. 通过将 `.env.example` 复制到以下包中的 `.env` 来配置环境变量：
   - `services/db`
   - `apps/api-service`
   - `services/action-builder`（可选，用于录制）
   - `services/knowledge-builder`（可选，用于知识提取）

3. 运行数据库迁移：

```bash
cd services/db && pnpm migrate
```

### 启动开发服务器

```bash
pnpm dev
```

## 贡献

- **[申请网站](https://actionbook.dev/request-website)** - 建议您希望Actionbook索引的网站。
- **[加入候补名单](https://actionbook.dev)** - 我们目前处于私人测试阶段。如果您有兴趣贡献或使用Actionbook，欢迎加入。

## 许可证

许可证详情请参阅 [LICENSE](LICENSE)。