## 项目概述

Page Agent 是一个纯 JavaScript 实现的页面内 GUI 代理（in-page GUI agent），允许用户通过自然语言控制网页界面。它由阿里巴巴开源，采用 TypeScript 编写，基于 MIT 许可证发布。Page Agent 的核心优势在于无需浏览器扩展、Python 环境或无头浏览器，只需在网页中引入一段脚本即可为任意网页赋予 AI 代理能力。项目基于 browser-use 的优秀工作构建，专为客户端网页增强设计，而非服务端自动化。

## 核心功能

- **轻松集成**：无需浏览器扩展、Python 或无头浏览器，纯页面内 JavaScript 即可运行。
- **基于文本的 DOM 操作**：不依赖截图或多模态模型，通过文本方式提取和操作 DOM 结构。
- **自带 LLM（BYOK）**：支持主流大语言模型，包括本地部署的模型（如 Ollama），用户可自由配置模型、API 地址和密钥。
- **可选 Chrome 扩展**：支持跨标签页任务，扩展提供多标签控制、历史记录、任务审批等功能。
- **MCP Server（Beta）**：通过 MCP 协议允许外部 Agent 客户端（如 Claude Desktop）控制浏览器。
- **内置工具系统**：提供点击、输入、滚动、选择等常用操作工具，并支持自定义工具扩展。
- **生命周期钩子**：支持在代理执行过程中挂载自定义逻辑。
- **数据脱敏**：可在发送给 LLM 前转换页面内容，保护敏感信息。
- **多语言支持**：界面支持英文和中文。

## 适用与不适用场景

**适用场景：**

- SaaS AI Copilot：为产品快速添加 AI 副驾驶，无需重写后端。
- 智能表单填写：将多步骤工作流简化为一句自然语言指令，适用于 ERP、CRM 和管理后台。
- 无障碍增强：通过自然语言、语音指令或屏幕阅读器让网页更易访问。
- 跨页面 Agent：通过 Chrome 扩展实现跨标签页的自动化任务。
- MCP 集成：为现有 Agent 客户端增加浏览器控制能力。

**不适用场景：**

- 服务端自动化：Page Agent 专为客户端网页增强设计，不适用于服务端自动化。
- 跨页面导航：核心库仅支持单页应用，无法在页面间导航（需借助扩展）。
- 视觉识别：依赖 DOM 结构，不支持基于截图的视觉识别。
- 复杂交互：不支持悬停、拖拽、Canvas 操作等高级交互。

## 技术架构与依赖

Page Agent 是一个使用 npm workspaces 管理的 monorepo，主要包含以下包：

- `page-agent`：主入口，包含内置 UI 面板。
- `@page-agent/core`：核心代理逻辑，无 UI。
- `@page-agent/llms`：LLM 客户端，支持重试和请求修补。
- `@page-agent/page-controller`：DOM 操作和视觉反馈，独立于 LLM。
- `@page-agent/ui`：面板和国际化。
- `@page-agent/mcp`：MCP 服务器，用于通过扩展控制浏览器。

依赖方面，项目使用 TypeScript、Vite 构建，支持 Zod 校验，并依赖 browser-use 的 DOM 处理组件和提示词。开发环境要求 Node.js ^22.13 或 >=24，npm >=11。

## 安装与快速开始

**一行代码集成（使用免费 Demo LLM）：**

```html
<script
    src="https://cdn.jsdelivr.net/npm/page-agent@1.12.2/dist/iife/page-agent.demo.js"
    crossorigin="anonymous"
></script>
```

> 注意：Demo CDN 使用免费测试 LLM API，仅用于技术评估，使用即表示同意相关条款。可通过 `?autoInit=false` 禁用自动初始化。

**NPM 安装：**

```bash
npm install page-agent
```

```javascript
import { PageAgent } from 'page-agent'

const agent = new PageAgent({
    model: 'qwen3.5-plus',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: 'YOUR_API_KEY',
    language: 'zh-CN',
})

await agent.execute('点击登录按钮')
```

## 典型使用方法

**编程式使用：**

```javascript
const agent = new PageAgent({
    model: 'gpt-5.2',
    baseURL: 'https://api.openai.com/v1',
    apiKey: 'sk-...',
})

await agent.execute('填写表单并提交')
```

**自定义系统提示词：**

```javascript
const agent = new PageAgent({
    // ...
    systemPrompt: '你是一个专注于表单填写的助手。',
})
```

**使用本地模型（Ollama）：**

```javascript
const agent = new PageAgent({
    baseURL: 'http://localhost:11434/v1',
    apiKey: 'NA',
    model: 'qwen3:14b',
})
```

**通过 Chrome 扩展控制多标签页：** 安装扩展后，可在侧边栏中管理多个标签页，并下达跨页任务。

**通过 MCP 控制浏览器：** 使用 `@page-agent/mcp` 包，配置 MCP 客户端（如 Claude Desktop）连接扩展。

## 配置与部署要点

- **LLM 配置**：必须配置模型名称、API 地址和 API 密钥。对于不需要密钥的部署（如本地模型），可省略 `apiKey`。
- **安全注意事项**：客户端脚本会内联 API 密钥，分发时需谨慎。建议使用 BYOK 模式，避免使用免费测试 API 处理敏感数据。
- **扩展配置**：扩展的配置（API 端点、密钥、模型）存储在浏览器本地，不同步到云端。
- **MCP 服务器**：默认绑定到 localhost，仅允许本地连接。
- **部署限制**：核心库仅支持单页应用，跨页任务需使用扩展。
- **性能调优**：可通过 `stepDelay` 调整步骤间隔，通过 `maxSteps` 控制最大步骤数。

## 限制、风险与许可证

**已知限制：**

- 仅支持单页应用，无法跨页面导航（核心库）。
- 不进行视觉识别，依赖 DOM 结构。
- 不支持悬停、拖拽、Canvas 操作等复杂交互。
- 免费测试 API 可能限流、降级或随时停止，不保证可用性。

**风险：**

- 使用免费测试 API 时，数据可能经过中国大陆服务器，请遵守当地数据保护法规。
- 页面内容发送给 LLM 前虽经简化，但不保证敏感信息完全移除，请谨慎使用。
- 客户端脚本可能暴露 API 密钥，请勿在公开环境中分发。

**许可证：** MIT License。项目基于 browser-use（MIT License）构建，DOM 处理组件和提示词源自该项目的贡献。

## 官方链接

- GitHub 仓库：https://github.com/alibaba/page-agent
- 在线 Demo：https://alibaba.github.io/page-agent/
- 文档：https://alibaba.github.io/page-agent/docs/introduction/overview
- Chrome 扩展：https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj
- npm 包：https://www.npmjs.com/package/page-agent
- 最新版本：v1.12.2（2026-07-16）

## 信息来源和分析时间

本指南基于 2026 年 7 月 16 日获取的 GitHub 仓库 alibaba/page-agent 的 README、文档和变更日志编写。仓库资料未提供更详细的信息，如完整的 API 参考或贡献指南，请参阅官方文档。