Page Agent 项目分析报告

分析日期：2026-07-06

---

一、项目介绍

1.1 项目概述

Page Agent 是阿里巴巴开源的一款纯客户端 JavaScript GUI Agent。它的核心理念是："把 AI Agent 直接嵌入到你的网页中，用自然语言控制界面"。用户无需安装浏览器扩展、Python 环境或无头浏览器，只需在网页中引入一行 <script> 标签，即可让 AI 自动理解网页结构并执行点击、填表、滚动等操作 [1]。

项目受 browser-use 启发，其 DOM 处理组件和 Prompt 设计来自 browser-use，但定位完全不同：Page Agent 专为客户端 Web 增强设计，而非服务端自动化。Playwright/browser-use 是从外部"操控"浏览器（像遥控器），Page Agent 是从内部"增强"网页（像植入的智能芯片）[2]。

1.2 项目信息

项目	详情
项目名称	Page Agent
项目地址	https://github.com/alibaba/page-agent
项目官网/文档	https://alibaba.github.io/page-agent/
在线 Demo	https://alibaba.github.io/page-agent/
npm 包	page-agent（周下载量 ~25,516）
作者/组织	阿里巴巴（Alibaba），主要维护者 Simon (gaomeng1900)
Stars	23,100+（截至 2026 年 7 月）
当前版本	v1.11.0（2026 年 7 月 3 日发布）
开源协议	MIT License
主要语言	TypeScript 80.7%、JavaScript 12.3%、CSS 5.7%、HTML 1.3%
首次发布	2025 年 9 月 23 日
提交数	1,085+
npm 版本数	74 个

1.3 项目示意图

项目 README 中包含 demo 演示视频截图，展示了 Page Agent 在网页右下角的交互面板。用户输入自然语言指令后，Agent 会在面板中展示思考过程、执行步骤和操作结果，同时在页面上高亮被操作的元素。曾登上 Hacker News 首页，引发广泛讨论。

---

二、项目亮点

2.1 纯文本 DOM 操作，无需截图

Page Agent 不截屏、不使用多模态 LLM。它将 DOM 树序列化为带数字索引的文本结构，每个可交互元素分配一个 [N] 标记，LLM 只需返回 click_element_by_index(2) 这样的工具调用即可。任何支持 function calling 的纯文本 LLM 都能驱动它，Token 成本远低于图像方案 [3]。

DOM 序列化示例：

URL: https://example.com/login
Title: 登录 - My App

[0]<input placeholder="用户名" />
[1]<input type="password" placeholder="密码" />
[2]<button>登录</button>
[3]<a>注册账号</a>

2.2 纯客户端运行，零后端部署

所有代码在浏览器 JavaScript 运行时中执行。通过 CDN 一行 <script> 标签或 npm install 即可集成，无需后端服务、无需 Python 环境、无需无头浏览器 [1]。

2.3 ReAct 循环 + 反思模型

Agent 内置经典的 ReAct 循环（Observe → Think → Act），每一步调用 LLM 前强制模型进行反思，回答三个问题 [3]：

反思项	说明
evaluation_previous_goal	上一步效果评估——成功还是失败？
memory	需要记住的关键信息——什么值得保存？
next_goal	下一步目标——现在要做什么？

这保证了长任务中不会"忘记"已完成的步骤，有效避免 Agent 陷入循环。

2.4 自备 LLM（Bring Your Own LLM）

支持任何兼容 OpenAI API 规范的大模型，包括 Qwen、GPT-5.x、Claude、DeepSeek、Gemini、Ollama 本地模型等 [4]。

2.5 安全可控

安全机制	说明
操作白名单/黑名单	限制 Agent 可执行的工具类型
数据脱敏（Data Masking）	通过 transformContent 钩子过滤敏感内容
自定义知识库注入	通过 systemPrompt 注入业务规则
生命周期钩子	beforeStep/afterStep 拦截每一步操作

2.6 与同类项目的差异化优势

对比维度	Page Agent	browser-use	Playwright
运行位置	浏览器端 JS，同进程	服务端 Python	服务端 Node/Python
是否需要截图	否（纯文本 DOM）	是（依赖截图）	不适用
是否需要多模态 LLM	否（纯文本 LLM）	是	不适用
集成复杂度	一行 <script> 标签	需后端服务	需后端服务
依赖	仅浏览器	Python + 浏览器二进制	Node/Python + 浏览器
设计定位	客户端 Web 增强	服务端自动化	测试/爬虫
目标用户	Web 开发者/产品团队	爬虫/Agent 开发者	QA/测试工程师
Token 成本	低（纯文本）	高（图像 Token）	不适用

---

三、项目运行环境

3.1 硬件要求

• 无特殊硬件要求
• 如需本地部署 LLM（如 Ollama），建议 GPU 显存 24GB 以上（如 RTX 3090），推荐使用 qwen3:14b 及以上规模模型 [4]

3.2 操作系统支持

• 所有现代操作系统（Windows、macOS、Linux）
• 核心依赖仅为浏览器，跨平台无差异

3.3 软件依赖

开发环境：

依赖	版本要求
Node.js	^22.22.1 或 >= 24
npm	^11.6.3
浏览器	任何现代浏览器（Chrome、Edge、Firefox、Safari）

生产环境（使用方）：

• 仅需现代浏览器，无其他依赖
• 需要接入 LLM API（OpenAI 兼容接口）

本地 LLM 部署（可选）：

# Ollama 配置示例
$env:OLLAMA_CONTEXT_LENGTH=64000
$env:OLLAMA_HOST="0.0.0.0:11434"
$env:OLLAMA_ORIGINS="*"
ollama serve

3.4 安装步骤

方式一：CDN 快速体验（一行代码）

<script src="https://cdn.jsdelivr.net/npm/page-agent@1.11.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>

国内镜像：

<script src="https://registry.npmmirror.com/page-agent/1.11.0/files/dist/iife/page-agent.demo.js" crossorigin="true"></script>

方式二：NPM 安装（生产环境）

npm install page-agent

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('点击登录按钮')

---

四、项目代码介绍

4.1 代码架构图（Monorepo 架构）

page-agent/
├── packages/
│   ├── page-agent/              # AI 核心代理（npm: page-agent）
│   │   ├── PageAgent            # 代理主类（含 UI 面板），协调工具和 LLM
│   │   ├── tools/               # LLM 工具定义，封装各类操作能力
│   │   ├── ui/                  # UI 组件和面板，提供人机交互界面
│   │   └── llms/                # LLM 集成层，对接各类大模型
│   ├── core/                    # 核心引擎（npm: @page-agent/core）
│   │   └── PageAgentCore        # 无 UI 的 Headless Agent
│   ├── page-controller/         # DOM 操作层（npm: @page-agent/page-controller）
│   │                            # 负责 DOM 提取、元素交互，独立于 LLM
│   ├── ui/                      # 共享 UI 组件
│   ├── llms/                    # 共享 LLM 客户端
│   ├── extension/               # Chrome 扩展（跨页面任务）
│   ├── mcp/                     # MCP Server（Beta）
│   └── website/                 # 文档和演示站点
├── docs/                        # 项目文档
├── scripts/                     # 构建脚本
├── package.json                 # 根包配置（workspaces 管理）
├── tsconfig.base.json           # TypeScript 基础配置
└── README.md

架构设计原则：

1. 分层设计：AI 决策（page-agent/core）与页面操作（page-controller）分离，DOM 操作层可独立复用
2. 工具化思想：所有操作封装为工具，LLM 像调用函数一样使用，支持自定义工具扩展
3. 纯前端无后端：通过纯前端技术实现核心能力，避免后端部署复杂度
4. 事件驱动：使用类型安全的事件总线实现组件间通信 [5]

4.2 核心模块介绍

4.2.1 PageAgent（page-agent 包）

完整的 Agent 类，继承自 PageAgentCore，内置 UI 面板。自动创建 PageController 实例。适用于大多数场景。

class PageAgent extends PageAgentCore {
    panel: Panel
    pageController: PageController
    constructor(config: PageAgentConfig)
}

4.2.2 PageAgentCore（core 包）

无 UI 的核心 Agent 类，适用于自定义 UI 或 Headless 场景 [6]。

class PageAgentCore extends EventTarget {
    status: 'idle' | 'running' | 'completed' | 'error' | 'stopped'
    history: HistoricalEvent[]
    task: string
    pageController: PageController
    tools: Map<string, PageAgentTool>

    execute(task: string): Promise<ExecutionResult>
    stop(): Promise<void>
    dispose(): void
}

关键配置项：

• maxSteps：每任务最大步数（默认 40）
• language：输出语言（'en-US' | 'zh-CN'）
• customTools：自定义工具扩展
• transformContent：页面内容转换（用于数据脱敏）
• systemPrompt：完全覆盖系统 Prompt
• enableJavaScriptExecution：启用 JS 执行工具（实验性）
• beforeStep/afterStep：生命周期钩子（实验性）

4.2.3 PageController（page-controller 包）

负责 DOM 提取和元素交互，独立于 LLM。将页面状态结构化输出为 LLM 可消费的格式 [7]。

关键方法：

方法	功能
getBrowserState()	获取结构化浏览器状态（URL、标题、简化 HTML）
clickElement(index)	按索引点击元素
inputText(index, text)	在输入框填写文字
selectDropdownOption(index, text)	选择下拉选项
scroll(options)	垂直滚动
scrollHorizontally(options)	水平滚动

配置项：

• enableMask：操作时显示遮罩层
• viewportExpansion：视口扩展（-1 表示提取整个页面）
• excludeElements/includeElements：排除/强制包含的元素
• extraAttributes：额外提取的 HTML 属性

4.2.4 内置工具系统（9 个工具）

工具	功能
click_element_by_index	按索引点击元素
input_text	在输入框填写文字
select_dropdown_option	选择下拉框选项
scroll	垂直滚动页面
scroll_horizontally	水平滚动
execute_javascript	执行任意 JS（支持 AbortSignal）
wait	等待 1-10 秒
ask_user	向用户提问（人机协作）
done	任务完成，返回结果

4.3 核心代码解析

4.3.1 ReAct 循环核心逻辑

Page Agent 的 ReAct 循环是项目的核心。其工作流程为：

Observe（观察）→ Think（思考）→ Act（执行）→ 循环直到完成

每一步首先调用 PageController.getBrowserState() 获取当前页面的序列化 DOM 快照，然后将这个快照与操作历史一起发送给 LLM，LLM 返回工具调用指令（如 click_element_by_index(2)），Agent 调用 PageController 执行操作 [3]。

反思模型在每个步骤强制执行三个问题：evaluation_previous_goal（上一步效果评估）、memory（需要记住的关键信息）、next_goal（下一步目标），确保长任务中 Agent 保持上下文连贯。

4.3.2 初始化与执行（用户入口）

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',
})

const result = await agent.execute('点击登录按钮，填写用户名为 test@example.com')
console.log(result.success)  // true or false
console.log(result.data)     // 任务结果描述
console.log(result.history)  // 完整执行历史

4.3.3 Headless 模式（PageAgentCore）

import { PageAgentCore } from '@page-agent/core'
import { PageController } from '@page-agent/page-controller'

const pageController = new PageController({
    enableMask: true,
    viewportExpansion: -1,  // 提取整个页面
})

const agent = new PageAgentCore({
    pageController,
    baseURL: 'https://api.openai.com/v1',
    apiKey: 'your-api-key',
    model: 'gpt-5.2',
})

// 监听事件
agent.addEventListener('statuschange', () => {
    console.log('Status:', agent.status)
})
agent.addEventListener('activity', (e) => {
    const activity = (e as CustomEvent).detail
    console.log('Activity:', activity.type)  // thinking | executing | executed | retrying | error
})

await agent.execute('Fill in the form with test data')

Headless 模式通过事件总线提供完整的执行可观测性，支持 statuschange、activity 等事件，便于集成到自定义 UI 中 [6]。

4.3.4 自定义 PageController（非浏览器环境）

import { PageAgentCore } from '@page-agent/core'
import type { PageController } from '@page-agent/page-controller'

class PuppeteerPageController implements PageController {
    async getBrowserState() {
        // Puppeteer 实现：提取页面 DOM 并序列化
    }
    async clickElement(index: number) {
        // 通过 Puppeteer 执行点击
    }
    async inputText(index: number, text: string) {
        // 通过 Puppeteer 填写文本
    }
    async scroll(options: { down: boolean; numPages: number }) {
        // 通过 Puppeteer 执行滚动
    }
}

const agent = new PageAgentCore({
    pageController: new PuppeteerPageController(),
    baseURL: 'https://api.openai.com/v1',
    apiKey: 'your-api-key',
    model: 'gpt-5.2',
})

PageController 接口设计允许在非浏览器环境（如 Puppeteer、Playwright）中复用 Agent 核心逻辑，只需实现接口即可。这体现了架构分层设计的优势 [7]。

---

五、项目应用与评价

5.1 应用场景

场景	描述	典型例子
SaaS AI Copilot	为产品嵌入 AI 副驾驶，无需重写后端	用户说"把上周销售数据导出成 Excel"，Agent 自动定位导出按钮、选时间范围、点击确认
智能表单填写	将 20 次点击浓缩为一句自然语言	ERP/CRM 中一句话完成"按上次模板填客户信息"
老旧系统智能化	一行代码让 Legacy 系统变身 AI 助手	企业 OA 系统加 AI 操控能力，不动后端
无障碍增强	自然语言操作任何网页	视障用户配合读屏软件和语音指令使用复杂网页
客服系统升级	客服机器人从"说教"变"实干"	不再告诉用户"请点击某某按钮"，而是直接帮用户完成操作
交互式教学	AI 边操作边讲解	演示"如何提交报销申请"，新员工一看就会
跨页面 Agent	跨系统自动操作（需 Chrome 扩展）	在 A 系统查订单 → 到 B 系统建工单
MCP 控制	让外部 Agent 客户端控制浏览器	Claude Desktop 通过 MCP 远程操控网页

5.2 项目优点

1. 集成成本极低：CDN 一行 <script> 标签或 npm install 即可使用，无需后端改造，是业界集成门槛最低的 GUI Agent 方案。
2. 纯前端实现：无需后端部署、Python 环境、无头浏览器，所有代码在浏览器 JS 运行时中执行，降低运维成本。
3. 无需多模态 LLM：纯文本 DOM 操作，任何支持 function calling 的 LLM 即可驱动，Token 成本远低于图像方案。
4. 安全性设计完善：支持操作权限控制（白名单/黑名单）、数据脱敏、自定义知识库注入，适合企业级场景。
5. 对开发者友好：TypeScript 全栈、MIT 协议、Monorepo 结构清晰、文档完善，npm 已有 74 个版本迭代。
6. 扩展性强：支持自定义工具、自定义 PageController、自定义 UI，可适配任意浏览器环境。
7. 模型兼容性广：Qwen、GPT、Claude、DeepSeek、Gemini、Ollama 等均支持，不锁定单一模型供应商。
8. 可选 Chrome 扩展 + MCP Server：突破单页限制，支持跨页面任务和外部 Agent 控制。

5.3 项目不足

1. 仅支持单页上下文：核心 JS 库只能控制当前页面，跨页面任务需要可选的 Chrome 扩展（MCP Server 仍为 Beta 阶段，稳定性待验证）。
2. 不支持复杂交互：不支持鼠标悬停（hover）、拖拽（drag & drop）等复杂交互操作，对需要精细鼠标操作的任务无能为力。
3. 无视觉识别能力：无法处理图片、Canvas、SVG 等非文本内容，对验证码、图表等视觉元素无法处理。
4. 依赖 DOM 语义化：如果页面 HTML 结构混乱、缺少语义化标签，Agent 可能无法正确理解页面结构，导致操作失败。
5. LLM 成本：每次操作都需要调用 LLM，高频自动化场景下需提前规划成本，不适合毫秒级高频操作。
6. 跨域 iframe 限制：基于文本 DOM 的方案在跨域 iframe 场景下有天然的隔离限制，无法操作 iframe 内元素。
7. 不适合自动化测试/爬虫：这不是服务端自动化方案，不能用它替代 Selenium 或 Playwright 做回归测试和大规模数据采集。
8. 模型能力要求：小模型（<10B）或 tool calling 能力弱的模型通常表现不佳，需要较强的 LLM 支撑，对本地部署场景有硬件门槛。

---

参考来源

• Page Agent GitHub 仓库
• Page Agent 官方文档
• Page Agent 技术分析 - 头条
• Page Agent vs browser-use 对比分析
• Page Agent 技术架构解析
• PageAgentCore 官方文档
• PageController 官方文档
• npm: page-agent