Page Agent：让任意网页开口说话

一句话介绍

Page Agent 是阿里巴巴开源的「网页内置 AI Agent」——一段 JavaScript 注入任何网页，即可用自然语言操控界面元素，无须浏览器插件、无须后端、无须多模态模型。

---

背景：传统浏览器自动化的困境

如果你用过 Playwright、Puppeteer 或 Selenium，大概率踩过这些坑：需要安装一个大型 Python/Node 运行时、需要启动一个 headless 浏览器进程、截图传输给视觉模型导致延迟飙升、准确率还不稳定。更关键的是，这些工具都从外部控制浏览器——Agent 与网页之间隔着一层厚厚的进程边界。

Page Agent 换了一种思路：让 Agent 住进网页里。它不是控制一个远程浏览器，而是直接在页面 DOM 上下文中运行，一行 <script> 标签注入后，Agent 就能像真实用户一样与页面交互。这种"原地生长"的架构，从根本上绕过了传统方案的进程隔离开销。

该项目的作者是 Simon（GitHub @gaomeng1900），由阿里巴巴团队维护，核心设计理念是"client-side web enhancement"（客户端网页增强），明确不适用于服务端自动化场景。项目基于 browser-use 的 DOM 处理组件和 Prompt 构建，已在 GitHub 获得 24,900+ Stars，并入选 TrendShift 推荐榜单。

---

核心技术：DOM 脱水（DOM Dehydration）

Page Agent 的核心创新在于「DOM 脱水」机制。当 Agent 需要理解页面状态时，它不会发送整个 HTML 源码或截图，而是将页面压缩为一个轻量级的 FlatDomTree（扁平化 DOM 树）：

1. 静态解析：遍历 DOM 节点，过滤掉 <script>、<style> 等无意义元素，提取每个可交互元素的文本内容、坐标和选择器路径
2. 交互元素索引：为每个 <button>、<input>、<a> 等可交互元素分配唯一数字索引，建立 selectorMap 映射
3. 脱水传输：只将索引 + 文本发送给 LLM，LLM 返回"点击索引 5"这样的指令
4. 确定性执行：Agent 端根据索引在本地 selectorMap 中查找真实 DOM 元素，执行对应的 click()、type() 等操作

这一机制解决了两个核心问题：一是数据量——脱水后的 FlatDomTree 远小于原始 HTML 或截图，使得即使是较小的文本模型（如 Qwen3.5）也能精确操作；二是准确性——索引是确定性的，不像视觉模型可能对按钮位置误判。

Page Agent 通过 packages/page-controller 模块负责 DOM 脱水，内含 SimulatorMask 组件，可在自动化执行期间覆盖视觉遮罩层，阻止用户意外干扰自动化流程。

---

架构：Monorepo 模块化设计

项目采用 npm workspaces 构建 monorepo，版本 v1.11.0，共 8 个子包：

包名	职责
@page-agent/core	核心 Agent 逻辑，包含 PageAgentCore 类、工具定义（tools/）、Prompt 模板（prompts/）
@page-agent/page-controller	DOM 操控引擎，执行脱水、执行 actions
@page-agent/page-agent	面向用户的顶层 API 封装，PageAgent 类
@page-agent/llms	LLM 适配层，支持 OpenAI 兼容接口（baseURL + apiKey 模式）
@page-agent/mcp	MCP Server（Beta），允许外部 Agent 通过 Model Context Protocol 控制浏览器
@page-agent/ui	UI 组件库
@page-agent/extension	Chrome 扩展，支持跨标签页任务
@page-agent/website	文档站（Vite 构建）

开发栈：TypeScript 6 + Vite 8 + ESLint 10 + Prettier + Vitest 测试框架。Node.js 版本要求 ^22.22.1 || >=24，版本较新。

---

使用方式：从 Demo 到生产

最快体验（30 秒）

在任意网页控制台粘贴一行 CDN 脚本，即可激活 Demo Agent：

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

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

NPM 集成

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

Chrome 扩展

安装 Chrome 扩展后，可在任意网页打开 Page Agent，并通过 MCP Server 与 Claude Desktop、Copilot 等外部 Agent 连接，实现跨标签页任务编排。

---

MCP Server：连接外部 Agent 生态

Page Agent 的 MCP Server（Beta）是其扩展性的关键亮点。它将 Page Agent 暴露为一个 MCP 工具端点，外部 Agent（如 Claude Desktop）可以通过标准 MCP 协议调用浏览器控制能力。这意味着现有的 Agent 工作流不需要大改，直接把"控制网页"能力作为工具注册进去即可。

典型场景：用 Claude Desktop 写一段代码，然后通过 MCP 让 Page Agent 在浏览器中打开 GitHub 提交 PR——整个链路都是 Agent 到 Agent 的对话驱动。

---

应用场景

SaaS AI Copilot：几行代码将 AI 对话能力嵌入产品页面，用户说"帮我修改个人信息"，Agent 直接在页面表单中填入数据，无须后端改造。

智能表单填写：ERP、CRM 中复杂的多步骤表单，用自然语言"把客户地址改成 XX，发票类型改成专票"，Agent 自动完成 20+ 次点击操作。

无障碍增强：配合语音输入，用户可以"用声音操作网页"，Agent 读取 DOM 并执行对应操作，降低残障人士使用门槛。

自动化测试：开发阶段让 Agent 按自然语言描述执行端到端测试用例，无需维护复杂的 Playwright 测试脚本。

---

局限与挑战

1. 依赖 DOM 结构的稳定性：如果网页使用 Shadow DOM、iframe 或频繁改版的 React 单页应用，DOM 脱水后的索引可能失效
2. 无视觉理解：纯文本方案无法处理验证码、图片验证码等视觉挑战场景
3. 安全风险：注入页面的脚本拥有 DOM 写权限，生产环境必须配合数据脱敏（mask 机制）和 API Key 权限控制
4. 模型能力依赖：Agent 效果高度依赖底层 LLM 的指令遵循能力，较弱的模型可能执行错误操作

---

技术规格一览

• 语言：TypeScript（100%），无 Python 依赖
• 架构：Monorepo（npm workspaces）+ 模块化插件
• AI 框架：OpenAI 兼容接口（baseURL + apiKey），支持阿里通义千问、Claude（通过兼容端点）、本地 Ollama 等
• 代码质量：ESLint + Prettier + Vitest 全套工具链，@eslint-react/eslint-plugin 检查 React 代码
• License：MIT，可商用
• Stars：24,900+（持续增长中）

图1：Page Agent 官方演示海报，展示自然语言操控网页的核心体验

图2：Page Agent 官方 Banner（浅色模式），包含项目核心定位与统计数据