编程把 GUI Agent 放进网页 JS：alibaba/page-agent 走文本 DOM，不碰截图和多模态

2026-10-09 00:03:52

把 GUI Agent 放进网页 JS：alibaba/page-agent 走文本 DOM，不碰截图和多模态

项目信息

GitHub 仓库：alibaba/page-agent
官方文档：page-agent docs / introduction / overview
在线 Demo：alibaba.github.io/page-agent
npm：page-agent（npm install page-agent，当前版本 1.12.4，MIT License，作者 Simon）
Chrome 扩展：Page Agent Ext
MCP Server (Beta)：docs/features/mcp-server

仓库用 TypeScript 写的，创建于 2025-09-23，目前约 2.9 万 star。

一句话定位是 The GUI Agent Living in Your Webpage：一个 script 标签，让任意网页拥有自己的 AI agent。纯 JS 实现的 GUI agent，用自然语言操作 Web 应用，不需要后端，不需要客户端 Python，也不需要浏览器插件或无头浏览器。

它提供什么

集成简单：不装浏览器插件、不跑 Python、不开无头浏览器，纯页面内 JavaScript。
基于文本的 DOM 操作：不截图，因此不需要多模态模型，也不需要额外的浏览器权限。
自备 LLM：支持主流模型，包括本地部署的模型，只要走任意 OpenAI 兼容 endpoint 就能接。
可选扩展与 MCP：Chrome 扩展用来处理跨页面任务；MCP Server（Beta）让外部 Agent 客户端反过来驱动浏览器。
端侧运行：Agent 逻辑跑在网页的 JS 运行时里，天然继承用户当前的 cookie、登录态和权限。
HTML 脱水（DOM dehydration）：把整页节点压成只保留可交互元素的精简文本地图 FlatDomTree。
HITL 面板：human-in-the-loop 的 UI 面板。

几个典型用法：给 SaaS 产品加 AI Copilot，不重写后端；把 ERP/CRM/管理后台里 20 次点击的表单操作压成一句话；给网页做自然语言的无障碍入口；跨页面 Agent 走可选 Chrome 扩展；以及通过 MCP 给现有 Agent 补上浏览器控制能力。

快速开始

最省事的是直接引 CDN 上的 iife demo 构建（免费 Demo LLM，仅用于技术评估）：

在 URL 后加 ?autoInit=false，脚本只会被加载，不会自动创建 Demo Agent，之后你可以自己 new window.PageAgent(...) 手动初始化，接自己的 LLM。

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

架构

仓库按职责拆成了几个包：

packages/
├── core/                    # npm: "@page-agent/core" ⭐ Core agent logic (headless)
├── page-agent/              # npm: "page-agent" entry class (with UI + controller + demo builds)
├── website/                 # @page-agent/website (private)
├── llms/                    # @page-agent/llms
├── extension/               # 🚧 WIP: Browser extension (WXT + React)
├── page-controller/         # @page-agent/page-controller
└── ui/                      # @page-agent/ui

Page Agent：带内置 UI Panel 的主入口，继承自 PageAgentCore，依赖 @page-agent/core 与 @page-agent/ui，以 page-agent 的名字发布到 npm。日常 new PageAgent() 用的就是它。
Core（@page-agent/core）：无 UI 的 PageAgentCore，依赖 llms 与 page-controller。要嵌进自己的界面、自己管面板时用这一层。
LLMs（@page-agent/llms）：LLM 客户端，带 retry 逻辑，以及 reflection-before-action 的思路。OpenAIClient.ts 负责 OpenAI 兼容调用；相关类型是 MacroToolInput、AgentBrain、LLMConfig。
UI（@page-agent/ui）：Panel 与 i18n，通过 PanelAgentAdapter 接口和 PageAgent 解耦。
Page Controller（@page-agent/page-controller）：DOM 操作与可选的视觉反馈（SimulatorMask，enableMask: true 开启），不依赖 LLM。

执行流水线分四步：

DOM Extraction：Live DOM → FlatDomTree，代码在 page-controller/src/dom/dom_tree/。
Dehydration：DOM 树 → 供 LLM 阅读的精简文本。
LLM Processing：模型返回动作计划。
Indexed Operations：PageAgent 按元素 index 调 PageController。

PageController 暴露的是这类异步方法：

await this.pageController.updateTree()
await this.pageController.clickElement(index)
await this.pageController.inputText(index, text)
await this.pageController.scroll({ down: true, numPages: 1 })
const simplifiedHTML = await this.pageController.getSimplifiedHTML()
const pageInfo = await this.pageController.getPageInfo()

扫描 DOM 时，每个可交互元素会被标上 index + role + 文字 label，装饰性标记被剥掉，整页压成一份精简文本清单。模型读的是这份清单，不是像素。

边界

核心库只操作单个页面/视图。跨标签页、跨窗口要装可选的 Chrome 扩展，需要单独安装授权。
MCP Server 还在 Beta，作用是让 Claude Desktop、Copilot 这类外部 Agent 反向驱动它。
它面向 client-side web enhancement，不是服务端自动化工具。批量爬站、绕过限制、跨浏览器测试都不属于它的适用范围。
官方明确说明安全规则主要靠 prompt 而不是硬约束。嵌入不可信环境时要留意 XSS 面和对 API key 的保护。
Demo CDN 用的是免费测试 LLM API，有速率和来源限制，仅供技术评估；生产环境要自备 LLM。
强视觉依赖、纯图片交互的页面可能需要额外 workaround。

和 Playwright / Selenium / browser-use 的差别

Playwright、Selenium、Puppeteer 是外部进程，通过 WebDriver/CDP 读 DOM，适合脚本化的端到端测试和服务端 RPA。

Page Agent 的位置不同：它是网页内部的客户端 JS，读的是脱水后的文本 DOM，接一个 script 标签或一个 npm 包就能用，适合产品内嵌的操作型 copilot。

Contributing / License

不接受完全由 Bot/AI 自动生成、没有实质人类参与的代码贡献。MIT License。

编程 把 GUI Agent 放进网页 JS：alibaba/page-agent 走文本 DOM，不碰截图和多模态