Page Agent 详解：住在网页里的 GUI 代理
让 AI 操作网页，主流做法是在浏览器外面架一个"驾驶员"：截图、视觉模型识别、再外部驱动点击。阿里巴巴开源的 alibaba/page-agent 反其道而行——把代理直接搬进网页内部：一段脚本注入页面，代理读 DOM、懂结构、执行自然语言指令，全程不截图、不用视觉模型、不装插件。约 29.1k Star、MIT 协议，口号是"给任何网页一个属于它自己的 AI 代理"。本文从核心思路、快速上手、能力场景到与 Playwright 的本质区别，完整拆解。
1、项目概述
Page Agent 是一个纯页内运行的 JavaScript GUI 代理：用户用自然语言下达指令，代理直接理解页面结构并完成操作。仓库约 29.1k Star、2.6k Fork、1100+ 次提交，MIT 协议，TypeScript 编写。
一句话定位：
- 官方口号：The GUI Agent Living in Your Webpage——住在网页里的 GUI 代理
- 一段脚本，任何网页即刻获得自然语言操控能力
- 模型自选（BYO LLM）：主流模型皆可接，含本地部署，另有免费演示模型供试玩
- 可选 Chrome 扩展处理跨页任务；MCP Server 处于 beta
2、核心思路：纯文本 DOM，无视觉依赖
它对"GUI 代理"的答案很干脆：不截图、不用多模态，直接读页面结构文本。
三个"不"：
- 不截图：没有视觉识别环节，省掉多模态模型的成本与延迟
- 不外挂：纯 JavaScript 跑在页面里，无需无头浏览器、无需 Python、无需装扩展
- 不绑定厂商：模型、接口地址、密钥都由接入方自选
思路要点：
1. DOM 本身就是最完整的界面描述，比截图更精确、更省 token
2. 代理与页面同源运行，操作页面即调用原生 DOM 能力
3. 官方致谢其 DOM 处理组件与提示词源自 browser-use 项目（同为 MIT）
4. 体积小巧的 TypeScript 包，npm 与 CDN 双渠道分发
3、安装与快速上手
两种接入：网页里加一行 script 最快；工程化项目走 npm。
<!-- 方式一：CDN 一行接入（demo 版内置免费演示模型） -->
<script
src="https://cdn.jsdelivr.net/npm/page-agent@1.12.4/dist/iife/page-agent.demo.js"
crossorigin="anonymous"
></script>
// 方式二：npm 安装
// npm install page-agentimport { 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: 'en-US',
})
await agent.execute('Click the login button')上手要点：
1. CDN demo 版自带免费演示模型，粘进网页即可体验
2. 正式接入配三样：模型名、OpenAI 兼容的 baseURL、apiKey
3. execute 一句自然语言即执行，语言参数控制交互语种
4. baseURL 指向兼容接口，因此本地或私有部署模型同样能接
4、能力与典型场景
官方列出的三类主场景，加上两个进阶通道。
主场景：
- 智能表单填写：理解字段语义，替用户填完复杂表单
- SaaS 的 AI 副驾驶：把"自然语言操作界面"做成产品功能
- 无障碍辅助：让不便操作鼠标的用户用语言驾驭页面
进阶通道：
- Chrome 扩展（可选）：跨标签页、多页面任务
- MCP Server（beta）：让 Claude 等代理客户端经 MCP 控制浏览器
场景要点：
1. 表单与站内导航是最甜的落点：结构固定、语义清晰、误伤面小
2. 对 SaaS 厂商，它相当于一行代码加上"AI 操作助手"卖点
3. MCP 通道把它从"产品功能"扩展为"代理生态里的一个工具"
5、与 Playwright/Puppeteer 的本质区别
两者都"操作网页"，但站在网页的两侧：一边是外部测试驱动，一边是内部能力增强。
对比要点：
- Playwright / Puppeteer：服务端自动化与测试框架，从外部控制浏览器，靠脚本与选择器
- Page Agent：客户端增强，嵌在页面自身，靠自然语言与 LLM 读 DOM
- 官方明示：为客户端网页增强设计，不做服务端自动化
选型建议：
1. 写自动化测试、爬虫、CI 集成 → Playwright / Puppeteer（或此前的 Scrapy 思路）
2. 给自家产品加自然语言操作、给用户当助手 → Page Agent
3. 两者不互斥：测试在外部驱动，体验在内部增强
4. 需要跨站自动化流程且要视觉兜底 → 考虑 browser-use 等外挂方案
6、技术栈与工程细节
工程面它是个规整的现代前端项目。
技术构成：
- TypeScript monorepo，packages 目录分包管理
- ESLint、Prettier、Husky 保障代码质量与提交规范
- npm 分发，IIFE 产物支撑 CDN 一行接入
- 包体积小，页面加载负担轻
来源致谢：
- DOM 处理组件与提示词设计源自 MIT 协议的 browser-use 项目
- 在其基础上做了"页内运行"的架构改造
7、使用建议与注意事项
使用建议：
- 先用 CDN demo 版在自家页面跑通体验，再切正式模型
- 指令设计要贴合 DOM 语义："点击登录按钮"优于"往右下角点一下"
- 跨页任务再考虑 Chrome 扩展；代理生态集成走 MCP
- 表单类功能先灰度，观察误操作率再放量
注意事项：
- 密钥安全：apiKey 写在前端意味着对用户可见，生产环境应经后端代理转发请求
- 纯 DOM 路线看不清 Canvas、视频内画面等非 DOM 内容
- 代理能替用户操作，也意味着能误操作：高危按钮要加确认
- MCP Server 尚在 beta，接口可能变动
8、总结
Page Agent 是阿里巴巴开源的页内 GUI 代理（29.1k Star、MIT、TypeScript）：一段 CDN 脚本或一个 npm 包，让网页直接获得自然语言操控能力。它不截图、不用视觉模型，靠 LLM 读纯文本 DOM 理解界面；模型自选含本地部署，主打智能表单、SaaS 副驾驶与无障碍三类场景，另有 Chrome 扩展跨页与 beta 期的 MCP Server；DOM 处理与提示词源自 browser-use 并做了页内化改造。
落地建议：想给产品加"AI 操作界面"能力的团队，先用 demo 脚本验证体验，再经后端代理接入正式模型、灰度观察误操作率；测试与爬虫场景仍交给 Playwright、Scrapy 等外部工具。对于要把自然语言变成界面操作能力的 Web 产品，Page Agent 是必要的轻量首选。
