【实战解析】阿里开源 PageAgent：纯前端 GUI Agent，一行JS让网页支持自然语言操控

阿里巴巴开源了 PageAgent（GitHub 9600+ Stars），一个纯前端 JavaScript GUI Agent 库。本文从技术架构（DOM文本化 vs 截图识别）、代码集成、模型兼容性、适用场景等角度做深度解读，附实际接入代码和踩坑记录。适合做 SaaS 产品、企业管理后台的前端开发者。

- 前言
- 一、跟传统方案有什么不同
- - [1.1 传统 GUI 自动化的问题](#1.1 传统 GUI 自动化的问题)
  - [1.2 PageAgent 的 "Inside-out" 思路](#1.2 PageAgent 的 "Inside-out" 思路)
- 二、技术架构拆解
- - [2.1 核心工作流](#2.1 核心工作流)
  - [2.2 DOM 文本化](#2.2 DOM 文本化)
  - [2.3 代码接入](#2.3 代码接入)
- 三、实际试用和踩坑
- - [3.1 试用过程](#3.1 试用过程)
  - [3.2 踩坑记录](#3.2 踩坑记录)
  - [3.3 跨页面的问题](#3.3 跨页面的问题)
- 四、适用场景分析
- 五、总结
- 六、参考资料

前言

上周刷 GitHub Trending 看到这个项目的时候，说实话第一反应是"又一个GUI自动化工具？"。但点进去看了下 README 和源码,发现它跟我之前用过的那些方案都不一样。它不是从外面控制浏览器，而是直接住在网页里面。

PageAgent 是阿里巴巴开源的一个 JavaScript 页面内 GUI Agent，MIT 协议。截到今天 GitHub 上已经 9600+ Stars 了。它的 slogan 是 "The GUI Agent Living in Your Webpage"，直译过来就是"住在你网页里的GUI Agent"。

这篇文章我从技术角度拆解下它到底做了什么，顺便记录下我实际试用的过程。

一、跟传统方案有什么不同

1.1 传统 GUI 自动化的问题

我们先看看现有的方案：

方案	运行位置	依赖	登录态	速度
Selenium/Playwright	后端	Python + 无头浏览器	需同步Cookie	慢（网络开销）
浏览器扩展 (如Browser Use)	扩展层	用户安装扩展	部分继承	中
RPA工具 (截图识别)	外部	多模态视觉模型	不继承	慢（截图+OCR）
PageAgent	页面内	无	天然继承	快（纯DOM）

传统方案的痛点其实挺明显的：后端方案有网络开销且需要同步Cookie；截图方案又慢又贵需要视觉模型；扩展方案需要用户安装东西。

1.2 PageAgent 的 "Inside-out" 思路

PageAgent 走了一条完全不同的路------它不是从外面控制浏览器,而是作为页面的一部分在里面跑。这带来了几个天然优势：

跑在页面里，自动拥有用户的所有Cookie和权限
直接操作DOM，不需要经过网络传输
不需要截图，不需要多模态视觉模型
用户不需要安装任何东西

二、技术架构拆解

2.1 核心工作流

复制代码

用户自然语言指令
        │
        ▼
  ┌─────────────┐
  │  DOM 文本化   │  遍历DOM树，提取可交互元素编号
  └──────┬──────┘
         │
         ▼  文本描述 + 用户指令
  ┌─────────────┐
  │  LLM 推理    │  返回操作序列: click([3]), type([5], "hello")
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │  DOM 操作执行  │  模拟点击、输入、滚动等事件
  └──────┬──────┘
         │
         ▼
  任务完成 or 继续循环

2.2 DOM 文本化

这是 PageAgent 最核心的设计。它不截图,而是遍历 DOM 树提取可交互元素,生成精简文本描述：

复制代码

[1] button "登录"
[2] input "用户名" placeholder="请输入"
[3] input "密码" type="password"
[4] checkbox "记住我" checked=false
[5] link "忘记密码"

每个元素有编号、类型、文字内容。模型看这个比看一坨 HTML 源码或者一张截图效率高得多。

为什么不用截图？算了下成本对比：

方案	模型要求	单次成本	速度
截图 + 多模态模型	GPT-4o 等	~$0.01-0.03	2-5秒
DOM文本化 + 文本模型	gpt-4o-mini / 千问	~$0.001-0.003	0.5-1秒

成本差了一个数量级，速度也快了不少。

2.3 代码接入

快速体验（Demo模式，用阿里提供的测试API）：

html 复制代码

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

一行代码。页面右下角会出现对话框。

正式集成（NPM）：

bash 复制代码

npm install page-agent

typescript 复制代码

import { PageAgent } from 'page-agent'

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

// 执行自然语言指令
await agent.execute('把截止日期改到下周五')

接 OpenAI 也一样简单：

typescript 复制代码

const agent = new PageAgent({
    model: 'gpt-4o-mini',
    baseURL: 'https://api.openai.com/v1',
    apiKey: 'YOUR_OPENAI_KEY',
    language: 'zh-CN',
})

await agent.execute('在搜索框输入 PageAgent 并回车')

支持通义千问、OpenAI、Gemini，只要兼容 OpenAI API 格式的模型都行。

三、实际试用和踩坑

3.1 试用过程

我在一个内部管理后台上试了下,大致流程：

bash 复制代码

# 1. 安装
npm install page-agent

# 2. 在页面入口文件里初始化
# 用的通义千问 qwen-plus

简单的操作（"点击XX按钮""在搜索框输入XX"）基本都能正确执行。表单填充也行,说"把名字改成张三"它能找到对的输入框。

3.2 踩坑记录

坑	描述	解决
Shadow DOM	Web Components 里的元素操作不了	目前无解,等官方支持
CSP 限制	公司项目 CSP 比较严，核心库加载失败	改用 Chrome 扩展模式
长链路中断	10步以上的任务中间容易断	拆成多个短指令分步执行
模型幻觉	偶尔点错元素	换更好的模型 or 加重试逻辑

说实话,长链路任务中断这个问题比较头疼。比如"登录→搜索→点详情→下载"这种4步的操作,大概率能走完。但如果是10步以上的复杂流程,中间出错的概率就高了。目前我的做法是把长任务拆成多个短指令一步步来。

3.3 跨页面的问题

核心库只能操作当前页面。如果任务涉及多个页面（比如"去A页面查数据，然后到B页面填进去"），需要配合 Chrome 扩展使用。这个扩展做了标签页桥接，让 Agent 能跨标签操作。

但这就多了一步------用户得装扩展。对于面向内部员工的场景还好,面向外部用户就比较别扭了。

四、适用场景分析

场景	适合度	原因
SaaS产品AI助手	很适合	不改后端,前端一行JS接入
ERP/CRM表单填写	很适合	几十个字段一句话搞定
无障碍辅助	适合	语音控制网页,降低使用门槛
自动化UI测试	适合	自然语言写测试用例,维护成本低
复杂跨页面工作流	勉强	需配扩展,长链路不稳定
Canvas/WebGL应用	不适合	DOM文本化方案无法识别画布内容

我觉得最甜蜜的场景是老系统改造。那种用了好几年的管理后台,改造成本极高,但用户天天吐槽不好用。现在前端加一行JS,用户就能用自然语言操作了。不用动后端,不用重构前端,投入产出比极高。

五、总结

PageAgent 做对的地方：

"Inside-out" 架构,从页面内部而非外部控制
DOM 文本化替代截图识别,又快又便宜
接入成本极低,一行JS就能跑

还需要改进的：

Shadow DOM 支持
长链路任务稳定性
跨页面能力（目前依赖扩展）

作为一个 9600 星的早期项目,完成度已经不错了。做 SaaS 或者管理后台的朋友可以先用 Demo 模式试试,看看在你的场景里效果如何。

六、参考资料

你有在自己的项目里试过 PageAgent 吗？或者用过其他GUI自动化方案？评论区聊聊踩过什么坑

觉得有用的话 点赞收藏关注，后面会出更多开源项目的实战分析