Page-Agent 阿里开源深度解析：18K Star 网页 GUI Agent，用自然语言操控网页

1. 技术背景：为什么网页自动化需要新范式？

网页自动化领域长期被 Selenium、Playwright、Puppeteer 等工具主导。这些工具的核心思路是服务端控制——启动一个无头浏览器（Headless Browser），通过 WebDriver 协议或 DevTools Protocol 从外部操控页面。这种架构在爬虫和测试场景中表现良好，但在 AI Agent 时代暴露了三个致命缺陷：

第一，架构臃肿。 服务端方案需要 Python 运行时、浏览器二进制、WebDriver 驱动，部署成本高昂。一个需要嵌入网页的 AI 助手，不可能要求用户先装一套 Python 环境。

第二，多模态依赖。 以 Browser Use 为代表的新一代 Web Agent 依赖截图 + 视觉模型理解页面，每次操作都需要调用多模态 LLM（如 GPT-4o），Token 消耗巨大、延迟高、成本难以控制。

第三，集成困难。 传统方案是"外部操控者"视角，无法深度嵌入现有 Web 应用。想给 SaaS 产品加一个 AI Copilot？传统方案需要搭建完整的后端代理服务。

2025 年 6 月，阿里巴巴开源了 Page-Agent，提出了一种全新的范式：纯前端、基于文本的 DOM 操作、无需截图、无需后端。项目发布后迅速走红，截至 2026 年 10 月已在 GitHub 获得 18.7K+ Star，成为网页 AI Agent 领域最受关注的开源项目之一。

如果你对 AI Agent 生态感兴趣，推荐阅读我们之前的深度解析：Unlimited-OCR 百度开源长文档 OCR 神器 和 REA 逆向工程 AI 助手。

2. 核心创新：纯前端 JavaScript 实现的 GUI Agent

Page-Agent 的核心设计理念可以用一句话概括：把 AI Agent 直接嵌入网页本身。

2.1 一行代码集成

整个 Agent 的核心只需要一行 HTML：

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

加载后，页面右下角会出现一个聊天面板，用户可以直接用自然语言指挥 Agent 操作页面——点击按钮、填写表单、滚动页面、执行 JavaScript，一切都在浏览器内完成。

2.2 与同类方案的本质区别

Page-Agent 的独特定位是客户端增强（Client-side Web Enhancement），而非服务端自动化。它不是要替代 Selenium 做爬虫，而是要让任何网页变成一个 AI 原生应用。

3. 架构原理：从 DOM 到自然语言的完整管线

Page-Agent 的架构分为四个核心层，每层职责清晰、解耦良好。理解这套架构，是深度使用它的前提。

3.1 Monorepo 模块结构

packages/
├── page-controller/   # DOM 操作与视觉反馈（SimulatorMask）
├── llms/              # LLM 客户端，支持 OpenAI 兼容 API
├── core/              # PageAgentCore —— 无 UI 的核心 Agent 逻辑
├── ui/                # 聊天面板 UI（i18n 支持）
├── page-agent/        # 主入口，整合 Core + UI + Controller
├── extension/         # Chrome 扩展（跨页面 Agent）
├── mcp/               # MCP Server（外部 Agent 控制浏览器）
└── website/           # 文档站点

关键设计原则：PageController 不依赖 LLM，LLMs 不依赖 PageController。Core 层是桥梁，负责将两者粘合。

3.2 DOM 处理管线：从 Live DOM 到简化文本

Page-Agent 最核心的技术创新在于 DOM 文本化管线。它不截图，而是把页面的 DOM 树转化为 LLM 可理解的简化文本表示。整个流程分三步：

Step 1：DOM 提取（Live DOM → FlatDomTree）

page-controller 模块遍历当前页面的 Live DOM，构建一棵 FlatDomTree。这棵树会过滤掉不可见元素、装饰性节点，保留所有可交互元素（按钮、输入框、链接、下拉菜单等），并为每个交互元素分配一个数字索引（index）。

// PageController 核心接口（简化）
class PageController {
    // 获取简化后的 DOM 文本表示
    async getSimplifiedHTML(): Promise<string>

    // 通过索引点击元素
    async clickElement(index: number): Promise<ActionResult>

    // 通过索引输入文本
    async inputText(index: number, text: string): Promise<ActionResult>

    // 滚动页面
    async scroll(options: ScrollOptions): Promise<ActionResult>

    // 选择下拉选项
    async selectOption(index: number, text: string): Promise<ActionResult>
}

Step 2：脱水（Dehydration）

将 FlatDomTree 序列化为紧凑的文本格式，类似这样：

[1] button "登录"
[2] input "用户名" 
[3] input "密码"
[4] link "忘记密码？"
[5] checkbox "记住我"

每个可交互元素都有唯一的索引号和可读的文本描述。LLM 不需要"看"页面，只需要"读"这份文本清单就能理解页面结构。

Step 3：LLM 决策

简化文本被送入 LLM，LLM 返回结构化的操作指令（通过 Tool Calling 机制），例如：

{
    "tool": "click_element_by_index",
    "args": { "index": 1 }
}

PageAgent 根据索引在真实 DOM 上执行操作。整个过程零截图、零 OCR、零多模态模型。

3.3 Re-act 循环：观察-思考-行动

Page-Agent 的 Agent 循环遵循经典的 Re-act（Reasoning + Acting） 模式，在 PageAgentCore 中实现：

┌─────────────────────────────────────────┐
│              Agent Step                 │
│                                         │
│  1. Observe（观察）                      │
│     → 获取当前页面的简化 DOM 文本          │
│     → 收集历史事件（已完成的操作、错误等）   │
│                                         │
│  2. Think（思考）                        │
│     → Reflection：评估当前状态            │
│     → 短期规划：下一步应该做什么           │
│     → LLM 调用：决定具体动作              │
│                                         │
│  3. Act（行动）                          │
│     → 执行 LLM 选择的 Tool               │
│     → 更新历史记录                        │
│     → 检查任务是否完成                    │
│                                         │
│  4. Loop or Done                        │
│     → 未完成 → 回到 Step 1               │
│     → 完成 → 调用 done tool 返回结果      │
└─────────────────────────────────────────┘

每个 Step 最多调用一次 LLM，默认最大步数 maxSteps = 40。这意味着一个复杂任务最多进行 40 次 LLM 调用，Token 消耗可控。

3.4 内置工具集

Page-Agent 为 Agent 提供了一组精心设计的内置工具：

所有工具都通过 Zod Schema 定义参数类型，确保 LLM 输出的参数经过严格校验。

4. 快速上手：从 Demo 到生产集成

4.1 零配置体验（Demo 模式）

最快的体验方式——使用官方提供的免费 Demo LLM：

<!DOCTYPE html>
<html>
<head>
    <title>Page-Agent Demo</title>
</head>
<body>
    <!-- 你的网页内容 -->
    <form>
        <input type="text" placeholder="用户名">
        <input type="password" placeholder="密码">
        <button type="submit">登录</button>
    </form>

    <!-- 一行引入 Page-Agent -->
    <script
        src="https://cdn.jsdelivr.net/npm/page-agent@1.12.4/dist/iife/page-agent.demo.js"
        crossorigin="anonymous"
    ></script>
</body>
</html>

打开页面后，右下角会出现聊天面板。试着输入"帮我填写用户名 admin 并点击登录"，Agent 会自动识别表单元素并执行操作。

⚠️ Demo 模式使用免费的测试 LLM API，仅用于技术评估，不适合生产环境。

4.2 NPM 集成（推荐生产使用）

npm install page-agent

import { PageAgent } from 'page-agent'

// 初始化 Agent，接入你自己的 LLM
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('点击导航栏中的"产品"链接')

// 监听状态变化
agent.addEventListener('statuschange', (e) => {
    console.log('Agent 状态:', e.detail.status)
    // idle → running → completed / error / stopped
})

// 监听执行活动（实时反馈，适合 UI 展示）
agent.addEventListener('activity', (e) => {
    console.log('活动:', e.detail.type)
    // thinking → executing → executed → ...
})

4.3 自定义工具扩展

Page-Agent 支持注册自定义工具，让 Agent 能执行你的业务逻辑：

import { PageAgent, tool } from 'page-agent'
import * as z from 'zod/v4'

const agent = new PageAgent({
    model: 'gpt-4o-mini',
    baseURL: 'https://api.openai.com/v1',
    apiKey: '***',
    // 注册自定义工具
    customTools: {
        search_products: tool({
            description: '搜索商品并返回结果列表',
            inputSchema: z.object({
                keyword: z.string().describe('搜索关键词'),
                maxResults: z.number().default(10),
            }),
            execute: async (args) => {
                const res = await fetch(`/api/products?q=${args.keyword}`)
                const data = await res.json()
                return JSON.stringify(data.products.slice(0, args.maxResults))
            },
        }),
    },
})

// 现在 Agent 可以调用 search_products 工具
await agent.execute('帮我搜索蓝牙耳机，只看前 5 个结果')

4.4 Chrome 扩展模式（跨页面任务）

对于需要跨多个标签页工作的复杂任务，Page-Agent 提供了 Chrome 扩展：

packages/extension/
├── MultiPageAgent.ts          # 跨页面 Agent 协调器
├── RemotePageController.ts    # 远程页面控制器
└── TabsController.ts          # 标签页管理

扩展模式下，Agent 可以在 Tab A 读取数据，切换到 Tab B 填写表单，再回到 Tab A 验证结果——这是纯页面内模式做不到的。

扩展还提供了 MCP Server（Beta），允许外部 Agent（如 Claude Desktop、Hermes Agent）通过 MCP 协议控制浏览器。

5. 实战应用场景

5.1 SaaS 产品 AI Copilot

这是 Page-Agent 最核心的应用场景。假设你有一个 ERP 系统，用户需要在"采购订单"页面完成一系列操作。传统方式需要用户手动点击多个按钮、填写多个字段。集成 Page-Agent 后：

// 在你的 ERP 页面中嵌入
const agent = new PageAgent({
    model: 'qwen3.5-plus',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: '***',
    language: 'zh-CN',
    // 限制 Agent 的操作范围（安全沙箱）
    allowedOrigins: ['https://your-erp.com'],
})

用户只需说"帮我创建一个采购订单，供应商选华为，物料选 A 类电阻 1000 个"，Agent 自动完成所有表单填写和按钮点击。

5.2 智能表单自动填充

对于 CRM、OA 等需要频繁填写复杂表单的系统，Page-Agent 可以将 20 次点击操作压缩为一句自然语言指令。特别适合：

• 批量数据录入：从文本描述中提取结构化数据并填入表单
• 跨系统数据同步：从邮件/文档中提取信息填入业务系统
• 新手引导：AI Copilot 指导用户完成复杂操作流程

5.3 无障碍增强

Page-Agent 的文本化 DOM 天然适合无障碍场景：

• 语音控制：结合 Web Speech API，用户可以用语音指令操作网页
• 屏幕阅读器：Agent 可以用自然语言描述页面内容
• 运动障碍辅助：减少精确点击的需求，用自然语言替代

5.4 自动化测试与数据采集

虽然 Page-Agent 的设计初衷是客户端增强，但它的 execute_javascript 工具和 DOM 理解能力也可以用于：

• 页面内容提取：用自然语言描述要提取的数据，Agent 自动定位并返回
• 表单自动化测试：用自然语言描述测试步骤，Agent 自动执行

6. 支持的 LLM 模型

Page-Agent 采用 OpenAI 兼容 API 协议，理论上支持所有主流 LLM：

关键要求：模型必须支持 Function Calling / Tool Use。纯文本补全模型无法使用。

// 接入本地部署的 Ollama
const agent = new PageAgent({
    model: 'llama3.1',
    baseURL: 'http://localhost:11434/v1',
    apiKey: 'ollama', // Ollama 不需要真实 key
    language: 'zh-CN',
})

7. 局限性与未来方向

7.1 当前局限

1. 仅限同源页面。 纯页面内模式只能操作当前页面的 DOM，无法跨域操作。跨页面需要 Chrome 扩展。

2. 复杂页面性能。 对于 DOM 节点超过 5000 个的超复杂页面（如大型数据表格），DOM 文本化后的 Token 消耗会显著增加。

3. 动态内容延迟。 SPA 框架（React/Vue）的异步渲染可能导致 Agent 在 DOM 尚未就绪时执行操作。需要合理使用 wait 工具。

4. LLM 准确性。 Agent 的操作准确性高度依赖 LLM 的 Tool Calling 能力。较弱的模型可能在复杂页面中迷路。

5. 安全考量。 execute_javascript 工具允许 Agent 执行任意 JS 代码，在生产环境中需要谨慎配置权限。

7.2 未来发展方向

根据项目维护者的说明，未来重点方向包括：

• 更智能的 DOM 压缩：减少 Token 消耗，支持更复杂的页面
• 多步骤任务规划：增强 Agent 的长期规划能力
• 更好的错误恢复：操作失败后的自动重试和替代方案
• MCP 生态集成：与更多 AI Agent 框架互通
• 企业级安全特性：操作审计、权限控制、沙箱隔离

常见问题 (FAQ)

问：Page-Agent 需要后端服务吗？
答：完全不需要。Page-Agent 是纯前端 JavaScript 库，所有处理都在浏览器内完成，无需任何后端服务或代理。这使得它可以轻松嵌入任何现有网页。

问：它是否像 Selenium 那样需要浏览器驱动？
答：不需要。Page-Agent 不依赖 WebDriver 或任何浏览器自动化驱动，它通过原生 DOM API 直接操作页面元素。

问：Page-Agent 支持哪些浏览器？
答：支持所有现代浏览器：Chrome、Edge、Firefox 和 Safari。由于它使用标准的 Web API，没有特殊依赖。

问：它与 Browser Use 等方案有什么区别？
答：核心区别在于页面理解方式。Page-Agent 使用文本化 DOM（不截图），而 Browser Use 和类似方案依赖截图 + 多模态 LLM 理解页面。这使得 Page-Agent Token 消耗更低、延迟更小、成本更可控。

问：是否需要编程经验才能使用？
答：基础使用只需要会添加一行 <script> 标签。对于高级定制（如自定义工具），需要一些 JavaScript/TypeScript 基础，但官方文档提供了完整示例。

问：Page-Agent 能处理 React/Vue/Angular 等 SPA 框架吗？
答：可以。它操作的是实际渲染后的 DOM，因此与前端框架无关。不过需要注意异步渲染的时机，可能需要使用 wait 工具确保元素已就绪。

问：商业使用需要付费吗？
答：完全免费。Page-Agent 采用 MIT 许可证，允许自由使用、修改和分发，包括商业用途。

8. 总结

Page-Agent 代表了网页自动化的一种全新范式——把 AI Agent 从服务端拉回浏览器，用文本替代截图，用一行代码替代一套基础设施。

它不是 Selenium 的替代品，而是网页 AI 化的新基座。如果你想给现有 Web 产品加上 AI Copilot 能力，Page-Agent 是目前集成成本最低、架构最轻量的方案。

关键数据一览：

📎 项目地址：github.com/alibaba/page-agent 📎 在线 Demo：alibaba.github.io/page-agent 📎 官方文档：alibaba.github.io/page-agent/docs