Page Agent 网页AI代理完全教程：从入门到精通 - 上篇

文章目录一、概述二、四大核心特性2.1 极简集成（Easy Integration）2.2 基于文本的 DOM 操作（Text-based DOM Manipulation）2.3 自带大模型（Bring Your Own LLMs）2.4 可选的 Chrome 扩展三、项目历史与技术栈四、适用场景（Use Cases）五、技术架构深度解析5.1 整体架构5.2 Monorepo 包结构5.3 Agent 循环机制（Re-act Loop）5.4 数据流六、环境搭建与快速开始6.1 前置要求6.2 方式一：CDN 快速体验（新手推荐）6.3 方式二：NPM 安装（生产环境推荐）6.4 方式三：本地开发（贡献者）七、LLM 集成与模型配置7.1 架构7.2 支持的主要模型7.3 本地模型支持7.4 模型补丁机制（Model Patch）八、DOM 处理机制8.1 核心思想8.2 FlatDomTree 数据结构8.3 DOM 树构建流程8.4 交互元素检测8.5 顶层元素检测（Top Element Detection）8.6 视口过滤（Viewport Filtering）8.7 特殊元素处理8.8 DOM 树输出示例九、工具系统（Tools）9.1 工具定义结构9.2 内置工具9.3 wait 工具的智能计时9.4 自定义工具9.5 工具设计最佳实践十、Chrome 扩展开发10.1 概述10.2 架构10.3 安装与构建10.4 多标签页协作示例十一、MCP Server11.1 启动11.2 配置文件11.3 MCP Tools11.4 与 Claude Desktop 集成十二、高级用法与最佳实践12.1 任务分解策略12.2 错误恢复12.3 性能优化12.4 API 密钥安全12.5 SaaS 集成示例十三、源码级分析13.1 核心循环源码13.2 系统提示词（简化版）13.3 actions.ts 源码解读十四、测试与调试14.1 测试框架14.2 调试技巧14.3 常见调试场景十五、与同类项目的对比十六、常见问题与故障排除十七、总结一、概述在 Web 应用日益复杂、用户操作步骤愈发冗长的今天，"能否用一句话让网页自动完成操作？"正从科幻走向现实。Page Agent是阿里巴巴开源的驻留于网页的 GUI 代理（In-page GUI Agent），其核心理念是——单个 JavaScript 脚本即可让任何网页拥有自己的 AI 代理能力。根据项目官方定义：“驻留于网页的 GUI 代理。单个脚本即可让任何网页拥有自己的 AI 代理。”与 Puppeteer、Playwright、Selenium 等传统浏览器自动化工具不同，Page Agent不需要浏览器扩展、Python 环境、无头浏览器或任何后端服务。它完全运行在用户的浏览器页面内，通过纯 JavaScript 实现对 DOM 的理解和操作。这篇文章将全面介绍 Page Agent 的架构设计、核心原理、使用方法和最佳实践。二、四大核心特性2.1 极简集成（Easy Integration）仅需一行 HTML 即可集成：