一行JavaScript代码实现AI自动化：深度解析阿里巴巴开源项目PageAgent
开源地址：https://github.com/alibaba/page-agent
Page Agent 是一个完全运行在浏览器中的 AI 驱动自动化框架。它彻底摆脱了传统自动化方案对无头浏览器、Python 运行环境或浏览器扩展的依赖，以极其轻量的页内 JavaScript 库形式存在。这意味着任何 Web 应用都能通过自然语言直接控制，完全不需要后端基础设施。
该项目由阿里巴巴开发，基于 MIT 许可证维护，当前版本 1.6.1。整个工程采用 TypeScript monorepo 架构，借助 npm workspaces 统一管理，并使用 Vite 作为构建工具。
Page Agent：连通大语言模型与现实网页的桥梁
Page Agent 的根本价值在于，它在大语言模型与可交互的 Web 页面之间建立了一座通道。你只需用一句自然语言发出指令，例如 “点击登录按钮并填入我的邮箱”，代理就会自主观察页面状态、推理下一步行动，并在循环中反复执行 DOM 操作，直至任务完成。
其突出优势之一，是基于文本的 DOM 操作策略。Page Agent 不会通过屏幕截图依赖多模态 LLM——那类方案不仅成本高，响应也慢。相反，它会从实时 DOM 树中提取出结构清晰且经过精简的交互元素文本表示。LLM 直接根据这些文本进行推理，判断需要和哪个元素交互、执行何种动作。这样既快速又轻量，并且几乎可以对接所有兼容 OpenAI 接口的模型。
分层架构与自主执行循环
Page Agent 采用分层架构，每一层的职责都被封装在独立的包中。各层之间通过异步、面向接口的方式进行通信，从而保证了高度的解耦和可测试性。
Agent 执行循环是整个系统的核心，它严格遵循 ReAct（推理 + 行动）模式，并融入了独有的“行动前反思”机制。在每一轮循环中，代理都会先观察页面状态，回顾之前的子目标与进度，规划接下来的动作，然后执行。这一循环不断重复，直至任务被标记为完成或者达到预设的最大步数。
Page Agent 是一个纯客户端 ReAct 循环，完全在浏览器内运行——无需 Python、无头浏览器或任何后端改造。它把页面的 DOM 读取为结构化文本，通过 LLM 推理出下一步，并利用浏览器原生的元素 API 去执行操作。
开箱即用的智能工具集
Page Agent 内置了一套供 LLM 在任务执行过程中调用的工具。每一个工具都通过 Zod schema 定义并进行输入校验，实际的 DOM 操作则委托给 PageController 来完成。
| 工具 | 说明 |
|---|---|
click_element_by_index | 通过数字索引点击可交互元素 |
input_text | 通过索引向输入框写入文本 |
select_dropdown_option | 根据元素索引和选项文本选择下拉项 |
scroll | 垂直滚动页面（或目标可滚动元素内部） |
scroll_horizontally | 水平滚动页面或指定元素 |
wait | 等待指定秒数，用于页面或数据加载 |
ask_user | 向用户提问并等待回复 |
done | 标记当前任务完成，并附带最终结果消息 |
execute_javascript | (实验性) 在当前页上执行任意 JavaScript 代码 |
所有的工具都是可扩展的——你可以通过 customTools 配置项增加自定义工具、覆盖内置工具，或者移除不需要的部分。
核心优势速览
| 特性 | 详细描述 |
|---|---|
| 零基础设施 | 无需 Python、无头浏览器或后端服务器。全部在页面内用 JavaScript 完成。 |
| 文本驱动的 DOM 理解 | 从 DOM 中提取结构化文本——无需截图，也不必依赖多模态模型。 |
| 自带 LLM | 兼容任何与 OpenAI 接口一致的 API（DashScope、OpenAI、Azure、本地模型等）。 |
| 可视化反馈 | 内置动画遮罩层和光标模拟，实时向用户展示 Agent 当前正在进行的操作。 |
| 多页面支持 | 可选的 Chrome 扩展能够将 Agent 的控制范围扩展至多个浏览器标签页。 |
| MCP 集成 | 外部 AI Agent（Claude Desktop、Cursor 等）可通过 MCP 协议驱动浏览器任务。 |
| 高度可定制 | 支持自定义工具、生命周期钩子、系统提示词替换以及内容转换钩子。 |
| 极致轻量 | 打包体积极小，没有冗余依赖。同时提供 ESM 和 IIFE 两种模块格式。 |
典型应用场景
Page Agent 的设计初衷是客户端 Web 增强，而非服务端自动化，因此特别适合以下场景：
- SaaS AI 助手 —— 只需要几行代码就能将智能助手嵌入到你自己的产品里，无需改动后端架构。
- 智能表单填写 —— 把原来需要数十次点击的工作流压缩成一条自然语言指令，在 ERP、CRM 和各种管理后台中效果尤为突出。
- 无障碍增强 —— 让任何一个 Web 应用都能以自然语言来操控，极低门槛地支持语音指令和屏幕阅读器。
- 多页面代理任务 —— 借助可选的 Chrome 扩展和 MCP 服务器，让你自己的 AI Agent 能够横跨多个浏览器标签页执行任务。
三种集成路径
根据不同的需求，Page Agent 提供了三种从简单到灵活的集成方式：
| 方式 | 难度 | 适用场景 |
|---|---|---|
| 一行 script 标签 | 入门级 | 快速原型验证和演示 |
NPM 包 (page-agent) | 进阶级 | 与自建 LLM 结合的生产级集成 |
| Chrome 扩展 + MCP | 高级 | 跨页面工作流与外部 Agent 的协同控制 |
页面内模式
这是最简单的模式。便捷类 PageAgent 会创建一个 PageController，将其传入 PageAgentCore，并挂载一个用于视觉反馈的 Panel。所有部件都在同一个文档上下文中运行。
Chrome 扩展模式
扩展引入了一种远程控制架构。MultiPageAgent 继承自 PageAgentCore，但将原来的 PageController 替换为 RemotePageController。后者通过 Chrome 消息机制（chrome.runtime.sendMessage）与运行在每个标签页内容脚本中的真实 PageController 实例通信。TabsController 则负责管理标签页生命周期，并实现跨标签页导航。
MCP 服务器模式
MCP 服务器是一个 Node.js 命令行工具，通过本地的 HTTP + WebSocket 服务器，把外部 AI Agent（如 Claude、GPT 等）桥接到 Chrome 扩展。它会在浏览器中打开一个启动页面，激活扩展的枢纽标签页，然后通过 WebSocket 交换任务指令和结果。实际的执行环境仍然是浏览器中的扩展。