Page Agent：用自然语言直接操作网页的内嵌GUI智能体 | alibaba/page-agent

📌 项目地址：alibaba/page-agent | ⭐ 18,176 颗星 | 🔧 TypeScript | 📜 MIT

它解决什么问题

很多网页操作重复且繁琐，比如每天要在后台系统里填表单、点按钮、翻页面。传统方案要么用 Puppeteer/Playwright 写脚本，要么装浏览器扩展，都需要额外的运行时和权限。Page Agent 选择了一条更轻的路：一个 JavaScript 脚本，直接放在网页里，用自然语言指令驱动 DOM 操作。

这个思路的前提是：大多数网页操作的本质是 DOM 元素的增删改查。LLM 理解“点击登录按钮”并不难，难的是让 LLM 知道当前页面有哪些可操作的元素。Page Agent 把 DOM 树文本化，再把指令和 DOM 上下文一起扔给模型，让模型输出结构化操作步骤，然后直接用 DOM API 执行。

技术原理：文本 DOM 解析 + LLM 规划

核心流程很直白：

感知：读取当前页面的 DOM 树，提取关键元素的 attributes、text、角色（比如 button、input 等）。这一步不需要截图，纯文本。
规划：把你的自然语言指令（比如“把搜索框的日期改为上周”），和提取的 DOM 结构一起发给 LLM。模型返回一个 JSON 格式的操作序列，例如 [{"action": "click", "selector": "#date-picker"}, {"action": "type", "value": "2024-01-01"}]。
执行：在浏览器中，用 document.querySelector 这类 API 依次执行。

这个方案有几个明显的优缺点。

优点：

不需要截图，没有多模态模型的延迟和成本。（多模态模型通常比纯文本模型贵 5-10 倍）
不需要浏览器扩展或 Node.js 环境。一切在页面内完成，安全权限只依赖页面自身。
隐私友好：不把页面视觉内容传到外部，只传文本化的 DOM 信息。对 SaaS 客户来说，这比截屏更容易接受。

缺点：

依赖 DOM 结构的可解析性。如果页面大量使用 Canvas、WebGL 或无文本图标的 SVG，LLM 就看不见了。
对于需要视觉判断的任务（比如“找出页面中第二个红色按钮”），纯文本做不到。
LLM 规划的正确率不是 100%，尤其当 DOM 树里有大量隐藏元素或动态加载内容时，容易误判。

快速上手：两种集成方式

README 提供了一行 CDN 的试用方式和 NPM 的生产方式。

试用 — 一行 script 标签：

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

国内用镜像：https://registry.npmmirror.com/page-agent/1.8.2/files/dist/iife/page-agent.demo.js

注意：这个 demo 脚本自带了一个免费的测试 LLM API（代码里写死的），仅供技术评估。官方说你可以通过 ?autoInit=false 参数关闭自动初始化，然后自己 new window.PageAgent(...)。

生产 — 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: 'en-US',
})

await agent.execute('Click the login button')

你得自己准备 LLM 的 API Key。支持任何兼容 OpenAI 接口的模型（比如通义千问、DeepSeek、甚至本地 ollama）。这个 baseURL 可以指向任意 OpenAI-like 的端点。

两个扩展方向

除了在单页面里嵌入，Page Agent 提供了两个跨页面的能力：

Chrome 扩展：当你需要操作多个标签页（比如从 A 页面复制数据贴到 B 页面），扩展让 agent 能在浏览器全局环境里工作。
MCP Server (Beta)：这是一个外部接口，让其他 AI 客户端（比如 Claude Desktop 或自建 agent）能通过它控制浏览器。MCP 协议把浏览器包装成一个工具，agent 可以调用。

这两个功能在 README 里标了可选（Optional），说明它们不是核心卖点，但提供了进一步扩展的路径。

真正适用的场景

我试了一下（用 NPM 方式接入了一个内部 CRM），觉得这些场景值得考虑：

给自家 SaaS 产品加一个 AI 操作入口：你不需要重写后端 API，只需要在前端引入 Page Agent，然后让用户直接说“把张三的状态改为已签约”。后端逻辑不变，只是操作从手动点击变成了自然语言触发。这对内部管理系统特别有用，因为界面固定、风险可控。
无障碍访问：视力障碍用户可以通过语音或屏幕阅读器配合 Page Agent 操作网页。因为 agent 可以输出文字反馈，“我已经点击了提交按钮”，这比纯视觉依赖的屏幕阅读器更直接。
跨标签页的流程自动化：比如需要从 CRM 复制客户信息，打开邮箱粘贴并发送。如果用 Puppeteer，你需要处理 cookie、跨域等问题；用 Page Agent 的 Chrome 扩展，至少语言描述更直观。

不适合的场景：

页面结构频繁变动的公网网站（比如 Twitter/X），今天按钮 id 是 #login，明天可能变成 #auth-email。LLM 的规划成功率会随 DOM 变化急剧下降。
需要高可靠性的关键任务（比如金融交易、下单）。LLM 输出 JSON 可能格式错误或执行时抛错，不能保证 100% 正确。
需要长时间运行的自动化任务（比如整晚抓数据）。Page Agent 是前端脚本，页面刷新或网络断开就丢失状态。

我的看法

Page Agent 站对了生态位：它没有试图替代 Selenium 或 Puppeteer，而是给前端开发者一个低成本、低侵入的方式去接入 AI 控制。18176 个 star 说明前端社区对“用自然语言直接 JS 操控 DOM”这件事很感兴趣。实际效果取决于你选择的 LLM 的规划能力——如果模型对 DOM 上下文理解偏差，agent 就会“理解错”。我建议先用免费 demo 在真实业务页面上跑几个指令，评估准确率再决定是否投产。

更详尽的 API 和配置请翻阅官方文档：https://alibaba.github.io/page-agent/docs/introduction/overview